@mevdragon/vidfarm-devcli 0.20.8 → 0.20.10

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

@@ -104,8 +104,14 @@ Recurring characters that must look the same across videos have a **dedicated, b
 4. **Write `character_about.md` and `<character_id>.json`** (e.g. `character_zara.json`) into the same folder (`browse_files action=write` with `content`, or `vidfarm put-file --content`).
 5. **Annotate all three** with notes naming the character so `files --search "our mascot"` finds them from any phrasing.
 
-**Renaming / fixing up.** Character folders and files are renamable in place — `browse_files action=rename` (web copilot) or `vidfarm directory rename <path> <new-name> [--file-id <id>]` (devcli); the explorer UI has a **Rename** action on every file/folder row. If you rename a character's folder, update the `id`, `sprite_card_path`, and `about_path` inside its manifest to match (and rename the `<character_id>.json` file itself).
+**Renaming / moving / copying.** The whole directory is reorganizable in place, for **paid AND free** users, via three REST routes, their devcli twins, and the explorer's kebab / right-click menu:
+
+- **rename** — `POST /api/v1/user/me/directory/rename` `{ path, new_name, file_id? }` · `vidfarm directory rename <path> <new-name> [--file-id <id>]`. Renames a `/files`/`/temp` file (display name only — the view URL keeps working) or a folder in any writable root (its files + nested subfolders come along).
+- **move** — `POST /api/v1/user/me/directory/move` `{ path, to, file_id? }` · `vidfarm directory move <path> <to-folder> [--file-id <id>]`. Relocates a FILE into `to` (with `file_id`) or nests a whole FOLDER under `to`. **Same root only** (`/files`·`/temp`·`/raws`·`/approved`); metadata-only, so S3 objects are untouched.
+- **copy** — `POST /api/v1/user/me/directory/copy` `{ path, to?, file_id?, new_name? }` · `vidfarm directory copy <path> [<to-folder>] [--file-id <id>] [--as <name>]`. Duplicates a file/folder sharing the same underlying S3 object (cheap, no re-upload). Same root only, `/files`·`/temp`·`/raws` (not `/approved` — a ready post is a single publishable unit; not `/projects` — read-only). Omit `to` to duplicate in place.
+
+The web copilot exposes the same three as `browse_files action=rename|move|copy`. If you rename or move a character's folder, update the `id`, `sprite_card_path`, and `about_path` inside its manifest to match (and rename the `<character_id>.json` file itself).
 
 **Assume My Files is multi-offer.** A user often runs more than one product, offer, brand, or region, and namescopes assets into folders accordingly — by product (`acme-skincare/`, `zensleep/`), by offer/campaign (`summer-sale/`), by region (`us/`, `eu/`), by asset type (`logos/`, `ugc-clips/`), or any arbitrary scheme. There is **no fixed layout** — read the `folders` tree first and reason about how this user organized things. Before pulling assets for a task, infer which folder(s) match the product/offer/region the current composition is about (match folder names to the composition title, video context, and what the user said), then scope reads to that folder so you never mix one brand's logo/product-shot/music into another brand's video. If the target offer is ambiguous, ask which product/offer/region (or which folder) this work is for rather than guessing across offers.
 
-In the editor web copilot the same filesystem is exposed via the **`browse_files` tool** (`action=list` / `action=search` / `action=read` / `action=write` / `action=annotate` / `action=move` / `action=rename`), so the copilot follows the identical reasoning: search or list to find the right offer's folder, then read an asset — or `write` a text doc (About.md, awareness-levels.md, …) or import a media URL (`source_url`) into that folder, annotating anything worth finding again. `action=rename` renames a `/files` or `/temp` file or folder in place (pass `path` + `new_name`, plus `file_id` for a file) — use it to keep character folders and asset names tidy. `browse_files list` defaults to `path='/'` when `path` is omitted, so the `/raws` (hunted raws) and `/temp` (scratch) roots surface alongside the My Files folders instead of being hidden; a `/raws` listing also accepts a `content_type` filter (exact shot-kind — `talking_head`, `b_roll`, `product_shot`, `screen_recording`, …), and every listing paginates via `offset` / `limit`. The devcli equivalents are `vidfarm files [--search]` / `get-file` / `put-file [--notes]` / `annotate-file` / `directory rename`.
+In the editor web copilot the same filesystem is exposed via the **`browse_files` tool** (`action=list` / `action=search` / `action=read` / `action=write` / `action=annotate` / `action=move` / `action=copy` / `action=rename`), so the copilot follows the identical reasoning: search or list to find the right offer's folder, then read an asset — or `write` a text doc (About.md, awareness-levels.md, …) or import a media URL (`source_url`) into that folder, annotating anything worth finding again. `action=rename`/`move`/`copy` reorganize the tree (see the three routes above) — use them to keep character folders and asset names tidy. `browse_files list` defaults to `path='/'` when `path` is omitted, so the `/raws` (hunted raws) and `/temp` (scratch) roots surface alongside the My Files folders instead of being hidden; a `/raws` listing also accepts a `content_type` filter (exact shot-kind — `talking_head`, `b_roll`, `product_shot`, `screen_recording`, …), and every listing paginates via `offset` / `limit`. The devcli equivalents are `vidfarm files [--search]` / `get-file` / `put-file [--notes]` / `annotate-file` / `directory rename|move|copy`.

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

@@ -121,7 +121,7 @@ If a local AI script rewrites text or scenes without consuming those files first
 | `vidfarm generate <image\|video> --prompt "…"` | `POST /api/v1/primitives/{images,videos}/generate` (polls job) | generate AI media → finished URL |
 | `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-background-greenscreen <image> [--key-color #00FF00] [--tolerance 0.3] [--out <f>]` | `POST /api/v1/primitives/images/remove-background-greenscreen` (polls job) | cheap chroma-key removal of a FLAT solid background → transparent PNG (cloud primitive) |
+| `vidfarm remove-greenscreen <image\|video> [--preset green\|blue\|white\|black\|digital-green\|magenta] [--key-color #00FF00] [--tolerance 0.3] [--local] [--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. Aliases: `greenscreen`, `remove-background-greenscreen`. |
 | `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 |
@@ -149,6 +149,8 @@ If a local AI script rewrites text or scenes without consuming those files first
 | `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys |
 | `vidfarm upload <file> [--folder <path>]` | `POST /api/v1/user/me/temporary-files/upload` | upload → durable URL (ephemeral; prefer `--folder temp` for scratch) |
 | `vidfarm download <url> [dest]` | (streams any URL to disk) | download media |
+| `vidfarm download-post <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | download a social/media post into a durable MP4 or slideshow |
+| `vidfarm download-post-audio <url>` | `POST /api/v1/primitives/audio/download` + poll | download a social/media post's audio into a durable audio file |
 | `vidfarm files [--folder <path>]` | `GET /api/v1/user/me/attachments` | list My Files assets + folders |
 | `vidfarm files --search "…" [--folder <path>]` | `POST /api/v1/user/me/attachments/search` | find My Files assets by MEANING (keyword + vector over name/folder/notes) |
 | `vidfarm get-file <id> [dest] [--print]` | (resolve id → view_url, then stream/print) | read one My Files asset |

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

@@ -17,18 +17,17 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/images/remove-background" \
   -d '{"source_image_url": "https://cdn.example.com/photo.jpg"}'
 ```
 
-## Primitive: image_remove_background_greenscreen
+## Primitive: remove-greenscreen (image **or** video chroma-key)
 
-Cheap **local chroma-key** background removal — no third-party API, just `sharp` doing per-pixel color-distance keying, so it costs a fraction of `image_remove_background`. Use it whenever the source sits on a **flat, solid, evenly-lit background**: a green screen, or any single fill color you pass via `key_color` (e.g. `#FFFFFF` for a white background, `#0047BB` for blue). The result is a transparent PNG/WebP at a durable Vidfarm URL.
+**Local chroma-key** background removal for an IMAGE **or** a VIDEO — no third-party API, so it costs a fraction of `image_remove_background`. Use it whenever the source sits on a **flat, solid, evenly-lit background**: a green screen, or any single fill color. An IMAGE returns a transparent PNG/WebP; a VIDEO returns a transparent **WebM (VP9 alpha)** that stays transparent in the `/editor` preview AND the final render (it composites over whatever layers sit behind it).
 
