@officexapp/vidfarm-devcli 0.21.24 → 0.21.26

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

@@ -81,16 +81,24 @@ Do not use this skill to author new templates from scratch, deploy platform infr
 
 ## 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:
+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 quote the per-video cost in one plain line each:
 
-- **minimize** — cheapest. Stay on FREE local compute wherever possible (local render, local TTS — `vidfarm tts` already defaults to the free local Kokoro voice in this mode — `stt --engine whisper`, `remove-greenscreen --local`, reused raw clips + HTML hyperframes). For assets, reach for the **free stock catalog** before paying to generate anything — `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` pulls royalty-free, commercial-safe music/sound-effects/images/icons/stock-video from pixabay/openverse/iconify at $0 instead of billing AI music/image generation (see the `vidfarm-media` skill). No surprise AI spend.
+| Mode | Cost per video | What it means |
+|---|---|---|
+| **minimize** | **$0 — explicitly free** | free local compute + free stock media only; billed AI is refused without `--yes` |
+| **hybrid** *(recommended)* | **~$0.01–$1** | free where it's free; pay AI only where it clearly wins |
+| **rich-ai** | **$1+** | best quality; AI image/video/voice/music used freely |
+
+**Every dollar above is billed to the user's OWN AI provider keys (BYOK)** — the keys they save via `vidfarm add-provider-key <provider> <key>` or **Settings → Bring your own keys** (<https://vidfarm.cc/settings/developer>). Vidfarm isn't marking it up; the model providers charge it directly. (Vidfarm wallet credits are only spent when the user deliberately runs on the platform key instead of their own.) Say this out loud the first time you ask — it's why `minimize` really is $0: with no key spend, nothing can be charged.
+
+- **minimize** — **$0 videos.** Stay on FREE local compute wherever possible (local render, local TTS — `vidfarm tts` already defaults to the free local Kokoro voice in this mode — `stt --engine whisper`, `remove-greenscreen --local`, reused raw clips + HTML hyperframes). For assets, reach for the **free stock catalog** before paying to generate anything — `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` pulls royalty-free, commercial-safe music/sound-effects/images/icons/stock-video from pixabay/openverse/iconify at $0 instead of billing AI music/image generation (see the `vidfarm-media` skill). No surprise AI spend.
   - **Check the keyless sources first — Openverse and iconify.** Openverse (CC/CC0 **music, SFX, and images**) and iconify (**icons**) need **no account or key at all**, so they always work in `minimize` mode. Prefer them for BGM, sound effects, icons, and CC imagery before anything else.
   - **Pixabay key** unlocks the photos/vectors/stock-video slots (music/SFX/icons/CC images are keyless). It's a **free** stock-media key, not an AI key. Don't assume it's missing when a search comes up short — it **may already be saved**: check `vidfarm provider-keys` (or the web app's **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>). If it isn't, the user grabs a free one at <https://pixabay.com/api/docs/> and saves it once — `vidfarm add-provider-key pixabay <key>`, the Settings surface, or by handing the key to their desktop AI agent to run that command. After it's saved, cost-mode `minimize` sourcing works end-to-end at $0.
   - **You can still get CUSTOM art in `minimize` — hand the prompt to the user and let a free image generator do it.** Stock and `mask` only cover art that already exists somewhere; when the video genuinely needs a bespoke graphic, **don't conclude "we can't" and don't quietly bill `generate`**. Write the prompt and ask the user to paste it into a **free** image generator — <https://meta.ai>, free-tier ChatGPT, or a free Hugging Face image Space (<https://huggingface.co/spaces>) — then hand the PNG back with `vidfarm put-file` (or drag it into **My Files** in the web app). $0, zero wallet spend. Full loop + the prompt template: **“Free manual image-gen”** below.
