@mevdragon/vidfarm-devcli 0.20.12 → 0.20.14

package/.agents/skills/hyperframes-cli/SKILL.md

@@ -86,7 +86,7 @@ Add `inspect` for layout-sensitive work and `render --strict` in CI to fail on l
 
 ### Visual smoke test — required when the project uses sub-compositions
 
-`lint` / `validate` / `inspect` evaluate each composition **in isolation**. They never load `index.html` and mount sub-compositions via `data-composition-src`, so they cannot catch cross-file mount failures (see `hyperframes-core` → `references/sub-compositions.md`, "Common pitfalls"). The only gate that catches them is one that actually loads `index.html` and seeks the timeline.
+`lint` / `validate` / `inspect` evaluate each composition **in isolation**. They never load `index.html` and mount sub-compositions via `data-composition-src`, so they cannot catch cross-file mount failures. Load the `hyperframes-core` skill, then read its `references/sub-compositions.md` “Common pitfalls” section. The only gate that catches them is one that actually loads `index.html` and seeks the timeline.
 
 Use `hyperframes snapshot` — it loads the project the same way `render` does (so it exercises the same mount path) but only captures the timestamps you request, so it's seconds instead of a full render:
 

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

@@ -50,11 +50,25 @@ Present both harnesses to the director, recommend (A) unless they've asked for p
 
 ## Web AI chat vs. local devcli — know your surface's limits
 