-- `POST /api/v1/primitives/images/remove-background-greenscreen` (flat alias: `POST /api/v1/primitives/remove-background-greenscreen`)
-- Body: `{ "tracer": "...", "payload": { "source_image_url": "https://...", "key_color"?: "#00FF00", "tolerance"?: 0.3, "softness"?: 0.1, "despill"?: true, "output_format"?: "png" | "webp" }, "webhook_url"?: "..." }`
-  - `key_color` — the background color to key out (hex / `rgb(...)` / named `green`/`white`/`blue`/`black`). Default `#00FF00`.
-  - `tolerance` (0–1, default `0.3`) — how close a pixel must be to `key_color` to be removed. Raise it if fringe survives, lower it if the subject is being eaten.
-  - `softness` (0–1, default `0.1`) — feather band beyond `tolerance` for anti-aliased edges.
-  - `despill` (default `true`) — suppresses the residual key-color rim on the subject's edges (only applied for chromatic keys like green/blue).
-- Response: standard primitive job; poll for completion, then read `image.file_url` / `primary_file_url`. `keyed_fraction` in the output tells you what share of pixels were removed (near-0 usually means the wrong `key_color` or too-low `tolerance`).
-- Billing: small compute-only wallet fee (`greenscreen_chroma_key` cost center) — cheaper than the RapidAPI route.
+- **Unified (auto-detect):** `POST /api/v1/primitives/remove-greenscreen` — detects image vs video from the source and dispatches. Preferred entry point.
+- Image-only: `POST /api/v1/primitives/images/remove-background-greenscreen` (flat alias: `POST /api/v1/primitives/remove-background-greenscreen`). Video-only: `POST /api/v1/primitives/videos/remove-greenscreen`.
+- Body: `{ "tracer": "...", "payload": { "source_url": "https://..." (image OR video), "media_type"?: "image" | "video" (skip auto-detect), "preset"?: "green" | "digital-green" | "blue" | "white" | "black" | "magenta", "key_color"?: "#00FF00", "tolerance"?: 0.3, "softness"?: 0.1, "despill"?: true, "output_format"?: "png" | "webp" (image only) }, "webhook_url"?: "..." }`
+  - `preset` — pick a common background color by name; fills `key_color` + tuned defaults. `key_color` (hex / `rgb(...)` / named) overrides the preset for a custom color/range.
+  - `tolerance` (0–1) — how close a pixel must be to key it out. Raise it if fringe survives, lower it if the subject is eaten. `softness` (0–1) feathers the edge; `despill` (default `true`) trims the residual key-color rim (green/blue only).
+- Response: standard primitive job; poll, then read `primary_file_url` (a `.png/.webp` for image, `.webm` for video). After keying, `set_layer_media` the URL back onto the source layer to swap the transparent cut-out in place.
+- Billing: the **real measured AWS compute cost × 1.2** (`greenscreen_chroma_key` cost center) — no flat fee. Far cheaper than the RapidAPI matting route.
 
 ## Primitive: media_overlay ("create media overlay" — Vox-style)
 
