@officexapp/vidfarm-devcli 0.21.30 → 0.21.31

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

@@ -210,6 +210,7 @@ Present both harnesses to the director, recommend (A) unless they've asked for p
 - **Stickers are usually animated, not pasted.** Once placed, animate each one with `vidfarm keyframes` presets (`pop-in`, `float`, `shake`, `grow`, `slide-in-left`, `drift`) — that's HTML/CSS canvas motion, deterministic, free, and identical in preview and render. Layer moves up (pop-in, then idle float) for real life. See `references/editor-workflows.md` → "Cutout graphics for explainers".
 - **A sticker can carry its OWN motion too.** A *moving* subject has no single bounding box, so it isn't a PNG: key the clip with `vidfarm remove-greenscreen <video>` → transparent WebM (browser/editor-playable, the right choice on a composition).
 - **The plate must be a color the ART DOESN'T USE — green is a default, not a law.** A chroma key removes exactly ONE color, so a green plate under green artwork (leaves, frogs, plants, money, an "eco" icon set) keys holes straight through the stickers. `sticker-pack`/`cutout` handle this for you in two ways, and you should still say it out loud when it matters: **(a)** when generating, they read the subject and move the plate off any hue it mentions — green → magenta (`#FF00FF`) → blue (`#0047BB`) → black → white — and print which plate they picked and why; **(b)** when splitting a sheet you already have, they **detect the plate from the sheet's four corners**, so a red/purple/blue sheet handed back from a web generator just works. Pin it yourself with `--key-color "#FF00FF"` / `--preset magenta` (that disables the auto-pick), or `--no-auto-key` to force plain green. If a pack's palette collides with *every* standard plate, split it into two sheets on two different plates rather than fighting the key.
+- **The ART must be CLOSED and SOLIDLY FILLED — this is the other half of surviving the key, and the #1 way stickers come back broken.** Ask an image model for "icons on a green plate" and it will happily draw **outline art**: a colored stroke with the shape's interior left as bare plate. It looks perfect on the sheet, and after the key each sticker is a **rim floating around a see-through hole** (an apple-shaped outline with nothing inside it). Same outcome from a *near-plate* fill (the keyer works on tolerance, not exact match), a translucent/glassy/glowing material, or a soft glow fading into the plate. **You cannot key those pixels back — it has to be in the prompt:** *"every object is a closed, solidly filled shape; outlines must enclose an opaque fill of a different color; no outline-only or hollow art; nothing on the art in the plate color or any near-shade of it; fully opaque, no translucency, glow or drop shadow."* `cutout --generate`, `sticker-pack --generate`, `handoff image` and the `create-overlay` primitive **append that clause for you** with the chosen plate hex — write it yourself only when you prompt a generator directly. After the key, both commands report per-item `hole_pct`/`hollow` (console `⚠ N% hollow`, `--json`, `stickers.json`) — a ring or picture frame reads the same way, so it **warns, never blocks**. Flagged and it shouldn't be? Re-generate with the fill clause; a *near*-plate fill can sometimes be rescued with a lower `--tolerance`; one stubborn item can be lifted with `vidfarm mask --crop …` (ONNX matting ignores fill color).
 - **Transparent GIF is supported, for GIF-only surfaces.** `vidfarm sticker-pack … --output-format gif` (stills) and `vidfarm remove-greenscreen <video> --gif` (animated) emit transparent GIFs. GIF alpha is **1-bit**, so edges go hard — fine for chat/forum/Notion sticker surfaces, worse than PNG/WebP/WebM for compositing on a timeline. Prefer PNG/WebP/WebM unless the destination only eats GIF.
 
 **Explainer house style — the defaults to build with unless told otherwise.** **White background / light mode** (plain white stage, no gradients, no dark mode, no photo backdrop), **kinetic word-by-word captions** in dark ink on the light stage (`vidfarm captions generate --style word-pop --color "#111111" --active-color "#7C3AED" --background-style plain` — skip outlines/shadows, they're only needed over busy footage), and **female TTS narration** (`vidfarm tts --voice coral` on OpenAI — `nova` for energy, `sage` for calm; `Kore`/`Leda` on Gemini; any ElevenLabs voice via `vidfarm voices`). **Keep it clean and simple** — one idea on screen at a time, two or three cutouts per beat, one accent color, one font, lots of white space; remove before you add. **Illustrations default to simplicity**: flat vector, simple shapes, minimal detail, 2–3 flat colors, no baked-in text — simple art keys cleanly, trims tight, and stays on-style across the whole cast. State the defaults once so the director can override any of them. Full detail: recipe `recipes/cutout-graphics-for-explainers.md` (“House style — the explainer defaults”).
@@ -317,6 +318,7 @@ Choose the narrowest path that satisfies the request.
 3. If the task is “change this video,” read `references/editor-workflows.md`.
 4. If the task is “find footage” or “use our existing assets,” read `references/assets-and-sourcing.md`.
 4b. If the task is **“download this video/audio off a website”** (a pasted YouTube / TikTok / Instagram / X post URL the user wants the actual file from), Vidfarm does that for you on a **paid plan** — `POST /api/v1/primitives/videos/download` (or `/audio/download`), devcli `vidfarm download-video <url>` / `vidfarm download-audio <url>`. **Free plan → do not call it; walk the user through opening the URL in Chrome and downloading it from the page, then `vidfarm put-file` the local file in for $0.** Details in `references/assets-and-sourcing.md` → `references/primitives.md`.
+4c. If the task is **“turn this Reddit/X thread, subreddit, or account into a video”** — “tweet to TikTok”, “Reddit to TikTok”, “make a video from this thread”, “what are the top comments saying” — run `vidfarm recycle <source>` (or `POST /api/v1/primitives/social/recycle`) with the URL. It **decomposes** the source into raw JSON (text, comment tree, media URLs, author pics, stats) and hands it back unranked so YOU pick what to remix. **Paid plan; `max_records` is the spend ceiling.** Brokers the reddit-lead-gen / x-lead-gen OfficeX apps, so it waits out their async job for you. Details in `references/assets-and-sourcing.md` → `references/primitives.md`.
 5. If the task is scripted, local, CI-driven, or `vidfarm serve`-based, read `references/automation-and-local-dev.md`.
 6. If the task explicitly asks for a primitive or needs specialized generation/transcription work, read `references/primitives.md`.
 7. If the task is the MARKETPLACE (ordering videos from specialist agents): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. Placing/listing orders is the thin REST wrapper in `references/core-workflows.md` (§ Marketplace); anything deeper on a gig (inbox, proofs, payouts) needs the external Dollar Platoon skill — `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`.

package/.agents/skills/vidfarm/recipes/cutout-graphics-for-explainers.md

@@ -18,7 +18,7 @@ The mechanical trio — **generate on a chroma plate → key it out → trim to
 - **Female TTS narration.** Default to a warm, friendly **female** voice and say which one you picked: local-first `vidfarm tts "<script>" --voice coral` (OpenAI — `nova` if the script wants more energy, `sage` for calmer), `--voice Kore` or `Leda` on Gemini, or `vidfarm voices` → `vidfarm tts --cloud --voice <voice_id>` on ElevenLabs. Tell the director they can swap it in one flag.
 - **Clean and simple wins.** One idea on screen at a time. Two or three cutouts per beat, not eight. Generous white space, one accent color, one font. When in doubt, remove an element rather than add one.
 
-**Illustrations default to simplicity.** Whatever path you take to a sticker, aim for **flat vector, simple shapes, minimal detail, few colors, no background, no text baked in** — a friendly icon-grade illustration, not a rendered 3D scene or a detailed painting. Simple art keys cleanly, trims tight, scales without mush, animates readably at 9:16, and stays on-style across a whole cast. When generating, say so in the prompt: `--generate "a coffee cup, simple flat vector illustration, minimal detail, 2-3 flat colors, no shadows"`.
+**Illustrations default to simplicity — and to SOLID FILLS.** Whatever path you take to a sticker, aim for **flat vector, simple shapes, minimal detail, few colors, solid opaque fills, no background, no text baked in** — a friendly icon-grade illustration, not a rendered 3D scene or a detailed painting. Simple art keys cleanly, trims tight, scales without mush, animates readably at 9:16, and stays on-style across a whole cast. "Solid fills" is the load-bearing word: **outline-only art has its interior keyed away and comes back as a rim around a transparent hole** (see "Then make the ART key-safe too" below). When generating, say so in the prompt: `--generate "a coffee cup, simple flat vector illustration, minimal detail, 2-3 flat colors, solid filled shapes (not outline-only), no shadows"`.
 
 **In cost-saving mode, don't generate illustrations at all — mask them out of images the director already has.** If `vidfarm cost-mode` is `minimize` (or the director says "without burning credits"), the default for adding an illustration is `vidfarm mask <their-image> --crop …` — lifting art out of an infographic, poster, deck slide, brand sheet, or screenshot for **$0 and zero AI calls**. Ask for source art before you ask for a generation budget; the guided loop is **"Mask from an image you already have"** below. **If no source art exists and the graphic must be custom, you still don't have to spend** — hand the director a prompt for a **free** image generator (meta.ai / free ChatGPT / a Hugging Face Space) and cut the returned sheet into stickers locally: **"Free manual image-gen"** below.
 
@@ -63,6 +63,20 @@ Out comes `./stickers/sticker-01-red-barn.png`, `sticker-02-tractor.png`, … ea
 
 Override whenever you know better: `--key-color "#FF00FF"` or `--preset magenta` pins the plate (and turns the auto-pick off); `--no-auto-key` forces plain green. If a pack's palette collides with *every* standard plate — a rainbow icon set — split it across two sheets on two different plates rather than fighting `--tolerance`. And when a sticker is a *green* subject, never let the user generate it on green: the hand-off brief (`vidfarm handoff image`) already picks the plate for them and carries the matching `--key-color` into the follow-up command.
 
+**Then make the ART key-safe too — CLOSED, SOLIDLY FILLED shapes.** Picking the right plate is only half of surviving the key. The other half is the failure you actually see in the wild: you ask for "sticker icons on a green plate" and the model draws **outline art** — a colored stroke with the shape's *interior left as bare plate*. On the sheet it looks perfect. After the key, the interior is gone with the background, and every sticker composites as a **rim floating around a see-through hole** (an apple that's just an apple-shaped outline, a clock with no face). Same result from three cousins: a fill that's a *near-shade* of the plate (the keyer works on tolerance, not exact match), a **translucent/glassy/glowing** material that lets the plate through, and a **soft glow or drop shadow** that fades into the plate at the edges.
+
+None of that is fixable after generation — you cannot key back pixels that were never drawn. So it belongs in the **prompt**, every time:
+
+> Every object must be a CLOSED, SOLIDLY FILLED shape — outlines and strokes must enclose an opaque fill of a different color. No outline-only, hollow, or line-art objects; never leave a shape's interior as bare background. No part of any object — fill, outline, highlight, gradient, shading or detail — may be `<PLATE HEX>` or any near-shade, tint or tone of it. No transparent, translucent, glassy, glowing or ghosted materials; every pixel of every object is fully opaque. No soft glows, blurs or drop shadows fading into the background. Keep the whole palette in strong contrast to `<PLATE HEX>`. The background must be visible ONLY around the outside of the objects, never showing through inside them.
+
+`cutout --generate`, `sticker-pack --generate`, `vidfarm handoff image`, and the `create-overlay` REST primitive all append that clause automatically with the chosen plate hex substituted in — **you only have to write it yourself when you're prompting a generator directly** (a free web tool by hand, or your own `POST /api/v1/primitives/images/generate` call). Do write it. It costs one paragraph and it is the difference between a usable pack and a re-generation.
+
+**And it's checked after the key.** `sticker-pack` and `cutout` measure, per item, the transparent area **fully enclosed by that item's own art** and report it as `hole_pct` (plus `holes`, and `hollow: true` at ≥20%) in `--json`, in `stickers.json`, and as a `⚠ N% hollow` flag on the console line. A ring, donut, picture frame or letter "O" reads the same way, so it **warns, never blocks** — the judgement is yours. When items you expected to be solid come back flagged:
+
+- **Re-generate the sheet** with the fill clause above spelled out. This is the fix ~90% of the time.
+- If the fill was merely *close* to the plate rather than absent, a lower `--tolerance` can rescue the sheet you already have. Nothing rescues a genuinely empty interior.
+- Last resort for one stubborn item: `vidfarm mask ./sheet.png --crop x,y,w,h` — ONNX matting doesn't care what color the fill is, so it lifts art the chroma key can't.
+
 **Generation is the failure point, not the cutting.** The sheet prompt is auto-appended with the important instruction — *every item fully separated by clear plate-colored background, nothing touching or overlapping, wide margins, no text, no shadows, one consistent style* — because **touching items segment as one sticker**. If a pack comes back merged, re-run the generation asking for more spacing before you fight the `--gap` knob.
 
 ### Stickers are not necessarily small — and they usually move
@@ -179,15 +193,15 @@ Everything here is **local and free** — crop, matte/key, and trim are all `ffm
 
 1. **List the cast.** Name every illustration the explainer needs, in the house style (flat vector, 2–3 flat colors, no baked-in text).
 2. **Hand the director this prompt**, filled in:
-   > A flat vector illustration sheet on a solid pure green background (#00FF00), no gradient, no shadow, no text, no labels. Arranged in a 3×2 grid with generous even spacing, each object fully separated and not touching any other object or the image edge: (1) `<object one>`, (2) `<object two>`, (3) `<object three>`, … Simple flat shapes, 2–3 flat colors, minimal detail, consistent style and line weight across all objects, front-facing, centered in its own cell. Square image, high resolution.
+   > A flat vector illustration sheet on a solid pure green background (#00FF00), no gradient, no shadow, no text, no labels. Arranged in a 3×2 grid with generous even spacing, each object fully separated and not touching any other object or the image edge: (1) `<object one>`, (2) `<object two>`, (3) `<object three>`, … Simple flat shapes, 2–3 flat colors, minimal detail, consistent style and line weight across all objects, front-facing, centered in its own cell. **Every object is a closed, solidly filled shape — outlines must enclose an opaque fill of a different color; no outline-only or hollow objects, and no object's interior left as bare green. Nothing on any object may be green or any near-shade of green; no transparent, translucent, glassy or glowing materials; no soft glows or drop shadows fading into the background.** Square image, high resolution.
 
-   **No text in the image, ever** — rendered text never keys or scales cleanly; add copy as a caption or HTML layer instead.
+   **No text in the image, ever** — rendered text never keys or scales cleanly; add copy as a caption or HTML layer instead. **And don't drop the bolded fill sentence** — the green gets deleted, so anything green *on* the art gets deleted with it; hollow outline art is the single most common way a hand-generated sheet comes back broken. (`vidfarm handoff image --theme … --items …` mints this whole brief with the plate and the fill clause already filled in — prefer it over typing the prompt yourself.)
 3. **Bring the sheet in:** `vidfarm put-file ./sheet.png` (or drag into **My Files** in the web app).
 4. **Split it into stickers — one command, all free:**
    ```
    vidfarm sticker-pack ./sheet.png --items "<object one>,<object two>,…" --out-dir ./stickers
    ```
-   It keys the flat green, finds each object in the alpha channel, and writes one trimmed transparent sticker per object (named from `--items`) plus `stickers.json`. Run it with `--dry-run` first to check the boxes. Two objects merged into one? The generator drew them too close — lower `--gap`, or grab that pair by hand:
+   It keys the flat green, finds each object in the alpha channel, and writes one trimmed transparent sticker per object (named from `--items`) plus `stickers.json`. Run it with `--dry-run` first to check the boxes. Any item flagged **`⚠ N% hollow`** came back as an outline around a transparent hole — unless it's genuinely a ring/frame, re-ask the director for that sheet with the fill sentence, or lift that one item with `vidfarm mask ./sheet.png --crop x,y,w,h` (ONNX matting doesn't care what the fill color is). Two objects merged into one? The generator drew them too close — lower `--gap`, or grab that pair by hand:
    ```
    vidfarm mask ./sheet.png --crop 4%,4%,29%,45% --flat "#00FF00" --out prop-a.png
    ```

package/.agents/skills/vidfarm/references/assets-and-sourcing.md

@@ -15,6 +15,23 @@ Both are async primitive jobs — poll `GET /api/v1/primitives/jobs/:jobId` unti
 
 **Don't reach for this when the real goal is clips.** If the user wants short clips mined out of a long video, `POST /raws/scan` with `source_url` already downloads the source for you as part of the hunt (below) — a separate download call is wasted spend.
 
+## Recycle a Reddit or X source into content ("tweet to TikTok", "Reddit to TikTok")
+
+When the source isn't a video file but a **conversation** — a Reddit thread and its comments, a subreddit's front page, an X thread and its replies, an account's timeline — the download routes are the wrong tool. Use `vidfarm recycle <source>` (devcli) or `POST /api/v1/primitives/social/recycle` (alias `/recycle-social`), which **decomposes** the source into JSON you can remix:
+
+| Paste this | You get back |
+| --- | --- |
+| `reddit.com/r/<sub>/comments/<id>/...` | the post + its whole comment tree |
+| `reddit.com/r/<sub>` or `r/<sub>` | that subreddit's threads |
+| `x.com/<user>/status/<id>` | the tweet + self-thread + replies |
+| `x.com/<user>` or `@<user>` | that account's posts, pinned first |
+
+Every item carries text, author + `avatar_url`, timestamps, permalink, engagement stats, and **media URLs** (X video resolves to the top-bitrate MP4). It never summarizes or ranks — you read `items[]` and choose the hook, the punchline comment, the stat worth a card. `max_records` is your spend ceiling; `nextCursor` resumes. Paid plans only.
+
+Under the hood it brokers the **reddit-lead-gen** and **x-lead-gen** OfficeX apps rather than holding Reddit/X keys itself — so it's a job wrapping a job, and the primitive waits out the upstream job for you. Full payload/response reference in `references/primitives.md` → *Primitive: social/recycle*.
+
+Pipe it forward: any `media[].url` goes straight into a layer or through `videos/download`; `profile.avatar_url` makes the "who said this" badge. **Recycled text is source material, not a script** — rewrite it to the hook/loop/payoff standard instead of pasting a comment thread on screen.
+
 ## Public raws catalog — browse BY CATEGORY (check here first)
 
 Before you hunt footage and long before you generate it, check what the platform **already has**. The public raws catalog is a curated, pre-tagged, free-to-use pool of short clips, organised into **categories** (shelves) — and browsing it by category is one of the highest-leverage moves available to you, for two reasons:

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

@@ -214,9 +214,9 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm inpaint <image> --mask <png> --prompt "…" [--region "label=…"] [--ref …] [--out <f>]` | `POST /api/v1/primitives/images/inpaint` (polls job) | masked image EDIT — replace ONLY the transparent-mask region, keep everything else (devcli twin of the /inpaint page) |
 | `vidfarm create-overlay "<subject>" [--key-color #00FF00] [--aspect-ratio 1:1] [--place <dir>] [--out <f>]` | `POST /api/v1/primitives/images/create-overlay` (polls job) | **Vox-style** transparent OVERLAY — AI image on a forced key-color background, chroma-keyed out in one job → ready-to-composite transparent PNG |
 | `vidfarm remove-greenscreen <image\|video> [--preset green\|blue\|white\|black\|digital-green\|magenta] [--key-color #00FF00] [--tolerance 0.3] [--local] [--gif] [--out <f>]` | `POST /api/v1/primitives/remove-greenscreen` (polls job) | chroma-key a FLAT solid background → transparent PNG/WebP (image) or WebM/VP9-alpha (video); auto-detects media kind. `--local` runs it FREE in-process (sharp/ffmpeg, no wallet); default cloud is billed at real compute × 1.2. **`--gif` writes a transparent GIF instead** (ANIMATED for a clip; `--gif-fps`/`--gif-width`/`--gif-alpha`) — local-only, 1-bit alpha, for GIF-only sticker surfaces; prefer PNG/WebP/WebM for compositing. Aliases: `greenscreen`, `remove-background-greenscreen`. |
