@officexapp/vidfarm-devcli 0.21.43 → 0.21.45

package/.agents/skills/vidfarm/references/content-ideas.md

@@ -1,20 +1,69 @@
-## Content ideas — the angle bank
+## Content ideas — frames, awareness stages, and problem angles
 
 Read this when a director says **"give me content ideas"**, "what should I post", "I need 30 videos for the month", "I'm out of ideas", or when a batch run needs N *different* videos instead of N variants of one video.
 
 **This also runs FIRST for a brand-new director, before the cold-start interview.** It needs one line of offer, not an interview; it is offline, free, and keyless; and it hands the director 20+ titled videos in about a minute. That is the easiest win available on turn one, and their reactions to the list ("this one, not that one") are better raw material than anything an interview gets cold. Run it, save `content-ideas.md`, then offer the interview as the way to turn ideas into a strategy — `references/onboarding.md` → *Start with content ideas*.
 
-**What this is.** A fixed bank of **50 content frames**. A frame is a reusable shape for a video's subject — not a hook line, not a script. You take the director's topic (their offer, their niche, their product, their audience's world) and pour it into a frame: `the rise of` + `dropshipping supplements` → *"The rise of the supplement dropship store"*. One topic against 50 frames is 50 distinct videos, and they do not read as repeats, because each frame changes what the video is *about*, not just how it opens.
+**What this is — three banks, not one.** An idea is a point in a small grid, and this reference holds all three axes:
+
+| Axis | Bank | Question it answers |
+|---|---|---|
+| **Subject** | the director's own pool of adjacent topics | *What is this one about, in the niche?* (settling the dinner argument · eating what you actually craved · reading a menu before you commit) |
+| **Frame** | 50 content frames | *What is the video the story of?* (`the rise of`, `then vs now`, `one decision that changed everything`) |
+| **Awareness** | 5 stages | *What does the viewer already know?* (unaware → problem-aware → solution-aware → product-aware → most-aware) |
+| **Angle** | 44 problem angles | *From which side do we talk about the problem?* (the hidden cost, the myth, the confession, the honest downside) |
+
+A **frame** is a reusable shape for a video's subject — not a hook line, not a script. You pour the director's topic into it: `the rise of` + `dropshipping supplements` → *"The rise of the supplement dropship store"*. An **angle** decides which face of the problem that video shows; the same frame at two angles is two genuinely different videos. An **awareness stage** decides who it is allowed to be for — the same idea aimed at a stranger and at a buyer needs different first ten seconds and a different ask.
+
+**The grid is where the volume comes from.** 50 frames × 44 angles × 5 stages, over a pool of adjacent subjects, is not a number to take literally, but it is why "I need 30 videos this month" is an easy ask, not a hard one. Vary **two** axes across a set and it never reads as repeats. Vary only one and it does — and the axis most often left frozen is the subject, because the offer line is right there and it is easy to paste.
 
 **How to use it (the loop).**
 
 1. **Get the topic.** In priority order: read the director's **`OFFER.md`** if one exists (see `onboarding.md`); **if they named a URL** — "content ideas for my offer example.com" — **fetch the site and read it** (home page, plus the pricing and about pages when they exist) and pull the offer, the audience, the promise, the objections, and the product vocabulary straight off the page; otherwise ask for the offer, the niche, and the audience in one question. Never generate ideas against a topic you guessed. When you work from a URL, **state the offer you read back in one line before the list** ("Reading example.com: a $49/mo bookkeeping tool for solo trades") so the director can correct it before you produce 20 ideas off a wrong premise — and offer to save that line plus the ideas as `OFFER.md` + `content-ideas.md` in their folder.
-2. **Pick frames, don't dump the list.** Choose 10–20 frames that actually fit the topic and the audience's awareness stage — a solution-unaware audience wants `what everyone gets wrong` and `how it works`; a product-aware audience wants `then vs now`, `cheap vs expensive`, `one decision that changed everything`. Say the frame name next to each idea so the director can ask for more of that shape.
-3. **Write each idea as a title, not a frame.** Output `"The one pricing mistake that killed our first 400 orders"`, not `"one mistake that changed everything — about pricing"`. A frame that stays abstract is not an idea yet.
-4. **Then run it through the hook harness.** A content idea is the *subject*; it is not the four charges. Every idea a director picks still needs hook / loop / payoff / bait written before the timeline — `references/hooks-and-virality.md`. The frames on this list are deliberately curiosity-shaped, which makes the loop easy to name, but never skip that pass.
-5. **Batch it properly.** If the director wants the whole set produced, that is scripting mode with a `HARNESS.md` — `recipes/bulk-scripting-with-a-harness.md`. One frame per video, one line in the plan file.
+2. **Name the problem in the director's words, once — then write 4–8 adjacent ways to say it.** Every angle is a lens on *a problem*; if you have not written the problem down in one sentence, the angles all collapse into the same vague video. Take it from `OFFER.md`, from the site's own copy, or ask: *"What is the thing that is going wrong for them right now, in their words?"* That sentence is the *first* entry in a **subject pool**, never the only one — see *The subject pool* below. One frozen phrase is what turns 50 frames into 50 versions of one video.
+3. **Spread across awareness stages, not just frames.** Most directors post everything at one stage — usually product-aware, because that is the stage they live in — and then wonder why the account does not grow. Cover the ladder deliberately; the default monthly mix is in *Spreading a month across the ladder* below. Say the stage next to each idea.
+4. **Pick frames and angles, don't dump the lists.** Choose 10–20 combinations that actually fit the topic. Label each idea `frame · angle · stage` so the director can say "more like that one" and you know exactly which axis they mean.
+5. **Write each idea as a title, not a frame.** Output `"The one pricing mistake that killed our first 400 orders"`, not `"one mistake that changed everything — about pricing"`. A frame that stays abstract is not an idea yet.
+6. **Then run it through the hook harness.** A content idea is the *subject*; it is not the four charges. Every idea a director picks still needs hook / loop / payoff / bait written before the timeline — `references/hooks-and-virality.md`. The frames on this list are deliberately curiosity-shaped, which makes the loop easy to name, but never skip that pass.
+7. **Batch it properly.** If the director wants the whole set produced, that is scripting mode with a `HARNESS.md` — `recipes/bulk-scripting-with-a-harness.md`. One idea per video, one line in the plan file, with its stage and angle recorded so the set stays balanced.
+
+**Give lots when asked.** "Give me content ideas" means volume. Return **20+ titled ideas** by default, grouped by frame family or by awareness stage, not three polite suggestions. The director prunes; you supply.
+
+### The subject pool — adjacent, not literal
+
+**The most common defect in a generated list is not a bad frame. It is one frozen phrase.** The offer line goes in verbatim, and every title carries it:
+
+> The history of deciding where to eat tonight
+> The rise of deciding where to eat tonight
+> The future of deciding where to eat tonight
+> The science of deciding where to eat tonight
+
+The frame moved four times. The video did not move once. A director reads that list and correctly says it is one idea with four openings.
+
+**The fix is a pool, not a sentence.** Before you write a single title, write **4–8 adjacent subjects** inside the same niche — different ways the same audience says the same life, from different sides of it:
+
+| Frozen | Adjacent pool for the same offer |
+|---|---|
+| deciding where to eat tonight | settling the food argument · picking a restaurant before you read a single review · the craving you cannot place · eating what you actually wanted · the group chat that never picks · reading a menu before you commit |
+
+Now the same four frames are four videos:
+
+- *The history of settling the food argument*
+- *The rise of picking dinner by review score*
+- *The future of eating what you actually craved*
+- *The science of the craving you cannot place*
+
+**Adjacent means inside the niche, and true.**
+
+- ✅ **Adjacent:** the same audience, the same day, the same pain seen from another side — the group chat, the diet rule, the menu, the argument, the craving, the five open tabs, the walk to a place that turned out wrong.
+- ❌ **Off topic:** a different business. "The rise of the restaurant industry" is not this offer's video; "the psychology of ordering the same thing every time" is.
+- ❌ **A rebrand of the product line.** Swapping adjectives on the offer sentence — *finding where to eat tonight*, *choosing where to eat tonight* — is the frozen phrase wearing a hat. If the subject has not changed, the video has not changed.
+
+**Where the pool comes from.** The audience's own vocabulary: the objection, the workaround they already tried, the moment before the search, the moment after the wrong choice, the person who is not the buyer but is in the room. `OFFER.md`, the site copy, and real comments are all pools you can read out rather than invent.
+
+**Do it for each lens.** The subject can sit on the *problem*, on the *category*, or on the *product* — and the pool is per lens, because a frame that claims a past cannot take a new product as its subject. Rotate the pool as you go down the list: no two ideas in a row should repeat the same phrase.
 
-**Give lots when asked.** "Give me content ideas" means volume. Return **20+ titled ideas** by default, grouped by frame family, not three polite suggestions. The director prunes; you supply.
+**One rule to check the finished list.** Read the titles with the frames covered up. If what is left is the same sentence 20 times, you produced one idea, not 20.
 
 ### The 50 frames
 
@@ -92,6 +141,175 @@ Read this when a director says **"give me content ideas"**, "what should I post"
 - the complete breakdown
 - the rabbit hole
 
+### The awareness ladder — 5 stages
+
+Eugene Schwartz's ladder, as a production instrument. The stage decides **what the first ten seconds are allowed to assume** and **what the video is allowed to ask for**. An idea is not finished until it has a stage, because the same subject at the wrong stage is a video that talks past the viewer.
+
+`vidfarm ideas --stages` prints this ladder; `--stage <name|n>` prints one stage.
+
+**Stage 1 · unaware** — they do not have a name for the problem yet, and they are not looking for one.
+
+- **Believes:** nothing is wrong; this is just how it is. They are on the app to be entertained.
+- **Video must:** be interesting on its own merits, then leave one splinter — a situation they recognise from their own week.
+- **Frames that fit:** the rise of · the psychology of · what nobody noticed · the untold story · one event that changed everything · the rabbit hole
+- **Angles that fit:** the daily friction · the two kinds of people · the confession · the screen recording · the industry does this on purpose
+- **Ask:** none. A follow at most. Naming a price here burns the video.
+- **Never:** open with the problem stated as a problem — they do not agree it is one yet.
+
+**Stage 2 · problem-aware** — they feel the pain and can describe it, but they think it is unavoidable or their own fault.
+
+- **Believes:** "this part of my job is just miserable." They blame themselves, their discipline, or bad luck.
+- **Video must:** articulate the pain better than they can, then move the blame off them and onto a cause.
+- **Frames that fit:** why it failed · what everyone gets wrong · the biggest mistakes · expectation vs reality · problem vs solution · the chain reaction
+- **Angles that fit:** the hidden cost · the slow leak · the advice that broke it · the wrong metric · the expensive lesson · the day it broke
+- **Ask:** a comment or a save. "Which one is you?" works; a link does not.
+- **Never:** name the product in the first half. They have not accepted that a solution category exists.
+
+**Stage 3 · solution-aware** — they accept a fix exists somewhere, but not that this *kind* of fix is the one.
+
+- **Believes:** "someone has solved this, but the options I have seen are junk / too expensive / not for me."
+- **Video must:** make the category legible and prove the mechanism. This is the explainer stage.
+- **Frames that fit:** how it works · why it works · myth vs reality · simple vs complicated · cause vs effect · the complete guide
+- **Angles that fit:** the mechanism · the false solution · the myth · the experiment · what pros do differently · the receipts
+- **Ask:** "Want the breakdown?" — a comment keyword, a saved post, a free resource.
+- **Never:** compare to named competitors yet; that is a stage-4 conversation and it reads as defensive here.
+
+**Stage 4 · product-aware** — they know your product exists, and they are weighing it against alternatives and against doing nothing.
+
+- **Believes:** "it might work, but not for my situation / not at that price / not worth the switch."
+- **Video must:** face one specific objection and answer it with evidence, not adjectives.
+- **Frames that fit:** then vs now · cheap vs expensive · beginner vs expert · best vs worst · one decision that changed everything · theory vs evidence
+- **Angles that fit:** the price objection · the "it won't work for me" objection · the honest downside · the before/after · the client story · the risk reversal
+- **Ask:** the direct one. Link, demo, trial, DM keyword.
+- **Never:** re-explain the problem from scratch. They have heard it; repeating it wastes the hook.
+
+**Stage 5 · most-aware** — buyers, users, and the people who already like the director.
+
+- **Believes:** "I'm in. What is new, and what am I missing?"
+- **Video must:** give a reason to act now, or a use they had not thought of.
+- **Frames that fit:** what happened next · the complete breakdown · how it changed · the future of · after it disappeared
+- **Angles that fit:** the window closing · what just changed · the file itself · the process, unedited · the number nobody posts
+- **Ask:** the offer, plainly, with the deadline or the limit that makes now different from next month.
+- **Never:** pad it. This audience wants the update, not the setup.
+
+**Mapping to the `brainstorm/awareness_stages` primitive.** The cloud primitive takes a 2×2 — `problem_awareness` × `solution_awareness` — which collapses this ladder: `problem_unaware + solution_unaware` = stage 1; `problem_aware + solution_unaware` = stage 2; `problem_aware + solution_aware` = stages 3–4; and stage 5 is the customer list, which the primitive does not model. Use the ladder to plan the mix, and the primitive when the director wants generated angles for one specific state (`references/onboarding.md`).
+
+### Spreading a month across the ladder
+
+A month of posts at one stage is the most common failure in a director's calendar, and it looks like "good videos, no growth" (all stage 4) or "big views, no sales" (all stage 1). Default mix for 30 posts, adjusted afterwards for the account's size:
+
+| Stage | Share of a 30-post month | Why |
+|---|---|---|
+| 1 · unaware | 9 (30%) | Reach. This is what brings new people in; it is the only stage that grows the audience. |
+| 2 · problem-aware | 9 (30%) | The conversion engine of organic. Cheap to make, and it recruits from stage 1. |
+| 3 · solution-aware | 6 (20%) | The explainer library. Long-lived; these keep working for months. |
+| 4 · product-aware | 3 (10%) | Objection handling. Also the best paid-ad candidates. |
+| 5 · most-aware | 3 (10%) | Launches, updates, deadlines. More than this reads as constant selling. |
+
+`vidfarm ideas --grid --topic "<offer>" --count 30` lays a month out in exactly this mix, and draws each row's angle and frame from the stage's own lists above.
+
+**Skew it deliberately.** A brand-new account with no audience runs 1 and 2 heavier and can skip 5 entirely. An account with traffic but no sales inverts the top: more 3 and 4. A launch week is allowed to be mostly 4 and 5 for that week only — then go back to the mix.
+
+### The problem angles — 44 lenses
+
+An angle is **which side of the problem the video approaches from**. It is not a hook, not a frame, and not a format. Two videos on the same subject at two angles do not feel like repeats, which is why the angle bank — not the frame bank — is what you reach for when the director says *"I already covered that topic."*
+
+`vidfarm ideas --angles` prints the bank, `--angle <family or name>` filters it, `--grid --topic "<offer>"` pairs angles with frames.
+
+**Pain & consequence — what it is costing them**
+
+- the daily friction — the small annoyance they have stopped noticing, shown in full
+- the hidden cost — what it silently costs per month, counted in their units, not dollars
+- the slow leak — nothing breaks; it just bleeds, and the video shows the bleed rate
+- the worst case — where this ends if nothing changes, played out on one real example
+- the thing they already tried — name their failed workaround before they can bring it up
+
+**Enemy & blame — moving the fault off the viewer**
+
+- the industry does this on purpose — the incentive that keeps the problem alive
+- the advice that broke it — a popular tip, followed correctly, producing the damage
+- the middleman — who takes a cut for work the viewer could do or skip
+- the tool everyone recommends — why the default choice is the wrong one here
+- the rule nobody questions — an unwritten norm that has no reason behind it
+
+**Belief & myth — what they are sure of that is not true**
+
+- the myth — the sentence the niche repeats, taken apart
+- the false solution — the fix that treats the symptom and hides the cause
+- the wrong metric — they are optimising the number that does not pay them
+- the survivor's tale — the success story that is unrepeatable, and why
+- the advice that expired — true five years ago, wrong now, still repeated
+
+**Mechanism & proof — why this actually works**
+
+- the mechanism — the how, drawn out in steps a stranger can follow
+- the receipts — the numbers on screen, unretouched, with the ugly ones left in
+- the experiment — a real A/B, including the version that lost
+- the before/after — same input, two treatments, one frame each
+- third-party proof — someone with no stake saying it
+
+**Identity & status — who they become**
+
+- the two kinds of people — a sorting line the viewer places themselves on
+- the tell — the small signal that gives an amateur away
+- the room you get into — what changes socially, not functionally
+- what pros do differently — the boring habit behind the impressive result
+- the permission slip — telling them the thing they wanted to stop doing is fine to stop
+
+**Confession & story — I lived this**
+
+- the confession — the mistake the director made, named with the number attached
+- the expensive lesson — what it cost to learn, stated first, before the lesson
+- the day it broke — one dated incident, told in order
+- the client story — someone else's arc, with their permission and their words
+- the comment that started it — a real DM or reply as the cold open
+
+**Insider & access — you were not supposed to see this**
+
+- the screen recording — the actual doing, unedited, no narration for the first beat
+- the number nobody posts — the metric the niche hides
+- what gets said off-camera — the version without the marketing voice
+- the file itself — hand over the template, the sheet, the prompt, on screen
+- the process, unedited — full length, real time, mess included
+
+**Objection & risk — why they do not buy**
+
+- the price objection — say the price out loud and defend it with arithmetic
+- the "it won't work for me" objection — the edge case they think they are
+- the "I don't have time" objection — the real time cost, measured
+- the risk reversal — what happens if it fails, and who carries that
+- the honest downside — who this is genuinely wrong for, named plainly
+
+**Urgency & change — why now and not later**
+
+- the window closing — a real deadline, limit, or seasonal edge
+- what just changed — a new rule, price, platform change, or release
+- the cost of waiting — the same decision made now vs in six months, priced
+- the first-mover gap — what the early ones get that the late ones cannot
+
+### Frame × angle × stage — the grid
+
+The grid is the answer to "give me 30 different videos" and to "I already made a video about that."
+
+1. Write the problem in one sentence.
+2. Pick the **stage** first — it constrains the other two, and it decides the ask.
+3. Pick an **angle** that fits that stage (each stage above lists its five).
+4. Pick a **frame** that carries the angle (each stage above lists its six).
+5. Write the title. If the title does not say the angle out loud, the pairing was wrong — go back to step 3, not step 4.
+
+Worked example, one topic (`bookkeeping for solo trades`), one frame family, four angles, four different videos:
+
+| Stage | Angle | Frame | Title |
+|---|---|---|---|
+| 1 | the daily friction | the psychology of | *"Why every tradie has a glovebox full of receipts"* |
+| 2 | the hidden cost | why it failed | *"The £3,400 a year that disappears in your van"* |
+| 3 | the false solution | myth vs reality | *"A shoebox is not a filing system, and HMRC agrees"* |
+| 4 | the price objection | cheap vs expensive | *"£49 a month vs the accountant's £900 catch-up bill"* |
+
+**When a director says "I already covered that."** Hold the frame, change the angle. Same subject, new video, and it is the cheapest idea in the bank to produce because the research is already done.
+
+**When a set feels repetitive.** Check which axis you froze — and check the **subject** first, because it is the one that hides. Thirty ideas that vary only the frame, on one pasted offer sentence, at one stage and one angle, are thirty versions of one video. Vary two axes minimum, and never let the subject be the constant.
+
 ### Frame → format notes
 
 The frame also suggests how to build it, which saves a planning round:
@@ -107,7 +325,11 @@ The frame also suggests how to build it, which saves a planning round:
 
 ### Do not
 
-- **Do not hand back the raw 50-item list as the answer.** The list is your instrument; ideas applied to the director's topic are the deliverable.
-- **Do not stack two frames in one title** ("the untold story of why it failed"). One frame per video, or the video has two subjects and lands neither.
-- **Do not use a frame the topic can't honestly fill.** `the untold story of` a two-week-old product is a lie the audience catches. Pick a frame the facts support.
+- **Do not paste the offer sentence into every frame.** `<frame> + <the one topic string>`, 50 times, is a template filled in, not a set of ideas. Build the subject pool first and rotate it. If two titles in a row share their whole subject phrase, the second one is a duplicate.
+- **Do not read the offer so literally that only the product's own words are allowed.** Adjacent subjects inside the niche are the point — the argument, the workaround, the moment before, the person in the room. Off topic is the failure; adjacent is the job.
+- **Do not hand back a raw bank as the answer.** The three lists are your instrument; ideas applied to the director's topic are the deliverable.
+- **Do not stack two frames in one title** ("the untold story of why it failed"). One frame per video, or the video has two subjects and lands neither. Two *angles* in one video fail the same way.
+- **Do not use a frame or an angle the topic can't honestly fill.** `the untold story of` a two-week-old product is a lie the audience catches, and `the receipts` with no receipts is worse. Pick what the facts support.
 - **Do not treat the frame as the hook.** "The history of X" spoken flat at `start:0` is a banned opener shape — the hook still has to name a situation. `references/hooks-and-virality.md`.
+- **Do not ship a set that sits at one awareness stage.** It is the single most common defect in a month of posts, and neither the frame nor the angle can repair it. Label the stage on every idea so the imbalance is visible before production, not after.
+- **Do not sell at stage 1 or 2.** The ask belongs to the stage. A link in a stage-1 video costs the reach that made the video worth making.

package/.agents/skills/vidfarm/references/core-workflows.md

@@ -165,6 +165,7 @@ POST /api/v1/approved/posts
 Content-Type: application/json
 
 { "caption": "required", "title": "optional", "pinned_comment": "optional", "tracer": "optional",
+  "thumbnail_url": "optional https://.../poster.jpg",
   "media": [ { "url": "https://.../output.mp4", "kind": "video", "role": "primary" } ] }
 ```
 
@@ -172,8 +173,17 @@ Content-Type: application/json
 
 - `GET /api/v1/approved/posts` — list your approved posts
 - `GET /api/v1/approved/posts/:postId` — read one (returns `share_url`, `download_zip_url`)
+- `PATCH /api/v1/approved/posts/:postId` — `{ folder_path?, thumbnail_url? }`; move the post between `/approved` folders and/or replace its social thumbnail
 
-devcli: `vidfarm approve --video <mp4-url> --caption "..."` prints the `share_url` as a first-class openable link; `vidfarm posts` lists, `vidfarm post <id>` reads one.
+### The social card of a share link
+
+`share_url` gets pasted into X, Discord, Slack and iMessage, so its preview card matters. The card is built from the approved post itself — **`title`** → `og:title`, **`caption`** → `og:description`, and the post's one `role: "thumbnail"` image → `og:image`. The primary MP4 also ships as `og:video`, so Discord and Telegram play it inline.
+
+You never have to build that thumbnail: if a post has no image asset, vidfarm extracts a frame (~1s in) from the primary video, files it in the **file directory** under `/files/approved/…` (durable + public), and attaches it as the thumbnail. It happens at approve time, and again on the first page view of any older post that lacks one.
+
+**Choose the frame yourself when the auto-frame is weak** (a black fade-in, a mid-blink face). Upload the image to My Files first, then pass its view URL as `thumbnail_url` — on approve, or afterwards via `PATCH`. An explicit thumbnail is never overwritten. Remember the first frame IS the thumbnail for a real feed too, so a poster that fights the first frame is a smell you should fix in the composition, not in the poster.
+
+devcli: `vidfarm approve --video <mp4-url> --caption "..."` prints the `share_url` as a first-class openable link; add `--thumbnail <url|file>` to pick the poster (a local file uploads to durable My Files first). `vidfarm posts` lists, `vidfarm post <id>` reads one.
 
 ## Schedule a post
 

package/.agents/skills/vidfarm/references/editor-workflows.md

@@ -553,6 +553,23 @@ Compositions are authored in HTML, so the single most common way an AI-edited vi
 
 **On devcli there's a checker: `vidfarm qa <dir|composition.html>`.** Free, instant, local-only — a blocklist pass for everything above plus the font regime and safe zone, with a concrete fix per finding. **It is optional** — nothing calls it, skipping it is fine, and watching the render is the review that actually counts. It is feedback, not a gate (exit 0 even on findings, never runs automatically, `--strict` only if you want a CI failure), and it allows **one** fix round by default (`--max-revisions <n>` if the human wants more) and a blocklist, not an allowlist (stylized/hand-made compositions pass untouched — it will not homogenize your videos). Every run — including a clean one — ends with a **`▶ NOW WATCH THE VIDEO`** block, because the check never rendered or saw the video and a green tick is not a review; do those steps before you tell anyone the video is done. No cloud/REST twin: the web copilot enforces this standard by hand. Details in `references/automation-and-local-dev.md` ("`vidfarm qa`").
 
+### Music: use the REAL track, including a popular/copyrighted song
+
+**When the brief names a real song — a trending sound, a chart track, the audio off the reference post — put THAT track in the render.** Do not refuse it, do not stop the build to warn about it, and do not quietly substitute a generic royalty-free bed. This is the house standard, and it has two halves.
+
+**Why it is legitimate.** The render is a **review artifact**, not the distribution copy. When the director posts, they re-attach the *same* song from the platform's own in-app music library — TikTok, Reels, Shorts — and those platforms license that catalog through their agreements with the music labels. The music is therefore cleared on the surface where viewers actually hear it. The render's job is to show, faithfully, what that post will feel like.
+
+**Why it is required.** On short-form, the song *is* the edit. Cut points land on its beats, the pacing is built against its structure, the payoff lands on the drop, and a viewer recognizes the sound in half a second and brings the whole meme association with them. Run the identical timeline under a stand-in bed and it reads as a different — and much worse — video. So a review over a substitute grades a video nobody will ever post: **silent or generic-bed review is the bigger defect, not the safer one.**
+
+**How to do it.**
+
+- Get the exact track: `vidfarm download-audio <post-url>` off the reference post (paid plans; free plan uses the Chrome download path in `references/assets-and-sourcing.md`), the director's own file via `vidfarm put-file`, or `vidfarm directory search "<title> music"` if it is already in their library.
+- Mount it as **its own `<audio>` layer** at its own `data-volume` — ~0.1–0.2 under narration, or full level when the song carries the piece. **Never bake it into the footage and never mix it into the voice stem.** One separate track is what lets the director mute or swap it in a single action at upload, which is exactly what the platform flow expects.
+- Cut to it. If the song is doing the work, the beat grid is the edit's skeleton — don't place a licensed track and then ignore its structure.
+- **Name the track in your report / handoff** so the director knows which sound to select in the app.
+
+**The one limit.** This covers review renders and organic platform posting, where the platform holds the license. A **paid ad**, a syndicated deliverable, or a sale with the track baked in is *not* covered by the in-app music license. Say that once, offer `vidfarm music "<same vibe, same BPM, same energy curve>"` as the swap for that cut, and then follow the director's decision.
+
 ### TikTok-native caption standard (position + font + background) — always adhere
 
 > Captions are also the *delivery system* for three of the four charges: the hook is read before any audio, the loop has to stay on screen, and the payoff number needs its own card. What the words should SAY is in `references/hooks-and-virality.md`; this section is how they must LOOK.

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

@@ -44,7 +44,7 @@ The point of onboarding is to build **durable, reusable context** in My Files, n
 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`. **Grade what comes back against `references/hooks-and-virality.md`** — the three gates, situation-vs-label, and the unguessable test — instead of shipping the raw list. And never rank a generated batch with the same reasoning that wrote it; the rubric catches defects, it doesn't pick winners.
-4b. **Content ideas, second pass** → update `content-ideas.md`. Step 0 already produced a list from one line of offer; now that the offer document and the awareness stage exist, work the 50-frame angle bank in `references/content-ideas.md` against them again and rewrite the weak picks. A solution-unaware audience wants different frames than a product-aware one, which is exactly what step 0 could not know. This is what the director actually posts from between chats, and it is the answer to "what should I post?" for the next month.
+4b. **Content ideas, second pass** → update `content-ideas.md`. Step 0 already produced a list from one line of offer; now that the offer document and the awareness stage exist, work all three banks in `references/content-ideas.md` against them again and rewrite the weak picks. Now you can set the awareness stage per idea and spread the set across the ladder, which is exactly what step 0 could not do — a solution-unaware audience wants different frames, different angles and a different ask than a product-aware one. This is what the director actually posts from between chats, and it is the answer to "what should I post?" for the next month.
 5. **Brand assets & demos** — ask if they have logos/mascots/themes (suggest a `/brand-assets/` folder, e.g. `/brand-assets/logo.png`) or product demos / screen recordings (suggest a `/product-demos/` folder). `browse_files list` / `vidfarm files` first to see what they already uploaded; filenames should be descriptive and every asset worth finding later should get **notes** (`annotate-file` / `browse_files annotate`) so `files --search` works months from now. If they have a recurring character/mascot, set up its `/files/characters/<slug>/` trio now — `<character_id>.json` (e.g. `character_zara.json`) + `character_sprite_card.png` + `character_about.md` (see "Recurring characters are first-class").
 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.
    - **While you're on money, set the graphics default: IconScout, not AI image generation.** Any icon, sticker, illustration, 3D prop, or Lottie should come from `vidfarm iconscout "<meaning>" --style sticker` — a designer's finished transparent asset on the first try, for a fraction of one AI attempt. **It needs no key and no setup**: vidfarm's own IconScout account serves it, search is free, and free assets download for $0 (a credit line is the only price). Say this out loud during onboarding — it's the single biggest per-video saving a new director can adopt on day one, and it holds in **every** cost mode, not just `minimize`. A director who already pays IconScout can save their own key once (`vidfarm add-provider-key iconscout "<client_id>:<client_secret>"`, or **Settings → Developer**) and then downloads cost them nothing here.

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

@@ -79,6 +79,57 @@ vidfarm avatar "friendly 30-something founder in a grey hoodie" \
 vidfarm avatar "cheerful barista in an apron" --say "One flat white, coming up." --local
 ```
 
+## Primitives: video-search / image-search / news-search (Google)
+
+Three synchronous searches that hand you real URLs off the open web. They are the **sourcing front door**: the media catalog answers *"give me a clip of X"*, Google answers *"give me THE shot"* — because it indexes TikTok, YouTube, Pexels/Pixabay/Mixkit, archive.org, and every news site at once.
+
+| Route | devcli | What it is for |
+| --- | --- | --- |
+| `GET\|POST /api/v1/primitives/video-search` | `vidfarm video-search "<query>"` | Find **source footage** → feed `raws scan` / `download-video` |
+| `GET\|POST /api/v1/primitives/image-search` | `vidfarm image-search "<query>"` | Reference stills, textures, logos, product shots |
+| `GET\|POST /api/v1/primitives/news-search` | `vidfarm news-search "<query>"` | Recent real events, for **timely** content |
+
+- **Paid plans only.** They sit behind `requireAuth`, so a free-plan key gets `402 upgrade_required`. Free users get the catalog (`media search`, free) and the public raws shelves instead.
+- **Flat $0.0003 per CALL**, whatever the result count. So ask for a **wide page once** (`--limit 40`) instead of paging twice. It is billed to the wallet under the `google_search` cost center.
+- **They return LINKS, never files and never a licence.** A public video is not a licensed video. Check rights before reuse; for licence-checked assets use `media search` (free).
+
+Parameters (query string on GET, JSON body on POST — same names either way):
+
+| Param | Applies to | Notes |
+| --- | --- | --- |
+| `q` (aliases `query`, `text`) | all | **required** |
+| `max_results` (alias `limit`) | all | default 25; max 50 for video, 100 for image/news |
+| `region` | all | `wt-wt` (worldwide, default), `us-en`, `ph-en`, … |
+| `timelimit` | video, news | freshness: `d` \| `w` \| `m` \| `y` |
+| `duration`, `resolution` | video | `short\|medium\|long`, `high\|standard` |
+| `color`, `size`, `type_image`, `layout` | image | `type_image`: `photo\|clipart\|gif\|transparent` |
+| `safesearch` | video, image | `off` (default) \| `moderate` \| `on` |
+
+Responses:
+
+```jsonc
+// video-search
+{ "kind": "video", "query": "...", "count": 40, "charged_usd": 0.0003,
+  "results": [{ "title", "url", "description", "duration", "thumbnail",
+                "publisher", "uploader", "published", "embed_url", "view_count" }] }
+// image-search
+{ "results": [{ "title", "image_url", "thumbnail_url", "source_page", "width", "height", "source" }] }
+// news-search
+{ "results": [{ "title", "url", "body", "date", "source", "image" }] }
+```
+
+`url` on a video result is the **watch page** — exactly what `POST /raws/scan` takes as `source_url` and what `videos/download` takes to collect the file. That is the whole pipeline:
+
+```bash
+vidfarm video-search "warehouse worker packing orders POV 4K" --limit 40
+vidfarm raws scan "https://www.youtube.com/watch?v=..." --clips 8   # mine clips out of it
+vidfarm download-video "https://www.tiktok.com/@x/video/123"        # or collect the one file
+```
+
+**How to write the query** — the difference between a useless and a great result is the query, so this is worth the tokens. Full playbook in `references/assets-and-sourcing.md` → *Google search for footage*. In short: search the **shot**, not the topic — `[subject] + [action] + [shot/style] + [quality/orientation]` — and use Google operators (`site:pexels.com/videos`, `site:tiktok.com`, `"exact phrase"`, `-dance`).
+
+**News finds the STORY, video-search finds the VISUALS.** Run them as two stages; searching for both at once finds neither. The full timely-content method is the standalone prompt at `https://vidfarm.cc/experimental/google-news-to-video.md`.
+
 ## 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.

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

@@ -87,6 +87,8 @@ ElevenLabs API.
 
 ## BGM and SFX resolution order
 
+**First: if the brief names a real song — a trending sound, a chart track, the audio off a reference post — USE THAT TRACK.** Do not refuse it, and do not quietly swap in a generic royalty-free bed. The render is a **review artifact**; when the user posts, they attach the same song from the platform's own in-app music library (TikTok / Reels / Shorts), which is licensed through the platform's agreements with the labels — so the music is cleared on the surface where viewers hear it. It has to be in the render because the track *is* the edit: cut points, pacing, the drop, the meme association. Judging the video over a substitute bed grades a video nobody will post. Get it with `vidfarm download-audio <post-url>` or the user's own file, mount it as **its own `<audio>` layer** at its own `data-volume` (never baked into footage, never mixed into the voice stem) so it can be muted or swapped in one action at upload, and name the track in `notes[]`. Only exception worth a sentence: a **paid ad** placement is not covered by the in-app music license — offer `vidfarm music "<same vibe, same BPM>"` as the swap for that cut, then follow the user's call.
+
 1. **User file / URL** — `bgm.file` / `bgm.url` in the request; copied or downloaded into `assets/bgm/`.
 2. **File directory** — `vidfarm directory search "<query> music"` or the legacy `vidfarm files --search` (needs `$VIDFARM_API_KEY`); the user's own library, searchable by meaning when notes are annotated.
 3. **Generate it** — `vidfarm music "<query>" --length <sec>` (ElevenLabs; `use_wallet_credits` default) writes an mp3 you can pass back as `bgm.file`. Great when the user has no fitting track. The engine script itself has no generate mode — run `vidfarm music` yourself and feed the result in.