@@ -52,6 +51,49 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/images/create-overlay" \
   -d '{"tracer": "vox-overlay", "payload": {"prompt": "a friendly cartoon lightbulb mascot, flat vector illustration", "aspect_ratio": "1:1"}}'
 ```
 
+## Primitive: videos/download
+
+Download a supported social/media post URL into a durable Vidfarm-hosted VISUAL asset. This route is intentionally broader than its old name suggests: it returns either a normal MP4 for video posts, or a slideshow payload for photo/carousel posts.
+
+- `POST /api/v1/primitives/videos/download`
+- Body: `{ "tracer": "...", "payload": { "source_url": "https://...", "quality"?: "best" | "hd" | "full_hd", "save_manifest"?: true }, "webhook_url"?: "..." }`
+- Response: standard primitive job. Poll `GET /api/v1/primitives/jobs/:jobId` until `status: "succeeded"`.
+  - Video post: read `primary_file_url` / `video.file_url` / `videoUrl` for the durable MP4.
+  - Photo/carousel post: read `mediaKind: "slideshow"`, ordered `slideImageUrls[]`, optional `slideAudioUrl`, and `primary_file_url` (first slide image).
+- Billing: RapidAPI pass-through wallet charge (`rapidapi_video_download`) plus the small mirror/extract pass (`video_download_lambda` when MP4 download is involved).
+- Free-plan / no-spend rule: do **not** use this paid route when the user wants a free path. In the web app, tell them to use the browser to find a downloader instead. Fallback wording is explicit: suggest Googling `"youtube video downloader"` or `"tiktok/twitter/instagram/etc audio/video downloader"`.
+- devcli wrapper: `vidfarm download-post <url> [--quality best|hd|full_hd]`
+
+Example:
+
+```bash
+curl -X POST "$VIDFARM_BASE/api/v1/primitives/videos/download" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"tracer": "demo-download-post", "payload": {"source_url": "https://www.tiktok.com/@example/video/123"}}'
+```
+
+## Primitive: audio/download
+
+Download just the original audio/music/voice track from a supported social/media post URL into a durable Vidfarm-hosted audio file. It reuses the same RapidAPI resolver as `videos/download`, but returns audio instead of a video/slideshow.
+
+- `POST /api/v1/primitives/audio/download`
+- Body: `{ "tracer": "...", "payload": { "source_url": "https://...", "save_manifest"?: true }, "webhook_url"?: "..." }`
+- Response: standard primitive job. Poll `GET /api/v1/primitives/jobs/:jobId` until `status: "succeeded"`, then read `primary_file_url` / `audio.file_url` / `audioUrl`.
+- Behavior: prefers the provider's direct audio track when present; otherwise resolves the source video and extracts audio server-side.
+- Billing: same RapidAPI wallet class as `videos/download`.
+- Free-plan / no-spend rule: same as the visual download route. Use the browser and, if needed, suggest Googling `"youtube audio downloader"` or `"tiktok/twitter/instagram/etc audio/video downloader"` instead of spending wallet credits.
+- devcli wrapper: `vidfarm download-post-audio <url>`
+
+Example:
+
+```bash
+curl -X POST "$VIDFARM_BASE/api/v1/primitives/audio/download" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"tracer": "demo-download-audio", "payload": {"source_url": "https://www.youtube.com/watch?v=example"}}'
+```
+
 ## 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

@@ -851,11 +851,17 @@ Recurring characters that must look the same across videos have a **dedicated, b
 4. **Write `character_about.md` and `<character_id>.json`** (e.g. `character_zara.json`) into the same folder (`browse_files action=write` with `content`, or `vidfarm put-file --content`).
 5. **Annotate all three** with notes naming the character so `files --search "our mascot"` finds them from any phrasing.
 
-**Renaming / fixing up.** Character folders and files are renamable in place — `browse_files action=rename` (web copilot) or `vidfarm directory rename <path> <new-name> [--file-id <id>]` (devcli); the explorer UI has a **Rename** action on every file/folder row. If you rename a character's folder, update the `id`, `sprite_card_path`, and `about_path` inside its manifest to match (and rename the `<character_id>.json` file itself).
+**Renaming / moving / copying.** The whole directory is reorganizable in place, for **paid AND free** users, via three REST routes, their devcli twins, and the explorer's kebab / right-click menu:
+
+- **rename** — `POST /api/v1/user/me/directory/rename` `{ path, new_name, file_id? }` · `vidfarm directory rename <path> <new-name> [--file-id <id>]`. Renames a `/files`/`/temp` file (display name only — the view URL keeps working) or a folder in any writable root (its files + nested subfolders come along).
+- **move** — `POST /api/v1/user/me/directory/move` `{ path, to, file_id? }` · `vidfarm directory move <path> <to-folder> [--file-id <id>]`. Relocates a FILE into `to` (with `file_id`) or nests a whole FOLDER under `to`. **Same root only** (`/files`·`/temp`·`/raws`·`/approved`); metadata-only, so S3 objects are untouched.
+- **copy** — `POST /api/v1/user/me/directory/copy` `{ path, to?, file_id?, new_name? }` · `vidfarm directory copy <path> [<to-folder>] [--file-id <id>] [--as <name>]`. Duplicates a file/folder sharing the same underlying S3 object (cheap, no re-upload). Same root only, `/files`·`/temp`·`/raws` (not `/approved` — a ready post is a single publishable unit; not `/projects` — read-only). Omit `to` to duplicate in place.
+
+The web copilot exposes the same three as `browse_files action=rename|move|copy`. If you rename or move a character's folder, update the `id`, `sprite_card_path`, and `about_path` inside its manifest to match (and rename the `<character_id>.json` file itself).
 
 **Assume My Files is multi-offer.** A user often runs more than one product, offer, brand, or region, and namescopes assets into folders accordingly — by product (`acme-skincare/`, `zensleep/`), by offer/campaign (`summer-sale/`), by region (`us/`, `eu/`), by asset type (`logos/`, `ugc-clips/`), or any arbitrary scheme. There is **no fixed layout** — read the `folders` tree first and reason about how this user organized things. Before pulling assets for a task, infer which folder(s) match the product/offer/region the current composition is about (match folder names to the composition title, video context, and what the user said), then scope reads to that folder so you never mix one brand's logo/product-shot/music into another brand's video. If the target offer is ambiguous, ask which product/offer/region (or which folder) this work is for rather than guessing across offers.
 
-In the editor web copilot the same filesystem is exposed via the **`browse_files` tool** (`action=list` / `action=search` / `action=read` / `action=write` / `action=annotate` / `action=move` / `action=rename`), so the copilot follows the identical reasoning: search or list to find the right offer's folder, then read an asset — or `write` a text doc (About.md, awareness-levels.md, …) or import a media URL (`source_url`) into that folder, annotating anything worth finding again. `action=rename` renames a `/files` or `/temp` file or folder in place (pass `path` + `new_name`, plus `file_id` for a file) — use it to keep character folders and asset names tidy. `browse_files list` defaults to `path='/'` when `path` is omitted, so the `/raws` (hunted raws) and `/temp` (scratch) roots surface alongside the My Files folders instead of being hidden; a `/raws` listing also accepts a `content_type` filter (exact shot-kind — `talking_head`, `b_roll`, `product_shot`, `screen_recording`, …), and every listing paginates via `offset` / `limit`. The devcli equivalents are `vidfarm files [--search]` / `get-file` / `put-file [--notes]` / `annotate-file` / `directory rename`.
+In the editor web copilot the same filesystem is exposed via the **`browse_files` tool** (`action=list` / `action=search` / `action=read` / `action=write` / `action=annotate` / `action=move` / `action=copy` / `action=rename`), so the copilot follows the identical reasoning: search or list to find the right offer's folder, then read an asset — or `write` a text doc (About.md, awareness-levels.md, …) or import a media URL (`source_url`) into that folder, annotating anything worth finding again. `action=rename`/`move`/`copy` reorganize the tree (see the three routes above) — use them to keep character folders and asset names tidy. `browse_files list` defaults to `path='/'` when `path` is omitted, so the `/raws` (hunted raws) and `/temp` (scratch) roots surface alongside the My Files folders instead of being hidden; a `/raws` listing also accepts a `content_type` filter (exact shot-kind — `talking_head`, `b_roll`, `product_shot`, `screen_recording`, …), and every listing paginates via `offset` / `limit`. The devcli equivalents are `vidfarm files [--search]` / `get-file` / `put-file [--notes]` / `annotate-file` / `directory rename|move|copy`.
 
 ## Automate a template via REST
 
@@ -980,7 +986,7 @@ If a local AI script rewrites text or scenes without consuming those files first
 | `vidfarm generate <image\|video> --prompt "…"` | `POST /api/v1/primitives/{images,videos}/generate` (polls job) | generate AI media → finished URL |
 | `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-background-greenscreen <image> [--key-color #00FF00] [--tolerance 0.3] [--out <f>]` | `POST /api/v1/primitives/images/remove-background-greenscreen` (polls job) | cheap chroma-key removal of a FLAT solid background → transparent PNG (cloud primitive) |
+| `vidfarm remove-greenscreen <image\|video> [--preset green\|blue\|white\|black\|digital-green\|magenta] [--key-color #00FF00] [--tolerance 0.3] [--local] [--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. Aliases: `greenscreen`, `remove-background-greenscreen`. |
 | `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 |
@@ -1008,6 +1014,8 @@ If a local AI script rewrites text or scenes without consuming those files first
 | `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys |
 | `vidfarm upload <file> [--folder <path>]` | `POST /api/v1/user/me/temporary-files/upload` | upload → durable URL (ephemeral; prefer `--folder temp` for scratch) |
 | `vidfarm download <url> [dest]` | (streams any URL to disk) | download media |
+| `vidfarm download-post <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | download a social/media post into a durable MP4 or slideshow |
+| `vidfarm download-post-audio <url>` | `POST /api/v1/primitives/audio/download` + poll | download a social/media post's audio into a durable audio file |
 | `vidfarm files [--folder <path>]` | `GET /api/v1/user/me/attachments` | list My Files assets + folders |
 | `vidfarm files --search "…" [--folder <path>]` | `POST /api/v1/user/me/attachments/search` | find My Files assets by MEANING (keyword + vector over name/folder/notes) |
 | `vidfarm get-file <id> [dest] [--print]` | (resolve id → view_url, then stream/print) | read one My Files asset |
@@ -1149,18 +1157,17 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/images/remove-background" \
   -d '{"source_image_url": "https://cdn.example.com/photo.jpg"}'
 ```
 
-## Primitive: image_remove_background_greenscreen
+## Primitive: remove-greenscreen (image **or** video chroma-key)
 
-Cheap **local chroma-key** background removal — no third-party API, just `sharp` doing per-pixel color-distance keying, so it costs a fraction of `image_remove_background`. Use it whenever the source sits on a **flat, solid, evenly-lit background**: a green screen, or any single fill color you pass via `key_color` (e.g. `#FFFFFF` for a white background, `#0047BB` for blue). The result is a transparent PNG/WebP at a durable Vidfarm URL.
+**Local chroma-key** background removal for an IMAGE **or** a VIDEO — no third-party API, so it costs a fraction of `image_remove_background`. Use it whenever the source sits on a **flat, solid, evenly-lit background**: a green screen, or any single fill color. An IMAGE returns a transparent PNG/WebP; a VIDEO returns a transparent **WebM (VP9 alpha)** that stays transparent in the `/editor` preview AND the final render (it composites over whatever layers sit behind it).
 
-- `POST /api/v1/primitives/images/remove-background-greenscreen` (flat alias: `POST /api/v1/primitives/remove-background-greenscreen`)
-- Body: `{ "tracer": "...", "payload": { "source_image_url": "https://...", "key_color"?: "#00FF00", "tolerance"?: 0.3, "softness"?: 0.1, "despill"?: true, "output_format"?: "png" | "webp" }, "webhook_url"?: "..." }`
-  - `key_color` — the background color to key out (hex / `rgb(...)` / named `green`/`white`/`blue`/`black`). Default `#00FF00`.
-  - `tolerance` (0–1, default `0.3`) — how close a pixel must be to `key_color` to be removed. Raise it if fringe survives, lower it if the subject is being eaten.
-  - `softness` (0–1, default `0.1`) — feather band beyond `tolerance` for anti-aliased edges.
-  - `despill` (default `true`) — suppresses the residual key-color rim on the subject's edges (only applied for chromatic keys like green/blue).
-- Response: standard primitive job; poll for completion, then read `image.file_url` / `primary_file_url`. `keyed_fraction` in the output tells you what share of pixels were removed (near-0 usually means the wrong `key_color` or too-low `tolerance`).
-- Billing: small compute-only wallet fee (`greenscreen_chroma_key` cost center) — cheaper than the RapidAPI route.
+- **Unified (auto-detect):** `POST /api/v1/primitives/remove-greenscreen` — detects image vs video from the source and dispatches. Preferred entry point.
+- Image-only: `POST /api/v1/primitives/images/remove-background-greenscreen` (flat alias: `POST /api/v1/primitives/remove-background-greenscreen`). Video-only: `POST /api/v1/primitives/videos/remove-greenscreen`.
+- Body: `{ "tracer": "...", "payload": { "source_url": "https://..." (image OR video), "media_type"?: "image" | "video" (skip auto-detect), "preset"?: "green" | "digital-green" | "blue" | "white" | "black" | "magenta", "key_color"?: "#00FF00", "tolerance"?: 0.3, "softness"?: 0.1, "despill"?: true, "output_format"?: "png" | "webp" (image only) }, "webhook_url"?: "..." }`
+  - `preset` — pick a common background color by name; fills `key_color` + tuned defaults. `key_color` (hex / `rgb(...)` / named) overrides the preset for a custom color/range.
+  - `tolerance` (0–1) — how close a pixel must be to key it out. Raise it if fringe survives, lower it if the subject is eaten. `softness` (0–1) feathers the edge; `despill` (default `true`) trims the residual key-color rim (green/blue only).
+- Response: standard primitive job; poll, then read `primary_file_url` (a `.png/.webp` for image, `.webm` for video). After keying, `set_layer_media` the URL back onto the source layer to swap the transparent cut-out in place.
+- Billing: the **real measured AWS compute cost × 1.2** (`greenscreen_chroma_key` cost center) — no flat fee. Far cheaper than the RapidAPI matting route.
 
 ## Primitive: media_overlay ("create media overlay" — Vox-style)
 
@@ -1184,6 +1191,49 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/images/create-overlay" \
   -d '{"tracer": "vox-overlay", "payload": {"prompt": "a friendly cartoon lightbulb mascot, flat vector illustration", "aspect_ratio": "1:1"}}'
 ```
 
+## Primitive: videos/download
+
+Download a supported social/media post URL into a durable Vidfarm-hosted VISUAL asset. This route is intentionally broader than its old name suggests: it returns either a normal MP4 for video posts, or a slideshow payload for photo/carousel posts.
+
+- `POST /api/v1/primitives/videos/download`
+- Body: `{ "tracer": "...", "payload": { "source_url": "https://...", "quality"?: "best" | "hd" | "full_hd", "save_manifest"?: true }, "webhook_url"?: "..." }`
+- Response: standard primitive job. Poll `GET /api/v1/primitives/jobs/:jobId` until `status: "succeeded"`.
+  - Video post: read `primary_file_url` / `video.file_url` / `videoUrl` for the durable MP4.
+  - Photo/carousel post: read `mediaKind: "slideshow"`, ordered `slideImageUrls[]`, optional `slideAudioUrl`, and `primary_file_url` (first slide image).
+- Billing: RapidAPI pass-through wallet charge (`rapidapi_video_download`) plus the small mirror/extract pass (`video_download_lambda` when MP4 download is involved).
+- Free-plan / no-spend rule: do **not** use this paid route when the user wants a free path. In the web app, tell them to use the browser to find a downloader instead. Fallback wording is explicit: suggest Googling `"youtube video downloader"` or `"tiktok/twitter/instagram/etc audio/video downloader"`.
+- devcli wrapper: `vidfarm download-post <url> [--quality best|hd|full_hd]`
+
+Example:
+
+```bash
+curl -X POST "$VIDFARM_BASE/api/v1/primitives/videos/download" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"tracer": "demo-download-post", "payload": {"source_url": "https://www.tiktok.com/@example/video/123"}}'
+```
+
+## Primitive: audio/download
+
+Download just the original audio/music/voice track from a supported social/media post URL into a durable Vidfarm-hosted audio file. It reuses the same RapidAPI resolver as `videos/download`, but returns audio instead of a video/slideshow.
+
+- `POST /api/v1/primitives/audio/download`
+- Body: `{ "tracer": "...", "payload": { "source_url": "https://...", "save_manifest"?: true }, "webhook_url"?: "..." }`
+- Response: standard primitive job. Poll `GET /api/v1/primitives/jobs/:jobId` until `status: "succeeded"`, then read `primary_file_url` / `audio.file_url` / `audioUrl`.
+- Behavior: prefers the provider's direct audio track when present; otherwise resolves the source video and extracts audio server-side.
+- Billing: same RapidAPI wallet class as `videos/download`.
+- Free-plan / no-spend rule: same as the visual download route. Use the browser and, if needed, suggest Googling `"youtube audio downloader"` or `"tiktok/twitter/instagram/etc audio/video downloader"` instead of spending wallet credits.
+- devcli wrapper: `vidfarm download-post-audio <url>`
+
+Example:
+
+```bash
+curl -X POST "$VIDFARM_BASE/api/v1/primitives/audio/download" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"tracer": "demo-download-audio", "payload": {"source_url": "https://www.youtube.com/watch?v=example"}}'
+```
+
 ## 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/dist/src/cli.js

@@ -22,7 +22,7 @@ import { renderCompositionStills } from "./devcli/stills.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
 import { runSkillsCommand } from "./devcli/skills.js";
 import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
-import { resolveLocalDataDir, localBackendAvailable, LocalModeUnavailableError } from "./devcli/local-backend.js";
+import { resolveLocalDataDir, localBackendAvailable, LocalModeUnavailableError, localApiRequest } from "./devcli/local-backend.js";
 // vidfarm-devcli — command-line bridge for the Vidfarm video studio. The
 // `serve` command boots the FULL editor locally (single origin, disk-backed
 // records + storage) so power users edit compositions on disk while a browser
@@ -172,14 +172,20 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --out <file>            Download the transparent PNG to this path
     --no-wait               Return the job id instead of polling to the URL
     --place <dir> --at <time>|--replace <layer_key>   Fuse onto a composition
-  remove-background-greenscreen <image|url>   Cheap chroma-key removal of a FLAT
-                            solid background → transparent PNG (cloud primitive;
-                            differs from remove-background = local ONNX matting)
-                            → POST /api/v1/primitives/images/remove-background-greenscreen
-    --key-color <c>         Background color to key out (default #00FF00; e.g. #FFFFFF)
+  remove-greenscreen <image|video|url>   Key out a FLAT solid background from an
+                            IMAGE (→ transparent PNG/WebP) or VIDEO (→ transparent
+                            WebM/VP9 alpha), auto-detecting the media kind.
+                            (aliases: greenscreen, remove-background-greenscreen)
+                            → POST /api/v1/primitives/remove-greenscreen
+    --preset <name>         green | digital-green | blue | white | black | magenta
+    --key-color <c>         Custom background color (hex/rgb/named; overrides --preset)
+    --media-type <k>        Force image|video instead of auto-detecting
     --tolerance <0..1>      Key radius (default 0.3); --softness <0..1> edge feather (0.1)
     --no-despill            Skip edge color-fringe suppression
-    --out <file>            Download the transparent PNG to this path
+    --output-format <f>     Image only: png|webp
+    --local                 Run the keyer in-process for FREE (sharp/ffmpeg, no wallet)
+    --cloud                 Force the billed cloud primitive (default when a key is set)
+    --out <file>            Download the transparent result to this path
   place <dir|composition.html>   Insert media into a local composition
                             (fill a gap, replace a scene, or overlay an AUDIO
                             track) — same clip markup the browser editor makes;
@@ -276,6 +282,10 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --clip [--prompt "..."] [--provider gemini|openai|openrouter|nvidia]
                             (raw) AI-clip the video into matching moments instead of
                             importing the whole thing (BYOK; nvidia = lite clipping key)
+                            Note: raw mode needs a VIDEO URL. For a LOCAL FILE from
+                            your computer, use 'vidfarm clipper ./file.mp4 --cloud'
+                            to upload it and import the whole video into /raws, or
+                            add --start/--end to save one exact subrange.
 
 Raws (the third library — mine long-form video into a reusable raws store):
   raws scan <video-path>    Hunt short clips out of a long video.        LOCAL-FIRST: local ffmpeg +
@@ -285,6 +295,9 @@ Raws (the third library — mine long-form video into a reusable raws store):
     --duration <sec>          Target clip length as a SOFT band (10→5-20s, 30→20-40s)
     --aspect 9:16|16:9|4:3|1:1  Crop clips (also: vertical/horizontal/square) [--crop-focus <f>]
     --no-text                 Prefer scenes WITHOUT captions/on-screen text (selection only)
+    --notes "<private notes>" Store private owner notes as user_notes on derived raws and
+                              bias decomposition/categorization with them. Explicit private
+                              shot-kind hints like "content_type: demo" stay owner-only.
     --cloud [--url <url>]     BACKUP: run on the deployed pipeline       → POST /raws/scan (+ poll)
                               (uploads to your temp folder — 30-day TTL — bills AWS compute only)
     --folder <name>           (with --cloud) Save the mined clips into /raws/<name>
@@ -308,9 +321,18 @@ Raws (the third library — mine long-form video into a reusable raws store):
     --tracer <name>           Group this session's clips (also the default folder)
     --folder <name>           Save the clip into /raws/<name>
     --name <text>             Human name for the clip
+    --notes "<private notes>" Store private owner notes as user_notes on the imported raw.
+                            The notes also bias categorization/decomposition, and an
+                            explicit private shot-kind hint like 'content_type: demo'
+                            or 'category: talking_head' is honored only for that owner.
     --audio-only              Save just the audio of the subrange as an .m4a raw
                             (needs --start/--end; e.g. lift a copyright-free track)
                             (multi-clip: re-run with a new range + same --tracer)
+                            Direct local-file upload to CLOUD raws is supported:
+                            'vidfarm clipper ./source.mp4 --cloud --folder campaign'
+                            imports the whole local file as one raw; add
+                            '--start ... --end ...' to upload the local file and
+                            save only that exact clipped range.
 
 Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit backup:
   tts "<text>"              Text → narration audio file.                 LOCAL: your OPENAI/GEMINI/
@@ -450,6 +472,8 @@ Approve & schedule (publish a finished MP4 as a shareable post):
     --media <url|file>      Extra media (repeatable; local files auto-upload to temp/)
     --folder <path>         Temp-store folder for uploaded local files (default: temp)
     --caption <text>        Post caption (required)
+                            Direct local-file upload is supported here:
+                            'vidfarm approve --video ./final.mp4 --caption "..."'
   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
   schedule <postId>         Schedule an approved post to a channel       → POST /api/v1/approved/posts/:postId/schedules
@@ -482,6 +506,11 @@ Files (multi-step flows the devcli handles for you):
                             e.g. vidfarm put-file About.md --folder acme-skincare
                                  echo "..." | vidfarm put-file --stdin --as About.md --folder acme
   download <url> [dest]     Stream any Vidfarm/media URL to disk
+  download-post <url>       Download a social/media post into Vidfarm media → POST /api/v1/primitives/videos/download
+    --quality <q>           best | hd | full_hd (default: best)
+    --no-wait               Return the queued job immediately instead of polling
+  download-post-audio <url> Download a social/media post's audio into Vidfarm → POST /api/v1/primitives/audio/download
+    --no-wait               Return the queued job immediately instead of polling
   files                     List My Files assets + folders               → GET /api/v1/user/me/attachments
     --folder <path>         Only files under this folder (e.g. a product/offer)
     --search <query>        Find files by MEANING (keyword + vector over  → POST /api/v1/user/me/attachments/search
@@ -500,6 +529,10 @@ Files (multi-step flows the devcli handles for you):
     --content-type <a,b>    Filter the /raws branch by shot-KIND tag (talking_head, b_roll, …)
   directory rename <path> <new-name>  Rename a /files or /temp file/folder   → POST /api/v1/user/me/directory/rename
     --file-id <id>          Rename a FILE (display name); omit to rename the folder at <path>
+  directory move <path> <to-folder>   Move a file/folder into another folder  → POST /api/v1/user/me/directory/move
+    --file-id <id>          Move a FILE; omit to move the folder (same root, e.g. /raws/demos → /raws/archive)
+  directory copy <path> [<to-folder>] Duplicate a file/folder (shared S3 obj)  → POST /api/v1/user/me/directory/copy
+    --file-id <id> --as <name>   Copy a FILE; omit --file-id to copy the folder; --as renames the copy
   directory save-url <url>  Save a durable media URL INTO My Files at a folder → POST /api/v1/user/me/attachments/from-url
     --folder <path>         Destination folder under /files (e.g. inpaints, promos)
     --as <name>             Name the saved file · --notes <text> vector-embedded notes
@@ -640,10 +673,11 @@ async function main() {
         case "overlay":
             await runCreateOverlayCommand(rest);
             return;
+        case "remove-greenscreen":
         case "remove-background-greenscreen":
         case "rmbg-green":
         case "greenscreen":
-            await runRemoveBackgroundGreenscreenCommand(rest);
+            await runRemoveGreenscreenCommand(rest);
             return;
         case "tts":
             await runTtsCommand(rest);
@@ -740,6 +774,12 @@ async function main() {
         case "download":
             await runDownloadCommand(rest);
             return;
+        case "download-post":
+            await runDownloadPostCommand(rest);
+            return;
+        case "download-post-audio":
+            await runDownloadPostAudioCommand(rest);
+            return;
         case "files":
             await runFilesCommand(rest);
             return;
@@ -2849,6 +2889,7 @@ function resolveJobMediaUrl(job) {
     const output = (result.output && typeof result.output === "object") ? result.output : result;
     const direct = readStr(output.primary_file_url)
         ?? readStr(output.video?.file_url)
+        ?? readStr(output.audio?.file_url)
         ?? readStr(output.image?.file_url)
         ?? readStr(output.render?.output_url);
     if (direct)
@@ -3551,33 +3592,67 @@ async function runCreateOverlayCommand(argv) {
     }
 }
 // ── Green-screen (chroma-key) background removal ──────────────────────────────
-// The devcli twin of the image_remove_background_greenscreen primitive: cheap
-// local chroma key on a flat, solid background. A cloud primitive job (distinct
-// from `vidfarm remove-background`, which is the free LOCAL ONNX matting engine).
-async function runRemoveBackgroundGreenscreenCommand(argv) {
+// The devcli twin of the remove-greenscreen primitive: key out a flat, solid
+// background from an IMAGE (→ transparent PNG/WebP) OR a VIDEO (→ transparent
+// WebM/VP9 alpha), auto-detecting the media kind. LOCAL vs CLOUD: --local runs
+// the keyer in-process for FREE (sharp/ffmpeg, no wallet); --cloud runs the
+// billed primitive. Default = cloud (paid), unless there's no cloud key AND the
+// local backend is present (free / offline), in which case it runs local.
+const GREENSCREEN_PRESET_NAMES = new Set(["green", "digital-green", "blue", "white", "black", "magenta"]);
+function resolveGreenscreenTarget(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;
+    const hasCloudKey = Boolean(values["api-key"] ?? process.env.VIDFARM_API_KEY);
+    if (!hasCloudKey && localBackendAvailable())
+        return "local";
+    return "cloud";
+}
+async function runRemoveGreenscreenCommand(argv) {
     const parsed = parseArgs({
         args: argv,
         allowPositionals: true,
         options: {
             ...commonOptions(),
             source: { type: "string" },
+            preset: { type: "string" },
+            "media-type": { type: "string" },
             "key-color": { type: "string" },
             tolerance: { type: "string" },
             softness: { type: "string" },
             "no-despill": { type: "boolean", default: false },
             "output-format": { type: "string" },
+            local: { type: "boolean", default: false },
+            cloud: { type: "boolean", default: false },
             out: { type: "string" },
             "no-wait": { type: "boolean", default: false },
             tracer: { type: "string" }
         }
     });
     const ctx = commonContext(parsed.values);
+    const target = resolveGreenscreenTarget(parsed.values);
+    if (target === "local" && !localBackendAvailable())
+        throw new LocalModeUnavailableError();
     const sourceArg = parsed.values.source ?? parsed.positionals[0];
     if (!sourceArg) {
-        throw new Error("remove-background-greenscreen requires a source image: `vidfarm remove-background-greenscreen <image|url> [--key-color #00FF00] [--out cutout.png]`.");
+        throw new Error("remove-greenscreen requires a source image or video: `vidfarm remove-greenscreen <image|video|url> [--preset green|blue|white|black|digital-green|magenta] [--key-color #00FF00] [--local] [--out cutout.png|.webm]`.");
     }
     const sourceUrl = await resolveSingleMediaUrl(ctx, sourceArg);
