@mevdragon/vidfarm-devcli 0.20.13 → 0.20.14

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

@@ -50,6 +50,8 @@ 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 |
@@ -79,6 +81,7 @@ 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
 

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,6 +50,8 @@ 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 |
@@ -79,6 +81,7 @@ 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
 

package/package.json

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