-| `vidfarm cutout <image\|url> [--generate "<prompt>"] [--preset green] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--out <f>]` | **local, free, ffmpeg-only** (no job) — key + `alphaextract`/`cropdetect` trim | **The transparent explainer-STICKER maker.** Keys out the flat plate **and then shrinks the canvas to the cutout's true min width/height** (a 1024² mostly-empty plate → a snug sticker whose pixel size IS the subject) so you can scale/position it precisely. `--generate` AI-generates the graphic first on a matching chroma plate (that step is the billed image primitive), then keys+trims in one shot; without it, keys+trims a file/url you already have. **IMAGE-only** (a moving subject has no single bounding box — key a clip with `remove-greenscreen`). Prefer this over `create-overlay` locally: same idea, but free and auto-trimmed. `--pad` keeps transparent breathing room; `--json` reports final `width`/`height`/`area_reduced_pct`. Alias: `sticker`. See recipe `cutout-graphics-for-explainers.md`. |
+| `vidfarm cutout <image\|url> [--generate "<prompt>"] [--preset green] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--out <f>]` | **local, free, ffmpeg-only** (no job) — key + `alphaextract`/`cropdetect` trim | **The transparent explainer-STICKER maker.** Keys out the flat plate **and then shrinks the canvas to the cutout's true min width/height** (a 1024² mostly-empty plate → a snug sticker whose pixel size IS the subject) so you can scale/position it precisely. `--generate` AI-generates the graphic first on a matching chroma plate (that step is the billed image primitive), then keys+trims in one shot; without it, keys+trims a file/url you already have. **IMAGE-only** (a moving subject has no single bounding box — key a clip with `remove-greenscreen`). Prefer this over `create-overlay` locally: same idea, but free and auto-trimmed. `--pad` keeps transparent breathing room; `--json` reports final `width`/`height`/`area_reduced_pct`, plus `hole_pct`/`hollow` — the "the key ate the fill" check (outline-only art keys into a rim around a transparent hole; `--generate` prompts against it automatically, and the console prints a `Hollow:` warning with the fix). Alias: `sticker`. See recipe `cutout-graphics-for-explainers.md`. |
 | `vidfarm mask <image\|url> [--crop x,y,w,h] [--flat <hex>] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--keep-region <f>] [--out <f>]` | **local, free** (no job) — ffmpeg crop + ONNX matting (or ffmpeg chroma-key) + `cropdetect` trim | **Lift an illustration OUT of an image you already have** (infographic / poster / marketing graphic / brand sheet / screenshot) → snug transparent PNG, the same reusable explainer sticker `cutout` makes but with **$0 and zero AI generation** — the cost-saving move whenever source art exists. `--crop x,y,w,h` (pixels **or** %) isolates ONE element from a multi-illustration source before masking (re-run with different rects to grab each). Background removed by **local ONNX matting** (any/busy background) by default, or **`--flat <hexcolor>`** chroma-keys a solid fill for crisper edges (an infographic's cream/white paper); then trims to the subject's true min width/height. **IMAGE-only** (matte a clip with `remove-background`). Aliases: `isolate`, `extract`. See recipe `cutout-graphics-for-explainers.md` → "Mask from an image you already have". |
-| `vidfarm sticker-pack [sheet\|url] [--generate "<theme>"] [--items "a,b,c"] [--count <n>] [--dry-run] [--gap <pct>] [--min-area <pct>] [--output-format png\|webp\|gif] [--out-dir <d>]` | **local, free, ffmpeg-only** (no job; only `--generate` bills, ONCE for the whole set) — key + alpha-channel segmentation + per-item trim | **The STICKER-PACK maker — the answer whenever a director asks for "a sticker pack" / prop set / icon set.** A pack is ONE greenscreen sheet holding every item, keyed once and then masked apart: 1/N the cost of N `cutout` calls, and the only way a cast stays on-style. Finds each item **automatically** by segmenting the keyed sheet's alpha into connected islands — no hand-measured `--crop` rects — and writes one snug transparent file per item (named from `--items`, reading order) plus a `stickers.json` manifest. `--dry-run` prints the detected boxes first; `--gap` merges (lower) or splits (raise) items that came out joined/broken; items have **no maximum size** — a full-frame landscape/backdrop is as valid a sticker as a 3% icon. **Plate color is chosen for you:** when generating it reads the subject and moves the plate off any hue the art uses (green → magenta → blue → black → white — a pack of leaves/frogs/money on GREEN would key holes through the art), and when splitting an existing sheet it DETECTS the plate from the sheet's four corners, so a red/purple sheet handed back from a web tool just works. Pin it with `--key-color`/`--preset`, or `--no-auto-key` for plain green. `--output-format gif` emits 1-bit-alpha GIFs for GIF-only surfaces. IMAGE-only. Aliases: `stickers`, `sticker-sheet`. See recipe `cutout-graphics-for-explainers.md` → "A sticker pack". |
+| `vidfarm sticker-pack [sheet\|url] [--generate "<theme>"] [--items "a,b,c"] [--count <n>] [--dry-run] [--gap <pct>] [--min-area <pct>] [--output-format png\|webp\|gif] [--out-dir <d>]` | **local, free, ffmpeg-only** (no job; only `--generate` bills, ONCE for the whole set) — key + alpha-channel segmentation + per-item trim | **The STICKER-PACK maker — the answer whenever a director asks for "a sticker pack" / prop set / icon set.** A pack is ONE greenscreen sheet holding every item, keyed once and then masked apart: 1/N the cost of N `cutout` calls, and the only way a cast stays on-style. Finds each item **automatically** by segmenting the keyed sheet's alpha into connected islands — no hand-measured `--crop` rects — and writes one snug transparent file per item (named from `--items`, reading order) plus a `stickers.json` manifest. `--dry-run` prints the detected boxes first; `--gap` merges (lower) or splits (raise) items that came out joined/broken; items have **no maximum size** — a full-frame landscape/backdrop is as valid a sticker as a 3% icon. **Plate color is chosen for you:** when generating it reads the subject and moves the plate off any hue the art uses (green → magenta → blue → black → white — a pack of leaves/frogs/money on GREEN would key holes through the art), and when splitting an existing sheet it DETECTS the plate from the sheet's four corners, so a red/purple sheet handed back from a web tool just works. Pin it with `--key-color`/`--preset`, or `--no-auto-key` for plain green. **The ART is made key-safe too:** the generation prompt is auto-appended with "closed, solidly filled shapes, no outline-only/hollow art, nothing in the plate hue or a near-shade, fully opaque, no glow/translucency" — the fix for stickers that come back as a rim around a transparent hole — and after keying each item reports `holes`/`hole_pct`/`hollow` (console `⚠ N% hollow` at ≥20%, plus `--json` and `stickers.json`). It **warns, never blocks** (a ring/frame/donut reads identically); re-generate with the fill clause, or lift that one item with `vidfarm mask --crop …`. `--output-format gif` emits 1-bit-alpha GIFs for GIF-only surfaces. IMAGE-only. Aliases: `stickers`, `sticker-sheet`. See recipe `cutout-graphics-for-explainers.md` → "A sticker pack". |
 | `vidfarm tts "…" [--style "…"] [--voice <v>] [--out <file>]` | (LOCAL-FIRST: your own OPENAI/GEMINI/OPENROUTER_API_KEY → audio file on disk; `--cloud` = `POST /api/v1/primitives/audio/speech` + poll, ElevenLabs on the platform key by default, `--own-key` for yours) | text → narration audio; `--cloud --voice <voice_id>` picks an ElevenLabs voice |
 | `vidfarm music "<prompt>" [--length <sec>] [--out <f>] [--own-key]` | `POST /api/v1/primitives/music/generate` (polls job) | prompt → music track (ElevenLabs; platform key + wallet by default, `--own-key` for yours) |
 | `vidfarm voices [--own-key] [--limit N]` | `GET /api/v1/primitives/audio/voices` | list ElevenLabs voices (voice_id/name/labels) for `tts --voice`; default a voice + tell the user they can choose |
@@ -245,7 +245,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm whoami` | `GET /api/v1/user/me` | who am I (also prints the active cost mode) |
 | `vidfarm cost-mode [minimize\|hybrid\|rich-ai\|pure-videogen]` | (local `~/.vidfarm/cost-mode.json`) | show/set the money-saving preference every billed command respects; no arg = show + explain each; `--clear` forgets it |
 | `vidfarm mode [interactive\|autonomous]` | local (`~/.vidfarm/interaction-mode.json`) | **The SECOND preference axis — ask it alongside cost mode.** Is the human in the loop? `interactive` = at checkpoints you hand them a copy-paste brief (an image prompt for a FREE web generator; a keyword list for sourcing clips) and they hand files back — usually BETTER output, and in `minimize` the only way to get custom art at all. `autonomous` = you finish solo within the budget. Independent of cost mode: every cost mode runs either way. No arg prints the pair + the explainer to relay; `--clear` forgets; per-run `--interactive`/`--autonomous`. Aliases: `interaction-mode`, `interaction`. |
-| `vidfarm handoff image --theme "<what>" [--items "a,b,c"] [--style …] [--single]` | local (pure text) | **The interactive-mode IMAGE brief.** Prints the exact prompt, the numbered steps, the free tools (meta.ai / ChatGPT / Gemini / HF Spaces) and the follow-up command. Defaults to a **sticker pack**: ONE sheet holding every item on a chroma plate → `vidfarm sticker-pack` splits it for $0. Picks a plate the art won't collide with (green art → magenta plate) and carries that `--key-color` into the follow-up. `--single` for one subject. |
+| `vidfarm handoff image --theme "<what>" [--items "a,b,c"] [--style …] [--single]` | local (pure text) | **The interactive-mode IMAGE brief.** Prints the exact prompt, the numbered steps, the free tools (meta.ai / ChatGPT / Gemini / HF Spaces) and the follow-up command. Defaults to a **sticker pack**: ONE sheet holding every item on a chroma plate → `vidfarm sticker-pack` splits it for $0. Picks a plate the art won't collide with (green art → magenta plate), spells out the **key-safe fill rules** (closed solidly-filled shapes, no outline-only/hollow art, nothing in a near-plate shade, fully opaque) so the sheet doesn't come back as rims around holes, and carries that `--key-color` into the follow-up. `--single` for one subject. |
 | `vidfarm handoff raws --keywords "a,b" [--platforms tiktok,youtube] [--count N] [--purpose "…"]` | local (pure text) | **The interactive-mode CLIP-SOURCING brief** — the bottom rung of the sourcing ladder (browser control → `clipper`/`raws scan --cloud` → public raws → the human). Prints what to search, how to download (a Google *search* for a downloader, never a link that rots), and the import command for when the folder is ready. |
 | `vidfarm storyboard [dir] [--init] [--frames "Title\|scene,…"] [--json]` | local (`STORYBOARD.md` / `SCRIPT.md`) | **The plan pass, and a core part of the composition format.** Scaffolds/reads the project's `STORYBOARD.md`: ordered frames with `duration`/`status`/`src`/`scene`/`voiceover`. The Vidfarm editor renders this file in its **Storyboard** view (contact sheet + per-frame comments + `outline → built → animated` progress), so it's the cheapest place to get a director's approval before building. Not to be confused with `vidfarm sequence` (which GENERATES storyboard images for the pure-videogen pipeline). Alias: `plan`. |
 | `vidfarm wallet [--job <id>\|--tracer <t>] [--limit <n>]` | `GET /api/v1/user/me/wallet` | cost log: balance + lifetime spend + recent charges. `--job <renderJobId>` prints **what that one video cost** (sums its charges); `--tracer <t>` sums a tracer. Cloud-only; readable on the free plan too (shows $0.00). Aliases: `spend`, `costs` |
@@ -254,6 +254,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm download <url> [dest]` | (streams any URL to disk) | download media from a **direct** media URL. Free — no plan, no job |
 | `vidfarm download-video <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | **download a video FROM A WEBSITE** (YouTube/TikTok/IG/X/other supported posts) into durable Vidfarm media; photo/carousel posts return an ordered slideshow. **PAID PLAN** (wallet-billed resolver; free plans get 402). Aliases: `download-post`, `download-url` |
 | `vidfarm download-audio <url>` | `POST /api/v1/primitives/audio/download` + poll | download just the AUDIO track (music/voice) off a website post into a durable audio file. **PAID PLAN**. Alias: `download-post-audio` |
+| `vidfarm recycle <source>` | `POST /api/v1/primitives/social/recycle` + poll | RECYCLE a Reddit/X source into reusable JSON ("tweet to tiktok", "reddit to tiktok"): thread + comments, subreddit threads, X thread + replies, or an account's posts — text, author + avatar, stats, media URLs. `--out` saves the full payload. **PAID PLAN**. Aliases: `recycle-social`, `tweet-to-video`, `reddit-to-video` |
 
 > **Free plan / `cost-mode minimize`:** both download commands are gated by `guardBilled` and will refuse or warn. The free path is **Chrome**: open the URL in a real browser, save the file off the page (right-click → *Save video as*, downloads pane, or a Googled `"<platform> video downloader"` site), then `vidfarm put-file ./the-file.mp4 --folder <folder>` to bring it in for $0. The CLI prints these steps on a 402. Never tell a free user the video simply can't be downloaded.
 | `vidfarm files [--folder <path>]` | `GET /api/v1/user/me/attachments` | list My Files assets + folders |

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

@@ -595,7 +595,7 @@ Beyond the Ken Burns / transition / animated-caption presets, the copilot can ha
 
 **Make the sticker (`vidfarm cutout`).** Local, free, ffmpeg-only, image-only. `vidfarm cutout --generate "<subject>"` AI-generates on a matching plate then keys+trims (only the generation is billed); `vidfarm cutout <file|url>` keys+trims a graphic you already have for $0. Because the output is trimmed tight, its on-frame **width % maps directly to how big the subject reads** — no invisible padding skewing the layout. Knobs: `--preset`/`--key-color` (match the plate), `--pad <px>` (transparent breathing room), `--alpha-threshold <0..255>` (trim faint haloed edges), `--output-format webp`, `--no-trim`. A *moving* subject has no single bounding box → key it as a clip with `vidfarm remove-greenscreen <video>` (→ transparent WebM) instead.
 
-**Make a whole PACK at once (`vidfarm sticker-pack`).** When the scene needs a *set* — props, icons, a cast, plus any backdrops — don't run `cutout` N times. Generate ONE greenscreen sheet holding every item and split it locally: `vidfarm sticker-pack --generate "<theme>" --items "a,b,c" --out-dir ./stickers` (one billed image job for the set), or `vidfarm sticker-pack ./sheet.png` for $0 on a sheet you already have. It keys the plate once, **segments the sheet's alpha channel to find each item automatically** (no hand-measured crop rects), trims each to its true box, and writes `stickers.json`. `--dry-run` to inspect the boxes; `--gap` to fix items that merged (lower) or split (raise). **Item size is unbounded** — a full-frame landscape/skyline/backdrop is as legitimate a sticker as a small icon, and belongs in the same sheet so it shares the cast's style. Recipe: `recipes/cutout-graphics-for-explainers.md` → "A sticker pack".
+**Make a whole PACK at once (`vidfarm sticker-pack`).** When the scene needs a *set* — props, icons, a cast, plus any backdrops — don't run `cutout` N times. Generate ONE greenscreen sheet holding every item and split it locally: `vidfarm sticker-pack --generate "<theme>" --items "a,b,c" --out-dir ./stickers` (one billed image job for the set), or `vidfarm sticker-pack ./sheet.png` for $0 on a sheet you already have. It keys the plate once, **segments the sheet's alpha channel to find each item automatically** (no hand-measured crop rects), trims each to its true box, and writes `stickers.json`. `--dry-run` to inspect the boxes; `--gap` to fix items that merged (lower) or split (raise). **Ask for solidly filled art** — outline-only/hollow shapes (or fills in a near-plate shade) get their interiors keyed away and composite as rims around transparent holes; the generation prompt says so automatically, and each item reports `⚠ N% hollow` / `hole_pct` after the key so you catch it before placing. **Item size is unbounded** — a full-frame landscape/skyline/backdrop is as legitimate a sticker as a small icon, and belongs in the same sheet so it shares the cast's style. Recipe: `recipes/cutout-graphics-for-explainers.md` → "A sticker pack".
 
 **Sticker formats.** Still sticker → **PNG** (or `--output-format webp` for smaller files). Sticker whose own artwork moves → **transparent WebM** via `vidfarm remove-greenscreen <video>` (ProRes `.mov` is the local fallback; `--cloud` always returns WebM). Sticker destined for a **GIF-only surface** (chat, forum, Notion, a shareable pack) → `--output-format gif` on `sticker-pack`, or `vidfarm remove-greenscreen <video> --gif` for an animated one; GIF alpha is 1-bit, so edges harden and soft shadows vanish — never the choice for compositing on a timeline.
 

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

@@ -35,7 +35,7 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/images/remove-background" \
 
 - `POST /api/v1/primitives/images/create-overlay` (flat alias: `POST /api/v1/primitives/create-media-overlay`)
 - Body: `{ "tracer": "...", "payload": { "prompt": "a cartoon rocket ship, flat vector illustration", "provider"?: "...", "model"?: "...", "prompt_attachments"?: ["https://..."], "aspect_ratio"?: "1:1", "image_size"?: "1K"|"2K"|"4K", "key_color"?: "#00FF00", "tolerance"?: 0.3, "softness"?: 0.1, "despill"?: true, "output_format"?: "png"|"webp" }, "webhook_url"?: "..." }`
-  - Just describe the **subject** in `prompt` — do NOT describe the background; the primitive appends the flat key-color background requirement for you.
+  - Just describe the **subject** in `prompt` — do NOT describe the background; the primitive appends the flat key-color background requirement for you, **and** the key-safe *artwork* requirement (closed solidly-filled shapes, no outline-only/hollow art, nothing on the subject in the key hue or a near-shade, fully opaque, no glow/translucency). That second clause is what stops the classic failure: outline art whose interior is bare plate keys into a **rim around a transparent hole**. If you build the prompt yourself for `images/generate` instead of using this primitive, write that clause in by hand.
   - `key_color` lets you key against something other than green if your subject is itself green-heavy (e.g. key against `#FF00FF` magenta for a green frog).
   - The chroma-key params (`tolerance`/`softness`/`despill`) behave exactly as in `image_remove_background_greenscreen`.
 - Response: `primary_file_url` is the finished transparent overlay; `greenscreen_source_url` is the raw pre-key frame (kept so you can re-key at a different tolerance without paying for another generation).
@@ -136,6 +136,85 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/audio/download" \
   -d '{"tracer": "demo-download-audio", "payload": {"source_url": "https://www.youtube.com/watch?v=example"}}'
 ```
 
+## Primitive: social/recycle
+
+**"Tweet to TikTok" and "Reddit to TikTok" live here.** The text-and-thread sibling of `videos/download`: point it at a Reddit or X/Twitter source and it **decomposes** that source into reusable JSON — the post text, the comment/reply thread, every image/video media URL, the author's profile pic and follower count, and the engagement stats — so YOU decide what to recycle into a new video. It deliberately does **not** summarize, rank, score, or filter. It dumps the data back raw.
+
+**Vidfarm does not hold Reddit/X vendor keys.** This primitive is a thin broker over the two OfficeX apps that already own that integration — **reddit-lead-gen** and **x-lead-gen** — called through their public REST job API. They own the vendor keys, retries, rate-limit budget, auto-pagination, and 90-day result storage; vidfarm owns target resolution, normalization, and the wallet charge. Both are async job APIs, so a recycle is **a job wrapping a job** — but the nesting is invisible: this primitive polls upstream to completion server-side and only resolves when the data is in hand, exactly like the GhostCut leg of `videos/remove-captions`. You poll `GET /api/v1/primitives/jobs/:jobId` like any other primitive.
+
+- `POST /api/v1/primitives/social/recycle` (alias: `POST /api/v1/primitives/recycle-social`)
+- Body: `{ "tracer": "...", "payload": { "source_url": "https://..." }, "webhook_url"?: "..." }`
+
+### The four shapes
+
+| You pass | Mode (auto-detected) | You get |
+| --- | --- | --- |
+| `https://reddit.com/r/<sub>/comments/<id>/...` | `reddit_thread` | the post + its comment tree, flattened in reading order |
+| `https://reddit.com/r/<sub>` (or `r/<sub>`) | `reddit_channel` | that subreddit's threads, paginated |
+| `https://x.com/<user>/status/<id>` | `twitter_thread` | the tweet + the author's self-thread + its replies, paginated |
+| `https://x.com/<user>` (or `@<user>`) | `twitter_channel` | that account's tweets (pinned first), paginated |
+
+A fifth mode, `reddit_user` (`https://reddit.com/user/<name>` or `u/<name>`), returns a redditor's posts and comments. Pass `mode` explicitly to override auto-detection, or `handle` + `network` instead of a URL.
+
+### Payload
+
+| Field | Default | Notes |
+| --- | --- | --- |
+| `source_url` | — | Reddit/X URL. Required unless you pass `handle` + `network`. Aliases: `url`, `thread_url`, `profile_url` |
+| `handle` + `network` | — | `{ "handle": "wallstreetbets", "network": "reddit" }`. Aliases for handle: `username`, `screenname`, `subreddit` |
+| `mode` | auto | Override the detected shape |
+| `max_records` | `100` | Cap on records (1–1000). The lead-gen apps auto-paginate to reach it and reserve credits for `ceil(max_records / 25)` pages — **this is your spend ceiling** |
+| `cursor` | — | Resume token from a previous run's `nextCursor` |
+| `prompt_filter` | — | Hand the lead-gen app a Gemini scoring prompt; adds `match_score` + `ai_notes` per item and costs slightly more per task upstream. We surface it and never act on it |
+| `query` | — | Restrict a channel pull to matching posts (Reddit search / X `from:<user> <query>`) |
+| `filter` / `sort` / `time_filter` | — | Reddit listing controls (`hot`, `new`, `top`, …) |
+| `search_type` | — | X search mode (`Top`, `Latest`, `Photos`, `Videos`) |
+| `include_profile` | `true` | One extra upstream job for the subreddit/account avatar, banner, bio, follower count |
+| `include_comments` | `true` | Thread modes only — set `false` to skip the replies leg (and its cost) |
+| `save_raw` | `true` | Persist the untouched upstream pages as `raw-pages.json` |
+
+### Result
+
+Poll `GET /api/v1/primitives/jobs/:jobId` until `status: "succeeded"`, then read:
+
+- `items[]` — the normalized view. Each entry: `{ network, kind: "post" | "comment", id, title, text, created_at, permalink, link_url, author: { handle, name, avatar_url, banner_url, followers, profile_url, bio, verified }, stats: { … }, media: [{ type: "image"|"video"|"gif", url, thumbnail_url, width, height, duration_ms }] }`. X video media resolves to the **highest-bitrate MP4** variant, not the HLS manifest.
+- `profile` — the subreddit/account itself (avatar, banner, bio, subscriber/follower count).
+- `mediaUrls[]` — every media URL flattened, ready to drop into layers or feed to `videos/download`.
+- `nextCursor` — pass it back as `payload.cursor` to page further. `truncated: true` means there IS more.
+- `counts` — `{ items, posts, comments, media, pages, upstream_jobs, credits_charged }`.
+- `upstreamJobs[]` — one entry per lead-gen job we ran: `{ network, endpoint, job_id, status, tasks, credits_charged, view_url }`. **`view_url` opens a NocoDB spreadsheet of that pull — hand it to the human when they want to browse results visually.**
+- `recycled.json` (also `primary_file_url`) — the **complete** normalized payload. `items` in the job result is trimmed when it would blow the job-record size limit; `itemsTruncatedInline: true` tells you to read the artifact instead.
+- `raw-pages.json` — every untouched upstream page, so you can reach fields this primitive doesn't model.
+
+- Billing: wallet, metered on the **OfficeX credits the lead-gen apps actually consumed** (`officex_social_recycle`), converted at `OFFICEX_CREDIT_USD`. A one-task thread costs a fraction of a 10-page timeline. Paid plans only — free plans get `402`, same as the download routes. If the *upstream* app runs out of OfficeX credits you get a `402` naming that app, which is an operator problem, not a customer one.
+- devcli wrapper: `vidfarm recycle <source>` (aliases: `recycle-social`, `tweet-to-video`, `reddit-to-video`). Flags: `--max-records N`, `--cursor`, `--query`, `--filter hot|new|top`, `--mode`, `--network`, `--no-comments`, `--no-profile`, `--out ./recycled.json` (writes the FULL normalized payload to disk), `--no-wait`. It prints the counts, the upstream NocoDB `view_url`s, and the resume cursor.
+- Legs: a recycle runs 1–3 upstream jobs (profile, feed, replies) **sequentially**, so a failure on the first never pays for the second. The optional profile leg degrades rather than sinking the pull.
+- Timeouts: upstream polling gives up after `SOCIAL_RECYCLE_POLL_TIMEOUT_MS` (default 5 min); the upstream job may still finish and can be browsed in that app.
+
+### Turning a recycle into a video
+
+1. Recycle the source with a small `max_records` (25–50 is usually plenty for one video).
+2. Read `items[]` yourself and pick the beat: the post's hook line, the two funniest comments, the stat everyone reacted to.
+3. Pull any `media[].url` you want as real footage through `videos/download` or straight into a layer; use `profile.avatar_url` for the "who said this" badge.
+4. Script and build as normal. **The recycled text is source material, not a script** — rewrite it to the hook/loop/payoff standard rather than pasting a comment thread on screen.
+
+Example:
+
+```bash
+curl -X POST "$VIDFARM_BASE/api/v1/primitives/social/recycle" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"tracer": "demo-recycle", "payload": {"source_url": "https://www.reddit.com/r/wallstreetbets/comments/p0esdp/slug/", "max_records": 50}}'
+```
+
+```bash
+# An X account's recent posts, no replies, cheapest possible pull
+curl -X POST "$VIDFARM_BASE/api/v1/primitives/recycle-social" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"tracer": "demo-recycle-x", "payload": {"source_url": "https://x.com/elonmusk", "max_records": 40, "include_profile": true}}'
+```
+
 ## Primitive: video_remove_captions
 
 Remove burned-in captions/subtitles/on-screen text from any video URL (GhostCut-powered — the same pipeline auto-decompose uses for its caption-free mirror, exposed as a standalone reusable primitive). Result is a durable caption-free MP4 stored at a Vidfarm URL.

package/SKILL.director.md

@@ -210,6 +210,7 @@ Present both harnesses to the director, recommend (A) unless they've asked for p
 - **Stickers are usually animated, not pasted.** Once placed, animate each one with `vidfarm keyframes` presets (`pop-in`, `float`, `shake`, `grow`, `slide-in-left`, `drift`) — that's HTML/CSS canvas motion, deterministic, free, and identical in preview and render. Layer moves up (pop-in, then idle float) for real life. See `references/editor-workflows.md` → "Cutout graphics for explainers".
 - **A sticker can carry its OWN motion too.** A *moving* subject has no single bounding box, so it isn't a PNG: key the clip with `vidfarm remove-greenscreen <video>` → transparent WebM (browser/editor-playable, the right choice on a composition).
 - **The plate must be a color the ART DOESN'T USE — green is a default, not a law.** A chroma key removes exactly ONE color, so a green plate under green artwork (leaves, frogs, plants, money, an "eco" icon set) keys holes straight through the stickers. `sticker-pack`/`cutout` handle this for you in two ways, and you should still say it out loud when it matters: **(a)** when generating, they read the subject and move the plate off any hue it mentions — green → magenta (`#FF00FF`) → blue (`#0047BB`) → black → white — and print which plate they picked and why; **(b)** when splitting a sheet you already have, they **detect the plate from the sheet's four corners**, so a red/purple/blue sheet handed back from a web generator just works. Pin it yourself with `--key-color "#FF00FF"` / `--preset magenta` (that disables the auto-pick), or `--no-auto-key` to force plain green. If a pack's palette collides with *every* standard plate, split it into two sheets on two different plates rather than fighting the key.
+- **The ART must be CLOSED and SOLIDLY FILLED — this is the other half of surviving the key, and the #1 way stickers come back broken.** Ask an image model for "icons on a green plate" and it will happily draw **outline art**: a colored stroke with the shape's interior left as bare plate. It looks perfect on the sheet, and after the key each sticker is a **rim floating around a see-through hole** (an apple-shaped outline with nothing inside it). Same outcome from a *near-plate* fill (the keyer works on tolerance, not exact match), a translucent/glassy/glowing material, or a soft glow fading into the plate. **You cannot key those pixels back — it has to be in the prompt:** *"every object is a closed, solidly filled shape; outlines must enclose an opaque fill of a different color; no outline-only or hollow art; nothing on the art in the plate color or any near-shade of it; fully opaque, no translucency, glow or drop shadow."* `cutout --generate`, `sticker-pack --generate`, `handoff image` and the `create-overlay` primitive **append that clause for you** with the chosen plate hex — write it yourself only when you prompt a generator directly. After the key, both commands report per-item `hole_pct`/`hollow` (console `⚠ N% hollow`, `--json`, `stickers.json`) — a ring or picture frame reads the same way, so it **warns, never blocks**. Flagged and it shouldn't be? Re-generate with the fill clause; a *near*-plate fill can sometimes be rescued with a lower `--tolerance`; one stubborn item can be lifted with `vidfarm mask --crop …` (ONNX matting ignores fill color).
 - **Transparent GIF is supported, for GIF-only surfaces.** `vidfarm sticker-pack … --output-format gif` (stills) and `vidfarm remove-greenscreen <video> --gif` (animated) emit transparent GIFs. GIF alpha is **1-bit**, so edges go hard — fine for chat/forum/Notion sticker surfaces, worse than PNG/WebP/WebM for compositing on a timeline. Prefer PNG/WebP/WebM unless the destination only eats GIF.
 
 **Explainer house style — the defaults to build with unless told otherwise.** **White background / light mode** (plain white stage, no gradients, no dark mode, no photo backdrop), **kinetic word-by-word captions** in dark ink on the light stage (`vidfarm captions generate --style word-pop --color "#111111" --active-color "#7C3AED" --background-style plain` — skip outlines/shadows, they're only needed over busy footage), and **female TTS narration** (`vidfarm tts --voice coral` on OpenAI — `nova` for energy, `sage` for calm; `Kore`/`Leda` on Gemini; any ElevenLabs voice via `vidfarm voices`). **Keep it clean and simple** — one idea on screen at a time, two or three cutouts per beat, one accent color, one font, lots of white space; remove before you add. **Illustrations default to simplicity**: flat vector, simple shapes, minimal detail, 2–3 flat colors, no baked-in text — simple art keys cleanly, trims tight, and stays on-style across the whole cast. State the defaults once so the director can override any of them. Full detail: recipe `recipes/cutout-graphics-for-explainers.md` (“House style — the explainer defaults”).
@@ -317,6 +318,7 @@ Choose the narrowest path that satisfies the request.
 3. If the task is “change this video,” read `references/editor-workflows.md`.
 4. If the task is “find footage” or “use our existing assets,” read `references/assets-and-sourcing.md`.
 4b. If the task is **“download this video/audio off a website”** (a pasted YouTube / TikTok / Instagram / X post URL the user wants the actual file from), Vidfarm does that for you on a **paid plan** — `POST /api/v1/primitives/videos/download` (or `/audio/download`), devcli `vidfarm download-video <url>` / `vidfarm download-audio <url>`. **Free plan → do not call it; walk the user through opening the URL in Chrome and downloading it from the page, then `vidfarm put-file` the local file in for $0.** Details in `references/assets-and-sourcing.md` → `references/primitives.md`.
+4c. If the task is **“turn this Reddit/X thread, subreddit, or account into a video”** — “tweet to TikTok”, “Reddit to TikTok”, “make a video from this thread”, “what are the top comments saying” — run `vidfarm recycle <source>` (or `POST /api/v1/primitives/social/recycle`) with the URL. It **decomposes** the source into raw JSON (text, comment tree, media URLs, author pics, stats) and hands it back unranked so YOU pick what to remix. **Paid plan; `max_records` is the spend ceiling.** Brokers the reddit-lead-gen / x-lead-gen OfficeX apps, so it waits out their async job for you. Details in `references/assets-and-sourcing.md` → `references/primitives.md`.
 5. If the task is scripted, local, CI-driven, or `vidfarm serve`-based, read `references/automation-and-local-dev.md`.
 6. If the task explicitly asks for a primitive or needs specialized generation/transcription work, read `references/primitives.md`.
 7. If the task is the MARKETPLACE (ordering videos from specialist agents): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. Placing/listing orders is the thin REST wrapper in `references/core-workflows.md` (§ Marketplace); anything deeper on a gig (inbox, proofs, payouts) needs the external Dollar Platoon skill — `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`.
@@ -1247,7 +1249,7 @@ Beyond the Ken Burns / transition / animated-caption presets, the copilot can ha
 
 **Make the sticker (`vidfarm cutout`).** Local, free, ffmpeg-only, image-only. `vidfarm cutout --generate "<subject>"` AI-generates on a matching plate then keys+trims (only the generation is billed); `vidfarm cutout <file|url>` keys+trims a graphic you already have for $0. Because the output is trimmed tight, its on-frame **width % maps directly to how big the subject reads** — no invisible padding skewing the layout. Knobs: `--preset`/`--key-color` (match the plate), `--pad <px>` (transparent breathing room), `--alpha-threshold <0..255>` (trim faint haloed edges), `--output-format webp`, `--no-trim`. A *moving* subject has no single bounding box → key it as a clip with `vidfarm remove-greenscreen <video>` (→ transparent WebM) instead.
 
-**Make a whole PACK at once (`vidfarm sticker-pack`).** When the scene needs a *set* — props, icons, a cast, plus any backdrops — don't run `cutout` N times. Generate ONE greenscreen sheet holding every item and split it locally: `vidfarm sticker-pack --generate "<theme>" --items "a,b,c" --out-dir ./stickers` (one billed image job for the set), or `vidfarm sticker-pack ./sheet.png` for $0 on a sheet you already have. It keys the plate once, **segments the sheet's alpha channel to find each item automatically** (no hand-measured crop rects), trims each to its true box, and writes `stickers.json`. `--dry-run` to inspect the boxes; `--gap` to fix items that merged (lower) or split (raise). **Item size is unbounded** — a full-frame landscape/skyline/backdrop is as legitimate a sticker as a small icon, and belongs in the same sheet so it shares the cast's style. Recipe: `recipes/cutout-graphics-for-explainers.md` → "A sticker pack".
+**Make a whole PACK at once (`vidfarm sticker-pack`).** When the scene needs a *set* — props, icons, a cast, plus any backdrops — don't run `cutout` N times. Generate ONE greenscreen sheet holding every item and split it locally: `vidfarm sticker-pack --generate "<theme>" --items "a,b,c" --out-dir ./stickers` (one billed image job for the set), or `vidfarm sticker-pack ./sheet.png` for $0 on a sheet you already have. It keys the plate once, **segments the sheet's alpha channel to find each item automatically** (no hand-measured crop rects), trims each to its true box, and writes `stickers.json`. `--dry-run` to inspect the boxes; `--gap` to fix items that merged (lower) or split (raise). **Ask for solidly filled art** — outline-only/hollow shapes (or fills in a near-plate shade) get their interiors keyed away and composite as rims around transparent holes; the generation prompt says so automatically, and each item reports `⚠ N% hollow` / `hole_pct` after the key so you catch it before placing. **Item size is unbounded** — a full-frame landscape/skyline/backdrop is as legitimate a sticker as a small icon, and belongs in the same sheet so it shares the cast's style. Recipe: `recipes/cutout-graphics-for-explainers.md` → "A sticker pack".
 
 **Sticker formats.** Still sticker → **PNG** (or `--output-format webp` for smaller files). Sticker whose own artwork moves → **transparent WebM** via `vidfarm remove-greenscreen <video>` (ProRes `.mov` is the local fallback; `--cloud` always returns WebM). Sticker destined for a **GIF-only surface** (chat, forum, Notion, a shareable pack) → `--output-format gif` on `sticker-pack`, or `vidfarm remove-greenscreen <video> --gif` for an animated one; GIF alpha is 1-bit, so edges harden and soft shadows vanish — never the choice for compositing on a timeline.
 
@@ -1542,6 +1544,23 @@ Both are async primitive jobs — poll `GET /api/v1/primitives/jobs/:jobId` unti
 
 **Don't reach for this when the real goal is clips.** If the user wants short clips mined out of a long video, `POST /raws/scan` with `source_url` already downloads the source for you as part of the hunt (below) — a separate download call is wasted spend.
 
+## Recycle a Reddit or X source into content ("tweet to TikTok", "Reddit to TikTok")
+
+When the source isn't a video file but a **conversation** — a Reddit thread and its comments, a subreddit's front page, an X thread and its replies, an account's timeline — the download routes are the wrong tool. Use `vidfarm recycle <source>` (devcli) or `POST /api/v1/primitives/social/recycle` (alias `/recycle-social`), which **decomposes** the source into JSON you can remix:
+
+| Paste this | You get back |
+| --- | --- |
+| `reddit.com/r/<sub>/comments/<id>/...` | the post + its whole comment tree |
+| `reddit.com/r/<sub>` or `r/<sub>` | that subreddit's threads |
+| `x.com/<user>/status/<id>` | the tweet + self-thread + replies |
+| `x.com/<user>` or `@<user>` | that account's posts, pinned first |
+
+Every item carries text, author + `avatar_url`, timestamps, permalink, engagement stats, and **media URLs** (X video resolves to the top-bitrate MP4). It never summarizes or ranks — you read `items[]` and choose the hook, the punchline comment, the stat worth a card. `max_records` is your spend ceiling; `nextCursor` resumes. Paid plans only.
+
+Under the hood it brokers the **reddit-lead-gen** and **x-lead-gen** OfficeX apps rather than holding Reddit/X keys itself — so it's a job wrapping a job, and the primitive waits out the upstream job for you. Full payload/response reference in `references/primitives.md` → *Primitive: social/recycle*.
+
+Pipe it forward: any `media[].url` goes straight into a layer or through `videos/download`; `profile.avatar_url` makes the "who said this" badge. **Recycled text is source material, not a script** — rewrite it to the hook/loop/payoff standard instead of pasting a comment thread on screen.
+
 ## Public raws catalog — browse BY CATEGORY (check here first)
 
 Before you hunt footage and long before you generate it, check what the platform **already has**. The public raws catalog is a curated, pre-tagged, free-to-use pool of short clips, organised into **categories** (shelves) — and browsing it by category is one of the highest-leverage moves available to you, for two reasons:
@@ -1908,9 +1927,9 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm inpaint <image> --mask <png> --prompt "…" [--region "label=…"] [--ref …] [--out <f>]` | `POST /api/v1/primitives/images/inpaint` (polls job) | masked image EDIT — replace ONLY the transparent-mask region, keep everything else (devcli twin of the /inpaint page) |
 | `vidfarm create-overlay "<subject>" [--key-color #00FF00] [--aspect-ratio 1:1] [--place <dir>] [--out <f>]` | `POST /api/v1/primitives/images/create-overlay` (polls job) | **Vox-style** transparent OVERLAY — AI image on a forced key-color background, chroma-keyed out in one job → ready-to-composite transparent PNG |
 | `vidfarm remove-greenscreen <image\|video> [--preset green\|blue\|white\|black\|digital-green\|magenta] [--key-color #00FF00] [--tolerance 0.3] [--local] [--gif] [--out <f>]` | `POST /api/v1/primitives/remove-greenscreen` (polls job) | chroma-key a FLAT solid background → transparent PNG/WebP (image) or WebM/VP9-alpha (video); auto-detects media kind. `--local` runs it FREE in-process (sharp/ffmpeg, no wallet); default cloud is billed at real compute × 1.2. **`--gif` writes a transparent GIF instead** (ANIMATED for a clip; `--gif-fps`/`--gif-width`/`--gif-alpha`) — local-only, 1-bit alpha, for GIF-only sticker surfaces; prefer PNG/WebP/WebM for compositing. Aliases: `greenscreen`, `remove-background-greenscreen`. |
-| `vidfarm cutout <image\|url> [--generate "<prompt>"] [--preset green] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--out <f>]` | **local, free, ffmpeg-only** (no job) — key + `alphaextract`/`cropdetect` trim | **The transparent explainer-STICKER maker.** Keys out the flat plate **and then shrinks the canvas to the cutout's true min width/height** (a 1024² mostly-empty plate → a snug sticker whose pixel size IS the subject) so you can scale/position it precisely. `--generate` AI-generates the graphic first on a matching chroma plate (that step is the billed image primitive), then keys+trims in one shot; without it, keys+trims a file/url you already have. **IMAGE-only** (a moving subject has no single bounding box — key a clip with `remove-greenscreen`). Prefer this over `create-overlay` locally: same idea, but free and auto-trimmed. `--pad` keeps transparent breathing room; `--json` reports final `width`/`height`/`area_reduced_pct`. Alias: `sticker`. See recipe `cutout-graphics-for-explainers.md`. |
+| `vidfarm cutout <image\|url> [--generate "<prompt>"] [--preset green] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--out <f>]` | **local, free, ffmpeg-only** (no job) — key + `alphaextract`/`cropdetect` trim | **The transparent explainer-STICKER maker.** Keys out the flat plate **and then shrinks the canvas to the cutout's true min width/height** (a 1024² mostly-empty plate → a snug sticker whose pixel size IS the subject) so you can scale/position it precisely. `--generate` AI-generates the graphic first on a matching chroma plate (that step is the billed image primitive), then keys+trims in one shot; without it, keys+trims a file/url you already have. **IMAGE-only** (a moving subject has no single bounding box — key a clip with `remove-greenscreen`). Prefer this over `create-overlay` locally: same idea, but free and auto-trimmed. `--pad` keeps transparent breathing room; `--json` reports final `width`/`height`/`area_reduced_pct`, plus `hole_pct`/`hollow` — the "the key ate the fill" check (outline-only art keys into a rim around a transparent hole; `--generate` prompts against it automatically, and the console prints a `Hollow:` warning with the fix). Alias: `sticker`. See recipe `cutout-graphics-for-explainers.md`. |
 | `vidfarm mask <image\|url> [--crop x,y,w,h] [--flat <hex>] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--keep-region <f>] [--out <f>]` | **local, free** (no job) — ffmpeg crop + ONNX matting (or ffmpeg chroma-key) + `cropdetect` trim | **Lift an illustration OUT of an image you already have** (infographic / poster / marketing graphic / brand sheet / screenshot) → snug transparent PNG, the same reusable explainer sticker `cutout` makes but with **$0 and zero AI generation** — the cost-saving move whenever source art exists. `--crop x,y,w,h` (pixels **or** %) isolates ONE element from a multi-illustration source before masking (re-run with different rects to grab each). Background removed by **local ONNX matting** (any/busy background) by default, or **`--flat <hexcolor>`** chroma-keys a solid fill for crisper edges (an infographic's cream/white paper); then trims to the subject's true min width/height. **IMAGE-only** (matte a clip with `remove-background`). Aliases: `isolate`, `extract`. See recipe `cutout-graphics-for-explainers.md` → "Mask from an image you already have". |
-| `vidfarm sticker-pack [sheet\|url] [--generate "<theme>"] [--items "a,b,c"] [--count <n>] [--dry-run] [--gap <pct>] [--min-area <pct>] [--output-format png\|webp\|gif] [--out-dir <d>]` | **local, free, ffmpeg-only** (no job; only `--generate` bills, ONCE for the whole set) — key + alpha-channel segmentation + per-item trim | **The STICKER-PACK maker — the answer whenever a director asks for "a sticker pack" / prop set / icon set.** A pack is ONE greenscreen sheet holding every item, keyed once and then masked apart: 1/N the cost of N `cutout` calls, and the only way a cast stays on-style. Finds each item **automatically** by segmenting the keyed sheet's alpha into connected islands — no hand-measured `--crop` rects — and writes one snug transparent file per item (named from `--items`, reading order) plus a `stickers.json` manifest. `--dry-run` prints the detected boxes first; `--gap` merges (lower) or splits (raise) items that came out joined/broken; items have **no maximum size** — a full-frame landscape/backdrop is as valid a sticker as a 3% icon. **Plate color is chosen for you:** when generating it reads the subject and moves the plate off any hue the art uses (green → magenta → blue → black → white — a pack of leaves/frogs/money on GREEN would key holes through the art), and when splitting an existing sheet it DETECTS the plate from the sheet's four corners, so a red/purple sheet handed back from a web tool just works. Pin it with `--key-color`/`--preset`, or `--no-auto-key` for plain green. `--output-format gif` emits 1-bit-alpha GIFs for GIF-only surfaces. IMAGE-only. Aliases: `stickers`, `sticker-sheet`. See recipe `cutout-graphics-for-explainers.md` → "A sticker pack". |
+| `vidfarm sticker-pack [sheet\|url] [--generate "<theme>"] [--items "a,b,c"] [--count <n>] [--dry-run] [--gap <pct>] [--min-area <pct>] [--output-format png\|webp\|gif] [--out-dir <d>]` | **local, free, ffmpeg-only** (no job; only `--generate` bills, ONCE for the whole set) — key + alpha-channel segmentation + per-item trim | **The STICKER-PACK maker — the answer whenever a director asks for "a sticker pack" / prop set / icon set.** A pack is ONE greenscreen sheet holding every item, keyed once and then masked apart: 1/N the cost of N `cutout` calls, and the only way a cast stays on-style. Finds each item **automatically** by segmenting the keyed sheet's alpha into connected islands — no hand-measured `--crop` rects — and writes one snug transparent file per item (named from `--items`, reading order) plus a `stickers.json` manifest. `--dry-run` prints the detected boxes first; `--gap` merges (lower) or splits (raise) items that came out joined/broken; items have **no maximum size** — a full-frame landscape/backdrop is as valid a sticker as a 3% icon. **Plate color is chosen for you:** when generating it reads the subject and moves the plate off any hue the art uses (green → magenta → blue → black → white — a pack of leaves/frogs/money on GREEN would key holes through the art), and when splitting an existing sheet it DETECTS the plate from the sheet's four corners, so a red/purple sheet handed back from a web tool just works. Pin it with `--key-color`/`--preset`, or `--no-auto-key` for plain green. **The ART is made key-safe too:** the generation prompt is auto-appended with "closed, solidly filled shapes, no outline-only/hollow art, nothing in the plate hue or a near-shade, fully opaque, no glow/translucency" — the fix for stickers that come back as a rim around a transparent hole — and after keying each item reports `holes`/`hole_pct`/`hollow` (console `⚠ N% hollow` at ≥20%, plus `--json` and `stickers.json`). It **warns, never blocks** (a ring/frame/donut reads identically); re-generate with the fill clause, or lift that one item with `vidfarm mask --crop …`. `--output-format gif` emits 1-bit-alpha GIFs for GIF-only surfaces. IMAGE-only. Aliases: `stickers`, `sticker-sheet`. See recipe `cutout-graphics-for-explainers.md` → "A sticker pack". |
 | `vidfarm tts "…" [--style "…"] [--voice <v>] [--out <file>]` | (LOCAL-FIRST: your own OPENAI/GEMINI/OPENROUTER_API_KEY → audio file on disk; `--cloud` = `POST /api/v1/primitives/audio/speech` + poll, ElevenLabs on the platform key by default, `--own-key` for yours) | text → narration audio; `--cloud --voice <voice_id>` picks an ElevenLabs voice |
 | `vidfarm music "<prompt>" [--length <sec>] [--out <f>] [--own-key]` | `POST /api/v1/primitives/music/generate` (polls job) | prompt → music track (ElevenLabs; platform key + wallet by default, `--own-key` for yours) |
 | `vidfarm voices [--own-key] [--limit N]` | `GET /api/v1/primitives/audio/voices` | list ElevenLabs voices (voice_id/name/labels) for `tts --voice`; default a voice + tell the user they can choose |
@@ -1939,7 +1958,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm whoami` | `GET /api/v1/user/me` | who am I (also prints the active cost mode) |
 | `vidfarm cost-mode [minimize\|hybrid\|rich-ai\|pure-videogen]` | (local `~/.vidfarm/cost-mode.json`) | show/set the money-saving preference every billed command respects; no arg = show + explain each; `--clear` forgets it |
 | `vidfarm mode [interactive\|autonomous]` | local (`~/.vidfarm/interaction-mode.json`) | **The SECOND preference axis — ask it alongside cost mode.** Is the human in the loop? `interactive` = at checkpoints you hand them a copy-paste brief (an image prompt for a FREE web generator; a keyword list for sourcing clips) and they hand files back — usually BETTER output, and in `minimize` the only way to get custom art at all. `autonomous` = you finish solo within the budget. Independent of cost mode: every cost mode runs either way. No arg prints the pair + the explainer to relay; `--clear` forgets; per-run `--interactive`/`--autonomous`. Aliases: `interaction-mode`, `interaction`. |
-| `vidfarm handoff image --theme "<what>" [--items "a,b,c"] [--style …] [--single]` | local (pure text) | **The interactive-mode IMAGE brief.** Prints the exact prompt, the numbered steps, the free tools (meta.ai / ChatGPT / Gemini / HF Spaces) and the follow-up command. Defaults to a **sticker pack**: ONE sheet holding every item on a chroma plate → `vidfarm sticker-pack` splits it for $0. Picks a plate the art won't collide with (green art → magenta plate) and carries that `--key-color` into the follow-up. `--single` for one subject. |
+| `vidfarm handoff image --theme "<what>" [--items "a,b,c"] [--style …] [--single]` | local (pure text) | **The interactive-mode IMAGE brief.** Prints the exact prompt, the numbered steps, the free tools (meta.ai / ChatGPT / Gemini / HF Spaces) and the follow-up command. Defaults to a **sticker pack**: ONE sheet holding every item on a chroma plate → `vidfarm sticker-pack` splits it for $0. Picks a plate the art won't collide with (green art → magenta plate), spells out the **key-safe fill rules** (closed solidly-filled shapes, no outline-only/hollow art, nothing in a near-plate shade, fully opaque) so the sheet doesn't come back as rims around holes, and carries that `--key-color` into the follow-up. `--single` for one subject. |
 | `vidfarm handoff raws --keywords "a,b" [--platforms tiktok,youtube] [--count N] [--purpose "…"]` | local (pure text) | **The interactive-mode CLIP-SOURCING brief** — the bottom rung of the sourcing ladder (browser control → `clipper`/`raws scan --cloud` → public raws → the human). Prints what to search, how to download (a Google *search* for a downloader, never a link that rots), and the import command for when the folder is ready. |
 | `vidfarm storyboard [dir] [--init] [--frames "Title\|scene,…"] [--json]` | local (`STORYBOARD.md` / `SCRIPT.md`) | **The plan pass, and a core part of the composition format.** Scaffolds/reads the project's `STORYBOARD.md`: ordered frames with `duration`/`status`/`src`/`scene`/`voiceover`. The Vidfarm editor renders this file in its **Storyboard** view (contact sheet + per-frame comments + `outline → built → animated` progress), so it's the cheapest place to get a director's approval before building. Not to be confused with `vidfarm sequence` (which GENERATES storyboard images for the pure-videogen pipeline). Alias: `plan`. |
 | `vidfarm wallet [--job <id>\|--tracer <t>] [--limit <n>]` | `GET /api/v1/user/me/wallet` | cost log: balance + lifetime spend + recent charges. `--job <renderJobId>` prints **what that one video cost** (sums its charges); `--tracer <t>` sums a tracer. Cloud-only; readable on the free plan too (shows $0.00). Aliases: `spend`, `costs` |
@@ -1948,6 +1967,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm download <url> [dest]` | (streams any URL to disk) | download media from a **direct** media URL. Free — no plan, no job |
 | `vidfarm download-video <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | **download a video FROM A WEBSITE** (YouTube/TikTok/IG/X/other supported posts) into durable Vidfarm media; photo/carousel posts return an ordered slideshow. **PAID PLAN** (wallet-billed resolver; free plans get 402). Aliases: `download-post`, `download-url` |
 | `vidfarm download-audio <url>` | `POST /api/v1/primitives/audio/download` + poll | download just the AUDIO track (music/voice) off a website post into a durable audio file. **PAID PLAN**. Alias: `download-post-audio` |
+| `vidfarm recycle <source>` | `POST /api/v1/primitives/social/recycle` + poll | RECYCLE a Reddit/X source into reusable JSON ("tweet to tiktok", "reddit to tiktok"): thread + comments, subreddit threads, X thread + replies, or an account's posts — text, author + avatar, stats, media URLs. `--out` saves the full payload. **PAID PLAN**. Aliases: `recycle-social`, `tweet-to-video`, `reddit-to-video` |
 
 > **Free plan / `cost-mode minimize`:** both download commands are gated by `guardBilled` and will refuse or warn. The free path is **Chrome**: open the URL in a real browser, save the file off the page (right-click → *Save video as*, downloads pane, or a Googled `"<platform> video downloader"` site), then `vidfarm put-file ./the-file.mp4 --folder <folder>` to bring it in for $0. The CLI prints these steps on a 402. Never tell a free user the video simply can't be downloaded.
 | `vidfarm files [--folder <path>]` | `GET /api/v1/user/me/attachments` | list My Files assets + folders |
@@ -2225,7 +2245,7 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/images/remove-background" \
 
 - `POST /api/v1/primitives/images/create-overlay` (flat alias: `POST /api/v1/primitives/create-media-overlay`)
 - Body: `{ "tracer": "...", "payload": { "prompt": "a cartoon rocket ship, flat vector illustration", "provider"?: "...", "model"?: "...", "prompt_attachments"?: ["https://..."], "aspect_ratio"?: "1:1", "image_size"?: "1K"|"2K"|"4K", "key_color"?: "#00FF00", "tolerance"?: 0.3, "softness"?: 0.1, "despill"?: true, "output_format"?: "png"|"webp" }, "webhook_url"?: "..." }`
-  - Just describe the **subject** in `prompt` — do NOT describe the background; the primitive appends the flat key-color background requirement for you.
+  - Just describe the **subject** in `prompt` — do NOT describe the background; the primitive appends the flat key-color background requirement for you, **and** the key-safe *artwork* requirement (closed solidly-filled shapes, no outline-only/hollow art, nothing on the subject in the key hue or a near-shade, fully opaque, no glow/translucency). That second clause is what stops the classic failure: outline art whose interior is bare plate keys into a **rim around a transparent hole**. If you build the prompt yourself for `images/generate` instead of using this primitive, write that clause in by hand.
   - `key_color` lets you key against something other than green if your subject is itself green-heavy (e.g. key against `#FF00FF` magenta for a green frog).
   - The chroma-key params (`tolerance`/`softness`/`despill`) behave exactly as in `image_remove_background_greenscreen`.
 - Response: `primary_file_url` is the finished transparent overlay; `greenscreen_source_url` is the raw pre-key frame (kept so you can re-key at a different tolerance without paying for another generation).
@@ -2326,6 +2346,85 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/audio/download" \
   -d '{"tracer": "demo-download-audio", "payload": {"source_url": "https://www.youtube.com/watch?v=example"}}'
 ```
 
+## Primitive: social/recycle
+
+**"Tweet to TikTok" and "Reddit to TikTok" live here.** The text-and-thread sibling of `videos/download`: point it at a Reddit or X/Twitter source and it **decomposes** that source into reusable JSON — the post text, the comment/reply thread, every image/video media URL, the author's profile pic and follower count, and the engagement stats — so YOU decide what to recycle into a new video. It deliberately does **not** summarize, rank, score, or filter. It dumps the data back raw.
+
+**Vidfarm does not hold Reddit/X vendor keys.** This primitive is a thin broker over the two OfficeX apps that already own that integration — **reddit-lead-gen** and **x-lead-gen** — called through their public REST job API. They own the vendor keys, retries, rate-limit budget, auto-pagination, and 90-day result storage; vidfarm owns target resolution, normalization, and the wallet charge. Both are async job APIs, so a recycle is **a job wrapping a job** — but the nesting is invisible: this primitive polls upstream to completion server-side and only resolves when the data is in hand, exactly like the GhostCut leg of `videos/remove-captions`. You poll `GET /api/v1/primitives/jobs/:jobId` like any other primitive.
+
+- `POST /api/v1/primitives/social/recycle` (alias: `POST /api/v1/primitives/recycle-social`)
+- Body: `{ "tracer": "...", "payload": { "source_url": "https://..." }, "webhook_url"?: "..." }`
+
+### The four shapes
+
+| You pass | Mode (auto-detected) | You get |
+| --- | --- | --- |
+| `https://reddit.com/r/<sub>/comments/<id>/...` | `reddit_thread` | the post + its comment tree, flattened in reading order |
+| `https://reddit.com/r/<sub>` (or `r/<sub>`) | `reddit_channel` | that subreddit's threads, paginated |
+| `https://x.com/<user>/status/<id>` | `twitter_thread` | the tweet + the author's self-thread + its replies, paginated |
+| `https://x.com/<user>` (or `@<user>`) | `twitter_channel` | that account's tweets (pinned first), paginated |
+
+A fifth mode, `reddit_user` (`https://reddit.com/user/<name>` or `u/<name>`), returns a redditor's posts and comments. Pass `mode` explicitly to override auto-detection, or `handle` + `network` instead of a URL.
+
+### Payload
+
+| Field | Default | Notes |
+| --- | --- | --- |
+| `source_url` | — | Reddit/X URL. Required unless you pass `handle` + `network`. Aliases: `url`, `thread_url`, `profile_url` |
+| `handle` + `network` | — | `{ "handle": "wallstreetbets", "network": "reddit" }`. Aliases for handle: `username`, `screenname`, `subreddit` |
+| `mode` | auto | Override the detected shape |
+| `max_records` | `100` | Cap on records (1–1000). The lead-gen apps auto-paginate to reach it and reserve credits for `ceil(max_records / 25)` pages — **this is your spend ceiling** |
+| `cursor` | — | Resume token from a previous run's `nextCursor` |
+| `prompt_filter` | — | Hand the lead-gen app a Gemini scoring prompt; adds `match_score` + `ai_notes` per item and costs slightly more per task upstream. We surface it and never act on it |
+| `query` | — | Restrict a channel pull to matching posts (Reddit search / X `from:<user> <query>`) |
+| `filter` / `sort` / `time_filter` | — | Reddit listing controls (`hot`, `new`, `top`, …) |
+| `search_type` | — | X search mode (`Top`, `Latest`, `Photos`, `Videos`) |
+| `include_profile` | `true` | One extra upstream job for the subreddit/account avatar, banner, bio, follower count |
+| `include_comments` | `true` | Thread modes only — set `false` to skip the replies leg (and its cost) |
+| `save_raw` | `true` | Persist the untouched upstream pages as `raw-pages.json` |
+
+### Result
+
+Poll `GET /api/v1/primitives/jobs/:jobId` until `status: "succeeded"`, then read:
+
+- `items[]` — the normalized view. Each entry: `{ network, kind: "post" | "comment", id, title, text, created_at, permalink, link_url, author: { handle, name, avatar_url, banner_url, followers, profile_url, bio, verified }, stats: { … }, media: [{ type: "image"|"video"|"gif", url, thumbnail_url, width, height, duration_ms }] }`. X video media resolves to the **highest-bitrate MP4** variant, not the HLS manifest.
+- `profile` — the subreddit/account itself (avatar, banner, bio, subscriber/follower count).
+- `mediaUrls[]` — every media URL flattened, ready to drop into layers or feed to `videos/download`.
+- `nextCursor` — pass it back as `payload.cursor` to page further. `truncated: true` means there IS more.
+- `counts` — `{ items, posts, comments, media, pages, upstream_jobs, credits_charged }`.
+- `upstreamJobs[]` — one entry per lead-gen job we ran: `{ network, endpoint, job_id, status, tasks, credits_charged, view_url }`. **`view_url` opens a NocoDB spreadsheet of that pull — hand it to the human when they want to browse results visually.**
+- `recycled.json` (also `primary_file_url`) — the **complete** normalized payload. `items` in the job result is trimmed when it would blow the job-record size limit; `itemsTruncatedInline: true` tells you to read the artifact instead.
+- `raw-pages.json` — every untouched upstream page, so you can reach fields this primitive doesn't model.
+
+- Billing: wallet, metered on the **OfficeX credits the lead-gen apps actually consumed** (`officex_social_recycle`), converted at `OFFICEX_CREDIT_USD`. A one-task thread costs a fraction of a 10-page timeline. Paid plans only — free plans get `402`, same as the download routes. If the *upstream* app runs out of OfficeX credits you get a `402` naming that app, which is an operator problem, not a customer one.
+- devcli wrapper: `vidfarm recycle <source>` (aliases: `recycle-social`, `tweet-to-video`, `reddit-to-video`). Flags: `--max-records N`, `--cursor`, `--query`, `--filter hot|new|top`, `--mode`, `--network`, `--no-comments`, `--no-profile`, `--out ./recycled.json` (writes the FULL normalized payload to disk), `--no-wait`. It prints the counts, the upstream NocoDB `view_url`s, and the resume cursor.
+- Legs: a recycle runs 1–3 upstream jobs (profile, feed, replies) **sequentially**, so a failure on the first never pays for the second. The optional profile leg degrades rather than sinking the pull.
+- Timeouts: upstream polling gives up after `SOCIAL_RECYCLE_POLL_TIMEOUT_MS` (default 5 min); the upstream job may still finish and can be browsed in that app.
+
+### Turning a recycle into a video
+
+1. Recycle the source with a small `max_records` (25–50 is usually plenty for one video).
+2. Read `items[]` yourself and pick the beat: the post's hook line, the two funniest comments, the stat everyone reacted to.
+3. Pull any `media[].url` you want as real footage through `videos/download` or straight into a layer; use `profile.avatar_url` for the "who said this" badge.
+4. Script and build as normal. **The recycled text is source material, not a script** — rewrite it to the hook/loop/payoff standard rather than pasting a comment thread on screen.
+
+Example:
+
+```bash
+curl -X POST "$VIDFARM_BASE/api/v1/primitives/social/recycle" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"tracer": "demo-recycle", "payload": {"source_url": "https://www.reddit.com/r/wallstreetbets/comments/p0esdp/slug/", "max_records": 50}}'
+```
+
+```bash
+# An X account's recent posts, no replies, cheapest possible pull
+curl -X POST "$VIDFARM_BASE/api/v1/primitives/recycle-social" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"tracer": "demo-recycle-x", "payload": {"source_url": "https://x.com/elonmusk", "max_records": 40, "include_profile": true}}'
+```
+
 ## Primitive: video_remove_captions
 
 Remove burned-in captions/subtitles/on-screen text from any video URL (GhostCut-powered — the same pipeline auto-decompose uses for its caption-free mirror, exposed as a standalone reusable primitive). Result is a durable caption-free MP4 stored at a Vidfarm URL.
@@ -2680,7 +2779,7 @@ The mechanical trio — **generate on a chroma plate → key it out → trim to
 - **Female TTS narration.** Default to a warm, friendly **female** voice and say which one you picked: local-first `vidfarm tts "<script>" --voice coral` (OpenAI — `nova` if the script wants more energy, `sage` for calmer), `--voice Kore` or `Leda` on Gemini, or `vidfarm voices` → `vidfarm tts --cloud --voice <voice_id>` on ElevenLabs. Tell the director they can swap it in one flag.
 - **Clean and simple wins.** One idea on screen at a time. Two or three cutouts per beat, not eight. Generous white space, one accent color, one font. When in doubt, remove an element rather than add one.
 
-**Illustrations default to simplicity.** Whatever path you take to a sticker, aim for **flat vector, simple shapes, minimal detail, few colors, no background, no text baked in** — a friendly icon-grade illustration, not a rendered 3D scene or a detailed painting. Simple art keys cleanly, trims tight, scales without mush, animates readably at 9:16, and stays on-style across a whole cast. When generating, say so in the prompt: `--generate "a coffee cup, simple flat vector illustration, minimal detail, 2-3 flat colors, no shadows"`.
+**Illustrations default to simplicity — and to SOLID FILLS.** Whatever path you take to a sticker, aim for **flat vector, simple shapes, minimal detail, few colors, solid opaque fills, no background, no text baked in** — a friendly icon-grade illustration, not a rendered 3D scene or a detailed painting. Simple art keys cleanly, trims tight, scales without mush, animates readably at 9:16, and stays on-style across a whole cast. "Solid fills" is the load-bearing word: **outline-only art has its interior keyed away and comes back as a rim around a transparent hole** (see "Then make the ART key-safe too" below). When generating, say so in the prompt: `--generate "a coffee cup, simple flat vector illustration, minimal detail, 2-3 flat colors, solid filled shapes (not outline-only), no shadows"`.
 
 **In cost-saving mode, don't generate illustrations at all — mask them out of images the director already has.** If `vidfarm cost-mode` is `minimize` (or the director says "without burning credits"), the default for adding an illustration is `vidfarm mask <their-image> --crop …` — lifting art out of an infographic, poster, deck slide, brand sheet, or screenshot for **$0 and zero AI calls**. Ask for source art before you ask for a generation budget; the guided loop is **"Mask from an image you already have"** below. **If no source art exists and the graphic must be custom, you still don't have to spend** — hand the director a prompt for a **free** image generator (meta.ai / free ChatGPT / a Hugging Face Space) and cut the returned sheet into stickers locally: **"Free manual image-gen"** below.
 
@@ -2725,6 +2824,20 @@ Out comes `./stickers/sticker-01-red-barn.png`, `sticker-02-tractor.png`, … ea
 
 Override whenever you know better: `--key-color "#FF00FF"` or `--preset magenta` pins the plate (and turns the auto-pick off); `--no-auto-key` forces plain green. If a pack's palette collides with *every* standard plate — a rainbow icon set — split it across two sheets on two different plates rather than fighting `--tolerance`. And when a sticker is a *green* subject, never let the user generate it on green: the hand-off brief (`vidfarm handoff image`) already picks the plate for them and carries the matching `--key-color` into the follow-up command.
 
+**Then make the ART key-safe too — CLOSED, SOLIDLY FILLED shapes.** Picking the right plate is only half of surviving the key. The other half is the failure you actually see in the wild: you ask for "sticker icons on a green plate" and the model draws **outline art** — a colored stroke with the shape's *interior left as bare plate*. On the sheet it looks perfect. After the key, the interior is gone with the background, and every sticker composites as a **rim floating around a see-through hole** (an apple that's just an apple-shaped outline, a clock with no face). Same result from three cousins: a fill that's a *near-shade* of the plate (the keyer works on tolerance, not exact match), a **translucent/glassy/glowing** material that lets the plate through, and a **soft glow or drop shadow** that fades into the plate at the edges.
+
+None of that is fixable after generation — you cannot key back pixels that were never drawn. So it belongs in the **prompt**, every time:
+
+> Every object must be a CLOSED, SOLIDLY FILLED shape — outlines and strokes must enclose an opaque fill of a different color. No outline-only, hollow, or line-art objects; never leave a shape's interior as bare background. No part of any object — fill, outline, highlight, gradient, shading or detail — may be `<PLATE HEX>` or any near-shade, tint or tone of it. No transparent, translucent, glassy, glowing or ghosted materials; every pixel of every object is fully opaque. No soft glows, blurs or drop shadows fading into the background. Keep the whole palette in strong contrast to `<PLATE HEX>`. The background must be visible ONLY around the outside of the objects, never showing through inside them.
+
+`cutout --generate`, `sticker-pack --generate`, `vidfarm handoff image`, and the `create-overlay` REST primitive all append that clause automatically with the chosen plate hex substituted in — **you only have to write it yourself when you're prompting a generator directly** (a free web tool by hand, or your own `POST /api/v1/primitives/images/generate` call). Do write it. It costs one paragraph and it is the difference between a usable pack and a re-generation.
+
+**And it's checked after the key.** `sticker-pack` and `cutout` measure, per item, the transparent area **fully enclosed by that item's own art** and report it as `hole_pct` (plus `holes`, and `hollow: true` at ≥20%) in `--json`, in `stickers.json`, and as a `⚠ N% hollow` flag on the console line. A ring, donut, picture frame or letter "O" reads the same way, so it **warns, never blocks** — the judgement is yours. When items you expected to be solid come back flagged:
+
+- **Re-generate the sheet** with the fill clause above spelled out. This is the fix ~90% of the time.
+- If the fill was merely *close* to the plate rather than absent, a lower `--tolerance` can rescue the sheet you already have. Nothing rescues a genuinely empty interior.
+- Last resort for one stubborn item: `vidfarm mask ./sheet.png --crop x,y,w,h` — ONNX matting doesn't care what color the fill is, so it lifts art the chroma key can't.
+
 **Generation is the failure point, not the cutting.** The sheet prompt is auto-appended with the important instruction — *every item fully separated by clear plate-colored background, nothing touching or overlapping, wide margins, no text, no shadows, one consistent style* — because **touching items segment as one sticker**. If a pack comes back merged, re-run the generation asking for more spacing before you fight the `--gap` knob.
 
 ### Stickers are not necessarily small — and they usually move
@@ -2841,15 +2954,15 @@ Everything here is **local and free** — crop, matte/key, and trim are all `ffm
 
 1. **List the cast.** Name every illustration the explainer needs, in the house style (flat vector, 2–3 flat colors, no baked-in text).
 2. **Hand the director this prompt**, filled in:
-   > A flat vector illustration sheet on a solid pure green background (#00FF00), no gradient, no shadow, no text, no labels. Arranged in a 3×2 grid with generous even spacing, each object fully separated and not touching any other object or the image edge: (1) `<object one>`, (2) `<object two>`, (3) `<object three>`, … Simple flat shapes, 2–3 flat colors, minimal detail, consistent style and line weight across all objects, front-facing, centered in its own cell. Square image, high resolution.
+   > A flat vector illustration sheet on a solid pure green background (#00FF00), no gradient, no shadow, no text, no labels. Arranged in a 3×2 grid with generous even spacing, each object fully separated and not touching any other object or the image edge: (1) `<object one>`, (2) `<object two>`, (3) `<object three>`, … Simple flat shapes, 2–3 flat colors, minimal detail, consistent style and line weight across all objects, front-facing, centered in its own cell. **Every object is a closed, solidly filled shape — outlines must enclose an opaque fill of a different color; no outline-only or hollow objects, and no object's interior left as bare green. Nothing on any object may be green or any near-shade of green; no transparent, translucent, glassy or glowing materials; no soft glows or drop shadows fading into the background.** Square image, high resolution.
 
-   **No text in the image, ever** — rendered text never keys or scales cleanly; add copy as a caption or HTML layer instead.
+   **No text in the image, ever** — rendered text never keys or scales cleanly; add copy as a caption or HTML layer instead. **And don't drop the bolded fill sentence** — the green gets deleted, so anything green *on* the art gets deleted with it; hollow outline art is the single most common way a hand-generated sheet comes back broken. (`vidfarm handoff image --theme … --items …` mints this whole brief with the plate and the fill clause already filled in — prefer it over typing the prompt yourself.)
 3. **Bring the sheet in:** `vidfarm put-file ./sheet.png` (or drag into **My Files** in the web app).
 4. **Split it into stickers — one command, all free:**
    ```
    vidfarm sticker-pack ./sheet.png --items "<object one>,<object two>,…" --out-dir ./stickers
    ```
-   It keys the flat green, finds each object in the alpha channel, and writes one trimmed transparent sticker per object (named from `--items`) plus `stickers.json`. Run it with `--dry-run` first to check the boxes. Two objects merged into one? The generator drew them too close — lower `--gap`, or grab that pair by hand:
+   It keys the flat green, finds each object in the alpha channel, and writes one trimmed transparent sticker per object (named from `--items`) plus `stickers.json`. Run it with `--dry-run` first to check the boxes. Any item flagged **`⚠ N% hollow`** came back as an outline around a transparent hole — unless it's genuinely a ring/frame, re-ask the director for that sheet with the fill sentence, or lift that one item with `vidfarm mask ./sheet.png --crop x,y,w,h` (ONNX matting doesn't care what the fill color is). Two objects merged into one? The generator drew them too close — lower `--gap`, or grab that pair by hand:
    ```
    vidfarm mask ./sheet.png --crop 4%,4%,29%,45% --flat "#00FF00" --out prop-a.png
    ```

package/SKILL.md

@@ -41,7 +41,7 @@ The last two are production *methods*, not just budgets. **rich-ai**: generate t
 
 **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 chroma plate** with no text (`#00FF00` green by default — but pick a different plate when the art itself is green, or the key will punch holes through it) — one round trip instead of many, which is the token-efficient move. Then split it locally at $0 in one command: `vidfarm sticker-pack ./sheet.png --items "a,b,c" --out-dir ./stickers` keys the green out, finds each item in the sheet automatically, and writes a snug transparent sticker per item. Prompt template + full loop in the director skill.
 
-**"Make me a sticker pack" = one greenscreen sheet, then masked apart.** A pack is a *set* that has to share one art style, so never generate the items one by one — generate a single image holding all of them on a flat `#00FF00` plate, then split it: `vidfarm sticker-pack --generate "<theme>" --items "a,b,c,d"` (one billed image job for the whole set, then free local keying + automatic alpha segmentation + per-item trim + a `stickers.json` manifest). **The plate must be a color the art doesn't use** — a green pack (leaves, frogs, plants, money) on a green plate keys holes through the art. The commands pick the plate off the subject when generating (green → magenta → blue → black → white, and they tell you when they move) and **detect the plate from an existing sheet's corners**, so a red or purple sheet from a web tool just works; pin it with `--key-color`/`--preset`, or `--no-auto-key` for plain green. Stickers are **not necessarily small** — a full-frame landscape or backdrop is as valid an item as an icon — and they're normally **animated on the canvas** (`vidfarm place` + `vidfarm keyframes` presets: pop-in, float, shake, grow, slide-in, drift). A sticker whose own art moves is a **transparent WebM** (`vidfarm remove-greenscreen <video>`), and for GIF-only surfaces both paths can emit **transparent GIFs** (`sticker-pack --output-format gif`, `remove-greenscreen --gif`, 1-bit alpha). Full recipe in the director skill.
+**"Make me a sticker pack" = one greenscreen sheet, then masked apart.** A pack is a *set* that has to share one art style, so never generate the items one by one — generate a single image holding all of them on a flat `#00FF00` plate, then split it: `vidfarm sticker-pack --generate "<theme>" --items "a,b,c,d"` (one billed image job for the whole set, then free local keying + automatic alpha segmentation + per-item trim + a `stickers.json` manifest). **The plate must be a color the art doesn't use** — a green pack (leaves, frogs, plants, money) on a green plate keys holes through the art. The commands pick the plate off the subject when generating (green → magenta → blue → black → white, and they tell you when they move) and **detect the plate from an existing sheet's corners**, so a red or purple sheet from a web tool just works; pin it with `--key-color`/`--preset`, or `--no-auto-key` for plain green. **And the art itself must be closed and solidly filled** — outline-only/hollow art (or a near-plate fill, or anything translucent/glowing) has its interior keyed away and composites as a rim around a see-through hole. The generation prompts say so for you; write it in by hand when you prompt a generator directly, and check the `⚠ N% hollow` / `hole_pct` flag each command reports after keying. Stickers are **not necessarily small** — a full-frame landscape or backdrop is as valid an item as an icon — and they're normally **animated on the canvas** (`vidfarm place` + `vidfarm keyframes` presets: pop-in, float, shake, grow, slide-in, drift). A sticker whose own art moves is a **transparent WebM** (`vidfarm remove-greenscreen <video>`), and for GIF-only surfaces both paths can emit **transparent GIFs** (`sticker-pack --output-format gif`, `remove-greenscreen --gif`, 1-bit alpha). Full recipe in the director skill.
 
 ## Ask the second question too — interactive or autonomous?
 
@@ -101,6 +101,7 @@ For composition *authoring* craft (motion, keyframes, scene design), Vidfarm shi
 3. "Change / re-theme this video" → `references/editor-workflows.md`
 4. "Find footage / use our assets" → `references/assets-and-sourcing.md`
 4b. **"Download this video/audio from <a website URL>"** → Vidfarm fetches it for you on a **paid plan**: `POST /api/v1/primitives/videos/download` (or `/audio/download`); devcli `vidfarm download-video <url>` / `vidfarm download-audio <url>`. Works on YouTube, TikTok, Instagram, X, and other supported posts; returns a durable Vidfarm file (photo/carousel posts → an ordered slideshow). **Free plan gets a 402 — don't call it. Tell the user (or, with browser automation, do it yourself) to open the URL in Chrome and download it from the page, then `vidfarm put-file ./the-file.mp4` to bring it in for $0.** Never answer "I can't download that." Details: `references/assets-and-sourcing.md`.
+4b-ii. **"Tweet to TikTok" / "Reddit to TikTok" / "make a video out of this thread / subreddit / account"** → `vidfarm recycle <source>` (devcli), or `POST /api/v1/primitives/social/recycle` with `{ tracer, payload: { source_url, max_records } }`. It **decomposes** a Reddit thread (post + comments), a subreddit (its threads), an X thread (tweet + replies), or an X profile (their posts) into raw JSON — text, comment tree, media URLs, author avatar, engagement stats — and hands it back **unranked and unsummarized** so you pick the hook, the punchline comment, the stat. Auto-paginates via `nextCursor`; `max_records` is the spend ceiling. Brokers the reddit-lead-gen / x-lead-gen OfficeX apps and waits out their async job for you. **Paid plan.** Details: `references/assets-and-sourcing.md`.
 4c. **"Create an avatar"** (spokesperson / presenter / host / UGC creator / talking head) → always a **talking-head VIDEO with spoken audio**, generated on an exact-key-color **greenscreen** plate and keyed off it in the same job → a **transparent presenter** you layer over any background. `vidfarm avatar "<who they are>" --say "<their line>" [--ref headshot.png]` / `POST /api/v1/primitives/videos/create-avatar`. Details: `references/primitives.md` → "Primitive: talking_avatar".
 5. "Script / batch / render loop" → `references/automation-and-local-dev.md`
 6. "I need TTS / music / captions / background removal" → `references/primitives.md`

package/dist/src/cli.js

@@ -22,7 +22,7 @@ import { renderCompositionStills } from "./devcli/stills.js";
 import { extractCompositionFacts, formatQaReport, qaCompositionHtml } from "./devcli/qa-check.js";
 import { discoverRegime, formatRegimeReport, listBuiltinRegimes, loadAndEvaluateRegime, mergeRegimeIntoReport, parseRegime, resolveRegimePath } from "./devcli/qa-regime.js";
 import { removeGreenscreenLocal, localGreenscreenAvailable, defaultGreenscreenOutPath, GREENSCREEN_PRESETS, trimTransparentBorders, cropImageRegion } from "./devcli/greenscreen-local.js";
-import { segmentAlphaComponents, encodeTransparentGif, encodeTransparentAnimatedGif, pickPlateColor, detectPlateColor } from "./devcli/sticker-pack.js";
+import { segmentAlphaComponents, encodeTransparentGif, encodeTransparentAnimatedGif, pickPlateColor, detectPlateColor, keySafeArtInstruction, analyzeKeyedArt, HOLE_WARN_PCT } from "./devcli/sticker-pack.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
 import { findFreePort } from "./devcli/port-utils.js";
 import { scanLocalServers } from "./devcli/process-scan.js";
@@ -351,7 +351,10 @@ Generate AI media and drop it on the timeline (for local coding agents):
                             transparent file (+ stickers.json). One image job for
                             the set = one art style, ~1/N the cost of N cutouts.
                             Items may be any size, from an icon to a full-frame
-                            landscape. Local, free, ffmpeg-only. Image-only.
+                            landscape. Prompts for key-safe art (solid fills, no
+                            outline-only/hollow shapes, nothing in a near-plate
+                            shade) and flags any item that came out hollow.
+                            Local, free, ffmpeg-only. Image-only.
                             (aliases: stickers, sticker-sheet)
     --generate "<theme>"    AI-generate the sheet first (ONE billed image job for
                             the WHOLE pack) on a spaced grid over a chroma plate
@@ -808,6 +811,19 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
     --content-type <a,b>    With --search: filter the /raws branch by shot-KIND tag
                             (talking_head,b_roll,product_shot,screen_recording,demo,
                             reaction,interview,establishing,lifestyle,text_graphic)
+  recycle <source>          PAID. RECYCLE a Reddit or X/Twitter source into reusable JSON —
+                            "tweet to tiktok" / "reddit to tiktok". Accepts a Reddit thread URL
+                            (post + comments), a subreddit (r/name or URL -> its threads), an X
+                            thread URL (tweet + replies), or an X profile (@handle or URL -> their
+                            posts). Returns items[] with text, author + avatar, stats, permalinks
+                            and every image/video media URL - unranked and unsummarized, so YOU
+                            pick what to remix. Brokered through the reddit-lead-gen / x-lead-gen
+                            OfficeX apps, billed on the credits they consume.
+                            Flags: --max-records N (spend ceiling, default 100) --cursor <token>
+                            --query <text> --filter hot|new|top --mode <mode> --network <net>
+                            --no-comments --no-profile --out ./recycled.json --no-wait
+                            Aliases: recycle-social, tweet-to-video, reddit-to-video
+                            -> POST /api/v1/primitives/social/recycle
   get-file <id> [dest]      Resolve a My Files id to its URL and download it
     --print                 Print text contents (md/txt/csv/json) instead of saving
   annotate-file <id|name>   Set metadata notes on one My Files entry     → PATCH /api/v1/user/me/attachments/:id
@@ -1179,6 +1195,13 @@ async function main() {
         case "download-audio":
             await runDownloadPostAudioCommand(rest);
             return;
+        // "tweet to tiktok" / "reddit to tiktok": decompose a social source to JSON.
+        case "recycle-social":
+        case "tweet-to-video":
+        case "reddit-to-video":
+        case "recycle":
+            await runRecycleCommand(rest);
+            return;
         case "files":
             await runFilesCommand(rest);
             return;
@@ -5303,9 +5326,12 @@ function cutoutPlateInstruction(keyColorHex) {
             : /^#?ff00ff$/i.test(keyColorHex) ? "solid magenta"
                 : `a solid flat ${keyColorHex}`;
     return (`Isolated subject on a completely flat, evenly-lit ${named} (${keyColorHex}) background — ` +
-        `like a green-screen plate. The subject must contain NONE of that background color anywhere on it. ` +
+        `like a green-screen plate. ` +
         `Center the subject with generous empty margin on all sides, no drop shadow or reflection cast on the ` +
-        `background, crisp clean edges, sticker/cutout style, single subject, no text.`);
+        `background, crisp clean edges, sticker/cutout style, single subject, no text. ` +
+        // The plate color is only half the battle — art drawn as a hollow outline
+        // (or in a near-plate shade) gets its middle keyed away too.
+        keySafeArtInstruction(keyColorHex));
 }
 async function runCutoutCommand(argv) {
     const parsed = parseArgs({
@@ -5482,6 +5508,16 @@ async function runCutoutCommand(argv) {
         const shrinkPct = trim.origWidth && trim.origHeight && trim.width && trim.height
             ? Math.round((1 - (trim.width * trim.height) / (trim.origWidth * trim.origHeight)) * 100)
             : null;
+        // Did the key eat the ART as well as the plate? Outline-only art (interior
+        // left as bare plate) or a near-plate fill comes back as a rim around a
+        // see-through hole — invisible until it composites over a real background.
+        const art = await analyzeKeyedArt(trim.outputPath);
+        const hollowNote = art?.hollow
+            ? `${art.hole_pct}% of this cutout is transparent HOLES inside the art. If it's meant to be a ring/frame/donut, ignore this. ` +
+                `Otherwise the key ate the fill: the art was drawn as an outline with a bare ${keyColor} interior, or filled in a near-${keyColor} shade. ` +
+                `Fix it in the PROMPT — ask for "a closed, solidly filled shape, no outline-only or hollow art, nothing in ${keyColor} or any near-shade of it, ` +
+                `fully opaque, no translucency or glow" — and re-generate. (--tolerance lower can rescue a near-shade fill; nothing rescues an empty one.)`
+            : null;
         if (ctx.json) {
             printJson({
                 ok: true,
@@ -5495,13 +5531,18 @@ async function runCutoutCommand(argv) {
                 trimmed: trim.trimmed,
                 area_reduced_pct: shrinkPct,
                 bytes: safeSize(trim.outputPath),
-                key_color: keyColor
+                key_color: keyColor,
+                hole_pct: art?.hole_pct ?? null,
+                hollow: art?.hollow ?? false,
+                hollow_note: hollowNote
             });
         }
         else {
             console.log(`${GREEN}Cutout ready:${RESET} ${trim.outputPath} ${DIM}(${trim.width}×${trim.height}, ${formatBytes(safeSize(trim.outputPath))}${trim.trimmed && shrinkPct !== null ? `, −${shrinkPct}% area` : ""})${RESET}`);
             if (!trim.trimmed && !noTrim)
                 console.log(`${YELLOW}Note:${RESET} ${DIM}no transparent margin to trim — the subject already reached the edges, or the plate keyed to fully transparent (check --preset/--key-color).${RESET}`);
+            if (hollowNote)
+                console.log(`${YELLOW}Hollow:${RESET} ${DIM}${hollowNote}${RESET}`);
             console.log(`${DIM}Drop it on a composition: vidfarm place <dir> --src "${trim.outputPath}" --kind image [--ken-burns zoom-in]. Animate it (zoom/grow/shake/move) with vidfarm keyframes — see the skill's "Cutout graphics for explainers" recipe.${RESET}`);
         }
     }
@@ -5722,8 +5763,9 @@ function stickerSheetInstruction(keyColorHex, count, items) {
         `${named} (${keyColorHex}) background. ${list} ` +
         `CRITICAL: every item must be fully separated from the others by a clear margin of plain ${keyColorHex} background — ` +
         `nothing touching, overlapping, or connected. Keep a wide ${keyColorHex} margin around the edges of the sheet too. ` +
-        `No item may contain that background color anywhere on it. No drop shadows, no reflections, no text, no labels, ` +
-        `no frames or dividing lines between items. One consistent art style across all items, crisp clean edges, sticker/cutout style.`);
+        `No drop shadows, no reflections, no text, no labels, ` +
+        `no frames or dividing lines between items. One consistent art style across all items, crisp clean edges, sticker/cutout style. ` +
+        keySafeArtInstruction(keyColorHex));
 }
 async function runStickerPackCommand(argv) {
     const parsed = parseArgs({
@@ -5930,16 +5972,37 @@ async function runStickerPackCommand(argv) {
         if (!seg.components.length) {
             throw new Error("No items found in the sheet. Either the plate didn't key (check --preset/--key-color, raise --tolerance) or every item was filtered as speckle (lower --min-area).");
         }
+        // ---- 3b. Hollow-sticker check -------------------------------------------
+        // The other half of "did the key work": items that came back as a rim around
+        // a transparent hole, because the art was drawn as an outline (interior left
+        // as bare plate) or filled in a near-plate shade. It looks fine on the sheet
+        // and only shows up once the sticker composites over a real background — so
+        // say it here, loudly, with the fix. A ring/donut/frame reads the same way,
+        // which is why this warns and never blocks.
+        let hollowNote = null;
+        if (seg.hollow.length) {
+            const named = seg.hollow.map((i) => `${String(i).padStart(2, "0")}${itemNames[i - 1] ? ` (${itemNames[i - 1]})` : ""} — ${seg.components.find((c) => c.index === i)?.hole_pct}% see-through`);
+            hollowNote =
+                `${seg.hollow.length} of ${seg.components.length} sticker(s) came out mostly hollow: ${named.join(", ")}. ` +
+                    `If those are meant to be rings/frames/donuts, ignore this. Otherwise the key ate their FILL: the art was drawn ` +
+                    `as an outline with a bare ${keyColor} interior, or filled in a near-${keyColor} shade. Fix it in the PROMPT, not the keyer — ` +
+                    `ask for "closed, solidly filled shapes, no outline-only or hollow objects, nothing on the art in ${keyColor} or any ` +
+                    `near-shade of it, fully opaque, no translucency or glow" — then re-generate the sheet. ` +
+                    `(Lowering --tolerance can rescue a near-shade fill from an existing sheet, but not a genuinely empty one.)`;
+            if (!ctx.json)
+                console.log(`${YELLOW}Hollow:${RESET} ${DIM}${hollowNote}${RESET}`);
+        }
         if (parsed.values["dry-run"]) {
             // Report the boxes without writing stickers — for eyeballing segmentation
             // before spending disk, and for hand-fixing a merged item with `mask --crop`.
             if (ctx.json) {
-                printJson({ ok: true, target: "local", dry_run: true, sheet: `${seg.sourceWidth}x${seg.sourceHeight}`, found: seg.components.length, skipped_specks: seg.rejected, key_color: keyColor, key_color_auto: plateAuto, items: seg.components });
+                printJson({ ok: true, target: "local", dry_run: true, sheet: `${seg.sourceWidth}x${seg.sourceHeight}`, found: seg.components.length, skipped_specks: seg.rejected, key_color: keyColor, key_color_auto: plateAuto, hollow: seg.hollow, hollow_note: hollowNote, items: seg.components });
             }
             else {
                 console.log(`${GREEN}Found ${seg.components.length} item${seg.components.length === 1 ? "" : "s"}${RESET} ${DIM}on the ${seg.sourceWidth}×${seg.sourceHeight} sheet${seg.rejected ? `, ${seg.rejected} speck(s) skipped` : ""} (dry run — nothing written):${RESET}`);
                 for (const c of seg.components) {
-                    console.log(`  ${DIM}${String(c.index).padStart(2, "0")}  crop ${c.x},${c.y},${c.width},${c.height}  (${c.width}×${c.height}, ${c.area_pct}% of sheet)${RESET}`);
+                    const hollowFlag = c.hole_pct >= HOLE_WARN_PCT ? `  ${YELLOW}⚠ ${c.hole_pct}% hollow${RESET}` : "";
+                    console.log(`  ${DIM}${String(c.index).padStart(2, "0")}  crop ${c.x},${c.y},${c.width},${c.height}  (${c.width}×${c.height}, ${c.area_pct}% of sheet)${RESET}${hollowFlag}`);
                 }
                 console.log(`${DIM}Merged two items into one box? Raise the gap between them in the prompt, lower --gap, or grab that one by hand: vidfarm mask <sheet> --crop x,y,w,h --flat "${keyColor}".${RESET}`);
             }
@@ -5973,10 +6036,14 @@ async function runStickerPackCommand(argv) {
                 height: trim.height,
                 sheet_crop: { x: c.x, y: c.y, width: c.width, height: c.height },
                 area_pct: c.area_pct,
+                holes: c.holes,
+                hole_pct: c.hole_pct,
+                hollow: c.hole_pct >= HOLE_WARN_PCT,
                 bytes: safeSize(finalPath)
             });
             if (!ctx.json) {
-                console.log(`  ${GREEN}✓${RESET} ${path.relative(process.cwd(), finalPath)} ${DIM}(${trim.width}×${trim.height}, ${formatBytes(safeSize(finalPath))})${RESET}`);
+                const hollowFlag = c.hole_pct >= HOLE_WARN_PCT ? ` ${YELLOW}⚠ ${c.hole_pct}% hollow${RESET}` : "";
+                console.log(`  ${GREEN}✓${RESET} ${path.relative(process.cwd(), finalPath)} ${DIM}(${trim.width}×${trim.height}, ${formatBytes(safeSize(finalPath))})${RESET}${hollowFlag}`);
             }
         }
         // A manifest so the next step (place/keyframes, or an agent picking props by
@@ -5986,6 +6053,8 @@ async function runStickerPackCommand(argv) {
             generated_from: generatePrompt ? "generate" : sourceArg,
             key_color: keyColor,
             key_color_auto: plateAuto,
+            hollow: seg.hollow,
+            hollow_note: hollowNote,
             sheet_width: seg.sourceWidth,
             sheet_height: seg.sourceHeight,
             format: wantGif ? "gif" : stillExt,
@@ -5993,7 +6062,7 @@ async function runStickerPackCommand(argv) {
             stickers: written
         }, null, 2)}\n`);
         if (ctx.json) {
-            printJson({ ok: true, target: "local", out_dir: outDir, manifest: manifestPath, count: written.length, skipped_specks: seg.rejected, key_color: keyColor, key_color_auto: plateAuto, key_color_note: plateNote, stickers: written });
+            printJson({ ok: true, target: "local", out_dir: outDir, manifest: manifestPath, count: written.length, skipped_specks: seg.rejected, key_color: keyColor, key_color_auto: plateAuto, key_color_note: plateNote, hollow: seg.hollow, hollow_note: hollowNote, stickers: written });
         }
         else {
             console.log(`${GREEN}Sticker pack ready:${RESET} ${written.length} transparent sticker${written.length === 1 ? "" : "s"} in ${outDir} ${DIM}(manifest: stickers.json${seg.rejected ? `, ${seg.rejected} speck(s) skipped` : ""})${RESET}`);
@@ -8254,6 +8323,118 @@ async function runDownloadPostCommand(argv) {
     const final = await pollPrimitiveJob(ctx, jobId);
     emitPrimitiveJobResult(ctx, final, "download-post");
 }
+async function runRecycleCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            "max-records": { type: "string" },
+            cursor: { type: "string" },
+            query: { type: "string" },
+            filter: { type: "string" },
+            sort: { type: "string" },
+            mode: { type: "string" },
+            network: { type: "string" },
+            "no-comments": { type: "boolean", default: false },
+            "no-profile": { type: "boolean", default: false },
+            out: { type: "string" },
+            "no-wait": { type: "boolean", default: false },
+            tracer: { type: "string" }
+        }
+    });
+    const source = parsed.positionals[0];
+    if (!source) {
+        throw new Error("recycle requires a Reddit or X/Twitter source — a thread URL, a subreddit (r/name), a profile URL, or @handle.");
+    }
+    const maxRecords = parsed.values["max-records"] ? Number(parsed.values["max-records"]) : undefined;
+    if (maxRecords !== undefined && (!Number.isInteger(maxRecords) || maxRecords < 1 || maxRecords > 1000)) {
+        throw new Error("recycle --max-records must be an integer between 1 and 1000.");
+    }
+    const ctx = commonContext(parsed.values);
+    guardBilled(ctx, {
+        label: "recycle a Reddit/X source into JSON (paid plan — brokered via the OfficeX lead-gen apps)",
+        estimate: maxRecords && maxRecords > 100
+            ? "several cents (max-records drives upstream pagination)"
+            : "~$0.002-$0.02 per pull",
+        freeAlternative: "open the thread in a browser and copy the text you want by hand"
+    });
+    // A bare handle/subreddit is ambiguous without a network; a URL is not.
+    const looksLikeUrl = /^https?:\/\//i.test(source) || source.includes(".com/");
+    const payload = looksLikeUrl ? { source_url: source } : { handle: source };
+    if (!looksLikeUrl && parsed.values.network)
+        payload.network = String(parsed.values.network);
+    if (parsed.values.mode)
+        payload.mode = String(parsed.values.mode);
+    if (maxRecords !== undefined)
+        payload.max_records = maxRecords;
+    if (parsed.values.cursor)
+        payload.cursor = String(parsed.values.cursor);
+    if (parsed.values.query)
+        payload.query = String(parsed.values.query);
+    if (parsed.values.filter)
+        payload.filter = String(parsed.values.filter);
+    if (parsed.values.sort)
+        payload.sort = String(parsed.values.sort);
+    if (parsed.values["no-comments"])
+        payload.include_comments = false;
+    if (parsed.values["no-profile"])
+        payload.include_profile = false;
+    const tracer = String(parsed.values.tracer ?? `devcli-recycle-${Date.now().toString(36)}`);
+    const submit = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/api/v1/primitives/social/recycle",
+        auth: ctx.auth,
+        body: { tracer, payload }
+    });
+    assertApiOk(submit, "recycle");
+    const jobId = submit.json?.job_id;
+    if (!jobId || parsed.values["no-wait"]) {
+        emitResult(submit, ctx.json);
+        return;
+    }
+    if (!ctx.json) {
+        console.log(`${DIM}Recycling ${source} (${jobId})… the upstream lead-gen job is polled server-side.${RESET}`);
+    }
+    const final = await pollPrimitiveJob(ctx, jobId);
+    // --out writes the FULL normalized payload to disk; the job result inlines
+    // only a prefix when the item list is large.
+    const outPath = parsed.values.out ? String(parsed.values.out) : null;
+    if (outPath) {
+        const result = (final?.result ?? {});
+        const recycledUrl = result.recycled?.url
+            ?? result.primary_file_url;
+        if (typeof recycledUrl === "string" && recycledUrl) {
+            const res = await fetch(recycledUrl);
+            if (res.ok) {
+                mkdirSync(path.dirname(path.resolve(outPath)), { recursive: true });
+                writeFileSync(path.resolve(outPath), await res.text());
+                if (!ctx.json)
+                    console.log(`${DIM}Wrote full recycled JSON → ${outPath}${RESET}`);
+            }
+            else if (!ctx.json) {
+                console.warn(`[vidfarm] could not fetch recycled.json (${res.status}) — the job result still has it.`);
+            }
+        }
+    }
+    if (!ctx.json) {
+        const result = (final?.result ?? {});
+        const counts = (result.counts ?? {});
+        console.log(`${DIM}mode=${String(result.mode ?? "?")} items=${String(counts.items ?? "?")} `
+            + `(posts=${String(counts.posts ?? "?")} comments=${String(counts.comments ?? "?")}) `
+            + `media=${String(counts.media ?? "?")} credits=${String(counts.credits_charged ?? "?")}${RESET}`);
+        for (const job of result.upstreamJobs ?? []) {
+            if (typeof job.view_url === "string" && job.view_url) {
+                console.log(`${DIM}  browse ${String(job.endpoint)} in a spreadsheet: ${job.view_url}${RESET}`);
+            }
+        }
+        if (result.nextCursor) {
+            console.log(`${DIM}  more available — re-run with --cursor ${String(result.nextCursor).slice(0, 24)}…${RESET}`);
+        }
+    }
+    emitPrimitiveJobResult(ctx, final, "recycle");
+}
 async function runDownloadPostAudioCommand(argv) {
     const parsed = parseArgs({
         args: argv,

package/dist/src/devcli/handoff.js

@@ -22,7 +22,7 @@
 // Both builders return plain text meant to be shown verbatim to the user, plus a
 // structured form for `--json` so an agent can render it its own way. No network,
 // no backend imports — this module is pure string assembly.
-import { pickPlateColor } from "./sticker-pack.js";
+import { pickPlateColor, keySafeArtInstruction } from "./sticker-pack.js";
 const DEFAULT_STYLE = "simple flat vector illustration, minimal detail, 2-3 flat colors, no shadows, no text";
 /** Pick a sensible grid for N items (roughly square, wider than tall). */
 function gridFor(count) {
@@ -67,18 +67,22 @@ export function buildImageHandoff(input) {
             `CRITICAL: every object must be fully separated from the others by a clear margin of plain ${keyColor} background —`,
             `nothing touching, overlapping or connected, and nothing touching the image edge.`,
             `One consistent art style, line weight and palette across all objects. Front-facing, centered in its own cell.`,
+            // Load-bearing: the user is about to spend their own time on this sheet,
+            // and hollow/outline-only art comes back as rims around holes.
+            keySafeArtInstruction(keyColor),
             `Square image, high resolution.`
         ].join(" ")
         : [
             `${input.theme} — ${style} — isolated on a solid pure ${keyColor} background`,
             `(flat, evenly lit, no gradient, no shadow cast on the background, no text).`,
             `Center the subject with generous empty margin on all sides, crisp clean edges, single subject.`,
+            keySafeArtInstruction(keyColor),
             `Square image, high resolution.`
         ].join(" ");
     const steps = pack
         ? [
             "Open a FREE image generator you're already signed into (list below).",
-            "Paste the prompt below and generate. If any two objects come out touching, re-generate asking for wider spacing — touching objects get cut out as one sticker.",
+            "Paste the prompt below and generate. Two checks before you send it back: (a) if any two objects are touching, re-generate asking for wider spacing — touching objects get cut out as ONE sticker; (b) if any object is a hollow outline with the background showing through its middle, re-generate asking for solid fills — that interior gets deleted with the background and the sticker ends up as a rim around a hole.",
             "Download the image (PNG preferred) and tell me the file path — or drop it in this project folder.",
             `I'll split it into individual transparent stickers locally for $0: \`vidfarm sticker-pack <sheet> --out-dir ${outDir}\`.`
         ]

package/dist/src/devcli/sticker-pack.js

@@ -132,6 +132,42 @@ export async function detectPlateColor(sourcePath, opts = {}) {
     const hex = `#${avg.map((v) => v.toString(16).padStart(2, "0")).join("").toUpperCase()}`;
     return { hex, rgb: avg };
 }
+// ── Key-safe ART instruction ─────────────────────────────────────────────────
+// Picking a plate the art doesn't use (above) is only HALF of surviving a chroma
+// key. The other half is what the art is made of, and it's the failure we see in
+// the wild: an image model hears "sticker on a green plate" and draws OUTLINE
+// art — a colored stroke with the shape's interior left as bare background. On
+// screen that looks fine. After the key, the interior is gone, and the sticker
+// composites as a rim floating around a see-through hole.
+//
+// The same failure arrives three other ways: a fill that's a near-shade of the
+// plate (keyed by tolerance, not by exact match), a translucent/glassy material
+// that lets the plate through, and a soft glow/drop-shadow that fades INTO the
+// plate at the edges.
+//
+// All four are prompt-preventable, so every generation path that mints art
+// destined for a key (cutout, sticker-pack, the hand-off brief the user pastes
+// into a free web tool) appends this clause. Detection after the fact is the net
+// (`detectEnclosedHoles` below) — this is the mechanism.
+/**
+ * The "your art has to survive the key" clause, worded for an image model.
+ * Append to any prompt whose output will be chroma-keyed on `keyColorHex`.
+ */
+export function keySafeArtInstruction(keyColorHex) {
+    const hex = keyColorHex.toUpperCase();
+    return (`KEY-SAFE ARTWORK (the ${hex} background gets deleted, so anything ${hex} on the art is deleted too): ` +
+        `every object must be a CLOSED, SOLIDLY FILLED shape — outlines and strokes must enclose an opaque fill of a ` +
+        `different color. NO outline-only / hollow / line-art objects, and never leave a shape's interior as bare ` +
+        `background. No part of any object — fill, outline, highlight, gradient, glow, shading or detail — may be ${hex} ` +
+        `or any near-shade, tint or tone of ${hex}. No transparent, translucent, glassy, glowing, misty or ghosted ` +
+        `materials; every pixel of every object is fully opaque. No soft glows, blurs or drop shadows fading into the ` +
+        `background. Keep the whole palette in strong contrast to ${hex}. The background must be visible ONLY around the ` +
+        `outside of the objects, never showing through inside them.`);
+}
+/** At/above this `hole_pct` a sticker is worth warning about: past ~a fifth of
+ *  its own box, "the key ate the fill" is far more likely than "the artist drew
+ *  a ring". Tuned to stay quiet on letter counters, handles and small gaps. */
+export const HOLE_WARN_PCT = 20;
 /** Read a still's alpha plane as raw 8-bit luma at a given size (bundle-safe:
  *  ffmpeg's `alphaextract` writes alpha as luma; rawvideo skips any decoding on
  *  our side). Returns exactly width*height bytes. */
@@ -199,6 +235,93 @@ function dilate(mask, w, h, radius) {
     }
     return out;
 }
+/**
+ * Find transparent islands that are fully SURROUNDED by opaque art — the exact
+ * signature of the "hollow sticker" bug: art drawn as an outline (or filled in a
+ * near-plate shade) has its middle deleted by the key, and composites as a rim
+ * around a see-through hole.
+ *
+ * Mechanically it's the complement of a background flood-fill: every transparent
+ * pixel reachable from the mask's border is the plate doing its job; every
+ * transparent pixel that is NOT reachable is a hole punched inside something.
+ * 4-connected on purpose — an 8-connected fill leaks through a 1px diagonal
+ * seam in antialiased line art and would under-report every real hole.
+ *
+ * Note this cannot distinguish a bug from a deliberate ring/donut/picture-frame,
+ * so callers WARN on the result, never reject it.
+ */
+export function detectEnclosedHoles(mask, w, h, opts = {}) {
+    const reachable = new Uint8Array(w * h);
+    const queue = new Int32Array(w * h);
+    let head = 0;
+    let tail = 0;
+    const push = (p) => {
+        if (!mask[p] && !reachable[p]) {
+            reachable[p] = 1;
+            queue[tail++] = p;
+        }
+    };
+    for (let x = 0; x < w; x++) {
+        push(x);
+        push((h - 1) * w + x);
+    }
+    for (let y = 0; y < h; y++) {
+        push(y * w);
+        push(y * w + (w - 1));
+    }
+    while (head < tail) {
+        const p = queue[head++];
+        const py = (p / w) | 0;
+        const px = p - py * w;
+        if (px > 0)
+            push(p - 1);
+        if (px < w - 1)
+            push(p + 1);
+        if (py > 0)
+            push(p - w);
+        if (py < h - 1)
+            push(p + w);
+    }
+    // Anything transparent and unreached is enclosed — group it into islands.
+    const minAreaPx = Math.max(1, Math.round(opts.minAreaPx ?? 4));
+    const seen = new Uint8Array(w * h);
+    const holes = [];
+    const stack = new Int32Array(w * h);
+    for (let start = 0; start < mask.length; start++) {
+        if (mask[start] || reachable[start] || seen[start])
+            continue;
+        let top = 0;
+        stack[top++] = start;
+        seen[start] = 1;
+        const hole = { minX: w, minY: h, maxX: -1, maxY: -1, area: 0 };
+        while (top > 0) {
+            const p = stack[--top];
+            const py = (p / w) | 0;
+            const px = p - py * w;
+            hole.area++;
+            if (px < hole.minX)
+                hole.minX = px;
+            if (px > hole.maxX)
+                hole.maxX = px;
+            if (py < hole.minY)
+                hole.minY = py;
+            if (py > hole.maxY)
+                hole.maxY = py;
+            const neighbors = [px > 0 ? p - 1 : -1, px < w - 1 ? p + 1 : -1, py > 0 ? p - w : -1, py < h - 1 ? p + w : -1];
+            for (const q of neighbors) {
+                if (q < 0 || mask[q] || reachable[q] || seen[q])
+                    continue;
+                seen[q] = 1;
+                stack[top++] = q;
+            }
+        }
+        // Sub-threshold islands are antialiasing dropouts and despill speckle, not
+        // a missing fill — a real hollow interior is orders of magnitude bigger.
+        if (hole.area >= minAreaPx)
+            holes.push(hole);
+    }
+    return holes;
+}
 /**
  * Find every item on a keyed plate by segmenting its alpha channel into
  * connected islands of opaque pixels — the automatic replacement for measuring
@@ -312,22 +435,93 @@ export async function segmentAlphaComponents(input) {
     // ---- Map sample-space boxes back to source pixels --------------------------
     // One sample pixel of slack on each side covers the downscale's rounding, so a
     // subject's outermost antialiased edge never gets clipped off.
+    // ---- Attribute enclosed holes to the item that surrounds them --------------
+    // A hole lives strictly inside the art that encloses it, so its center falls
+    // in that item's box. Boxes can nest (a small icon inside a big backdrop), so
+    // the SMALLEST containing box wins — the nearest enclosing art is the owner.
+    const holes = detectEnclosedHoles(mask, sw, sh, { minAreaPx: Math.max(6, Math.round(total * 0.00005)) });
+    const holeArea = new Array(ordered.length).fill(0);
+    const holeCount = new Array(ordered.length).fill(0);
+    for (const hole of holes) {
+        const cx = (hole.minX + hole.maxX) / 2;
+        const cy = (hole.minY + hole.maxY) / 2;
+        let owner = -1;
+        let ownerArea = Infinity;
+        for (let i = 0; i < ordered.length; i++) {
+            const b = ordered[i];
+            if (cx < b.minX || cx > b.maxX || cy < b.minY || cy > b.maxY)
+                continue;
+            const boxArea = (b.maxX - b.minX + 1) * (b.maxY - b.minY + 1);
+            if (boxArea < ownerArea) {
+                owner = i;
+                ownerArea = boxArea;
+            }
+        }
+        if (owner >= 0) {
+            holeArea[owner] += hole.area;
+            holeCount[owner]++;
+        }
+    }
     const inv = 1 / scale;
     const components = ordered.map((b, i) => {
         const x0 = Math.max(0, Math.floor((b.minX - 1) * inv));
         const y0 = Math.max(0, Math.floor((b.minY - 1) * inv));
         const x1 = Math.min(dims.width, Math.ceil((b.maxX + 2) * inv));
         const y1 = Math.min(dims.height, Math.ceil((b.maxY + 2) * inv));
+        // Measured against the item's own silhouette (fill + holes), not the plate:
+        // "a fifth of THIS sticker is missing" is the question that matters.
+        const silhouette = b.area + holeArea[i];
         return {
             index: i + 1,
             x: x0,
             y: y0,
             width: Math.max(1, x1 - x0),
             height: Math.max(1, y1 - y0),
-            area_pct: Math.round((b.area / total) * 1000) / 10
+            area_pct: Math.round((b.area / total) * 1000) / 10,
+            holes: holeCount[i],
+            hole_pct: silhouette > 0 ? Math.round((holeArea[i] / silhouette) * 1000) / 10 : 0
         };
     });
-    return { components, sourceWidth: dims.width, sourceHeight: dims.height, sampleWidth: sw, sampleHeight: sh, rejected };
+    const hollow = components.filter((c) => c.hole_pct >= HOLE_WARN_PCT).map((c) => c.index);
+    return { components, sourceWidth: dims.width, sourceHeight: dims.height, sampleWidth: sw, sampleHeight: sh, rejected, hollow };
+}
+/**
+ * The single-subject version of the hollow-sticker check: does THIS keyed still
+ * have transparency punched through the middle of its art? Used by `cutout`,
+ * which has one subject and so needs no segmentation — just the same
+ * background-flood-fill complement over the whole alpha plane.
+ */
+export async function analyzeKeyedArt(sourcePath) {
+    if (!existsSync(sourcePath))
+        return null;
+    const dims = await probeImageDimensions(sourcePath);
+    if (!dims)
+        return null;
+    const longSide = Math.max(dims.width, dims.height);
+    const scale = longSide > 640 ? 640 / longSide : 1;
+    const sw = Math.max(1, Math.round(dims.width * scale));
+    const sh = Math.max(1, Math.round(dims.height * scale));
+    let alpha;
+    try {
+        alpha = await readAlphaPlane(sourcePath, sw, sh);
+    }
+    catch {
+        return null; // no alpha channel to read → nothing to say
+    }
+    const mask = new Uint8Array(sw * sh);
+    let opaque = 0;
+    for (let i = 0; i < mask.length; i++)
+        if (alpha[i] > 8) {
+            mask[i] = 1;
+            opaque++;
+        }
+    if (!opaque)
+        return null;
+    const total = sw * sh;
+    const holes = detectEnclosedHoles(mask, sw, sh, { minAreaPx: Math.max(6, Math.round(total * 0.00005)) });
+    const holeArea = holes.reduce((sum, h) => sum + h.area, 0);
+    const hole_pct = Math.round((holeArea / (opaque + holeArea)) * 1000) / 10;
+    return { holes: holes.length, hole_pct, hollow: hole_pct >= HOLE_WARN_PCT };
 }
 /**
  * Re-encode a transparent still as a transparent GIF — the format a lot of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.30",
+  "version": "0.21.31",
   "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": {
@@ -95,6 +95,8 @@
     "test:clips": "node --import tsx --test test/clip-curation.test.ts",
     "test:qa": "node --import tsx --test test/qa-check.test.ts",
     "test:studio-brand": "node --import tsx --test test/studio-brand.test.ts",
+    "test:stickers": "node --import tsx --test test/sticker-pack.test.ts",
+    "test:social-recycle": "node --import tsx --test test/social-recycle.test.ts",
     "check:skills": "node scripts/build-director-skill-rollup.mjs --check && node scripts/check-skill-routes.mjs",
     "benchmark:editor-chat": "node --import tsx scripts/benchmark-editor-chat-harness.mjs",
     "cdk:deploy:prod-serverless": "npm run build && dotenv -e .env.production -- npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-prod.js'",