-    const payload = { source_image_url: sourceUrl };
+    const presetRaw = parsed.values.preset?.trim().toLowerCase();
+    if (presetRaw && !GREENSCREEN_PRESET_NAMES.has(presetRaw)) {
+        throw new Error(`Unknown --preset "${presetRaw}". Choose one of: ${[...GREENSCREEN_PRESET_NAMES].join(", ")}, or pass --key-color <hex>.`);
+    }
+    const mediaTypeArg = parsed.values["media-type"]?.trim().toLowerCase();
+    const mediaType = mediaTypeArg === "image" || mediaTypeArg === "video"
+        ? mediaTypeArg
+        : (/\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(sourceUrl) ? "video" : "image");
+    const payload = { source_url: sourceUrl, media_type: mediaType };
+    if (presetRaw)
+        payload.preset = presetRaw;
     if (parsed.values["key-color"])
         payload.key_color = parsed.values["key-color"];
     if (parsed.values.tolerance)
@@ -3586,12 +3661,17 @@ async function runRemoveBackgroundGreenscreenCommand(argv) {
         payload.softness = Number(parsed.values.softness);
     if (parsed.values["no-despill"])
         payload.despill = false;
-    if (parsed.values["output-format"])
+    if (mediaType === "image" && parsed.values["output-format"])
         payload.output_format = parsed.values["output-format"];
-    const tracer = parsed.values.tracer ?? `devcli-gsbg-${Date.now().toString(36)}`;
-    const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/images/remove-background-greenscreen", auth: ctx.auth, body: { tracer, payload } });
-    assertApiOk(submit, "remove-background-greenscreen");
+    const tracer = parsed.values.tracer ?? `devcli-greenscreen-${Date.now().toString(36)}`;
+    const route = "/api/v1/primitives/remove-greenscreen";
+    const submit = target === "local"
+        ? await localApiRequest({ method: "POST", path: route, auth: ctx.auth, body: { tracer, payload }, home: ctx.home })
+        : await apiRequest({ method: "POST", host: ctx.host, path: route, auth: ctx.auth, body: { tracer, payload } });
+    assertApiOk(submit, "remove-greenscreen");
     const jobId = submit.json?.job_id;
+    if (!ctx.json)
+        console.log(`${DIM}${target === "local" ? "Local (free)" : "Cloud"} ${mediaType} greenscreen removal…${RESET}`);
     const wait = !parsed.values["no-wait"];
     if (!wait || !jobId) {
         if (!ctx.json && jobId)
@@ -3601,7 +3681,7 @@ async function runRemoveBackgroundGreenscreenCommand(argv) {
     }
     if (!ctx.json)
         console.log(`${DIM}Keying out background (${jobId})… polling every 5s.${RESET}`);
-    const job = await pollPrimitiveJob(ctx, jobId);
+    const job = await pollGreenscreenJob(ctx, target, jobId);
     const mediaUrl = resolveJobMediaUrl(job);
     const status = String(job?.status ?? "");
     if (!mediaUrl) {
@@ -3621,12 +3701,38 @@ async function runRemoveBackgroundGreenscreenCommand(argv) {
         await downloadUrlToFile(mediaUrl, outPath);
     }
     if (ctx.json) {
-        printJson({ ok: true, job_id: jobId, media_url: mediaUrl, out: outPath, keyed_fraction: job?.result?.keyed_fraction ?? null });
+        printJson({ ok: true, job_id: jobId, media_type: mediaType, target, media_url: mediaUrl, out: outPath });
     }
     else {
-        console.log(`${GREEN}Transparent cut-out ready:${RESET} ${mediaUrl}`);
+        console.log(`${GREEN}Transparent ${mediaType === "video" ? "WebM" : "cut-out"} ready:${RESET} ${mediaUrl}`);
         if (outPath)
             console.log(`${DIM}Saved to ${outPath}${RESET}`);
+        console.log(`${DIM}Place it with: vidfarm set-media <dir> --src "${mediaUrl}" --replace <layer_key> (keeps its transparency).${RESET}`);
+    }
+}
+// Poll a greenscreen job through the same backend it was submitted to (local
+// in-process app or cloud). Mirrors pollPrimitiveJob's terminal conditions.
+async function pollGreenscreenJob(ctx, target, jobId) {
+    if (target !== "local")
+        return pollPrimitiveJob(ctx, jobId);
+    const MAX_WAIT_MS = 8 * 60 * 1000;
+    const startedAt = Date.now();
+    let last = null;
+    for (;;) {
+        await sleep(5000);
+        const res = await localApiRequest({ method: "GET", path: `/api/v1/user/me/jobs/${encodeURIComponent(jobId)}`, auth: ctx.auth, home: ctx.home });
+        if (res.ok && res.json) {
+            last = res.json;
+            const status = String(last.status ?? "");
+            if (!ctx.json)
+                console.log(`${DIM}  ${status}${typeof last.progress === "number" ? ` ${Math.round(last.progress * 100)}%` : ""}${RESET}`);
+            if (status === "succeeded" || status === "failed" || status === "cancelled")
+                return last;
+            if (resolveJobMediaUrl(last))
+                return last;
+        }
+        if (Date.now() - startedAt > MAX_WAIT_MS)
+            return last ?? { status: "timeout" };
     }
 }
 // ── Speech: tts / stt ────────────────────────────────────────────────────────
@@ -4760,6 +4866,7 @@ async function runClipperCommand(argv) {
             tracer: { type: "string" },
             folder: { type: "string" },
             name: { type: "string" },
+            notes: { type: "string" },
             "audio-only": { type: "boolean", default: false }
         }
     });
