@officexapp/vidfarm-devcli 0.21.30 → 0.21.32

package/dist/src/cli.js

@@ -22,7 +22,8 @@ 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 { dedupeMediaLocal, localDedupeAvailable, defaultDedupeOutPath, describeLocalDedupe, DEDUPE_PRESETS, DEDUPE_DEFAULT_PRESET, isDedupePresetName } from "./devcli/dedupe-local.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";
@@ -329,6 +330,38 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --cloud                 Force the billed cloud primitive
     --out <file>            Write the transparent result to this path (local writes
                             <source>.transparent.png/.webm next to it by default)
+  dedupe <video|image|url>  DEDUPLICATE a finished render so a re-post reads as a
+                            NEW upload instead of tripping a platform's duplicate-
+                            content check. Invisible to a viewer. Runs on the
+                            EXPORTED file — no second render.
+                            (aliases: dedup, deduplicate, uniquify)
+                            → POST /api/v1/primitives/media/dedupe
+    --preset <name>         none | light | standard | strong | legacy
+                            standard (default) = skew 2%, zoom 3%, rotate 2°,
+                            speed +2%, saturation +4%, +contrast/brightness/hue/grain
+    --variants <n>          Mint N mutually-distinct copies in one pass (variant 1
+                            is the preset as authored; later variants get jittered
+                            magnitudes and flipped signs). One per account/slot.
+    --variant <n>           Start numbering here (resume a batch); --seed <s> for
+                            extra entropy so two batches of one source diverge
+    --no-jitter             Apply the preset verbatim to every variant
+    --zoom/--rotate/--skew/--tilt/--speed/--saturation/--contrast/--brightness/
+    --hue/--blur/--noise/--volume   Override any single knob (beats the preset)
+    --flip                  Mirror horizontally. Strongest single knob, but it
+                            visibly reverses on-screen text — opt in deliberately.
+    --effects-json '{...}'  Set several knobs at once
+    --tint-color/--tint-opacity   Flat color wash over the frame (default off)
+    --width/--height        Force an output size (default: keep the source's)
+    --crf <n>               Base x264 quality; jittered ±1 per variant
+    --keep-metadata         Don't strip container metadata (creation time,
+                            encoder, source handler) — stripping is the default
+    --media-type <k>        Force image|video instead of auto-detecting
+    --output-format <f>     Image only: png|jpeg|webp
+    --local                 Dedupe on your machine with bundled ffmpeg for FREE
+                            (no wallet, no account; cloud-parity) — DEFAULT
+    --cloud                 Force the billed cloud primitive
+    --out <file>            Single-variant output path (default <source>.dedupe.<ext>)
+    --out-dir <dir>         Where to write batch variants
   cutout <image|url>        Make a transparent explainer STICKER: key out the flat
                             plate, then trim the canvas down to the cutout's true
                             min width/height. Local, free, ffmpeg-only. Image-only.
@@ -351,7 +384,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
@@ -737,8 +773,16 @@ Approve & schedule (publish a finished MP4 as a shareable post):
                             (add --temp only for a disposable 30-day preview.)
   posts                     List your approved posts                     → GET  /api/v1/approved/posts
   post <postId>             Read one approved post (prints share URL)    → GET  /api/v1/approved/posts/:postId
+  channels                  List destinations you can schedule to        → GET  /api/v1/user/me/channels
   schedule <postId>         Schedule an approved post to a channel       → POST /api/v1/approved/posts/:postId/schedules
+    --at <iso>             When to send (ISO 8601, min 10 min from now)
+    --to <destination>     Channel id, email address, or @handle — all resolve
+                           server-side, so 'vidfarm channels' is optional
+    --type email|flockposter   Destination kind (default flockposter)
   schedules <postId>        Browse an approved post's schedules          → GET  /api/v1/approved/posts/:postId/schedules
+  reschedule <postId> <scheduleId>  Move a queued send                  → PATCH  /api/v1/approved/posts/:postId/schedules/:scheduleId
+  unschedule <postId> <scheduleId>  Cancel a queued send                → DELETE /api/v1/approved/posts/:postId/schedules/:scheduleId
+                            An error here means the send was NOT stopped.
 
 Account:
   login <email>             Send an OTP code to email                    → POST /api/v1/user/request-otp
