@officexapp/vidfarm-devcli 0.21.45 → 0.21.46

package/.agents/skills/vidfarm/references/browser-harness.md

@@ -0,0 +1,93 @@
+## Free browser sourcing — drive the user's own Chrome instead of paying
+
+The sourcing ladder starts at *"your own browser control, if you have it."* **browser-harness is how you have it.** It attaches you to the user's already-running Chrome over one CDP websocket, so you can search, scroll, click and download on their own logged-in session and their own IP — at **$0**, with no Vidfarm plan, no API key, and no wallet.
+
+That matters because the four routes an agent reaches for when sourcing footage are all **paid plans only**. A free-tier director asking the single most common question in the product — *"find me a clip of X"* — otherwise gets a 402. With browser-harness they get footage.
+
+| Paid Vidfarm primitive | Free browser substitute | What you lose |
+|---|---|---|
+| `vidfarm video-search "<shot>"` ($0.0003/call) | `vidfarm browse videos "<shot>"` → Google Videos | You read the SERP yourself; no ranked JSON |
+| `vidfarm image-search "<shot>"` ($0.0003/call) | `vidfarm browse images "<shot>"` → Google Images | Full-res URLs need a click-through per result |
+| `vidfarm news-search "<topic>" --fresh w` ($0.0003/call) | `vidfarm browse news "<topic>"` → Google News | No `--fresh` operator; use Google's own Tools → time filter |
+| `vidfarm download-video <url>` (wallet resolver) | `vidfarm browse page "<url>"` → save the media off the page | Manual per URL; but a logged-in session reaches posts an anonymous resolver cannot |
+| `vidfarm recycle <reddit/x url>` | browse the thread and read it | No structured comment tree — you extract by hand |
+
+**Say the trade honestly.** The paid primitives return clean ranked JSON in one call and are genuinely cheap — two orders of magnitude under one AI image attempt. Browser sourcing costs no money and more of your turns. In `minimize` it is the right call every time. In `hybrid` prefer it for a wide first sweep and pay for the primitive when you need many precise results fast. In `rich-ai` / `pure-videogen` don't bother — the spend is already authorized and your turns are worth more.
+
+### Setup — one command
+
+```bash
+vidfarm browser setup        # installs browser-harness via uv, registers its skill, prints the Chrome step
+vidfarm browser status       # what's installed
+vidfarm browser doctor       # connection check (wraps `browser-harness --doctor`)
+```
+
+`setup` does three things and then stops at the one it cannot do for the user:
+
+1. `uv tool install --python 3.12 --upgrade --force browser-harness` (it prints the `uv` installer first if `uv` is missing).
+2. Writes `browser-harness`'s own SKILL.md into `.agents/skills/browser-harness/SKILL.md` beside the vidfarm pack — **read that file before your first browse**; it carries the accessibility-tree-first workflow, tab handling, downloads, iframes and the CDP escape hatch. This page is the Vidfarm-side routing, not a replacement for it.
+3. Prints the **one manual step**: Chrome → `chrome://inspect/#remote-debugging` → tick *"Allow remote debugging for this browser instance"*. Nothing can do this for the user. On macOS a per-connection permission sheet may follow — `browser-harness mac-approve` clears it.
+
+`vidfarm doctor` reports it as `browser control`, at `⚠` when absent. It is optional: a box without it is a healthy box, just a more expensive one.
+
+**Proactively offer it to every free-plan user.** Before you tell someone the search primitive needs a paid plan, offer the setup — it is about a minute, it is free forever, and it converts "I can't source that" into "I found six candidates." Same for anyone in cost mode `minimize`. Do not install it silently: it drives their personal browser, so ask first and say what it does.
+
+### The browse recipes
+
+`vidfarm browse <videos|images|news|page> "<query|url>"` prints the recipe for one sourcing job — the Google surface to open, the extraction to run, and the vidfarm command it feeds:
+
+```bash
+vidfarm browse videos "warehouse worker packing orders POV 4K"
+vidfarm browse images "manila street market wide shot"
+vidfarm browse news   "AI startup funding announced"
+vidfarm browse page   "https://www.tiktok.com/@user/video/123…"
+vidfarm browse videos "…" --run     # pipe it straight into browser-harness instead of printing
+vidfarm browse videos "…" --json    # the same recipe as data
+```
+
+Default is **print, not run** — deliberately. Google's markup moves, and an agent that reads the recipe and adapts it beats one that runs it blind. Reach for `--run` when you have already browsed successfully this session.
+
+**Query craft carries more weight here than anywhere else in the pack** — Google is the ranking function now, not Vidfarm. Use the shot formula (`[subject] + [action] + [shot/style] + [quality/orientation]`), the `site:` aims at Pexels / Pixabay / Mixkit / archive.org / Wikimedia, and the Creative-Commons YouTube operators. All of that is in `references/assets-and-sourcing.md` → *Google search for footage*; it applies unchanged whether you paid for the search or browsed it.
+
+Surface parameters: the recipes use Google's current `udm=` (`2` images, `7` videos, `12` news). If a surface comes back looking wrong, rerun with `--legacy` for the older `tbm=isch|vid|nws`.
+
+### Collecting raws with it — the loop that matters
+
+Browser sourcing is at its best on a **raws collection pass**, not on a single lookup. You are filling a shot pool, so batch it:
+
+```bash
+# 1. plan the shot list first (see "Phase 0" in SKILL.md) — never browse without one
+vidfarm storyboard ./work --init --frames "Hook,Problem,Reveal,CTA"
+
+# 2. one browse per SHOT, not per video
+vidfarm browse videos "founder frustrated at desk vertical raw footage"
+
+# 3. mine each good hit into short tagged raws — free, local
+vidfarm raws scan "<result url>" --duration 10 --aspect 9:16 --no-text --prompt "<the beat this covers>"
+vidfarm clipper  "<result url>" --start 00:01:12 --end 00:01:19   # or one surgical cut
+
+# 4. everything lands in the searchable local library, reusable across every later video
+vidfarm raws search "founder looking defeated"
+```
+
+If `raws scan` cannot bootstrap a remote URL without a key, that is exactly the gap browser control fills: save the file from the page in Chrome, then `vidfarm clipper ./saved.mp4` or `vidfarm put-file ./saved.mp4`.
+
+**Check the free catalog before you browse at all.** `vidfarm public-raws --categories` and `vidfarm media search "<meaning>"` and `vidfarm iconscout "<meaning>" --free` cost nothing and cost no turns either. Browsing is rung 1 of the ladder, but the free shelves are rung 0.
+
+### Interactive mode — hand Chrome to the human instead
+
+In `interactive` mode you have a better option than driving the browser yourself: **tell the user to drive it.** A person scrubbing a TikTok search picks better footage than any keyword extraction, and it costs them two minutes.
+
+Give them the shot list, not a task: *"Search TikTok for `packing orders small business` and `day in the life warehouse`, grab 4–6 clips where the hands are visible and there's no burned-in text, drop them in `./raws-inbox/`."* Then import the folder. `vidfarm handoff raws --keywords "…" --platforms tiktok,youtube --purpose "<what the clips are for>"` mints that brief in full.
+
+The two are complementary, not alternatives: browse yourself to find *which* sources are worth a human's attention, then hand the shortlist over for the taste call. Same shape as the image checkpoint — you write the prompt, they run the free generator.
+
+### Limits, and the honest caveats
+
+- **It is the user's real browser.** Their sessions, cookies, history and open tabs are in reach. Ask before setting it up, keep to the pages the task needs, and never touch a logged-in surface the task didn't call for.
+- **Recordings are off by default and stay off** unless the user asks for them — they write page content to disk. `browser-harness recordings` shows the preference.
+- **Login walls: stop and ask.** Do not attempt credentials, MFA, or account selection.
+- **Captchas and rate limits are the real failure mode.** A burst of automated Google queries gets challenged. Space the searches, keep them wide rather than many, and if you get walled, fall back to the free catalog or the paid primitive rather than hammering.
+- **A public result is not a licensed asset.** Browsing changes what it costs to find footage, not what it costs to use it. Keep the source URL and the licence page for anything reaching a client render, and prefer public domain → CC0 → CC BY → explicit commercial stock → written permission, in that order.
+- **Don't reach for a browser when a fetch would do.** A public page, an API, a docs URL — `curl` it. The browser is for interaction, a logged-in session, JS-rendered results, and bot-protected pages.
+- **`vidfarm serve` is unaffected.** Browser control is for sourcing; the local editor, local render, `qa` and `stills` all run without it.

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