@@ -4791,6 +4898,8 @@ async function runClipperCommand(argv) {
         body.folder_path = String(parsed.values.folder);
     if (parsed.values.name)
         body.name = String(parsed.values.name);
+    if (parsed.values.notes)
+        body.user_notes = String(parsed.values.notes);
     if (audioOnly)
         body.audio_only = true;
     // Local-first: local URL clipping hands the source page URL straight to the
@@ -5176,6 +5285,88 @@ async function runDownloadCommand(argv) {
         console.log(`${GREEN}Downloaded ${formatBytes(bytes)} → ${dest}${RESET}`);
     }
 }
+async function runDownloadPostCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), quality: { type: "string", default: "best" }, "no-wait": { type: "boolean", default: false }, tracer: { type: "string" } }
+    });
+    const url = parsed.positionals[0];
+    if (!url)
+        throw new Error("download-post requires a source URL.");
+    const quality = String(parsed.values.quality ?? "best");
+    if (!["best", "hd", "full_hd"].includes(quality)) {
+        throw new Error("download-post --quality must be one of: best, hd, full_hd.");
+    }
+    const ctx = commonContext(parsed.values);
+    const tracer = String(parsed.values.tracer ?? `devcli-download-post-${Date.now().toString(36)}`);
+    const submit = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/api/v1/primitives/videos/download",
+        auth: ctx.auth,
+        body: { tracer, payload: { source_url: url, quality } }
+    });
+    assertApiOk(submit, "download-post");
+    const jobId = submit.json?.job_id;
+    if (!jobId || parsed.values["no-wait"]) {
+        emitResult(submit, ctx.json);
+        return;
+    }
+    if (!ctx.json)
+        console.log(`${DIM}Downloading social post (${jobId})… polling every 5s.${RESET}`);
+    const final = await pollPrimitiveJob(ctx, jobId);
+    emitPrimitiveJobResult(ctx, final, "download-post");
+}
+async function runDownloadPostAudioCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), "no-wait": { type: "boolean", default: false }, tracer: { type: "string" } }
+    });
+    const url = parsed.positionals[0];
+    if (!url)
+        throw new Error("download-post-audio requires a source URL.");
+    const ctx = commonContext(parsed.values);
+    const tracer = String(parsed.values.tracer ?? `devcli-download-post-audio-${Date.now().toString(36)}`);
+    const submit = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/api/v1/primitives/audio/download",
+        auth: ctx.auth,
+        body: { tracer, payload: { source_url: url } }
+    });
+    assertApiOk(submit, "download-post-audio");
+    const jobId = submit.json?.job_id;
+    if (!jobId || parsed.values["no-wait"]) {
+        emitResult(submit, ctx.json);
+        return;
+    }
+    if (!ctx.json)
+        console.log(`${DIM}Downloading social post audio (${jobId})… polling every 5s.${RESET}`);
+    const final = await pollPrimitiveJob(ctx, jobId);
+    emitPrimitiveJobResult(ctx, final, "download-post-audio");
+}
+function emitPrimitiveJobResult(ctx, job, action) {
+    const mediaUrl = resolveJobMediaUrl(job);
+    if (ctx.json) {
+        printJson(job);
+        return;
+    }
+    const status = String(job?.status ?? "");
+    if (status === "failed" || status === "cancelled") {
+        throw new Error(`${action} ${status}: ${String(job?.error ?? "unknown error")}`);
+    }
+    if (status && status !== "succeeded") {
+        console.log(`${DIM}${action} status: ${status}.${RESET}`);
+    }
+    if (mediaUrl) {
+        console.log(`${GREEN}Done${RESET} ${mediaUrl}`);
+    }
+    else {
+        printJson(job);
+    }
+}
 // Browse the user's My Files library — the persistent per-user asset store
 // (videos, images, audio, docs) organized into virtual folders. `files` lists
 // them (optionally scoped to a folder); `get-file` resolves one attachment id to