-- **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).
+- **hybrid** *(recommend this)* — **~$0.01–$1 per video, on their BYOK key.** Free where it's free; pay for AI only where it clearly wins (a hero shot, a voice you can't fake locally). A mostly-hyperframes video with one generated image lands near the low end; a few AI images plus premium narration approaches the high end.
   - **Narration starts free here too.** In BOTH `minimize` and `hybrid`, a bare `vidfarm tts "…"` runs the keyless local Kokoro-82M voice — no flag needed. Ask for a premium voice explicitly (`--style`, `--voice <provider preset>`, `--provider`, `--own-key`, or `--cloud`) when the piece needs one, and say so out loud so the user knows what they're paying for. `rich-ai` skips the free default entirely. If the local engine isn't installed on their machine, the run falls back to their provider key / cloud automatically and prints why.
   - **Free-TTS draft, premium-TTS final — now the default shape, so SAY it out loud.** Narration gets rewritten several times before the script locks, and paying for premium ElevenLabs TTS on every draft wastes money re-voicing lines that will change. The CLI defaults to the free local voice in `hybrid`, so drafts are free automatically — but a robotic draft voice reads as "broken" to a user who wasn't told. **Tell them the first time you generate narration**: the draft voice is the free local one, and you'll re-voice the approved final script in premium TTS (`--cloud` ElevenLabs, or `--style`/`--voice` on their own key) right before the last render. If they'd rather hear the real voice the whole way, pass the premium flags from the start — and if the piece is voice-led (a testimonial, a brand spot where the voice IS the product), offer premium up front instead of drafting free.
-- **rich-ai** — best quality; use AI image/video/voice/music freely.
+- **rich-ai** — **$1+ per video, on their BYOK key** (AI *video* generation especially — a few seconds of generated footage can be several dollars on its own). Best quality; use AI image/video/voice/music freely. When a run is likely to go well past $1, say the number before you spend it.
 
 Then **ask whether to remember the choice**, and save it where it will actually be read next time:
 

package/.agents/skills/vidfarm/references/automation-and-local-dev.md

@@ -215,12 +215,22 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 
 ## Cost mode — the devcli's money-saving guardrail
 
+The three modes, quoted as **cost per finished video**:
+
+| Mode | Per video | Posture |
+|---|---|---|
+| `minimize` | **$0 — explicitly free** | free local engines + free stock media only; billed ops refuse without `--yes` |
+| `hybrid` *(default recommendation)* | **~$0.01–$1** | free where free, AI where it clearly wins; each billed op prints its cost |
+| `rich-ai` | **$1+** | AI image/video/voice/music used freely; cost still printed |
+
+**All of it bills to the user's own AI provider keys (BYOK)** — the keys saved with `vidfarm add-provider-key <provider> <key>` or at **Settings → Bring your own keys** (<https://vidfarm.cc/settings/developer>). The model providers charge those keys directly; Vidfarm wallet credits only come into play when the user deliberately runs on the platform key instead of their own. So `minimize` isn't "cheap", it's **zero**: nothing reaches a paid key at all.
+
 `vidfarm cost-mode <minimize|hybrid|rich-ai>` records a single spend preference (in `~/.vidfarm/cost-mode.json`) that every **billed** command honors: `generate`, `music`, `decompose`, `inspiration-decompose`, `create`, `replicate`, `inpaint`, `create-overlay`, `cutout --generate` (only the generation step; a bare `cutout` on an existing graphic is free), and the cloud paths of `render --target cloud`, `tts --cloud`, `stt --cloud`, `remove-greenscreen` (non-`--local`). FREE local engines never gate (`render` local default, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, `cutout` on a file/url, all the file-editing verbs). `vidfarm media search` (the free stock catalog — pixabay/openverse/iconify music, SFX, images, icons, stock video) is also free and never gates.
 