@@ -536,6 +536,7 @@ Compositions are authored in HTML, so the single most common way an AI-edited vi
 - **CTA / "button" shapes.** Any filled capsule or rounded rect containing action copy — "Sign Up for a Free Trial →", "Learn More", "Get Started", "Book a Call" — especially gradient-filled with a glow or drop shadow. A social CTA is *spoken*, or a plain caption line, or an arrow pointing at the real UI. Not a button.
 - **Badges, chips, pills — including a SINGLE one.** The "✓ ID-Verified Tutors · ✓ No Credit Card Needed · ✓ 30-Min Trial" strip is the obvious case, but the far more common one is **one lonely capsule holding a stat or a label**: `( 10 hrs / week )`, `( STEP 2 )`, `( EP.01 )`, `( BEGINNER )`, `( +40% )`. Being alone does not make it native — a rounded, padded, filled tag around static text is a `<span class="badge">` wearing a different hat, and it is one of the loudest web tells in the whole frame. **The only legitimate pill in a video is the active-word highlight** (`spotlight`/`karaoke`), because it tracks the spoken word and moves. Static text gets `outline`, `plain`, or a tight band that hugs the glyphs (radius ≤ ~8px). If a stat deserves emphasis, give it emphasis the *editor* can give: bigger, heavier, ALL-CAPS, an accent color, a hand-drawn circle or underline around it, its own beat on screen.
 - **Cards, panels, containers.** A rounded-rect box (dark, bordered, shadowed, or `backdrop-filter` frosted) holding a heading plus a subheading/URL. Text belongs **on the footage**, not inside a floating panel with padding around it.