@@ -5245,6 +5436,21 @@ const DIRECTORY_HELP = `vidfarm directory — browse the unified file tree (/fil
     e.g. vidfarm directory rename /files/characters/zara zara-fox
          vidfarm directory rename /files/characters/zara/notes.md character_about.md --file-id att_123
 
+  directory move <path> <to-folder>    Move a file/folder into another folder     → POST /api/v1/user/me/directory/move
+    --file-id <id>                 Move a FILE into <to-folder>; omit to move the folder at <path> (nests under <to-folder>)
+    --json                         Raw JSON response
+    Same root only (/files·/temp·/raws·/approved). Metadata-only — S3 objects untouched.
+    e.g. vidfarm directory move /raws/demos /raws/archive
+         vidfarm directory move /files/inbox/logo.png /files/brand --file-id att_123
+
+  directory copy <path> [<to-folder>]  Duplicate a file/folder (shared S3 object)  → POST /api/v1/user/me/directory/copy
+    --file-id <id>                 Copy a FILE; omit to copy the folder at <path>
+    --as <name>                    Rename the copied file/folder
+    --json                         Raw JSON response
+    Same root only (/files·/temp·/raws). Omit <to-folder> to duplicate in place. Not for /approved or /projects.
+    e.g. vidfarm directory copy /raws/demos /raws/archive
+         vidfarm directory copy /files/brand/logo.png /files/inbox --file-id att_123 --as logo-copy.png
+
   directory save-url <url>         Save a durable media URL INTO My Files at a folder → POST /api/v1/user/me/attachments/from-url
     --folder <path>                Destination folder under /files (e.g. inpaints, promos)
     --as <name>                    Name the saved file (else derived from the URL)
@@ -5253,8 +5459,7 @@ const DIRECTORY_HELP = `vidfarm directory — browse the unified file tree (/fil
     e.g. vidfarm directory save-url "https://…/inpaint-out.png" --folder inpaints --as hero.png
     (server fetches the URL — handles cross-origin S3; the CLI twin of the pop-panel "Save to Files")
 
-  Aliases: directory | dir   ·   Auth: --api-key <key> or VIDFARM_API_KEY, --host <url>
-  Move a raw between folders with: vidfarm api PATCH /raws/<clipId> --data '{"folder_path":"…"}'`;
+  Aliases: directory | dir  (move|mv · copy|cp)   ·   Auth: --api-key <key> or VIDFARM_API_KEY, --host <url>`;
 async function runDirectoryCommand(argv) {
     const sub = argv[0];
     const rest = argv.slice(1);
@@ -5266,8 +5471,13 @@ async function runDirectoryCommand(argv) {
         case "find":
             return runDirectorySearch(rest);
         case "rename":
-        case "mv":
             return runDirectoryRename(rest);
+        case "move":
+        case "mv":
+            return runDirectoryMove(rest);
+        case "copy":
+        case "cp":
+            return runDirectoryCopy(rest);
         case "save-url":
         case "from-url":
         case "import-url":
@@ -5385,6 +5595,66 @@ async function runDirectoryRename(argv) {
     const newPath = result.json?.path ?? "";
     console.log(`${GREEN}✓${RESET} Renamed to ${BOLD}${newName}${RESET} ${DIM}[${space}]${RESET}${newPath ? `  ${DIM}${newPath}${RESET}` : ""}`);
 }
+// Move a file or folder into another folder (same root) → POST /me/directory/move.
+async function runDirectoryMove(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), "file-id": { type: "string" }, to: { type: "string" } }
+    });
+    const ctx = commonContext(parsed.values);
+    const sourcePath = parsed.positionals[0];
+    const to = parsed.values.to ?? parsed.positionals[1];
+    if (!sourcePath || !to) {
+        throw new Error('directory move requires a source and a destination folder: vidfarm directory move <path> <to-folder> [--file-id <id>]\n  e.g. vidfarm directory move /raws/demos /raws/archive\n       vidfarm directory move /files/inbox/logo.png /files/brand --file-id att_123');
+    }
+    const fileId = parsed.values["file-id"];
+    const space = targetSpaces(ctx.target)[0];
+    const result = await dispatch(ctx, { method: "POST", path: "/api/v1/user/me/directory/move", body: { path: sourcePath, to, ...(fileId ? { file_id: fileId } : {}) } }, space);
+    assertApiOk(result, "directory move");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    const newPath = result.json?.path ?? to;
+    console.log(`${GREEN}✓${RESET} Moved to ${BOLD}${newPath}${RESET} ${DIM}[${space}]${RESET}`);
+}
+// Duplicate a file or folder into another folder (same root) → POST /me/directory/copy.
+async function runDirectoryCopy(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), "file-id": { type: "string" }, to: { type: "string" }, as: { type: "string" } }
+    });
+    const ctx = commonContext(parsed.values);
+    const sourcePath = parsed.positionals[0];
+    const to = parsed.values.to ?? parsed.positionals[1];
+    if (!sourcePath) {
+        throw new Error('directory copy requires a source: vidfarm directory copy <path> [<to-folder>] [--file-id <id>] [--as <new-name>]\n  e.g. vidfarm directory copy /raws/demos /raws/archive\n       vidfarm directory copy /files/brand/logo.png /files/inbox --file-id att_123 --as logo-copy.png');
+    }
+    const fileId = parsed.values["file-id"];
+    const newName = parsed.values.as;
+    const space = targetSpaces(ctx.target)[0];
+    const result = await dispatch(ctx, {
+        method: "POST",
+        path: "/api/v1/user/me/directory/copy",
+        body: {
+            path: sourcePath,
+            ...(to ? { to } : {}),
+            ...(fileId ? { file_id: fileId } : {}),
+            ...(newName ? { new_name: newName } : {})
+        }
+    }, space);
+    assertApiOk(result, "directory copy");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    const newPath = result.json?.path ?? to ?? "";
+    const copied = result.json?.copied;
+    const suffix = typeof copied === "number" ? ` ${DIM}(${copied} file${copied === 1 ? "" : "s"})${RESET}` : "";
+    console.log(`${GREEN}✓${RESET} Copied to ${BOLD}${newPath}${RESET}${suffix} ${DIM}[${space}]${RESET}`);
+}
 // Save a durable media URL (e.g. a finished job's output) INTO My Files at a
 // folder — the CLI twin of the pop-panel "Save to Files" picker. Server fetches
 // the URL (handles cross-origin S3), so no local download round-trip needed.