@@ -808,6 +852,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
@@ -860,7 +917,8 @@ Cost spectrum (default to the cheapest approach that works; see SKILL.director.m
   command (generate, music, decompose, cloud render/TTS/STT/greenscreen, create, replicate)
   respects it: minimize refuses billed spend without --yes and points you at the free
   local path; the others run but print each op's cost. FREE local engines never gate
-  (local render, tts --engine local, stt --engine whisper, remove-greenscreen --local).
+  (local render, tts --engine local, stt --engine whisper, remove-greenscreen --local,
+   dedupe --local).
   In minimize AND hybrid, 'vidfarm tts' DEFAULTS to the free local Kokoro voice — ask for
   a premium voice (--style/--voice/--provider/--own-key/--cloud), or be in rich-ai /
   pure-videogen, to opt out.
@@ -1036,6 +1094,12 @@ async function main() {
         case "greenscreen":
             await runRemoveGreenscreenCommand(rest);
             return;
+        case "dedupe":
+        case "dedup":
+        case "deduplicate":
+        case "uniquify":
+            await runDedupeCommand(rest);
+            return;
         case "cutout":
         case "sticker":
             await runCutoutCommand(rest);
@@ -1118,12 +1182,21 @@ async function main() {
         case "post":
             await runPostCommand(rest);
             return;
+        case "channels":
+            await runChannelsCommand(rest);
+            return;
         case "schedule":
             await runScheduleCommand(rest);
             return;
         case "schedules":
             await runSchedulesCommand(rest);
             return;
+        case "reschedule":
+            await runRescheduleCommand(rest);
+            return;
+        case "unschedule":
+            await runUnscheduleCommand(rest);
+            return;
         case "login":
             await runLoginCommand(rest);
             return;
@@ -1179,6 +1252,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;
@@ -2311,6 +2391,7 @@ Rules:
 - STRUCTURE BEFORE POLISH — THE FOUR CHARGES, WRITTEN BEFORE YOU TOUCH THE TIMELINE. Most agent-made videos fail on structure, not polish, because the timeline is the fun part so it gets built first and the words get retrofitted. Invert it: (1) HOOK — write the opening line as text first: a complete clause (subject + verb), no jargon, naming a SITUATION ("I've quit six businesses") not a label ("anonymity"); it goes on screen at start:0, because caption chunk 1 is read before any audio and muted autoplay is the default. Banned openings: throat-clearing ("so I was thinking", "here's the thing"), a logo, a title card, a fade from black, context before the claim. (2) LOOP — one open question by 0:10, said ON SCREEN, closing INSIDE this video (state the timestamp it closes at; if you can't, there is no loop), and the withheld answer must be one the viewer CANNOT supply themselves — a formally-correct loop with a guessable answer passes every mechanical check and dies in the field. (3) PAYOFF — shown, not summarized, ≥5 uninterrupted seconds, landing BEFORE the final beat; the payoff is not the CTA. (4) BAIT — one ask in the final beat and in the post caption; never a DM funnel, "follow for part two", or ragebait. Then build the timeline. Re-theming a decomposed template: viral_dna already names the source's hook/retention/payoff — rebuild each charge for the new subject, never flatten the loop into a product statement. Full craft harness: the vidfarm skill's references/hooks-and-virality.md. Checkable form: \`vidfarm regime show hooks\`.
 - THE FIRST FRAME IS THE THUMBNAIL. Frame 0 is one frame of ~30 in the first second, but every feed card, share link, and paused player freezes on it — more people see that frame than watch the video. It must never be black, empty, mid-fade, or mid-animation: a real visual at start:0 (\`vidfarm retime . --layer <key> --start 0\`), the hook words already on screen at t=0, and NO entrance transition on the FIRST clip (\`vidfarm transitions set . --layer <key> --in none\`; junction transitions between later clips are fine). Look at the actual pixels before you render: \`vidfarm stills . --at 0\`.
 - ONE-TIME OR BULK? Ask before you build. If the director wants volume (daily posting, N variants, hook tests), that's SCRIPTING MODE: pin this fork as the base, vary exactly ONE thing per variant, and install a QA_REGIME.md — \`vidfarm regime init short-form --out ./QA_REGIME.md\` (bases: short-form, hooks, ugc-testimonial, explainer, product-demo), then EDIT it with them. It is their own written quality standard, and it exists because nobody watches variant #37 as carefully as #1. \`vidfarm qa .\` picks up ./QA_REGIME.md automatically; \`--regime <name|path>\` adds more (they stack, and any file of theirs anywhere is valid). Its \`checks:\` are machine-settled; its \`- [ ]\` items come back for YOU to answer honestly in your report — never claim a pass on the half the CLI can't judge. When a batch teaches you something, write it back into the regime.
+- DEDUPLICATE BEFORE YOU PUBLISH — AND ASK FIRST. Social platforms fingerprint every upload, so the same render posted twice (a second account, another platform, a re-post next month) gets the later copy suppressed as duplicate/reused content. BEFORE you render for publication, and before any bulk run, ASK the director: "do you want deduplicated copies for posting, and how many?" Ask THEN, not after — dedupe is a post-render ffmpeg pass, so the correct order is RENDER ONCE → DEDUPE N, and deciding late means paying for a second render. Run it on the EXPORTED file: \`vidfarm dedupe ./final.mp4\` (one copy) or \`vidfarm dedupe ./final.mp4 --variants N --seed <slug> --out-dir ./posts\` (N copies, one per account/slot). Free, offline, no wallet — it never re-renders the composition. The default \`standard\` preset is skew 2%, zoom 3%, rotate 2°, speed +2%, saturation +4%, plus contrast/brightness/hue/grain, a container-metadata strip and a per-variant CRF walk; invisible to a viewer, and each variant differs from the original AND from its siblings. Post each variant to a DIFFERENT account — two accounts posting the same variant defeats the point. A rotate forces a bigger centre-crop to hide the black corners (~6.7% on a tall frame at 2°) and the CLI says so; pass \`--rotate 0\` when framing matters more. Cloud twin: \`POST /api/v1/primitives/media/dedupe\`.
 - QA EVERY VIDEO BEFORE YOU RENDER: run \`vidfarm qa .\` in this directory. It's free, instant, and local — a blocklist for the slop above plus the first frame, the font regime, and the safe zone, with a concrete fix per finding. It's feedback, not a gate (exits 0 even on findings, never runs automatically) and a blocklist, not an allowlist, so stylized or hand-made work passes untouched. Fix what's real, ignore what's a deliberate style call. \`--json\` for scripted batches.
 
 The three paintbrushes (Vidfarm is thrift-first — do NOT spend AI credits on every scene):
@@ -5282,6 +5363,354 @@ async function runLocalGreenscreen(ctx, values, sourceArg, presetRaw) {
             rmSync(downloadDir, { recursive: true, force: true });
     }
 }
+// ── dedupe: make a re-post read as a NEW upload ──────────────────────────────
+// Social platforms fingerprint every upload. Posting the same render twice —
+// across accounts, or again next month — gets the later copy suppressed as
+// duplicate/reused content. `vidfarm dedupe` applies a calibrated, invisible
+// perturbation (skew, zoom, rotate, speed, saturation/contrast/brightness/hue,
+// grain, optional tint/mirror) plus a metadata strip and a per-variant CRF walk,
+// so each copy carries a distinct fingerprint.
+//
+// LOCAL by default: it is a pure ffmpeg pass, so it is FREE and offline and does
+// NOT require re-rendering the composition — dedupe the finished MP4 you already
+// paid to render instead of burning a second render.
+//
+// `--variants N` mints N mutually-distinct copies in one go (variant 1 is the
+// preset as authored; later variants get jittered magnitudes and flipped signs),
+// which is the shape bulk posting actually needs.
+function resolveDedupeTarget(values) {
+    if (values.local)
+        return "local";
+    if (values.cloud)
+        return "cloud";
+    const env = (process.env.VIDFARM_TARGET ?? "").trim().toLowerCase();
+    if (env === "local" || env === "cloud")
+        return env;
+    // The local ffmpeg pass is cloud-parity and free — prefer it (the runner
+    // downgrades to cloud if ffmpeg turns out to be unavailable at run time).
+    return "local";
+}
+// Per-knob flags, so any effect is overridable without hand-writing JSON.
+function collectDedupeEffectOverrides(values) {
+    const effects = {};
+    const numeric = [
+        ["zoom", "zoom"],
+        ["rotate", "rotate"],
+        ["skew", "skew"],
+        ["tilt", "tilt"],
+        ["speed", "speed"],
+        ["saturation", "saturation"],
+        ["contrast", "contrast"],
+        ["brightness", "brightness"],
+        ["hue", "hue_rotate"],
+        ["blur", "blur"],
+        ["noise", "noise"],
+        ["volume", "volume"]
+    ];
+    for (const [flag, key] of numeric) {
+        const raw = values[flag];
+        if (raw === undefined)
+            continue;
+        const parsed = Number(raw);
+        if (!Number.isFinite(parsed))
+            throw new Error(`--${flag} must be a number (got "${String(raw)}").`);
+        effects[key] = parsed;
+    }
+    if (values.flip)
+        effects.horizontal_flip = true;
+    if (values["effects-json"]) {
+        let parsed;
+        try {
+            parsed = JSON.parse(String(values["effects-json"]));
+        }
+        catch (error) {
+            throw new Error(`--effects-json is not valid JSON: ${error.message}`);
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("--effects-json must be a JSON object, e.g. '{\"zoom\":1.03,\"rotate\":-2}'.");
+        }
+        Object.assign(effects, parsed);
+    }
+    return effects;
+}
+async function runDedupeCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            source: { type: "string" },
+            preset: { type: "string" },
+            "media-type": { type: "string" },
+            variants: { type: "string" },
+            variant: { type: "string" },
+            seed: { type: "string" },
+            "no-jitter": { type: "boolean", default: false },
+            jitter: { type: "boolean", default: false },
+            // Per-knob overrides.
+            zoom: { type: "string" },
+            rotate: { type: "string" },
+            skew: { type: "string" },
+            tilt: { type: "string" },
+            speed: { type: "string" },
+            saturation: { type: "string" },
+            contrast: { type: "string" },
+            brightness: { type: "string" },
+            hue: { type: "string" },
+            blur: { type: "string" },
+            noise: { type: "string" },
+            volume: { type: "string" },
+            flip: { type: "boolean", default: false },
+            "effects-json": { type: "string" },
+            "tint-color": { type: "string" },
+            "tint-opacity": { type: "string" },
+            width: { type: "string" },
+            height: { type: "string" },
+            crf: { type: "string" },
+            "keep-metadata": { type: "boolean", default: false },
+            "output-format": { type: "string" },
+            local: { type: "boolean", default: false },
+            cloud: { type: "boolean", default: false },
+            out: { type: "string" },
+            "out-dir": { type: "string" },
+            "no-wait": { type: "boolean", default: false },
+            tracer: { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const sourceArg = parsed.values.source ?? parsed.positionals[0];
+    if (!sourceArg) {
+        throw new Error("dedupe requires a source video or image: `vidfarm dedupe <video|image|url> [--preset light|standard|strong] [--variants 3] [--out out.mp4]`.");
+    }
+    const presetRaw = parsed.values.preset?.trim().toLowerCase();
+    if (presetRaw && !isDedupePresetName(presetRaw)) {
+        throw new Error(`Unknown --preset "${presetRaw}". Choose one of: ${Object.keys(DEDUPE_PRESETS).join(", ")}.`);
+    }
+    const preset = presetRaw ?? DEDUPE_DEFAULT_PRESET;
+    const effectOverrides = collectDedupeEffectOverrides(parsed.values);
+    const variantCount = Math.max(1, Math.round(Number(parsed.values.variants ?? 1)) || 1);
+    if (variantCount > 100)
+        throw new Error("--variants is capped at 100 per run.");
+    const firstVariant = Math.max(1, Math.round(Number(parsed.values.variant ?? 1)) || 1);
+    const seed = parsed.values.seed ?? "";
+    const jitter = parsed.values["no-jitter"] ? false : (parsed.values.jitter ? true : undefined);
+    const stripMetadata = !parsed.values["keep-metadata"];
+    const mediaTypeArg = parsed.values["media-type"]?.trim().toLowerCase();
+    const mediaTypeOverride = mediaTypeArg === "image" || mediaTypeArg === "video" ? mediaTypeArg : undefined;
+    if (parsed.values.out && variantCount > 1) {
+        throw new Error("--out names a single file; with --variants use --out-dir (files are named <stem>.dedupe-NN.<ext>).");
+    }
+    let target = resolveDedupeTarget(parsed.values);
+    if (target === "local" && !(await localDedupeAvailable())) {
+        const hasCloudKey = Boolean(parsed.values["api-key"] ?? process.env.VIDFARM_API_KEY);
+        if (parsed.values.local) {
+            throw new Error("Local dedupe needs ffmpeg, which wasn't found. Install ffmpeg (or `npm i -g ffmpeg-static`), or run without --local to use the cloud primitive.");
+        }
+        if (!hasCloudKey) {
+            throw new Error("Dedupe needs either ffmpeg (for the free local pass) or a cloud API key. Install ffmpeg, or set VIDFARM_API_KEY / pass --cloud --api-key.");
+        }
+        target = "cloud";
+        if (!ctx.json)
+            console.log(`${DIM}ffmpeg not found — using the cloud dedupe primitive instead.${RESET}`);
+    }
+    if (target === "local") {
+        await runLocalDedupe(ctx, {
+            sourceArg,
+            preset,
+            effects: effectOverrides,
+            variantCount,
+            firstVariant,
+            seed,
+            jitter,
+            stripMetadata,
+            mediaType: mediaTypeOverride,
+            values: parsed.values
+        });
+        return;
+    }
+    // ---- CLOUD: billed primitive ----------------------------------------------
+    guardBilled(ctx, {
+        label: `cloud dedupe (${variantCount} variant${variantCount === 1 ? "" : "s"})`,
+        estimate: "billed at real compute ×1.2 per variant",
+        freeAlternative: "vidfarm dedupe --local (bundled ffmpeg, $0.00, identical transforms)"
+    });
+    const sourceUrl = await resolveSingleMediaUrl(ctx, sourceArg);
+    const mediaType = mediaTypeOverride
+        ?? (/\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(sourceUrl) ? "video" : "image");
+    const results = [];
+    for (let index = 0; index < variantCount; index += 1) {
+        const variant = firstVariant + index;
+        const payload = {
+            source_media_url: sourceUrl,
+            media_type: mediaType,
+            engine: "ffmpeg",
+            preset,
+            variant,
+            strip_metadata: stripMetadata
+        };
+        if (Object.keys(effectOverrides).length)
+            payload.effects = effectOverrides;
+        if (seed)
+            payload.seed = seed;
+        if (jitter !== undefined)
+            payload.jitter = jitter;
+        if (parsed.values["tint-color"])
+            payload.tint_color = parsed.values["tint-color"];
+        if (parsed.values["tint-opacity"] !== undefined)
+            payload.tint_opacity = Number(parsed.values["tint-opacity"]);
+        if (parsed.values.width !== undefined)
+            payload.width = Number(parsed.values.width);
+        if (parsed.values.height !== undefined)
+            payload.height = Number(parsed.values.height);
+        if (parsed.values.crf !== undefined)
+            payload.crf = Number(parsed.values.crf);
+        if (mediaType === "image" && parsed.values["output-format"])
+            payload.output_format = parsed.values["output-format"];
+        const tracer = parsed.values.tracer
+            ? `${String(parsed.values.tracer)}-v${variant}`
+            : `devcli-dedupe-${Date.now().toString(36)}-v${variant}`;
+        const submit = await apiRequest({
+            method: "POST",
+            host: ctx.host,
+            path: "/api/v1/primitives/media/dedupe",
+            auth: ctx.auth,
+            body: { tracer, payload }
+        });
+        assertApiOk(submit, "dedupe");
+        const jobId = submit.json?.job_id;
+        if (parsed.values["no-wait"] || !jobId) {
+            if (!ctx.json && jobId)
+                console.log(`${DIM}Queued ${jobId} (variant ${variant}, tracer ${tracer}). Poll: vidfarm api GET /api/v1/user/me/jobs/${jobId}${RESET}`);
+            results.push({ variant, job_id: jobId ?? null, status: "queued" });
+            continue;
+        }
+        if (!ctx.json)
+            console.log(`${DIM}Deduplicating variant ${variant} (${jobId})… polling every 5s.${RESET}`);
+        const job = await pollGreenscreenJob(ctx, "cloud", jobId);
+        const mediaUrl = resolveJobMediaUrl(job);
+        const status = String(job?.status ?? "");
+        if (!mediaUrl) {
+            results.push({ variant, job_id: jobId, status, media_url: null });
+            if (!ctx.json)
+                console.log(`${RED}Variant ${variant} ${status || "did not finish"} — no media URL.${RESET}`);
+            process.exitCode = 1;
+            continue;
+        }
+        let outPath = null;
+        const outDir = parsed.values["out-dir"];
+        if (parsed.values.out) {
+            outPath = path.resolve(process.cwd(), String(parsed.values.out));
+        }
+        else if (outDir) {
+            const ext = mediaType === "video" ? "mp4" : String(parsed.values["output-format"] ?? "png");
+            outPath = path.resolve(process.cwd(), outDir, `dedupe-${String(variant).padStart(2, "0")}.${ext}`);
+        }
+        if (outPath)
+            await downloadUrlToFile(mediaUrl, outPath);
+        results.push({ variant, job_id: jobId, status, media_url: mediaUrl, out: outPath });
+        if (!ctx.json)
+            console.log(`${GREEN}Variant ${variant} ready:${RESET} ${mediaUrl}${outPath ? ` ${DIM}→ ${outPath}${RESET}` : ""}`);
+    }
+    if (ctx.json) {
+        printJson({ ok: true, target: "cloud", preset, media_type: mediaType, variants: results });
+    }
+    else {
+        console.log(`${DIM}Post each variant to a DIFFERENT account/slot — two accounts posting the same variant defeats the point.${RESET}`);
+    }
+}
+// Run the dedupe pass LOCALLY with bundled ffmpeg — free, offline, no wallet, no
+// in-process backend (so it works in the published cloud-only CLI). Cloud-parity
+// filter graph, straight from lib/dedupe-recipe.ts.
+async function runLocalDedupe(ctx, input) {
+    // A path on disk is used in place; anything else (url / raw id / raws path)
+    // resolves to a URL and downloads first.
+    const directPath = path.resolve(process.cwd(), input.sourceArg);
+    const isLocalFile = !/^https?:\/\//i.test(input.sourceArg) && existsSync(directPath);
+    let sourcePath = directPath;
+    let downloadDir = null;
+    if (!isLocalFile) {
+        const sourceUrl = await resolveSingleMediaUrl(ctx, input.sourceArg);
+        downloadDir = mkdtempSync(path.join(tmpdir(), "vidfarm-dedupe-dl-"));
+        sourcePath = path.join(downloadDir, path.basename(new URL(sourceUrl).pathname) || "source.bin");
+        if (!ctx.json)
+            console.log(`${DIM}Downloading source…${RESET}`);
+        await downloadUrlToFile(sourceUrl, sourcePath);
+    }
+    try {
+        const outDir = input.values["out-dir"];
+        const outputFormat = input.values["output-format"]?.trim().toLowerCase();
+        const results = [];
+        for (let index = 0; index < input.variantCount; index += 1) {
+            const variant = input.firstVariant + index;
+            let outPath;
+            if (input.values.out) {
+                outPath = path.resolve(process.cwd(), String(input.values.out));
+            }
+            else {
+                const base = defaultDedupeOutPath(sourcePath, input.variantCount > 1 ? variant : 1);
+                const named = outputFormat && /\.(png|jpe?g|webp)$/i.test(`.${outputFormat}`)
+                    ? base.replace(/\.[^.]+$/, `.${outputFormat}`)
+                    : base;
+                outPath = outDir
+                    ? path.resolve(process.cwd(), outDir, path.basename(named))
+                    : named;
+            }
+            mkdirSync(path.dirname(outPath), { recursive: true });
+            const result = await dedupeMediaLocal({
+                sourcePath,
+                outputPath: outPath,
+                mediaType: input.mediaType,
+                preset: input.preset,
+                effects: input.effects,
+                variant,
+                seed: input.seed || undefined,
+                jitter: input.jitter,
+                stripMetadata: input.stripMetadata,
+                width: input.values.width !== undefined ? Number(input.values.width) : undefined,
+                height: input.values.height !== undefined ? Number(input.values.height) : undefined,
+                tintColor: input.values["tint-color"],
+                tintOpacity: input.values["tint-opacity"] !== undefined ? Number(input.values["tint-opacity"]) : undefined,
+                crf: input.values.crf !== undefined ? Number(input.values.crf) : undefined
+            });
+            results.push(result);
+            if (!ctx.json) {
+                const label = input.variantCount > 1 ? `Variant ${variant}` : "Deduped";
+                console.log(`${GREEN}${label}:${RESET} ${result.outputPath} ${DIM}(${formatBytes(result.bytes)})${RESET}`);
+                console.log(`${DIM}  ${describeLocalDedupe(result)}${RESET}`);
+                if (result.skewDropped) {
+                    console.log(`${YELLOW}  Note:${RESET} ${DIM}this ffmpeg has no vf_perspective, so the skew stage was skipped — every other transform still applied.${RESET}`);
+                }
+            }
+        }
+        if (ctx.json) {
+            printJson({
+                ok: true,
+                target: "local",
+                preset: input.preset,
+                media_type: results[0]?.mediaType ?? null,
+                variants: results.map((result) => ({
+                    variant: result.variant,
+                    out: result.outputPath,
+                    bytes: result.bytes,
+                    effects: result.effects,
+                    effective_zoom: result.effectiveZoom,
+                    speed: result.speed,
+                    crf: result.crf,
+                    skew_applied: result.skewApplied,
+                    skew_dropped: result.skewDropped,
+                    notes: result.notes
+                }))
+            });
+        }
+        else {
+            console.log(`${DIM}Free — no wallet, no re-render. ${input.variantCount > 1 ? "Post each variant to a DIFFERENT account/slot." : "Post this instead of the original when the original has already been published."}${RESET}`);
+        }
+    }
+    finally {
+        if (downloadDir)
+            rmSync(downloadDir, { recursive: true, force: true });
+    }
+}
 // ── cutout: generate → key greenscreen → alpha-trim to min bounding box ───────
 // The one-shot "make a transparent explainer sticker" verb. Three mechanical
 // steps that used to be run by hand (generate an AI graphic on a green plate →
@@ -5303,9 +5732,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 +5914,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 +5937,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 +6169,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 +6378,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 +6442,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 +6459,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 +6468,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}`);
@@ -7618,6 +8093,28 @@ async function runPostCommand(argv) {
     assertApiOk(result, "post");
     emitResult(result, ctx.json, [["Preview post ", result.json?.post?.share_url]]);
 }
+// Destinations are otherwise invisible to an API-only caller: before this the
+// only place a channel id appeared was the Settings page in a browser.
+async function runChannelsCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me/channels", auth: ctx.auth });
+    assertApiOk(result, "channels");
+    emitResult(result, ctx.json);
+    if (ctx.json)
+        return;
+    const channels = (result.json?.channels ?? []);
+    console.log("");
+    if (channels.length === 0) {
+        console.log("  No destination channels connected. Add an email channel in Settings → Channels, or connect FlockPoster.");
+        return;
+    }
+    console.log(`  ${BOLD}Pass any of these to 'vidfarm schedule --to'${RESET}`);
+    for (const channel of channels) {
+        const unverified = channel.schedulable === false ? "  (unverified — confirm the emailed link first)" : "";
+        console.log(`  ${String(channel.destination_type).padEnd(12)} ${String(channel.handle || channel.title).padEnd(32)} ${channel.destination_id}${unverified}`);
+    }
+}
 async function runScheduleCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -7630,7 +8127,7 @@ async function runScheduleCommand(argv) {
     if (!parsed.values.at)
         throw new Error("schedule requires --at <ISO 8601 timestamp>.");
     if (!parsed.values.to)
-        throw new Error("schedule requires --to <destination_id> (a FlockPoster channel or email).");
+        throw new Error("schedule requires --to <destination> (a channel id, email address, or @handle — run 'vidfarm channels' to list them).");
     const ctx = commonContext(parsed.values);
     const result = await apiRequest({
         method: "POST",
@@ -7638,7 +8135,7 @@ async function runScheduleCommand(argv) {
         path: `/api/v1/approved/posts/${encodeURIComponent(postId)}/schedules`,
         auth: ctx.auth,
         body: {
-            destination_type: parsed.values.type,
+            destination_type: inferDestinationType(argv, parsed.values.type, parsed.values.to),
             destination_id: parsed.values.to,
             scheduled_at: parsed.values.at,
             timezone: parsed.values.timezone,
@@ -7648,6 +8145,61 @@ async function runScheduleCommand(argv) {
     assertApiOk(result, "schedule");
     emitResult(result, ctx.json);
 }
+// --type defaults to flockposter, which silently misroutes 'schedule --to
+// someone@example.com'. An address is unambiguous, so honour it unless the
+// caller said --type outright.
+function inferDestinationType(argv, type, to) {
+    if (argv.includes("--type"))
+        return type ?? "flockposter";
+    return /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(to.trim()) ? "email" : (type ?? "flockposter");
+}
+async function runRescheduleCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), at: { type: "string" }, to: { type: "string" }, type: { type: "string", default: "flockposter" }, timezone: { type: "string" }, notes: { type: "string" } }
+    });
+    const [postId, scheduleId] = parsed.positionals;
+    if (!postId || !scheduleId)
+        throw new Error("reschedule requires <postId> <scheduleId> (list them with 'vidfarm schedules <postId>').");
+    if (!parsed.values.at)
+        throw new Error("reschedule requires --at <ISO 8601 timestamp>.");
+    if (!parsed.values.to)
+        throw new Error("reschedule requires --to <destination> (a channel id, email address, or @handle).");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "PATCH",
+        host: ctx.host,
+        path: `/api/v1/approved/posts/${encodeURIComponent(postId)}/schedules/${encodeURIComponent(scheduleId)}`,
+        auth: ctx.auth,
+        body: {
+            destination_type: inferDestinationType(argv, parsed.values.type, parsed.values.to),
+            destination_id: parsed.values.to,
+            scheduled_at: parsed.values.at,
+            timezone: parsed.values.timezone,
+            additional_notes: parsed.values.notes
+        }
+    });
+    assertApiOk(result, "reschedule");
+    emitResult(result, ctx.json);
+}
+async function runUnscheduleCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const [postId, scheduleId] = parsed.positionals;
+    if (!postId || !scheduleId)
+        throw new Error("unschedule requires <postId> <scheduleId> (list them with 'vidfarm schedules <postId>').");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "DELETE",
+        host: ctx.host,
+        path: `/api/v1/approved/posts/${encodeURIComponent(postId)}/schedules/${encodeURIComponent(scheduleId)}`,
+        auth: ctx.auth
+    });
+    // A failed cancel means the send is STILL QUEUED. assertApiOk throws, which is
+    // the honest outcome — never let this print as if it cancelled.
+    assertApiOk(result, "unschedule");
+    emitResult(result, ctx.json);
+}
 async function runSchedulesCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
     const postId = parsed.positionals[0];
@@ -8254,6 +8806,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,