+- **Layout templates — a whole frame arranged like a page.** A modal/dialog floating over a dimmed or blurred backdrop; a headline + subheadline + CTA stacked in a centred well; a blurred website screenshot used as the background plate. This is the frame-level version of the rule and it survives the deletion of every individual style above — see "The layout-template rule" below.
 - **Gradient text fills, neon border glows, elevation shadows, glassmorphism, hover-implying strokes.**
 - **Web page furniture of any kind:** navbars, hero sections, feature grids, two-column layouts, `<ul>` bullet lists with disc markers, tables, alerts, progress bars as decoration, logo-in-a-circle avatars, "as seen in" strips.
 - **Corporate web type:** Inter, Roboto, system-ui, Arial, Helvetica, Georgia, Times — at web weights (400–600) and web sizes (16–24px). Instantly reads as "a screenshot of a website."
@@ -544,6 +545,27 @@ Compositions are authored in HTML, so the single most common way an AI-edited vi
 
 **The capsule rule of thumb.** On any element that holds words: `border-radius` over ~8px **combined with** a background fill and padding = a badge. Either take the fill away (bare text + outline/shadow) or take the radius and padding down until the band hugs the glyphs. There is no third option for static text.
 
+#### The layout-template rule — the FRAME is not a page
+
+Every rule above judges one element. This one judges the **whole frame**, and it catches the case where each individual element looks defensible but the composition is still a web page. The archetype: a **modal** — the background dimmed and blurred out of focus, and floating on top of it a rounded bordered box holding a big headline, a smaller support line, and a fat red button. Nobody authored "slop" there; they authored a *layout template*, and a layout template is the strongest web tell there is, because a viewer recognizes the SHAPE before they read a single word.
+
+**The stack is the tell, not the box.** Delete the border, delete the fill, delete the button capsule, and *keep the arrangement* — headline, then a smaller line under it, then a call to action, centred in a well with symmetric margins — and it still reads as a landing page. A phone-shot video never arranges words into a document: it puts **one thought on screen at a time**, wherever the picture leaves room, and the next thought arrives on the next beat.
+
+**Banned frame-level shapes:**
+
+- **The modal / dialog.** A content block staged *on top of* a backdrop that has been dimmed, blurred, greyed, or scaled back to make it recede. Nothing in a video pops "above" the video.
+- **The hero triplet.** Headline → subheadline → CTA, stacked and centred. Also its cousins: title + kicker + logo lockup, question + answer + URL.
+- **The full-frame scrim used as staging.** A dark wash over the whole frame so a floating block reads on top. (A local legibility band on *one caption* is legal; a page-wide wash to stage a panel is not. Nor is a blurred-and-dimmed backdrop — a blurred fill behind a 16:9 clip in a 9:16 frame is fine on its own, but blur *plus* dimming is modal staging.)
+- **Page sections.** Nav strip, hero, three-up feature row, testimonial block, footer with fine print — in any order, in any frame.
+- **The blurred website screenshot as a background plate.** If the backdrop is a web page at all, the frame is a screen recording of a web page. Either show the real product UI full-bleed and in focus (that is legitimate footage), or don't show it.
+- **Document margins.** A centred content column with even gutters left and right and air above and below. Social frames are full-bleed; the text lands where the picture is empty, not inside a measured well.
+
+**The fix is always the same: unstack it into time.** Take the three lines the layout was going to show at once and give each one its own beat over live footage — the headline is the hook at t=0, the support line lands on the next cut, the CTA is *spoken* (or a bare caption on the final frame). You lose nothing, because a viewer reads one line at a time anyway; you gain the pacing that makes it look shot rather than designed.
+
+**The self-check before you place a text group:** *am I arranging words relative to each other, or relative to the picture?* Relative to each other = layout = web. Relative to the picture = a caption = native. Two on-screen text runs at once is already the ceiling; three stacked runs plus a call to action is a page.
+
+`vidfarm qa` catches the mechanical versions of this (`layout-template`, `modal-scrim`), but the frame-level judgement is yours — **look at a still** (`vidfarm stills ./work --at <t>`) and ask whether it could be a screenshot of a website. If yes, rebuild the beat.
+
 **ALLOWED and encouraged — these ARE social-native:**
 
 - **Arrows** (drawn, animated, hand-style), circles/scribbles/underline strokes highlighting part of the frame, hand-drawn marks, checkmarks *as glyphs inside a caption line* (not as chips).