package/dist/src/devcli/clips.js

@@ -12,7 +12,7 @@ import { homedir } from "node:os";
 import { parseArgs } from "node:util";
 import { createInterface } from "node:readline/promises";
 import { createIdV7 } from "../lib/ids.js";
-import { buildEffectiveGuidance, ClipModelClient, DEFAULT_CLIP_ASPECT, DEFAULT_CLIP_DURATION_BAND, detectLocalAgent, detectScenes, effectiveHuntDurationSec, estimateScanCostFromScenes, fitScenesToDurationBand, formatCostEstimate, hasFfmpeg, LocalAgentClipClient, normalizeAspect, normalizeCropFocus, normalizeWindows, parseClipHuntPrompt, parseTimeRanges, probeVideo, resolveDurationBand, resolveTargetClipCount, scanVideo, searchClips } from "../services/clip-curation/index.js";
+import { buildEffectiveGuidance, buildPrivateUserNotesGuidance, ClipModelClient, DEFAULT_CLIP_ASPECT, DEFAULT_CLIP_DURATION_BAND, detectLocalAgent, detectScenes, effectiveHuntDurationSec, estimateScanCostFromScenes, fitScenesToDurationBand, formatCostEstimate, hasFfmpeg, LocalAgentClipClient, normalizeAspect, normalizeCropFocus, normalizeWindows, parseClipHuntPrompt, parseTimeRanges, probeVideo, resolveDurationBand, resolveTargetClipCount, scanVideo, searchClips } from "../services/clip-curation/index.js";
 import { ClipStore } from "./clip-store.js";
 export const CLIPS_HELP = `vidfarm raws — build & search a local raws library (local ffmpeg + local agent by default)
 
@@ -27,6 +27,10 @@ export const CLIPS_HELP = `vidfarm raws — build & search a local raws library
                                    keeps/drops/merges scenes, and tags are biased to it.
                                    Inline hints are honored too: "between 12:30 and 15:45",
                                    "30 sec clips", "vertical", "no captions".
+    --notes "<private notes>"      Store private owner notes as user_notes on derived raws
+                                   and feed them into decomposition/categorization. Explicit
+                                   private shot-kind hints like "content_type: demo" or
+                                   "category: talking_head" are honored and stay owner-only.
     --range "MM:SS-MM:SS"          Only hunt inside this source range (repeatable / comma-separated)
     --duration <sec>               Target raw length as a SOFT band (10→5-20s, 30→20-40s, …)
     --aspect <a>                   Crop raws to 9:16 | 16:9 | 4:3 | 1:1 (or vertical/horizontal/square)
@@ -156,10 +160,12 @@ async function runScan(argv) {
             "nvidia-key": { type: "string" },
             "embed-provider": { type: "string" },
             "embed-key": { type: "string" },
+            notes: { type: "string" },
             home: { type: "string" }
         }
     });
     // ── Hunt spec: explicit flags win; inline prompt hints fill the gaps ──────
+    const userNotes = values.notes?.trim() || undefined;
     const guidancePromptRaw = values.prompt?.trim() || undefined;
     const parsedPrompt = parseClipHuntPrompt(guidancePromptRaw);
     const rawWindows = values.range?.length