+**Desktop users: this is a skill, not an SDK or required runtime.** It gives an AI agent Vidfarm's operating knowledge; it does not proxy requests, add hidden capabilities, or require the agent to use a particular client. Every cloud workflow described here can be performed with ordinary HTTP against the Vidfarm REST API. For convenience and safer composition/file workflows, recommend the `vidfarm` command from `@mevdragon/vidfarm-devcli`: it wraps the same REST routes, handles auth, uploads, polling, pagination, local files, and pull/edit/render loops. Use raw REST whenever the user prefers it, the CLI lacks a new route, or the work belongs in an existing service or automation stack.
+
+Choose the surface before choosing instructions:
+
+| Surface | Live timeline | Shell / local files | Use it for |
+|---|---:|---:|---|
+| Web copilot | Yes, through `editor_action` | No | Short and medium edits on the open composition |
+| Desktop coding agent | Through pulled files and devcli | Yes | Full rebuilds, scripts, batch work, and render/inspect loops |
+| Devcli without an agent | Command-driven | Yes | Deterministic pull, edit, render, approve, and automation operations |
+
+When this pack is installed locally, assume the desktop coding-agent surface unless trusted runtime context explicitly identifies the web editor. In web chat, declared tools and the latest `editor_context` override any capability described in this broad pack.
+
 You may be running as the **in-web AI chat** (the /editor copilot, the chat dock, or the /chat and /library assistants) or as a **local coding agent** driving `vidfarm-devcli` (Claude Code / Codex on the user's machine). Same three paintbrushes, different reach — be honest about which surface you are and route heavy work accordingly:
 
+- **Determine the surface before claiming capabilities.** The web chat has only its declared tools and REST routes. It cannot execute arbitrary JavaScript/Python, open a shell, create a local repository script, or use the user's filesystem. Never tell a web-chat user that you ran code or wrote a script unless a dedicated declared tool actually did so. A desktop coding agent has a real shell and filesystem and MAY write/run scripts, perform arbitrary local computations over paginated API results, create reports/CSVs/JSON, edit composition files, and orchestrate long devcli workflows within the user's authorization.
 - **The web AI chat can do all three paintbrushes** — clip raws, author HTML/hyperframe motion, and generate AI media — and it drives edits directly on the live timeline. Keep small-to-medium jobs here: text/caption swaps, a scene or two replaced, single generations, captions, approve/schedule. Just do them.
 - **Where the web chat struggles: complex, long, multi-step transformations.** A full multi-scene re-theme, an iterative render-critique-iterate loop, heavy scripted or batch work, or anything needing a real filesystem and many sequential tool calls will hit context limits, turn/timeout ceilings, and the web editor's constraints (CSS/declarative motion only — JS animation adapters are stripped on save). Don't grind a big transformation one layer at a time in a chat turn and stall.
 - **Practical workaround — hand the heavy job to local devcli.** When a task is genuinely large or long-running, **proactively recommend the director run it locally with an AI coding agent** (Claude Code / OpenAI Codex / any capable agent): `vidfarm pull <forkId>` writes the composition + the `.harness/` grounding bundle to disk, the agent edits with the full devcli verb set and JS animation adapters, renders free with `vidfarm serve`, and `vidfarm publish` pushes it back. This is the **best-quality (B) harness's** natural home (adversarial grading with a coding agent). Frame it as "this is a big rebuild — you'll get a better, faster result running it locally with a coding agent; here's how," not as a dead end.
+- **Offer a handoff, do not impersonate the desktop agent.** When web chat reaches that boundary, offer to save a Markdown handoff in My Files containing the objective, selected template/fork IDs, asset paths, grounding, constraints, completed work, and suggested devcli commands. Create it only after the user agrees. The desktop agent should read that document, pull the referenced fork, and then use its actual code/shell capabilities.
 - **Never send the user away just to read knowledge.** Deeper skill knowledge is always a **tool call** away in-place: call `load_skill` (e.g. `load_skill('vidfarm-director', file='references/editor-workflows.md')`, or a craft pack like `editor-capabilities` / `hyperframes-animation`) to pull the exact reference you need mid-conversation. Only recommend switching surfaces for the WORK (a heavy transformation), never for the information.
 
 ## Read Only What You Need
@@ -67,6 +81,21 @@ Read only the relevant reference file for the current task.
 - REST automation, `vidfarm` command surface, local serve loop, skill packs: `references/automation-and-local-dev.md`
 - Getting-started interviews, strategy docs, onboarding flow: `references/onboarding.md`
 - Primitive routes such as TTS, STT, music, overlays, background removal, product placement: `references/primitives.md`
+- Complete REST API map and raw-HTTP conventions: `references/rest-api.md`. Load it only when the user asks for REST, an endpoint/schema, direct HTTP integration, or exhaustive API coverage. For the entire specification, follow its domain links and load every listed reference; do not preload them into ordinary director conversations.
+
+## HyperFrames Skills — Load on Demand
+
+Vidfarm ships a curated HyperFrames skill suite alongside this director pack. Use it for composition authoring and motion craft without loading the entire suite into context.
+
+1. Route broad video-creation requests through `hyperframes` first. It selects the appropriate workflow skill.
+2. Load only the selected workflow skill, then add the narrow domain skill required by the current step.
+3. Load `hyperframes-core` before writing or restructuring composition HTML.
+4. Load `hyperframes-animation`, `hyperframes-keyframes`, `hyperframes-creative`, or `hyperframes-cli` only when the task needs that specific capability.
+5. Use `vidfarm-media` for narration, music, transcription, captions timing, background removal, and media sourcing. Prefer Vidfarm primitives and the user's existing library; when unavailable, use an equivalent capability already exposed by the user's desktop AI agent.
+
+On the web copilot, call `load_skill('<name>')` and load referenced files only when the selected skill reaches that step. On desktop, inspect the agent's available-skill catalog and local `.agents/skills` / `.claude/skills` entries before declaring a skill missing. If needed, install only the selected bundled pack with `vidfarm skills add <name>`; do not bulk-install or bulk-read the suite. If the Vidfarm CLI is unavailable, use the desktop agent's native skill discovery or local-skill mechanism and continue with the closest installed equivalent.
+
+HyperFrames authoring and rendering in this package are Vidfarm-native: local work uses the bundled composition toolchain and `vidfarm serve`; cloud work uses Vidfarm render routes. Do not require an external vendor account, repository, publish service, or telemetry endpoint. Keep `HYPERFRAMES_SKIP_SKILLS=1` and `HYPERFRAMES_NO_TELEMETRY=1` in Vidfarm-managed environments so the bundled skills stay pinned and local work does not phone home.
 
 ## Quick Router
 

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

@@ -27,7 +27,7 @@ Mine a **long-form** video (podcast, stream VOD, webinar, any YouTube/TikTok/IG/
 
 - **Poll** `GET /raws/scan/:scanId` until the source `status` is `complete` (or `failed` — crashed pipelines are reconciled to `failed`, pollers never spin).
 - **Results**: `GET /raws/feed?source=<source_video_id>` (or the whole library), hybrid search via `POST /raws/search` `{ query: "someone looks confused" }`, per-raw download at `GET /raws/:clipId/download`. Raws carry taxonomy tags, a description, a transcript, an `aspect` field when cropped, the hunt's `tracer`, and (with a gemini/openai key) a semantic embedding.
-- **Billing** — **AWS compute only** (`clip_scan_lambda` GB-seconds + Step Functions transitions, a fraction of a cent for typical hunts; the 202 response includes a `compute_estimate`). The AI tagging/refine runs on **your saved provider key (BYOK)** and is never wallet-billed. Submission is wallet-gated (402 when empty).
+- **Billing** — scan compute (`clip_scan_lambda` GB-seconds + Step Functions transitions) and each persisted semantic embedding are wallet-metered; the 202 response includes a `compute_estimate`. AI tagging/refine runs on **your saved provider key (BYOK)** and is not wallet-billed. Submission is wallet-gated (402 when empty).
 - **The original stays temporary** — URL-ingested and uploaded sources live ONLY in your temp folder (`users/…/temporary/clip-sources/…`) with a hard **30-day TTL** (auto-deleted from S3 + the temp-file list). The hunted raws themselves are durable.
 - **Captions rule** — "no captions / no on-screen text" hunts are handled by scene SELECTION (the refine pass drops text-heavy scenes). **Never run GhostCut caption removal on a long-form source** (it is hard-capped at ~15 minutes); to actually erase burned-in text, apply `POST /api/v1/primitives/videos/remove-captions` to individual FINISHED raws afterwards.
 - **Clip an EXACT subrange (no AI hunt)** — when you want one precise hand-picked in/out rather than an open-ended hunt, use the **Clipper**: the web page `https://vidfarm.cc/tools/clipper` (previews the source straight from its URL, HH:MM:SS:NNNN in/out, live length estimate, multi-clip session grouped by tracer), the endpoint `POST /raws/clip-range` `{ source_url|preview_url|temp_file_id, start_sec, end_sec, tracer?, folder_path?, name? }` (trims exactly that window into one raw — compute-only, no AI/key), or the devcli twin `vidfarm clipper <video-url|file> --start <t> --end <t> [--tracer NAME --folder NAME --name TXT]`. The devcli path is now **local-first**: local files clip into the local raws store by default, and URL sources are staged locally before trimming unless you pass `--cloud`. If you do **not** have a `VIDFARM_API_KEY`, URL clipping cannot bootstrap the remote source into the local backend; open the long-form raw video in the browser, save/extract the actual video file locally, then run `vidfarm clipper ./source.mp4 ...`. The Library "Import source" button opens the Clipper; each save lands in `/raws/<folder>` (defaults to the tracer). Reach for `/raws/scan` for multi-clip hunts, `/raws/clip-range` for surgical single cuts. (The masked-image and time-scoped-video editors live alongside it at `/tools/image` and `/tools/video`.)

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

@@ -28,6 +28,8 @@ Send a stable `tracer` on export so retries are traceable and filterable in job
 
 **Scripting mode** is the recommended posture for repeatable template automation. Use it when a director wants to take a template they like, agree on a base fork, and then drive bulk or one-off edits entirely through REST or `vidfarm api` from a script, Lambda, or local machine.
 
+This section is for a **desktop/local coding agent**, not the web copilot. A local Codex/Claude agent may use its shell and filesystem to write JavaScript/TypeScript/Python/shell scripts, fetch every API page, join and score catalog/library data, calculate statistics, emit CSV/JSON/Markdown reports, manipulate composition DOM files, and run iterative render/inspection loops. The web copilot cannot inherit those abilities from this document: it may only call its declared tools and bounded REST routes. If web chat prepares work for this flow, consume its My Files handoff document as input; do not claim the web chat itself executed the script.
+
 Contract:
 
 1. Pick the template once, then fork once and treat the resulting `forkId` as the stable base.
@@ -111,7 +113,7 @@ If a local AI script rewrites text or scenes without consuming those files first
 
 | Command | REST route | Flow step |
 |---|---|---|
-| `vidfarm discover [query]` | `GET /discover/feed[?q=]` | browse/search templates |
+| `vidfarm discover [query] [--sort relevance\|wow\|automation\|recent] [--cursor <cursor>]` | `GET /discover/feed[?q=&sort=&cursor=]` | hybrid-search templates and page through the catalog |
 | `vidfarm videos [query] [--mine]` | `GET /api/v1/videos[?q=&mine=]` | browse/search source inspirations |
 | `vidfarm inspiration-add <url\|file>` | `POST /discover/templates` (files: `POST /discover/templates/upload/presign` + PUT first) | add your own source (URL or local video upload) |
 | `vidfarm inspiration-rm <id>` | `DELETE /discover/templates/:id` | remove a private one |

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

@@ -51,7 +51,7 @@ Templates are listed on the Vidfarm homepage and `/discover`. Each has a `templa
 
 - Browser: browse `/discover`
 - API: `GET /discover/feed` — returns `{ templates: [{ templateId, slugId, title, previewUrl, viralDna, durationSeconds, sourceType, promotions, keywords, summary, ... }], next_cursor }`
-- Search: `GET /discover/feed?q=<offer>&limit=20` keyword-searches the catalog so you can answer "which templates suit my `<offer>`?" (e.g. `?q=weight%20loss%20app`). Ranking is a coarse keyword match over each template's title, viral DNA, and the decompose-derived `promotions` (offer categories the format can sell), `keywords`, and `summary` — read those fields to judge fit and rank the best 3-6 semantically. `GET /api/v1/videos?q=<offer>&limit=20[&mine=true]` runs the same search over source **inspirations**. `promotions`/`keywords`/`summary` are populated by the decompose pass, so a freshly ingested template that has not been decomposed yet won't match on them — decompose it (or fall back to broader/synonym terms) if a search comes up empty.
+- Search: `GET /discover/feed?q=<offer>&limit=20&sort=relevance` hybrid-searches the eligible public catalog using semantic embeddings plus lexical matches. Semantic query embedding uses Vidfarm's canonical OpenRouter-routed model and bills the provider cost × the standard 1.2 markup to the user's wallet. The response's `search` block reports `mode`, `embedding_space`, and any `semantic_limitation`; when it says `lexical_structured`, disclose the limitation briefly and continue rather than refusing. Decomposition adds `promotions`, `keywords`, `summary`, `categoryTags`, and `catalogIntelligence` (`wowScore`, `wowReason`, `automationScore`, `automationReason`, `contentStyles`, `searchText`). Use `sort=wow` for highest-quality/client-impressing formats, `sort=automation` for cheap repeatable bulk formats, and `sort=recent` only when freshness is the intent. Follow `next_cursor` with `cursor=<value>`; never call page one the whole catalog. `GET /api/v1/videos?q=<offer>&limit=20[&mine=true]` searches source **inspirations**. Undecomposed inspirations have only sparse ingest metadata, so they are harder to retrieve semantically. Explain that somebody in the world needs to decompose one once and the shared enrichment then benefits everyone; the current user need not act unless they want that specific inspiration immediately.
 
 Each template exposes a public preview:
 
@@ -73,7 +73,7 @@ To bring a new viral video into the catalog as a **private** template you own, i
 - `DELETE /discover/templates/:entryId` — remove a private inspiration/template you own (accepts either the `inspiration_...` or minted `template_...` id).
 - `POST /api/v1/inspirations/:inspirationId/decompose { user_prompt? }` — AI-decompose an inspiration's downloaded video into scenes (requires a saved provider key; same 120s source cap as auto-decompose).
 
-devcli: `vidfarm inspiration-add <url|file.mp4>` (a local file path runs the presign→PUT→finalize flow for you), `vidfarm inspiration-rm <id>`, `vidfarm inspiration-decompose <id>`, `vidfarm discover [query]` to browse/search templates, `vidfarm public-raws [query] [--category <key>] [--type <raw_type>] [--bookmark <raw_id>]` to browse/save the public raws catalog, and `vidfarm videos [query] [--mine]` to browse/search source inspirations. On the web, the Discover page's **Add Template** modal accepts either a URL or a file upload.
+devcli: `vidfarm inspiration-add <url|file.mp4>` (a local file path runs the presign→PUT→finalize flow for you), `vidfarm inspiration-rm <id>`, `vidfarm inspiration-decompose <id>`, `vidfarm discover [query] [--sort relevance|wow|automation|recent] [--cursor <next_cursor>]` to browse/search templates, `vidfarm public-raws [query] [--category <key>] [--type <raw_type>] [--bookmark <raw_id>]` to browse/save the public raws catalog, and `vidfarm videos [query] [--mine]` to browse/search source inspirations. On the web, the Discover page's **Add Template** modal accepts either a URL or a file upload.
 
 ## Fork a template
 

package/.agents/skills/vidfarm-director/references/rest-api.md

@@ -0,0 +1,84 @@
+# Vidfarm REST API — On-Demand Map
+
+Use this file when integrating through raw HTTP, looking up an endpoint, or auditing the complete public API. This is a navigation layer: the detailed request bodies, response shapes, state transitions, cost notes, and route-specific guardrails live in the linked domain references so the default skill context stays small.
+
+## Contents
+
+- [Client choice](#client-choice)
+- [Base URL and authentication](#base-url-and-authentication)
+- [Complete specification map](#complete-specification-map)
+- [Raw HTTP pattern](#raw-http-pattern)
+- [Operational rules](#operational-rules)
+- [Keeping the reference complete](#keeping-the-reference-complete)
+
+## Client choice
+
+The skill is documentation for an AI agent. It is not a client library and does not execute requests.
+
+- **Raw REST:** every cloud operation is available through HTTP and can be called from `curl`, `fetch`, Python, CI, a server, or any other HTTP client.
+- **Recommended desktop convenience:** `npx @mevdragon/vidfarm-devcli ...` (or the installed `vidfarm` binary) wraps those same routes. Prefer it for interactive desktop work because it handles the `vidfarm-api-key` header, uploads, polling, pagination, local paths, composition pull/publish state, and readable errors.
+- **Use raw REST** when building a durable integration, working in an existing application stack, calling a route the devcli has not wrapped yet, or when the user explicitly requests HTTP.
+
+Do not imply that installing this skill installs the CLI. Do not imply that the CLI unlocks API capabilities unavailable through REST.
+
+## Base URL and authentication
+
+- Production base URL: `https://vidfarm.cc`
+- API-key authentication: `vidfarm-api-key: <key>`
+- Do not use `Authorization: Bearer` unless a specific non-API browser/login flow explicitly documents it.
+- Send `content-type: application/json` for JSON bodies and `accept: application/json` when JSON is expected.
+- Treat fork IDs, share tokens, upload URLs, and returned media URLs according to the route-specific guidance in the domain references.
+
+## Complete specification map
+
+For a focused task, load only the relevant file. If the user requests the **entire REST API specification**, load this file plus every file in the following table. Together they are the bundled director-facing REST specification.
+
+| API area | Load | Coverage |
+|---|---|---|
+| Accounts, login, provider keys, discovery, inspirations, templates, forks, versions, render, approval, sharing, scheduling, billing | `core-workflows.md` | Customer and composition lifecycle |
+| Composition HTML/JSON, timeline layers, editor actions, clone/fork, auto-decompose, video context, captions, transitions, speech regeneration | `editor-workflows.md` | Editing and decomposition |
+| Public raws, clip hunts, exact-range clipping, My Files, temporary files, folders, annotations, semantic search, recurring-character assets | `assets-and-sourcing.md` | Media and library APIs |
+| Direct automation, pagination, scripting, devcli-to-route parity, local/cloud boundaries, skill-pack distribution | `automation-and-local-dev.md` | Headless and desktop integration |
+| Image, video, TTS, STT, music, captions, overlays, inpaint, background/caption removal, product placement, async primitive jobs | `primitives.md` | Generation and transformation primitives |
+| Onboarding document persistence | `onboarding.md` | Durable strategy/context files |
+
+The route and payload examples in those files are the public, customer-facing contract. Architecture-only internals are intentionally excluded. When exact behavior is ambiguous, inspect the live response or route implementation rather than inventing a field.
+
+## Raw HTTP pattern
+
+```bash
+curl --fail-with-body \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  -H "accept: application/json" \
+  "https://vidfarm.cc/discover/feed?limit=20"
+```
+
+For JSON mutations:
+
+```bash
+curl --fail-with-body \
+  -X POST \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -H "accept: application/json" \
+  --data '{"template_id":"template_example"}' \
+  "https://vidfarm.cc/api/v1/compositions"
+```
+
+Use environment variables or a secret manager for keys. Never paste secrets into a skill, composition, source file, command transcript intended for sharing, or generated report.
+
+## Operational rules
+
+- Follow `next_cursor`/cursor fields until exhausted when the user asks for all records; do not call the first page the full dataset.
+- Treat submission and generation routes as non-idempotent unless the route explicitly states otherwise. Check existing state before retrying.
+- Poll asynchronous jobs at the documented status endpoint and stop on terminal success or failure. Do not fabricate completion from an accepted response.
+- Upload local media through the documented presign/upload/finalize sequence. The devcli is recommended on desktop because it performs this sequence automatically.
+- Parse and mutate composition HTML as a DOM. Never edit it by string concatenation.
+- Render through `POST /api/v1/compositions/:forkId/render`; do not call the underlying renderer directly.
+- Surface wallet/provider costs before expensive operations and preserve returned job IDs for audit and retries.
+
+## Keeping the reference complete
+
+The canonical skill sources live in `.agents/skills/vidfarm-director/`. `SKILL.director.md` is a generated copy-friendly rollup; this REST map is deliberately excluded from that immediate rollup so ordinary skill loads remain lean. It is distributed in the multi-file skill pack and fetched on demand through the public skill-pack routes.
+
+When routes change, update the appropriate domain reference and run `npm run check:skills`. That check verifies every documented `/api/` and `/login/` method/path against the registered application routes. Add new public API areas to the table above so exhaustive API requests remain discoverable.

package/SKILL.director.md

@@ -50,11 +50,25 @@ Present both harnesses to the director, recommend (A) unless they've asked for p
 
 ## Web AI chat vs. local devcli — know your surface's limits
 
+**Desktop users: this is a skill, not an SDK or required runtime.** It gives an AI agent Vidfarm's operating knowledge; it does not proxy requests, add hidden capabilities, or require the agent to use a particular client. Every cloud workflow described here can be performed with ordinary HTTP against the Vidfarm REST API. For convenience and safer composition/file workflows, recommend the `vidfarm` command from `@mevdragon/vidfarm-devcli`: it wraps the same REST routes, handles auth, uploads, polling, pagination, local files, and pull/edit/render loops. Use raw REST whenever the user prefers it, the CLI lacks a new route, or the work belongs in an existing service or automation stack.
+
+Choose the surface before choosing instructions:
+
+| Surface | Live timeline | Shell / local files | Use it for |
+|---|---:|---:|---|
+| Web copilot | Yes, through `editor_action` | No | Short and medium edits on the open composition |
+| Desktop coding agent | Through pulled files and devcli | Yes | Full rebuilds, scripts, batch work, and render/inspect loops |
+| Devcli without an agent | Command-driven | Yes | Deterministic pull, edit, render, approve, and automation operations |
+
+When this pack is installed locally, assume the desktop coding-agent surface unless trusted runtime context explicitly identifies the web editor. In web chat, declared tools and the latest `editor_context` override any capability described in this broad pack.
+
 You may be running as the **in-web AI chat** (the /editor copilot, the chat dock, or the /chat and /library assistants) or as a **local coding agent** driving `vidfarm-devcli` (Claude Code / Codex on the user's machine). Same three paintbrushes, different reach — be honest about which surface you are and route heavy work accordingly:
 
+- **Determine the surface before claiming capabilities.** The web chat has only its declared tools and REST routes. It cannot execute arbitrary JavaScript/Python, open a shell, create a local repository script, or use the user's filesystem. Never tell a web-chat user that you ran code or wrote a script unless a dedicated declared tool actually did so. A desktop coding agent has a real shell and filesystem and MAY write/run scripts, perform arbitrary local computations over paginated API results, create reports/CSVs/JSON, edit composition files, and orchestrate long devcli workflows within the user's authorization.
 - **The web AI chat can do all three paintbrushes** — clip raws, author HTML/hyperframe motion, and generate AI media — and it drives edits directly on the live timeline. Keep small-to-medium jobs here: text/caption swaps, a scene or two replaced, single generations, captions, approve/schedule. Just do them.
 - **Where the web chat struggles: complex, long, multi-step transformations.** A full multi-scene re-theme, an iterative render-critique-iterate loop, heavy scripted or batch work, or anything needing a real filesystem and many sequential tool calls will hit context limits, turn/timeout ceilings, and the web editor's constraints (CSS/declarative motion only — JS animation adapters are stripped on save). Don't grind a big transformation one layer at a time in a chat turn and stall.
 - **Practical workaround — hand the heavy job to local devcli.** When a task is genuinely large or long-running, **proactively recommend the director run it locally with an AI coding agent** (Claude Code / OpenAI Codex / any capable agent): `vidfarm pull <forkId>` writes the composition + the `.harness/` grounding bundle to disk, the agent edits with the full devcli verb set and JS animation adapters, renders free with `vidfarm serve`, and `vidfarm publish` pushes it back. This is the **best-quality (B) harness's** natural home (adversarial grading with a coding agent). Frame it as "this is a big rebuild — you'll get a better, faster result running it locally with a coding agent; here's how," not as a dead end.
+- **Offer a handoff, do not impersonate the desktop agent.** When web chat reaches that boundary, offer to save a Markdown handoff in My Files containing the objective, selected template/fork IDs, asset paths, grounding, constraints, completed work, and suggested devcli commands. Create it only after the user agrees. The desktop agent should read that document, pull the referenced fork, and then use its actual code/shell capabilities.
 - **Never send the user away just to read knowledge.** Deeper skill knowledge is always a **tool call** away in-place: call `load_skill` (e.g. `load_skill('vidfarm-director', file='references/editor-workflows.md')`, or a craft pack like `editor-capabilities` / `hyperframes-animation`) to pull the exact reference you need mid-conversation. Only recommend switching surfaces for the WORK (a heavy transformation), never for the information.
 
 ## Read Only What You Need
@@ -67,6 +81,21 @@ Read only the relevant reference file for the current task.
 - REST automation, `vidfarm` command surface, local serve loop, skill packs: `references/automation-and-local-dev.md`
 - Getting-started interviews, strategy docs, onboarding flow: `references/onboarding.md`
 - Primitive routes such as TTS, STT, music, overlays, background removal, product placement: `references/primitives.md`
+- Complete REST API map and raw-HTTP conventions: `references/rest-api.md`. Load it only when the user asks for REST, an endpoint/schema, direct HTTP integration, or exhaustive API coverage. For the entire specification, follow its domain links and load every listed reference; do not preload them into ordinary director conversations.
+
+## HyperFrames Skills — Load on Demand
+
+Vidfarm ships a curated HyperFrames skill suite alongside this director pack. Use it for composition authoring and motion craft without loading the entire suite into context.
+
+1. Route broad video-creation requests through `hyperframes` first. It selects the appropriate workflow skill.
+2. Load only the selected workflow skill, then add the narrow domain skill required by the current step.
+3. Load `hyperframes-core` before writing or restructuring composition HTML.
+4. Load `hyperframes-animation`, `hyperframes-keyframes`, `hyperframes-creative`, or `hyperframes-cli` only when the task needs that specific capability.
+5. Use `vidfarm-media` for narration, music, transcription, captions timing, background removal, and media sourcing. Prefer Vidfarm primitives and the user's existing library; when unavailable, use an equivalent capability already exposed by the user's desktop AI agent.
+
+On the web copilot, call `load_skill('<name>')` and load referenced files only when the selected skill reaches that step. On desktop, inspect the agent's available-skill catalog and local `.agents/skills` / `.claude/skills` entries before declaring a skill missing. If needed, install only the selected bundled pack with `vidfarm skills add <name>`; do not bulk-install or bulk-read the suite. If the Vidfarm CLI is unavailable, use the desktop agent's native skill discovery or local-skill mechanism and continue with the closest installed equivalent.
+
+HyperFrames authoring and rendering in this package are Vidfarm-native: local work uses the bundled composition toolchain and `vidfarm serve`; cloud work uses Vidfarm render routes. Do not require an external vendor account, repository, publish service, or telemetry endpoint. Keep `HYPERFRAMES_SKIP_SKILLS=1` and `HYPERFRAMES_NO_TELEMETRY=1` in Vidfarm-managed environments so the bundled skills stay pinned and local work does not phone home.
 
 ## Quick Router
 
@@ -158,7 +187,7 @@ Templates are listed on the Vidfarm homepage and `/discover`. Each has a `templa
 
 - Browser: browse `/discover`
 - API: `GET /discover/feed` — returns `{ templates: [{ templateId, slugId, title, previewUrl, viralDna, durationSeconds, sourceType, promotions, keywords, summary, ... }], next_cursor }`
-- Search: `GET /discover/feed?q=<offer>&limit=20` keyword-searches the catalog so you can answer "which templates suit my `<offer>`?" (e.g. `?q=weight%20loss%20app`). Ranking is a coarse keyword match over each template's title, viral DNA, and the decompose-derived `promotions` (offer categories the format can sell), `keywords`, and `summary` — read those fields to judge fit and rank the best 3-6 semantically. `GET /api/v1/videos?q=<offer>&limit=20[&mine=true]` runs the same search over source **inspirations**. `promotions`/`keywords`/`summary` are populated by the decompose pass, so a freshly ingested template that has not been decomposed yet won't match on them — decompose it (or fall back to broader/synonym terms) if a search comes up empty.
+- Search: `GET /discover/feed?q=<offer>&limit=20&sort=relevance` hybrid-searches the eligible public catalog using semantic embeddings plus lexical matches. Semantic query embedding uses Vidfarm's canonical OpenRouter-routed model and bills the provider cost × the standard 1.2 markup to the user's wallet. The response's `search` block reports `mode`, `embedding_space`, and any `semantic_limitation`; when it says `lexical_structured`, disclose the limitation briefly and continue rather than refusing. Decomposition adds `promotions`, `keywords`, `summary`, `categoryTags`, and `catalogIntelligence` (`wowScore`, `wowReason`, `automationScore`, `automationReason`, `contentStyles`, `searchText`). Use `sort=wow` for highest-quality/client-impressing formats, `sort=automation` for cheap repeatable bulk formats, and `sort=recent` only when freshness is the intent. Follow `next_cursor` with `cursor=<value>`; never call page one the whole catalog. `GET /api/v1/videos?q=<offer>&limit=20[&mine=true]` searches source **inspirations**. Undecomposed inspirations have only sparse ingest metadata, so they are harder to retrieve semantically. Explain that somebody in the world needs to decompose one once and the shared enrichment then benefits everyone; the current user need not act unless they want that specific inspiration immediately.
 
 Each template exposes a public preview:
 
@@ -180,7 +209,7 @@ To bring a new viral video into the catalog as a **private** template you own, i
 - `DELETE /discover/templates/:entryId` — remove a private inspiration/template you own (accepts either the `inspiration_...` or minted `template_...` id).
 - `POST /api/v1/inspirations/:inspirationId/decompose { user_prompt? }` — AI-decompose an inspiration's downloaded video into scenes (requires a saved provider key; same 120s source cap as auto-decompose).
 
-devcli: `vidfarm inspiration-add <url|file.mp4>` (a local file path runs the presign→PUT→finalize flow for you), `vidfarm inspiration-rm <id>`, `vidfarm inspiration-decompose <id>`, `vidfarm discover [query]` to browse/search templates, `vidfarm public-raws [query] [--category <key>] [--type <raw_type>] [--bookmark <raw_id>]` to browse/save the public raws catalog, and `vidfarm videos [query] [--mine]` to browse/search source inspirations. On the web, the Discover page's **Add Template** modal accepts either a URL or a file upload.
+devcli: `vidfarm inspiration-add <url|file.mp4>` (a local file path runs the presign→PUT→finalize flow for you), `vidfarm inspiration-rm <id>`, `vidfarm inspiration-decompose <id>`, `vidfarm discover [query] [--sort relevance|wow|automation|recent] [--cursor <next_cursor>]` to browse/search templates, `vidfarm public-raws [query] [--category <key>] [--type <raw_type>] [--bookmark <raw_id>]` to browse/save the public raws catalog, and `vidfarm videos [query] [--mine]` to browse/search source inspirations. On the web, the Discover page's **Add Template** modal accepts either a URL or a file upload.
 
 ## Fork a template
 
@@ -774,7 +803,7 @@ Mine a **long-form** video (podcast, stream VOD, webinar, any YouTube/TikTok/IG/
 
 - **Poll** `GET /raws/scan/:scanId` until the source `status` is `complete` (or `failed` — crashed pipelines are reconciled to `failed`, pollers never spin).
 - **Results**: `GET /raws/feed?source=<source_video_id>` (or the whole library), hybrid search via `POST /raws/search` `{ query: "someone looks confused" }`, per-raw download at `GET /raws/:clipId/download`. Raws carry taxonomy tags, a description, a transcript, an `aspect` field when cropped, the hunt's `tracer`, and (with a gemini/openai key) a semantic embedding.
-- **Billing** — **AWS compute only** (`clip_scan_lambda` GB-seconds + Step Functions transitions, a fraction of a cent for typical hunts; the 202 response includes a `compute_estimate`). The AI tagging/refine runs on **your saved provider key (BYOK)** and is never wallet-billed. Submission is wallet-gated (402 when empty).
+- **Billing** — scan compute (`clip_scan_lambda` GB-seconds + Step Functions transitions) and each persisted semantic embedding are wallet-metered; the 202 response includes a `compute_estimate`. AI tagging/refine runs on **your saved provider key (BYOK)** and is not wallet-billed. Submission is wallet-gated (402 when empty).
 - **The original stays temporary** — URL-ingested and uploaded sources live ONLY in your temp folder (`users/…/temporary/clip-sources/…`) with a hard **30-day TTL** (auto-deleted from S3 + the temp-file list). The hunted raws themselves are durable.
 - **Captions rule** — "no captions / no on-screen text" hunts are handled by scene SELECTION (the refine pass drops text-heavy scenes). **Never run GhostCut caption removal on a long-form source** (it is hard-capped at ~15 minutes); to actually erase burned-in text, apply `POST /api/v1/primitives/videos/remove-captions` to individual FINISHED raws afterwards.
 - **Clip an EXACT subrange (no AI hunt)** — when you want one precise hand-picked in/out rather than an open-ended hunt, use the **Clipper**: the web page `https://vidfarm.cc/tools/clipper` (previews the source straight from its URL, HH:MM:SS:NNNN in/out, live length estimate, multi-clip session grouped by tracer), the endpoint `POST /raws/clip-range` `{ source_url|preview_url|temp_file_id, start_sec, end_sec, tracer?, folder_path?, name? }` (trims exactly that window into one raw — compute-only, no AI/key), or the devcli twin `vidfarm clipper <video-url|file> --start <t> --end <t> [--tracer NAME --folder NAME --name TXT]`. The devcli path is now **local-first**: local files clip into the local raws store by default, and URL sources are staged locally before trimming unless you pass `--cloud`. If you do **not** have a `VIDFARM_API_KEY`, URL clipping cannot bootstrap the remote source into the local backend; open the long-form raw video in the browser, save/extract the actual video file locally, then run `vidfarm clipper ./source.mp4 ...`. The Library "Import source" button opens the Clipper; each save lands in `/raws/<folder>` (defaults to the tracer). Reach for `/raws/scan` for multi-clip hunts, `/raws/clip-range` for surgical single cuts. (The masked-image and time-scoped-video editors live alongside it at `/tools/image` and `/tools/video`.)
@@ -893,6 +922,8 @@ Send a stable `tracer` on export so retries are traceable and filterable in job
 
 **Scripting mode** is the recommended posture for repeatable template automation. Use it when a director wants to take a template they like, agree on a base fork, and then drive bulk or one-off edits entirely through REST or `vidfarm api` from a script, Lambda, or local machine.
 
+This section is for a **desktop/local coding agent**, not the web copilot. A local Codex/Claude agent may use its shell and filesystem to write JavaScript/TypeScript/Python/shell scripts, fetch every API page, join and score catalog/library data, calculate statistics, emit CSV/JSON/Markdown reports, manipulate composition DOM files, and run iterative render/inspection loops. The web copilot cannot inherit those abilities from this document: it may only call its declared tools and bounded REST routes. If web chat prepares work for this flow, consume its My Files handoff document as input; do not claim the web chat itself executed the script.
+
 Contract:
 
 1. Pick the template once, then fork once and treat the resulting `forkId` as the stable base.
@@ -976,7 +1007,7 @@ If a local AI script rewrites text or scenes without consuming those files first
 
 | Command | REST route | Flow step |
 |---|---|---|
-| `vidfarm discover [query]` | `GET /discover/feed[?q=]` | browse/search templates |
+| `vidfarm discover [query] [--sort relevance\|wow\|automation\|recent] [--cursor <cursor>]` | `GET /discover/feed[?q=&sort=&cursor=]` | hybrid-search templates and page through the catalog |
 | `vidfarm videos [query] [--mine]` | `GET /api/v1/videos[?q=&mine=]` | browse/search source inspirations |
 | `vidfarm inspiration-add <url\|file>` | `POST /discover/templates` (files: `POST /discover/templates/upload/presign` + PUT first) | add your own source (URL or local video upload) |
 | `vidfarm inspiration-rm <id>` | `DELETE /discover/templates/:id` | remove a private one |

package/dist/src/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { copyFileSync, createWriteStream, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { homedir, tmpdir } from "node:os";
+import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
@@ -83,8 +83,10 @@ Local editor loop:
 
 Discover & inspiration (browse the viral-video catalog, add your own source):
   discover [query...]       List/search TEMPLATES (best for an offer)    → GET  /discover/feed
-    --query <text>          Keyword search (e.g. "weight loss app")
+    --query <text>          Hybrid semantic + keyword search
     --limit <n>             Max results
+    --cursor <cursor>       Continue from next_cursor
+    --sort <mode>           relevance, wow, automation, or recent
   public-raws [query...]    Browse PUBLIC RAWS (feed / categories)       → GET  /api/v1/public-raws
     --query <text>          Keyword/vector query over title + metadata
     --category <key>        Filter one public-raw category (e.g. emotion:confused)
@@ -487,11 +489,12 @@ Account:
   add-provider-key <provider> <secret>   Save an AI provider key         → POST /api/v1/user/me/provider-keys
 
 Agent skill (install the latest director skill so your AI agent can act):
-  update-skill              Fetch latest SKILL.director.md → .claude/skills  → GET /skill/vidfarm-director
-    --global                Install into ~/.claude/skills (default: ./.claude/skills)
-    --dir <path>            Install into a custom skills root
-    --platform              Also install SKILL.platform.md (vidfarm-platform)
-    --print                 Print the skill to stdout instead of writing a file
+  update-skill              DEPRECATED installer alias; installs the canonical
+                            multi-file vidfarm-director pack via \`skills add\`.
+                            Use \`vidfarm skills add vidfarm-director\` directly.
+    --dir <path>            Project root for the canonical pack install
+    --print                 Print the generated single-file director rollup
+                            (copy/share artifact; not the canonical install)
 
 Files (multi-step flows the devcli handles for you):
   upload <file>             Upload to the EPHEMERAL temp store, print URL → POST /api/v1/user/me/temporary-files/upload
@@ -2184,14 +2187,14 @@ async function runTemplateCommand(argv) {
     }
 }
 // ── Discover & inspiration ──────────────────────────────────────────────────
-// `discover` lists TEMPLATES; `--query` keyword-searches the catalog so an agent
+// `discover` lists TEMPLATES; `--query` hybrid-searches the catalog so an agent
 // CLI (Claude Code / Codex) can answer "which templates suit my <offer>?". Each
 // result carries decompose-derived promotions/keywords/summary to reason over.
 async function runDiscoverCommand(argv) {
-    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), limit: { type: "string" }, query: { type: "string" } } });
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), limit: { type: "string" }, query: { type: "string" }, cursor: { type: "string" }, sort: { type: "string" } } });
     const ctx = commonContext(parsed.values);
     const query = (parsed.values.query ?? parsed.positionals.join(" ").trim()) || undefined;
-    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/discover/feed", auth: ctx.auth, query: { limit: parsed.values.limit, q: query } });
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/discover/feed", auth: ctx.auth, query: { limit: parsed.values.limit, q: query, cursor: parsed.values.cursor, sort: parsed.values.sort } });
     assertApiOk(result, "discover");
     emitResult(result, ctx.json, [["Browse ", discoverFrontendUrl(ctx.host)]]);
 }
@@ -6250,29 +6253,18 @@ async function runUpdateSkillCommand(argv) {
         }
         return;
     }
-    const skillsRoot = parsed.values.dir
-        ? path.resolve(process.cwd(), String(parsed.values.dir))
-        : parsed.values.global
-            ? path.join(homedir(), ".claude", "skills")
-            : path.resolve(process.cwd(), ".claude", "skills");
-    const written = [];
-    for (const name of skillNames) {
-        const { contents, source } = await fetchSkillContents(ctx.host, SKILL_TARGETS[name]);
-        const destDir = path.join(skillsRoot, name);
-        mkdirSync(destDir, { recursive: true });
-        const destPath = path.join(destDir, "SKILL.md");
-        writeFileSync(destPath, contents, "utf8");
-        written.push({ skill: name, path: destPath, source, bytes: Buffer.byteLength(contents, "utf8") });
-    }
-    if (ctx.json) {
-        printJson({ ok: true, skillsRoot, installed: written });
-        return;
+    if (parsed.values.global || parsed.values.platform) {
+        throw new Error("update-skill --global/--platform are retired. Use `vidfarm skills add vidfarm-director --dir <project>` for the canonical multi-file pack; `update-skill --print` remains available for the generated copy-friendly rollup.");
     }
-    for (const entry of written) {
-        const tag = entry.source === "bundled" ? " (offline — bundled copy)" : "";
-        console.log(`${GREEN}Installed ${entry.skill} skill${tag} → ${entry.path}${RESET}`);
-    }
-    console.log("");
-    console.log(`  ${BOLD}Your AI agent can now use the "vidfarm-director" skill.${RESET}`);
+    if (!ctx.json) {
+        console.warn(`Deprecated: update-skill now delegates to the canonical multi-file skill installer. Use ${BOLD}vidfarm skills add vidfarm-director${RESET}.`);
+    }
+    await runSkillsCommand([
+        "add",
+        "vidfarm-director",
+        ...(parsed.values.dir ? ["--dir", String(parsed.values.dir)] : []),
+        ...(parsed.values.host ? ["--host", String(parsed.values.host)] : []),
+        ...(ctx.json ? ["--json"] : [])
+    ]);
 }
 //# sourceMappingURL=cli.js.map

package/dist/src/devcli/clip-store.js

@@ -71,6 +71,7 @@ export class ClipStore {
         thumbnail_path TEXT NOT NULL,
         tags_json TEXT NOT NULL,
         description TEXT NOT NULL DEFAULT '',
+        embedding_text TEXT,
         taxonomy_version TEXT NOT NULL,
         tier TEXT NOT NULL,
         user_notes TEXT,
@@ -96,6 +97,10 @@ export class ClipStore {
         scanned_at TEXT NOT NULL
       );
     `);
+        const clipColumns = this.db.prepare("PRAGMA table_info(clips)").all();
+        if (!clipColumns.some((column) => column.name === "embedding_text")) {
+            this.db.exec("ALTER TABLE clips ADD COLUMN embedding_text TEXT");
+        }
     }
     seedBuiltinPresets() {
         const stmt = this.db.prepare("INSERT OR REPLACE INTO presets(preset_id, name, description, criteria_json, builtin, created_at) VALUES (?, ?, ?, ?, 1, ?)");
@@ -109,9 +114,9 @@ export class ClipStore {
             this.db
                 .prepare(`INSERT OR REPLACE INTO clips
             (clip_id, source_video_id, source_filename, start_time_sec, end_time_sec, duration_sec,
-             file_path, thumbnail_path, tags_json, description, taxonomy_version, tier, user_notes, created_at)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-                .run(c.clip_id, c.source_video_id, c.source_filename, c.start_time_sec, c.end_time_sec, c.duration_sec, c.file_path, c.thumbnail_path, JSON.stringify(c.tags), c.description ?? "", c.taxonomy_version, c.tier, c.user_notes ?? null, c.created_at);
+             file_path, thumbnail_path, tags_json, description, embedding_text, taxonomy_version, tier, user_notes, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(c.clip_id, c.source_video_id, c.source_filename, c.start_time_sec, c.end_time_sec, c.duration_sec, c.file_path, c.thumbnail_path, JSON.stringify(c.tags), c.description ?? "", c.embedding_text ?? null, c.taxonomy_version, c.tier, c.user_notes ?? null, c.created_at);
             if (c.embedding && c.embedding.length === this.dim) {
                 this.db.prepare("DELETE FROM vec_clips WHERE clip_id = ?").run(c.clip_id);
                 this.db
@@ -331,6 +336,7 @@ function rowToClip(row) {
         thumbnail_path: row.thumbnail_path,
         tags: safeParse(row.tags_json, emptyTags()),
         description: row.description ?? "",
+        embedding_text: row.embedding_text ?? undefined,
         taxonomy_version: row.taxonomy_version,
         tier: row.tier ?? "flash-lite",
         user_notes: row.user_notes ?? undefined,

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, 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 { buildEffectiveGuidance, buildPrivateUserNotesGuidance, ClipModelClient, DEFAULT_CLIP_ASPECT, DEFAULT_CLIP_DURATION_BAND, detectLocalAgent, detectScenes, effectiveHuntDurationSec, estimateScanCostFromScenes, 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)
 
@@ -269,8 +269,7 @@ async function runScan(argv) {
         console.log(`[raws] preferring scenes without on-screen text/captions (selection only — GhostCut is never run on the source).`);
     console.log(`[raws] aiming for ~${targetClipCount} distinct raw${targetClipCount === 1 ? "" : "s"}${maxClips ? " (--max-clips)" : " (~10 / 10 min)"}.`);
     console.log(`[raws] detecting scenes …`);
-    const detected = await detectScenes(videoPath, { durationSec: probe.duration_sec, windows, ...sceneOptions });
-    const scenes = fitScenesToDurationBand(detected, durationBand);
+    const scenes = await detectScenes(videoPath, { durationSec: probe.duration_sec, windows, ...sceneOptions });
     if (scenes.length === 0)
         throw new Error("No scenes detected (is the video readable / non-empty?).");
     const store = new ClipStore(values.home);

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

@@ -130,7 +130,11 @@ export async function detectScenes(videoPath, opts = {}) {
 }
 async function detectScenesInSpan(videoPath, opts) {
     const threshold = opts.threshold ?? 0.3;
-    const minScene = opts.minSceneSec ?? 0.6;
+    // Preserve very short detected shots as independent candidates. Absorbing a
+    // 2-10 frame flash into its neighbour makes it impossible for prompt/OCR
+    // refinement to reject that flash later. 50ms only de-duplicates effectively
+    // identical detector timestamps.
+    const minScene = opts.minSceneSec ?? 0.05;
     const maxScene = opts.maxSceneSec ?? 8;
     const { spanStart, spanEnd } = opts;
     const spanDuration = spanEnd - spanStart;

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

@@ -14,10 +14,10 @@ import { extractKeyframes } from "./ffmpeg.js";
 const MAX_SCENES_PER_BATCH = 60;
 // Bound total cost on very long sources: past this many batches we keep the raw
 // segmentation for the whole video (logged) instead of firing dozens of calls.
-const MAX_REFINE_BATCHES = 6;
+const MAX_REFINE_BATCHES = 30;
 export async function refineScenesWithGuidance(input) {
     const { client, videoPath, scenes, guidancePrompt } = input;
-    if (!guidancePrompt.trim() || scenes.length <= 1) {
+    if (!guidancePrompt.trim() || scenes.length === 0) {
         return { scenes, refined: false, kept: scenes.length, dropped: 0, merged: 0 };
     }
     const batchCount = Math.ceil(scenes.length / MAX_SCENES_PER_BATCH);
@@ -60,6 +60,8 @@ export async function refineScenesWithGuidance(input) {
                 ? Math.max(1, Math.round((input.targetClipCount * batch.length) / scenes.length))
                 : undefined;
             const batchDecisions = await askForDecisions(client, guidancePrompt, batch, frames, batchTarget);
+            if (!batchDecisions)
+                throw new Error("model returned no refinement plan");
             for (let i = 0; i < batch.length; i++) {
                 decisions.push(batchDecisions?.[i] ?? keepDefault());
             }
@@ -111,7 +113,7 @@ async function askForDecisions(client, guidancePrompt, scenes, frames, targetCli
         maxOutputTokens: Math.max(1000, scenes.length * 40)
     });
 }
-function rebuildScenes(scenes, decisions) {
+export function rebuildScenes(scenes, decisions) {
     const out = [];
     let dropped = 0;
     let merged = 0;
@@ -122,19 +124,25 @@ function rebuildScenes(scenes, decisions) {
             dropped++;
             continue;
         }
-        if (d.merge_with_previous && out.length > 0) {
-            // Extend the previous kept clip to cover this scene.
-            const prev = out[out.length - 1];
-            prev.end_time_sec = scenes[i].end_time_sec;
-            prev.duration_sec = round3(prev.end_time_sec - prev.start_time_sec);
+        const previous = out[out.length - 1];
+        const isAdjacent = previous
+            ? Math.abs(previous.end_time_sec - scenes[i].start_time_sec) <= 0.05
+            : false;
+        if (d.merge_with_previous && previous && isAdjacent) {
+            // Extend only an ADJACENT previous kept clip. A dropped scene creates a
+            // real timeline gap; bridging that gap would silently put the rejected
+            // footage back into the exported raw.
+            previous.end_time_sec = scenes[i].end_time_sec;
+            previous.duration_sec = round3(previous.end_time_sec - previous.start_time_sec);
             merged++;
             continue;
         }
         out.push({ ...scenes[i], index: out.length });
     }
-    // Never return an empty plan — if the model dropped everything, keep the raw scenes.
+    // An empty plan is a valid strict-prompt result. Silently restoring every
+    // scene here would completely ignore the user's request.
     if (out.length === 0) {
-        return { scenes, refined: false, kept: scenes.length, dropped: 0, merged: 0, note: "model dropped every scene; using raw scenes" };
+        return { scenes: [], refined: true, kept: 0, dropped, merged };
     }
     return { scenes: out, refined: true, kept: out.length, dropped, merged };
 }

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

@@ -76,10 +76,10 @@ export async function processSceneToClip(input) {
         await extractThumbnail({ videoPath, scene, outPath: thumbLocal, cropFilter });
     }
     // 5. Embed the document text for semantic search (skipped when the client can't embed).
+    const embeddingText = buildClipEmbeddingText(tags, tagResult.description, ctx.userNotes);
     let embedding;
     if (ctx.client.canEmbed) {
-        const embedText = buildClipEmbeddingText(tags, tagResult.description, ctx.userNotes);
-        [embedding] = await ctx.client.embedDocuments([embedText]);
+        [embedding] = await ctx.client.embedDocuments([embeddingText]);
     }
     const clip = {
         clip_id: clipId,
@@ -92,6 +92,7 @@ export async function processSceneToClip(input) {
         thumbnail_path: ctx.thumbStoredPath ? ctx.thumbStoredPath(clipId, thumbLocal) : thumbLocal,
         tags,
         description: tagResult.description,
+        embedding_text: embeddingText,
         embedding,
         taxonomy_version: ctx.client.taxonomyVersion ?? ACTIVE_TAXONOMY_VERSION,
         tier: ctx.client.tier,
@@ -113,21 +114,15 @@ export async function scanVideo(opts) {
     const probe = opts.probe ?? (await probeVideo(opts.videoPath));
     const windows = normalizeWindows(opts.windows, probe.duration_sec);
     const band = opts.durationBand ?? null;
-    // Fit to the soft duration band BEFORE refine: the model then judges
-    // clip-sized units (fewer, more meaningful keyframes) instead of raw cuts.
-    // Callers passing pre-detected scenes (devcli estimate pass) must pre-fit
-    // them — the fit is intentionally NOT re-run on supplied scenes since
-    // fitting is not idempotent (a fitted 20s scene could re-merge toward the
-    // target on a second pass).
+    // Keep detected shots separate until AFTER prompt refinement. This is
+    // important: judging a multi-shot duration span from one midpoint frame can
+    // approve unrelated opening/closing footage or miss text overlays in them.
     let scenes = opts.scenes ??
-        fitScenesToDurationBand(await detectScenes(opts.videoPath, {
+        await detectScenes(opts.videoPath, {
             durationSec: probe.duration_sec,
             windows,
-            // A duration band lifts the scene-split ceiling so raw cuts can merge
-            // up to the requested clip length instead of being pre-chopped at 8s.
-            ...(band ? { maxSceneSec: band.max_sec } : {}),
             ...opts.sceneOptions
-        }), band);
+        });
     // Prompt-guided segmentation: let the guidance reshape which scenes become
     // clips (keep/drop/merge/dedup) before we spend tagging tokens on them.
     if (opts.ctx.guidancePrompt?.trim() && opts.ctx.refineSegmentation !== false) {
@@ -139,11 +134,15 @@ export async function scanVideo(opts) {
             workDir: opts.ctx.workDir,
             targetClipCount: opts.targetClipCount
         });
-        // Refine merges can exceed the band max — re-enforce it (fit never merges
-        // across the gaps refine's drops created, only contiguous spans).
-        scenes = fitScenesToDurationBand(refined.scenes, band);
+        if (!refined.refined && refined.note) {
+            throw new Error(`Prompt-guided raw selection failed: ${refined.note}`);
+        }
+        scenes = refined.scenes;
         opts.onRefine?.(refined);
     }
+    // Assemble prompt-approved, contiguous shots into useful clip durations.
+    // fitScenesToDurationBand never crosses a dropped gap.
+    scenes = fitScenesToDurationBand(scenes, band);
     // Deterministic count/uniqueness cap: if more scenes survived than the target
     // (refine skipped >60 scenes, or the model kept more than asked), keep an
     // evenly-spaced — hence less duplicative — subset.

package/dist/src/services/provider-errors.js

@@ -12,6 +12,9 @@ export class SpeechVoiceMismatchError extends Error {
 }
 export class ProviderQuotaExceededError extends Error {
 }
+/** The provider refused the request or output because of its content/safety policy. */
+export class ProviderSafetyError extends Error {
+}
 export class ProviderWaitExceededError extends Error {
 }
 export class ProviderLeaseTimeoutError extends Error {
@@ -63,6 +66,54 @@ export function isHardQuotaError(details) {
         "resource_exhausted"
     ].some((pattern) => normalized.includes(pattern));
 }
+export function isSafetyOrRefusalError(details) {
+    const normalized = details.toLowerCase();
+    return [
+        "content_policy_violation",
+        "content policy",
+        "safety policy",
+        "safety filter",
+        "safety_reason",
+        "finishreason\":\"safety",
+        "moderation_blocked",
+        "blocked_reason",
+        "blockedreason",
+        "prompt was blocked",
+        "moderation",
+        "moderated",
+        "responsible ai",
+        "refused",
+        "refusal",
+        "prohibited content",
+        "policy violation"
+    ].some((pattern) => normalized.includes(pattern));
+}
+export function providerFailureFromDetails(provider, operation, status, details) {
+    if (isSafetyOrRefusalError(details)) {
+        return new ProviderSafetyError(`${provider} refused this ${operation} because its safety or content policy was triggered${conciseProviderDetails(details)}. ` +
+            "Try revising the prompt or choose another provider/model.");
+    }
+    return new Error(`${provider} ${operation} returned ${status}${conciseProviderDetails(details)}`);
+}
+export function serializeProviderFailure(error) {
+    const message = error instanceof Error ? error.message : "AI provider request failed";
+    if (error instanceof ProviderSafetyError) {
+        return { message, type: "provider_safety_refusal", retryable: false, user_action: "Revise the prompt or choose another provider/model." };
+    }
+    if (error instanceof ProviderRateLimitError) {
+        return { message, type: "provider_rate_limited", retryable: true, retry_after_seconds: error.retryAfterSeconds, user_action: "Wait, then retry or choose another provider." };
+    }
+    if (error instanceof ProviderQuotaExceededError) {
+        return { message, type: "provider_quota_exceeded", retryable: false, user_action: "Check provider billing/quota or choose another provider." };
+    }
+    if (error instanceof ProviderAuthError) {
+        return { message, type: "provider_auth_error", retryable: false, user_action: "Check the saved provider API key." };
+    }
+    if (error instanceof ProviderTransientError) {
+        return { message, type: "provider_temporarily_unavailable", retryable: true, retry_after_seconds: error.retryAfterSeconds, user_action: "Retry shortly or choose another provider." };
+    }
+    return { message, type: "provider_request_failed", retryable: false };
+}
 export function conciseProviderDetails(details) {
     const compact = details.replace(/\s+/g, " ").trim();
     return compact ? `: ${compact.slice(0, 500)}` : "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.20.12",
+  "version": "0.20.14",
   "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": {
@@ -53,6 +53,7 @@
     "dev:cli": "tsx src/cli.ts",
     "build:frontend": "node scripts/build-homepage-client.mjs",
     "build:hyperframes-editor": "cd demo && node scripts/build.mjs",
+    "seo:refresh": "tsx scripts/generate-route-seo.ts",
     "operator:template-artifact": "node scripts/platform-operator-template-artifact.mjs",
     "bootstrap:staging-templates": "tsx scripts/bootstrap-staging-template-releases.ts",
     "migrate:sqlite-to-dynamodb": "tsx scripts/migrate-sqlite-to-dynamodb.ts",
@@ -60,7 +61,10 @@
     "rollback:prod-inplace": "bash scripts/rollback-prod-inplace.sh",
     "build": "npm run build:frontend && npm run build:hyperframes-editor && node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
     "start": "node --import ./dist/src/instrument.js --enable-source-maps dist/src/index.js",
-    "check": "tsc -p tsconfig.json --noEmit",
+    "check": "tsc -p tsconfig.json --noEmit && npm run check:skills",
+    "test:clips": "node --import tsx --test test/clip-curation.test.ts",
+    "check:skills": "node scripts/build-director-skill-rollup.mjs --check && node scripts/check-skill-routes.mjs",
+    "benchmark:editor-chat": "node --import tsx scripts/benchmark-editor-chat-harness.mjs",
     "cdk:deploy:prod-serverless": "npm run build && dotenv -e .env.production -- npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-prod.js'",
     "cdk:synth:staging-serverless": "npm run build && dotenv -e .env.staging -- npx aws-cdk synth --app 'node dist/infra/cdk/bin/vidfarm-serverless-staging.js'",
     "cdk:deploy:staging-serverless": "npm run build && dotenv -e .env.staging -- npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-serverless-staging.js'",