-- **minimize** — a billed op is **refused** unless you add `--yes`; the error names the free local alternative (which now includes the matching `vidfarm media search` for music/SFX/image/video). Use this to guarantee no surprise AI spend. Before paying to generate music, sound effects, or images, try `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` first — free royalty-free assets instead of a billed `music`/`generate` call. **Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons) need no account at all**, so they always work in `minimize`. Photos/vectors/stock-video need a **free Pixabay key** that **may already be saved** — check `vidfarm provider-keys` (or web **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>) before assuming a short result means "no key." If absent, save one once: `vidfarm add-provider-key pixabay <key>` (free key from <https://pixabay.com/api/docs/>), the Settings surface, or hand it to the desktop AI agent to run that command.
+- **minimize ($0 videos)** — a billed op is **refused** unless you add `--yes`; the error names the free local alternative (which now includes the matching `vidfarm media search` for music/SFX/image/video). Use this to guarantee no surprise AI spend. Before paying to generate music, sound effects, or images, try `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` first — free royalty-free assets instead of a billed `music`/`generate` call. **Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons) need no account at all**, so they always work in `minimize`. Photos/vectors/stock-video need a **free Pixabay key** that **may already be saved** — check `vidfarm provider-keys` (or web **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>) before assuming a short result means "no key." If absent, save one once: `vidfarm add-provider-key pixabay <key>` (free key from <https://pixabay.com/api/docs/>), the Settings surface, or hand it to the desktop AI agent to run that command.
 - **minimize still gets CUSTOM images — via a free manual generator.** A refused `generate` is not the end of the road. Offer the user the manual loop (ask once, then make it the session default): **you write the prompt → they run it free in <https://meta.ai>, free-tier ChatGPT, or a free Hugging Face image Space (<https://huggingface.co/spaces>) → they hand the PNG back** via `vidfarm put-file ./sheet.png` or web **My Files**. Ask for **one sheet holding every graphic you need**, gridded on a **flat pure-green plate** (`#00FF00`), no text — one round trip instead of N, which saves the user's time and your tokens. Then split it locally for $0: `vidfarm mask ./sheet.png --crop x,y,w,h --flat "#00FF00" --out prop-a.png`, once per element (drop `--flat` and let local ONNX matting handle it if the tool ignored the green background). Full prompt template + loop: recipe `recipes/cutout-graphics-for-explainers.md` (“Free manual image-gen”).
-- **hybrid** *(default recommendation)* — billed ops run but print a one-line cost notice each.
-- **rich-ai** — billed ops run without gating; cost is still printed.
+- **hybrid (~$0.01–$1 per video)** *(default recommendation)* — billed ops run but print a one-line cost notice each, charged to the user's BYOK key.
+- **rich-ai ($1+ per video)** — billed ops run without gating; cost is still printed. AI *video* generation is the line item that pushes a video well past $1 — quote it before running.
 
 **Narration defaults to the FREE local voice in minimize AND hybrid.** A bare `vidfarm tts "…"` runs the keyless local Kokoro-82M engine in both of those modes — you no longer have to remember `--engine local`. A run **opts out** of that default by asking for a premium voice (`--style`, `--provider`, `--model`, `--own-key`, or a non-Kokoro `--voice` like `alloy`/`Kore`/an ElevenLabs id), by passing `--cloud`/`--engine byok`, or by being in `rich-ai`. If the local engine isn't installed on the machine (it needs `pip install kokoro-onnx soundfile` + a ~340MB model on first use), the run **falls back** to the user's provider key / cloud instead of failing — it prints the reason on stderr so you can tell the user why the voice changed.
 

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.** `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 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.
 - Don't write keys into a per-repo `.env`. Details: `references/tts.md`.
 
 ## The audio engine

package/SKILL.director.md

@@ -81,16 +81,24 @@ Do not use this skill to author new templates from scratch, deploy platform infr
 
 ## 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:
+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 quote the per-video cost in one plain line each:
 
-- **minimize** — cheapest. Stay on FREE local compute wherever possible (local render, local TTS — `vidfarm tts` already defaults to the free local Kokoro voice in this mode — `stt --engine whisper`, `remove-greenscreen --local`, reused raw clips + HTML hyperframes). For assets, reach for the **free stock catalog** before paying to generate anything — `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` pulls royalty-free, commercial-safe music/sound-effects/images/icons/stock-video from pixabay/openverse/iconify at $0 instead of billing AI music/image generation (see the `vidfarm-media` skill). No surprise AI spend.
+| Mode | Cost per video | What it means |
+|---|---|---|
+| **minimize** | **$0 — explicitly free** | free local compute + free stock media only; billed AI is refused without `--yes` |
+| **hybrid** *(recommended)* | **~$0.01–$1** | free where it's free; pay AI only where it clearly wins |
+| **rich-ai** | **$1+** | best quality; AI image/video/voice/music used freely |
+
+**Every dollar above is billed to the user's OWN AI provider keys (BYOK)** — the keys they save via `vidfarm add-provider-key <provider> <key>` or **Settings → Bring your own keys** (<https://vidfarm.cc/settings/developer>). Vidfarm isn't marking it up; the model providers charge it directly. (Vidfarm wallet credits are only spent when the user deliberately runs on the platform key instead of their own.) Say this out loud the first time you ask — it's why `minimize` really is $0: with no key spend, nothing can be charged.
+
+- **minimize** — **$0 videos.** Stay on FREE local compute wherever possible (local render, local TTS — `vidfarm tts` already defaults to the free local Kokoro voice in this mode — `stt --engine whisper`, `remove-greenscreen --local`, reused raw clips + HTML hyperframes). For assets, reach for the **free stock catalog** before paying to generate anything — `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` pulls royalty-free, commercial-safe music/sound-effects/images/icons/stock-video from pixabay/openverse/iconify at $0 instead of billing AI music/image generation (see the `vidfarm-media` skill). No surprise AI spend.
   - **Check the keyless sources first — Openverse and iconify.** Openverse (CC/CC0 **music, SFX, and images**) and iconify (**icons**) need **no account or key at all**, so they always work in `minimize` mode. Prefer them for BGM, sound effects, icons, and CC imagery before anything else.
   - **Pixabay key** unlocks the photos/vectors/stock-video slots (music/SFX/icons/CC images are keyless). It's a **free** stock-media key, not an AI key. Don't assume it's missing when a search comes up short — it **may already be saved**: check `vidfarm provider-keys` (or the web app's **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>). If it isn't, the user grabs a free one at <https://pixabay.com/api/docs/> and saves it once — `vidfarm add-provider-key pixabay <key>`, the Settings surface, or by handing the key to their desktop AI agent to run that command. After it's saved, cost-mode `minimize` sourcing works end-to-end at $0.
   - **You can still get CUSTOM art in `minimize` — hand the prompt to the user and let a free image generator do it.** Stock and `mask` only cover art that already exists somewhere; when the video genuinely needs a bespoke graphic, **don't conclude "we can't" and don't quietly bill `generate`**. Write the prompt and ask the user to paste it into a **free** image generator — <https://meta.ai>, free-tier ChatGPT, or a free Hugging Face image Space (<https://huggingface.co/spaces>) — then hand the PNG back with `vidfarm put-file` (or drag it into **My Files** in the web app). $0, zero wallet spend. Full loop + the prompt template: **“Free manual image-gen”** below.
-- **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).
+- **hybrid** *(recommend this)* — **~$0.01–$1 per video, on their BYOK key.** Free where it's free; pay for AI only where it clearly wins (a hero shot, a voice you can't fake locally). A mostly-hyperframes video with one generated image lands near the low end; a few AI images plus premium narration approaches the high end.
   - **Narration starts free here too.** In BOTH `minimize` and `hybrid`, a bare `vidfarm tts "…"` runs the keyless local Kokoro-82M voice — no flag needed. Ask for a premium voice explicitly (`--style`, `--voice <provider preset>`, `--provider`, `--own-key`, or `--cloud`) when the piece needs one, and say so out loud so the user knows what they're paying for. `rich-ai` skips the free default entirely. If the local engine isn't installed on their machine, the run falls back to their provider key / cloud automatically and prints why.
   - **Free-TTS draft, premium-TTS final — now the default shape, so SAY it out loud.** Narration gets rewritten several times before the script locks, and paying for premium ElevenLabs TTS on every draft wastes money re-voicing lines that will change. The CLI defaults to the free local voice in `hybrid`, so drafts are free automatically — but a robotic draft voice reads as "broken" to a user who wasn't told. **Tell them the first time you generate narration**: the draft voice is the free local one, and you'll re-voice the approved final script in premium TTS (`--cloud` ElevenLabs, or `--style`/`--voice` on their own key) right before the last render. If they'd rather hear the real voice the whole way, pass the premium flags from the start — and if the piece is voice-led (a testimonial, a brand spot where the voice IS the product), offer premium up front instead of drafting free.
-- **rich-ai** — best quality; use AI image/video/voice/music freely.
+- **rich-ai** — **$1+ per video, on their BYOK key** (AI *video* generation especially — a few seconds of generated footage can be several dollars on its own). Best quality; use AI image/video/voice/music freely. When a run is likely to go well past $1, say the number before you spend it.
 
 Then **ask whether to remember the choice**, and save it where it will actually be read next time:
 
@@ -1393,12 +1401,22 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 
 ## Cost mode — the devcli's money-saving guardrail
 
+The three modes, quoted as **cost per finished video**:
+
+| Mode | Per video | Posture |
+|---|---|---|
+| `minimize` | **$0 — explicitly free** | free local engines + free stock media only; billed ops refuse without `--yes` |
+| `hybrid` *(default recommendation)* | **~$0.01–$1** | free where free, AI where it clearly wins; each billed op prints its cost |
+| `rich-ai` | **$1+** | AI image/video/voice/music used freely; cost still printed |
+
+**All of it bills to the user's own AI provider keys (BYOK)** — the keys saved with `vidfarm add-provider-key <provider> <key>` or at **Settings → Bring your own keys** (<https://vidfarm.cc/settings/developer>). The model providers charge those keys directly; Vidfarm wallet credits only come into play when the user deliberately runs on the platform key instead of their own. So `minimize` isn't "cheap", it's **zero**: nothing reaches a paid key at all.
+
 `vidfarm cost-mode <minimize|hybrid|rich-ai>` records a single spend preference (in `~/.vidfarm/cost-mode.json`) that every **billed** command honors: `generate`, `music`, `decompose`, `inspiration-decompose`, `create`, `replicate`, `inpaint`, `create-overlay`, `cutout --generate` (only the generation step; a bare `cutout` on an existing graphic is free), and the cloud paths of `render --target cloud`, `tts --cloud`, `stt --cloud`, `remove-greenscreen` (non-`--local`). FREE local engines never gate (`render` local default, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, `cutout` on a file/url, all the file-editing verbs). `vidfarm media search` (the free stock catalog — pixabay/openverse/iconify music, SFX, images, icons, stock video) is also free and never gates.
 
-- **minimize** — a billed op is **refused** unless you add `--yes`; the error names the free local alternative (which now includes the matching `vidfarm media search` for music/SFX/image/video). Use this to guarantee no surprise AI spend. Before paying to generate music, sound effects, or images, try `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` first — free royalty-free assets instead of a billed `music`/`generate` call. **Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons) need no account at all**, so they always work in `minimize`. Photos/vectors/stock-video need a **free Pixabay key** that **may already be saved** — check `vidfarm provider-keys` (or web **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>) before assuming a short result means "no key." If absent, save one once: `vidfarm add-provider-key pixabay <key>` (free key from <https://pixabay.com/api/docs/>), the Settings surface, or hand it to the desktop AI agent to run that command.
+- **minimize ($0 videos)** — a billed op is **refused** unless you add `--yes`; the error names the free local alternative (which now includes the matching `vidfarm media search` for music/SFX/image/video). Use this to guarantee no surprise AI spend. Before paying to generate music, sound effects, or images, try `vidfarm media search "<meaning>" --type <bgm|sfx|image|vector|icon|video>` first — free royalty-free assets instead of a billed `music`/`generate` call. **Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons) need no account at all**, so they always work in `minimize`. Photos/vectors/stock-video need a **free Pixabay key** that **may already be saved** — check `vidfarm provider-keys` (or web **Settings → Bring your own keys** / <https://vidfarm.cc/settings/developer>) before assuming a short result means "no key." If absent, save one once: `vidfarm add-provider-key pixabay <key>` (free key from <https://pixabay.com/api/docs/>), the Settings surface, or hand it to the desktop AI agent to run that command.
 - **minimize still gets CUSTOM images — via a free manual generator.** A refused `generate` is not the end of the road. Offer the user the manual loop (ask once, then make it the session default): **you write the prompt → they run it free in <https://meta.ai>, free-tier ChatGPT, or a free Hugging Face image Space (<https://huggingface.co/spaces>) → they hand the PNG back** via `vidfarm put-file ./sheet.png` or web **My Files**. Ask for **one sheet holding every graphic you need**, gridded on a **flat pure-green plate** (`#00FF00`), no text — one round trip instead of N, which saves the user's time and your tokens. Then split it locally for $0: `vidfarm mask ./sheet.png --crop x,y,w,h --flat "#00FF00" --out prop-a.png`, once per element (drop `--flat` and let local ONNX matting handle it if the tool ignored the green background). Full prompt template + loop: recipe `recipes/cutout-graphics-for-explainers.md` (“Free manual image-gen”).
-- **hybrid** *(default recommendation)* — billed ops run but print a one-line cost notice each.
-- **rich-ai** — billed ops run without gating; cost is still printed.
+- **hybrid (~$0.01–$1 per video)** *(default recommendation)* — billed ops run but print a one-line cost notice each, charged to the user's BYOK key.
+- **rich-ai ($1+ per video)** — billed ops run without gating; cost is still printed. AI *video* generation is the line item that pushes a video well past $1 — quote it before running.
 
 **Narration defaults to the FREE local voice in minimize AND hybrid.** A bare `vidfarm tts "…"` runs the keyless local Kokoro-82M engine in both of those modes — you no longer have to remember `--engine local`. A run **opts out** of that default by asking for a premium voice (`--style`, `--provider`, `--model`, `--own-key`, or a non-Kokoro `--voice` like `alloy`/`Kore`/an ElevenLabs id), by passing `--cloud`/`--engine byok`, or by being in `rich-ai`. If the local engine isn't installed on the machine (it needs `pip install kokoro-onnx soundfile` + a ~340MB model on first use), the run **falls back** to the user's provider key / cloud instead of failing — it prints the reason on stderr so you can tell the user why the voice changed.
 

package/SKILL.md

@@ -26,7 +26,15 @@ Default to the cheapest approach that works, and surface cost before any expensi
 
 ## Save the user money — ask their cost mode first
 
-Before spending any AI credits, ask which posture they want and explain each simply: **minimize** (cheapest — free local compute, no surprise AI spend), **hybrid** (recommended — free where free, pay AI only where it clearly wins), or **pure-ai** (best quality — AI media freely). With the devcli, persist it via `vidfarm cost-mode <choice>` (billed commands then respect it; `minimize` refuses billed ops without `--yes`). **Narration follows the mode automatically**: in `minimize` and `hybrid`, plain `vidfarm tts "…"` uses the free local Kokoro voice — ask for a premium voice explicitly (`--style`/`--voice`/`--provider`/`--cloud`) when the piece needs one, and tell the user which tier they're hearing. Then ask if they want it remembered across sessions — save to the agent's own memory (Claude Code → `CLAUDE.md`; Codex/OpenCode/others → `AGENTS.md`; or a note they name), asking first. In the **web app UI** there's no memory file to write, so just ask each time unless they state a standing preference. Full guidance is in the director skill.
+Before spending any AI credits, ask which posture they want and **quote the per-video cost**:
+
+| Mode | Cost per video | What it means |
+|---|---|---|
+| **minimize** | **$0 — explicitly free** | free local compute + free stock media; no AI spend at all |
+| **hybrid** *(recommended)* | **~$0.01–$1** | free where free, pay AI only where it clearly wins |
+| **rich-ai** *(stored as `pure-ai`)* | **$1+** | best quality; AI image/video/voice/music freely |
+
+**Those charges go to the user's own AI provider keys (BYOK)** — saved via `vidfarm add-provider-key <provider> <key>` or **Settings → Bring your own keys** (<https://vidfarm.cc/settings/developer>). The providers bill those keys directly; Vidfarm wallet credits only apply when the user deliberately runs on the platform key. That's why `minimize` is genuinely $0, not just cheap. With the devcli, persist it via `vidfarm cost-mode <choice>` (billed commands then respect it; `minimize` refuses billed ops without `--yes`). **Narration follows the mode automatically**: in `minimize` and `hybrid`, plain `vidfarm tts "…"` uses the free local Kokoro voice — ask for a premium voice explicitly (`--style`/`--voice`/`--provider`/`--cloud`) when the piece needs one, and tell the user which tier they're hearing. Then ask if they want it remembered across sessions — save to the agent's own memory (Claude Code → `CLAUDE.md`; Codex/OpenCode/others → `AGENTS.md`; or a note they name), asking first. In the **web app UI** there's no memory file to write, so just ask each time unless they state a standing preference. Full guidance is in the director skill.
 
 **Even in `minimize`, you can still get custom images — for free, manually.** When stock and masking existing art won't cover a bespoke graphic, don't say "not possible" and don't quietly spend: ask the user once whether to **default to free manual image generation**, then write the prompt and have them run it in <https://meta.ai>, free-tier ChatGPT, or a free Hugging Face image Space, and hand the PNG back (`vidfarm put-file`, or drag into My Files). Ask for **one image containing every graphic you need**, gridded on a **flat pure-green background** (`#00FF00`) with no text — one round trip instead of many, which is the token-efficient move. Then split it locally at $0: `vidfarm mask ./sheet.png --crop x,y,w,h --flat "#00FF00"` once per element gives you snug transparent stickers. Prompt template + full loop in the director skill.
 

package/dist/src/cli.js

@@ -79,7 +79,9 @@ Account (persisted login — points the CLI + \`serve\` at cloud prod):
   logout                    Clear the persisted credential
   whoami                    Show the logged-in account, host, plan, and cost mode
   cost-mode [mode]          Show or set the money-saving preference all billed
-                            commands respect: minimize | hybrid | rich-ai.
+                            commands respect, quoted per finished video:
+                            minimize = $0 · hybrid = ~$0.01-$1 · rich-ai = $1+.
+                            Spend is billed to YOUR AI provider keys (BYOK).
                             No arg = show current + explain the three simply.
                             --clear forgets it · --note "<why>" annotates the save.
                             Override per-run with --cost-mode <m> / VIDFARM_COST_MODE;
@@ -686,6 +688,9 @@ Cost spectrum (default to the cheapest approach that works; see SKILL.director.m
   $10+       Heavy AI generation (many/long AI clips, custom characters).
   Notes: image gen is cheap (use freely); AI VIDEO gen is expensive (ask the user
   first). Decompose is a one-time ~$0.10 — or skip it by forking a decomposed template.
+  Per-video budget by mode: minimize = $0 (explicitly free), hybrid = ~$0.01-$1,
+  rich-ai = $1+. All of it is billed to YOUR OWN AI provider keys (BYOK) — add them
+  with 'vidfarm add-provider-key <provider> <key>' or at vidfarm.cc/settings/developer.
   Set 'vidfarm cost-mode <minimize|hybrid|rich-ai>' once and every billed command
   (generate, music, decompose, cloud render/TTS/STT/greenscreen, create, replicate)
   respects it: minimize refuses billed spend without --yes and points you at the free

package/dist/src/devcli/cost-mode.js

@@ -5,12 +5,20 @@
 //
 // The mode is a single durable preference the human picks ONCE (ideally asked by
 // their AI agent up front), then every billed command respects it:
-//   - minimize : never burn AI credits by surprise. Prefer free local engines;
-//                refuse billed cloud/AI ops unless the user re-confirms (--yes).
-//   - hybrid   : free where it's free, spend on AI only where it clearly wins.
-//                (default recommendation.) Billed ops run but print a cost line.
-//   - pure-ai  : best-quality; AI image/video/voice/music used freely. Billed
-//                ops run; cost is still surfaced. Shown to humans as "rich-ai".
+//   - minimize : ~$0 per video. Never burn AI credits by surprise. Prefer free
+//                local engines; refuse billed cloud/AI ops unless the user
+//                re-confirms (--yes).
+//   - hybrid   : roughly $0.01–$1 per video. Free where it's free, spend on AI
+//                only where it clearly wins. (default recommendation.) Billed
+//                ops run but print a cost line.
+//   - pure-ai  : $1+ per video. Best-quality; AI image/video/voice/music used
+//                freely. Billed ops run; cost is still surfaced. Shown to
+//                humans as "rich-ai".
+//
+// Those dollar figures are what the AI providers charge, and they are billed to
+// the user's OWN provider keys (BYOK — the keys saved via `vidfarm
+// add-provider-key` / Settings → Bring your own keys), not to Vidfarm. Vidfarm
+// wallet credits are only used when the user explicitly runs on the platform key.
 //
 // This module lives in the CLI's static import closure and is BACKEND-FREE (only
 // Node built-ins) so it ships in the public cloud-only package.
@@ -101,18 +109,20 @@ export function resolveCostMode(values) {
     return { mode: DEFAULT_COST_MODE, isSet: false, source: "default" };
 }
 export const COST_MODE_BLURB = {
-    minimize: "Minimize costs — stay on FREE local compute wherever possible (local render, " +
+    minimize: "Minimize costs — explicitly $0 videos. Stay on FREE local compute wherever possible (local render, " +
         "local TTS/STT, local greenscreen/matting, reused clips + HTML motion). For assets, " +
         'reach for the free stock catalog first — vidfarm media search "<meaning>" --type ' +
         "bgm|sfx|image|vector|icon|video. Check the KEYLESS sources first: Openverse (CC/CC0 " +
         "music, SFX, images) and iconify (icons) need no account at all. A free Pixabay key adds " +
         "photos/vectors/stock-video and may already be saved (check vidfarm provider-keys). " +
         "Billed cloud/AI generation is refused unless you re-confirm it (--yes).",
-    hybrid: "Hybrid (recommended) — free where it's free, spend AI credits only where they " +
-        "clearly win (a hero shot, a voice you can't fake locally). Billed ops run but " +
-        "each prints its cost so nothing is a surprise.",
-    "pure-ai": "Rich AI — best quality; AI image/video/voice/music used freely. Billed ops run " +
-        "without gating; cost is still shown."
+    hybrid: "Hybrid (recommended) — roughly $0.01–$1 per video. Free where it's free, spend AI " +
+        "credits only where they clearly win (a hero shot, a voice you can't fake locally). " +
+        "Billed ops run but each prints its cost so nothing is a surprise. Charges land on " +
+        "your own AI provider keys (BYOK).",
+    "pure-ai": "Rich AI — $1+ per video. Best quality; AI image/video/voice/music used freely. " +
+        "Billed ops run without gating; cost is still shown. Charges land on your own AI " +
+        "provider keys (BYOK)."
 };
 /** One short human line summarizing the active mode. */
 export function costModeSummaryLine(resolved) {
@@ -122,10 +132,12 @@ export function costModeSummaryLine(resolved) {
 /** The 3-line "explain it simply" block an agent should relay to the user. */
 export function costModeExplainer() {
     return [
-        "How much do you want Vidfarm to spend on AI credits?",
-        "  • minimize — cheapest: free local compute + free stock media, no surprise AI spend.",
-        "  • hybrid   — recommended: free where free, pay AI only where it clearly wins.",
-        "  • rich-ai  — best quality: use AI image/video/voice/music freely.",
+        "How much do you want Vidfarm to spend on AI per video?",
+        "  • minimize — $0 videos: free local compute + free stock media, no AI spend at all.",
+        "  • hybrid   — ~$0.01–$1 per video (recommended): free where free, pay AI only where it clearly wins.",
+        "  • rich-ai  — $1+ per video: best quality, use AI image/video/voice/music freely.",
+        "Any spend is billed to YOUR own AI provider keys (BYOK) — add them with",
+        "  `vidfarm add-provider-key <provider> <key>` or at vidfarm.cc/settings/developer.",
         "Tip: before paying to generate music/SFX/images/video, try the free stock catalog —",
         '  vidfarm media search "<meaning>" --type bgm|sfx|image|vector|icon|video.',
         "  Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.24",
+  "version": "0.21.26",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {
@@ -66,7 +66,7 @@
     "node": ">=22.0.0"
   },
   "scripts": {
-    "postinstall": "patch-package || true",
+    "prepare": "patch-package || true",
     "dev": "tsx --import ./src/instrument.ts watch src/index.ts",
     "dev:frontend": "node scripts/build-homepage-client.mjs --watch",
     "dev:cli": "tsx src/cli.ts",