@@ -181,7 +187,10 @@ async function runScan(argv) {
     const cropFocus = normalizeCropFocus(values["crop-focus"]);
     const avoidText = values["allow-text"] ? false : (Boolean(values["no-text"]) || parsedPrompt.avoid_text || true);
     const maxClips = values["max-clips"] ? Math.max(1, Math.round(Number(values["max-clips"]))) : parsedPrompt.max_clips ?? undefined;
-    const guidance = buildEffectiveGuidance({ contentPrompt: guidancePromptRaw, avoidText }) || undefined;
+    const guidance = buildEffectiveGuidance({
+        contentPrompt: [guidancePromptRaw, buildPrivateUserNotesGuidance(userNotes)].filter(Boolean).join("\n"),
+        avoidText
+    }) || undefined;
     // ── BACKUP path: run the hunt on the deployed pipeline (--cloud) ──────────
     if (values.cloud) {
         const apiProvider = values.provider && !["agent", "local", "local-agent"].includes(values.provider)
@@ -195,6 +204,7 @@ async function runScan(argv) {
             tracer: values.tracer,
             folder: values.folder,
             prompt: guidancePromptRaw,
+            userNotes,
             provider: apiProvider,
             windows: rawWindows,
             durationBand,
@@ -339,6 +349,7 @@ async function runScan(argv) {
         framesPerScene,
         includeAudio,
         guidancePrompt: guidance,
+        userNotes,
         refineSegmentation: !values["no-refine"],
         reencodeClips: true,
         audioOnly: Boolean(values["audio-only"]),
@@ -461,6 +472,7 @@ async function runScanCloud(input) {
         body: JSON.stringify({
             ...(input.sourceUrl ? { source_url: input.sourceUrl } : { temp_file_id: tempFileId, filename: fileName }),
             prompt: input.prompt ?? "",
+            ...(input.userNotes ? { user_notes: input.userNotes } : {}),
             ...(input.provider ? { provider: input.provider } : {}),
             ...(input.tracer ? { tracer: input.tracer } : {}),
             ...(input.folder ? { folder_path: input.folder } : {}),

package/dist/src/services/clip-curation/gemini.js

@@ -312,8 +312,8 @@ function resolveEmbeddingConfig(provider, apiKey, explicit) {
         return { provider: "openai", apiKey };
     return null; // openrouter: no embeddings unless an explicit config is given
 }
-/** The document text embedded for a clip: description + transcript + salient tags. */
-export function buildClipEmbeddingText(tags, description) {
+/** The document text embedded for a clip: description + transcript + salient tags + private owner notes. */
+export function buildClipEmbeddingText(tags, description, userNotes) {
     const parts = [];
     if (description)
         parts.push(description);
@@ -332,6 +332,8 @@ export function buildClipEmbeddingText(tags, description) {
     ];
     if (tagBits.length)
         parts.push(tagBits.join(", "));
+    if (userNotes?.trim())
+        parts.push(`Owner notes: ${userNotes.trim()}`);
     return parts.join("\n").trim() || "video clip";
 }
 export function buildTaggingPrompt(transcript, version, hasAudio = false, guidancePrompt) {

package/dist/src/services/clip-curation/hunt.js

@@ -6,6 +6,7 @@
 // NEVER GhostCut on the long-form source). Shared by devcli (local), the Hono
 // API, and the cloud scan Lambda so every surface parses and normalizes
 // identically. All helpers are pure/deterministic — no AI calls here.
+import { ACTIVE_TAXONOMY_VERSION, getTaxonomy } from "./taxonomy.js";
 // ── Unspecified-prompt defaults ─────────────────────────────────────────────
 // When a user imports a source video without saying what they want, we bias
 // toward the short-form product default: a handful of DISTINCT, vertical,
@@ -293,6 +294,61 @@ export function buildEffectiveGuidance(input) {
         parts.push(AVOID_TEXT_GUIDANCE);
     return parts.join("\n");
 }
+function canonicalizeContentTypeHint(value) {
+    const normalized = String(value ?? "")
+        .trim()
+        .toLowerCase()
+        .replace(/^#/, "")
+        .replace(/[\s-]+/g, "_");
+    if (!normalized)
+        return null;
+    if (normalized === "broll")
+        return "b_roll";
+    return normalized;
+}
+export function extractUserContentTypeHints(notes, version = ACTIVE_TAXONOMY_VERSION) {
+    const text = String(notes ?? "").trim();
+    if (!text)
+        return [];
+    const allowed = new Set(getTaxonomy(version).categories.content_type.map((value) => canonicalizeContentTypeHint(value)));
+    const found = new Set();
+    const capture = (value) => {
+        const normalized = canonicalizeContentTypeHint(value);
+        if (normalized && allowed.has(normalized))
+            found.add(normalized);
+    };
+    for (const match of text.matchAll(/\b(?:content[_\s-]*type|category|tag)s?\s*[:=]\s*([^\n.;]+)/gi)) {
+        const raw = String(match[1] ?? "");
+        for (const piece of raw.split(/[,/|]+|\band\b/gi))
+            capture(piece);
+    }
+    for (const match of text.matchAll(/\b#?(talking[\s_-]*head|b[\s_-]*roll|product[\s_-]*shot|screen[\s_-]*recording|demo|reaction|interview|establishing|lifestyle|text[\s_-]*graphic)\b/gi)) {
+        capture(String(match[1] ?? ""));
+    }
+    return [...found];
+}
+export function applyUserContentTypeHints(tags, notes, version = ACTIVE_TAXONOMY_VERSION) {
+    const hinted = extractUserContentTypeHints(notes, version);
+    if (!hinted.length)
+        return tags;
+    return {
+        ...tags,
+        content_type: [...new Set([...(tags.content_type ?? []), ...hinted])]
+    };
+}
+export function buildPrivateUserNotesGuidance(notes, version = ACTIVE_TAXONOMY_VERSION) {
+    const text = String(notes ?? "").trim();
+    if (!text)
+        return "";
+    const hinted = extractUserContentTypeHints(text, version);
+    const parts = [
+        `Private owner notes for this raw: "${text}". Use them to bias categorization and description, but stay truthful to the footage.`
+    ];
+    if (hinted.length) {
+        parts.push(`If the footage supports it, include these owner-requested private content_type tags: ${hinted.join(", ")}.`);
+    }
+    return parts.join("\n");
+}
 /**
  * Deterministically extract structured hints from a free-form hunt prompt:
  * "please only hunt for clips between 12:30 and 15:45", "short 10 sec clips",

package/dist/src/services/clip-curation/index.js

@@ -6,7 +6,7 @@ export { ACTIVE_TAXONOMY_VERSION, MULTI_VALUE_CATEGORIES, getTaxonomy, sanitizeT
 export { BUILTIN_PRESETS, findBuiltinPreset } from "./presets.js";
 export { ClipModelClient, ClipGeminiClient, ClipEmbeddingClient, EMBEDDING_DIM, EMBEDDING_MODEL, EMBEDDING_MODELS, TAG_MODEL_BY_TIER, buildClipEmbeddingText, buildQueryPrompt, buildTaggingPrompt, normalize } from "./gemini.js";
 export { LocalAgentClipClient, detectLocalAgent, extractJsonObject } from "./local-agent.js";
-export { AVOID_TEXT_GUIDANCE, DEFAULT_CLIP_ASPECT, DEFAULT_CLIP_DURATION_BAND, DEFAULT_CLIPS_PER_10_MIN, applyHuntSpecDefaults, buildEffectiveGuidance, capScenesEvenlyToCount, cropFilterFor, effectiveHuntDurationSec, fitScenesToDurationBand, normalizeAspect, normalizeCropFocus, normalizeHuntSpec, normalizeWindows, parseClipHuntPrompt, parseTimecode, parseTimeRanges, resolveDurationBand, resolveTargetClipCount } from "./hunt.js";
+export { AVOID_TEXT_GUIDANCE, DEFAULT_CLIP_ASPECT, DEFAULT_CLIP_DURATION_BAND, DEFAULT_CLIPS_PER_10_MIN, applyHuntSpecDefaults, applyUserContentTypeHints, buildEffectiveGuidance, buildPrivateUserNotesGuidance, capScenesEvenlyToCount, cropFilterFor, effectiveHuntDurationSec, extractUserContentTypeHints, fitScenesToDurationBand, normalizeAspect, normalizeCropFocus, normalizeHuntSpec, normalizeWindows, parseClipHuntPrompt, parseTimecode, parseTimeRanges, resolveDurationBand, resolveTargetClipCount } from "./hunt.js";
 export { detectScenes, extractAudioClip, extractClip, extractKeyframes, extractSceneAudio, extractThumbnail, extractWaveformThumbnail, hasFfmpeg, probeVideo, resolveFfmpeg, resolveFfprobe } from "./ffmpeg.js";
 export { cosineSimilarity, matchesCriteria, rankHits, scoreClip, searchClips, structuredMatchRatio } from "./query.js";
 export { estimateScanCostFromDuration, estimateScanCostFromScenes, formatCostEstimate } from "./cost.js";

package/dist/src/services/clip-curation/scan.js

@@ -9,7 +9,7 @@ import { createIdV7 } from "../../lib/ids.js";
 import { ACTIVE_TAXONOMY_VERSION } from "./taxonomy.js";
 import { buildClipEmbeddingText } from "./gemini.js";
 import { detectScenes, extractAudioClip, extractClip, extractKeyframes, extractSceneAudio, extractThumbnail, extractWaveformThumbnail, probeVideo } from "./ffmpeg.js";
-import { capScenesEvenlyToCount, cropFilterFor, fitScenesToDurationBand, normalizeWindows } from "./hunt.js";
+import { applyUserContentTypeHints, capScenesEvenlyToCount, cropFilterFor, fitScenesToDurationBand, normalizeWindows } from "./hunt.js";
 import { refineScenesWithGuidance } from "./refine.js";
 /** Turn one scene into a Clip. Throws only on unrecoverable extraction failure. */
 export async function processSceneToClip(input) {
@@ -46,6 +46,7 @@ export async function processSceneToClip(input) {
         scene,
         guidancePrompt: ctx.guidancePrompt
     });
+    const tags = applyUserContentTypeHints(tagResult.tags, ctx.userNotes, ctx.client.taxonomyVersion ?? ACTIVE_TAXONOMY_VERSION);
     // 4. Cut the clip + thumbnail. Audio-only hunts emit an .m4a (no video) with a
     //    waveform PNG thumbnail; ordinary hunts emit an .mp4 cropped to the target
     //    aspect when requested.
@@ -77,7 +78,7 @@ export async function processSceneToClip(input) {
     // 5. Embed the document text for semantic search (skipped when the client can't embed).
     let embedding;
     if (ctx.client.canEmbed) {
-        const embedText = buildClipEmbeddingText(tagResult.tags, tagResult.description);
+        const embedText = buildClipEmbeddingText(tags, tagResult.description, ctx.userNotes);
         [embedding] = await ctx.client.embedDocuments([embedText]);
     }
     const clip = {
@@ -89,7 +90,7 @@ export async function processSceneToClip(input) {
         duration_sec: scene.duration_sec,
         file_path: ctx.clipStoredPath ? ctx.clipStoredPath(clipId, clipLocal) : clipLocal,
         thumbnail_path: ctx.thumbStoredPath ? ctx.thumbStoredPath(clipId, thumbLocal) : thumbLocal,
-        tags: tagResult.tags,
+        tags,
         description: tagResult.description,
         embedding,
         taxonomy_version: ctx.client.taxonomyVersion ?? ACTIVE_TAXONOMY_VERSION,
@@ -98,6 +99,7 @@ export async function processSceneToClip(input) {
         embedding_model: ctx.client.embeddingModelId ?? undefined,
         aspect: !audioOnly && cropFilter && ctx.crop ? ctx.crop.aspect : undefined,
         media_kind: audioOnly ? "audio" : undefined,
+        user_notes: ctx.userNotes?.trim() || undefined,
         owner_id: input.ownerId,
         created_at: new Date().toISOString()
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.20.8",
+  "version": "0.20.10",
   "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": {