@mevdragon/vidfarm-devcli 0.3.6 → 0.4.1

package/README.md

@@ -48,4 +48,6 @@ npx -y @mevdragon/vidfarm-devcli <template_id>
 
 Flags: `--port`, `--dir`, `--host`, `--fork`, `--api-key` (or `VIDFARM_API_KEY`), `--share`, `--refetch`. Use `dev-serve` as an explicit subcommand to skip the fetch step and just serve an existing directory.
 
+Beyond the local editor loop, the devcli also wraps the **entire director REST flow** as 1:1 commands — `discover`, `inspiration-add`, `fork`, `decompose`, `snapshot`, `render`, `approve`, `schedule`, `posts`, `upload`/`download`, plus a raw `vidfarm api <METHOD> <path>` passthrough. Each maps to exactly one REST route and prints the prod frontend URL to open. Run `vidfarm --help` for the full surface, or see `SKILL.director.md` § "`vidfarm-devcli` — full command surface".
+
 See `SKILL.platform.md` § "Local editor dev loop" for the request-rewrite / SSE reload flow.

package/SKILL.director.md

@@ -1,6 +1,6 @@
 ---
 name: vidfarm-director
-description: Use Vidfarm as a director. Fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, publish to MP4, and share. Includes login, provider keys, discovery, publishing, versioning, and billing.
+description: Use Vidfarm as a director. Browse/add inspiration videos, fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, render to MP4, approve into a shareable post, and schedule it. Includes login, provider keys, discovery, versioning, uploads/downloads, and billing. Every step is available as a raw REST route and as a 1:1 `vidfarm-devcli` command.
 ---
 
 # Vidfarm Director
@@ -82,6 +82,16 @@ Each template exposes a public preview:
 
 Directors don't edit templates directly. They fork.
 
+### Add your own source (inspiration)
+
+To bring a new viral video into the catalog as a **private** template you own, ingest its social URL:
+
+- `POST /discover/templates { source_url, tagline?, notes? }` — accepts TikTok / YouTube / Instagram / Twitter-X URLs only. The video download runs async; the response is the inspiration record (`202`, `status: "processing"`). The card finalizes into a private `template_...` the next time `GET /discover/feed` is polled (the feed poll doubles as the completion check).
+- `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>`, `vidfarm inspiration-rm <id>`, `vidfarm inspiration-decompose <id>`, and `vidfarm discover` to browse.
+
 ## Fork a template
 
 ```
@@ -193,9 +203,9 @@ Use it whenever you need to know what the video says or shows: writing/translati
 - **Editor chat (frontend AI)** exposes this as the optional `video_context` tool — the copilot calls it on demand.
 - **Desktop agents (Claude Code / Codex)**: `vidfarm edit <template_id>` syncs the same payload to `video-context.json` on disk next to `composition.html` (use `--refetch` to refresh it after a new decompose), or fetch the route directly.
 
-## Publish
+## Render (publish to MP4)
 
-Publishing renders the fork's current working state to an MP4 using shared Remotion Lambda. The route is `/export`:
+Rendering publishes the fork's current working state to an MP4 using shared Remotion Lambda. In the Trackpad Editor this is the **Render** button; the REST route is still named `/export` (the route name predates the UI rename — treat "Render", "publish", and `/export` as the same operation). The devcli exposes it as `vidfarm render <forkId> [--wait]`.
 
 ```
 POST /api/v1/compositions/:forkId/export
@@ -214,6 +224,41 @@ Response includes `{ ok, renderId, status: "RUNNING" | "SUCCEEDED" | "FAILED", p
 
 Every publish creates an immutable version snapshot at `versions/<N>/composition.html` and `versions/<N>/composition.json`.
 
+## Approve a finished post
+
+A render produces a bare MP4 URL. **Approving** wraps that MP4 (plus caption, title, pinned comment, and any carousel slides) into a shareable preview page — the phone-mockup page a human opens to review and copy the post.
+
+```
+POST /api/v1/approved/posts
+Content-Type: application/json
+
+{ "caption": "required", "title": "optional", "pinned_comment": "optional", "tracer": "optional",
+  "media": [ { "url": "https://.../output.mp4", "kind": "video", "role": "primary" } ] }
+```
+
+`caption` is required. `media[]` items take `{ url, kind?: "image"|"video"|..., role?: "primary"|"slide"|... }`. Response (`201`) is the approved post including **`share_url`** — the prod frontend page for previewing/sharing. Surface that URL to the user; it is the headline output of this step.
+
+- `GET /api/v1/approved/posts` — list your approved posts
+- `GET /api/v1/approved/posts/:postId` — read one (returns `share_url`, `download_zip_url`)
+
+devcli: `vidfarm approve --video <mp4-url> --caption "..."` prints the `share_url` as a first-class openable link; `vidfarm posts` lists, `vidfarm post <id>` reads one.
+
+## Schedule a post
+
+Schedule an approved post to a connected destination channel (FlockPoster social account or email) at one ISO timestamp:
+
+```
+POST /api/v1/approved/posts/:postId/schedules
+Content-Type: application/json
+
+{ "destination_type": "flockposter" | "email", "destination_id": "<channel or email>",
+  "scheduled_at": "2026-07-10T14:00:00Z", "timezone": "America/New_York", "additional_notes": "optional" }
+```
+
+Minimum 10-minute lead time. Response (`201`) is the schedule record. Browse existing schedules with `GET /api/v1/approved/posts/:postId/schedules`.
+
+devcli: `vidfarm schedule <postId> --at <iso> --to <destinationId> [--type flockposter|email]`, and `vidfarm schedules <postId>` to browse.
+
 ## Version history
 
 ```
@@ -300,7 +345,43 @@ For agents that operate Vidfarm headlessly, the typical loop is:
 
 Send a stable `tracer` on export so retries are traceable and filterable in job history — but note that submission is **not idempotent**: every POST creates a new job (and a new charge) even with the same tracer. Do not blind-retry expensive submissions; check the render status first.
 
-## Local dev loop with `vidfarm-devcli`
+## `vidfarm-devcli` — full command surface
+
+`@mevdragon/vidfarm-devcli` wraps the **entire director REST flow** as CLI commands. It is a thin shell over the REST API, not a second implementation: **every named command maps 1:1 to exactly one REST route**, and all it adds is fork auto-resolution, the `vidfarm-api-key` header, prod frontend links in the output, render-poll waiting, and the multi-step upload/download flows. Auth via `--api-key <key>` or `VIDFARM_API_KEY`.
+
+**Raw REST vs devcli — your choice.** If you want full control, call the REST API directly (or use the raw passthrough `vidfarm api <METHOD> <path> [--data <json>] [--query k=v]`). If you want ergonomics + openable frontend URLs, use the named commands. They are interchangeable — pick per call.
+
+| Command | REST route | Flow step |
+|---|---|---|
+| `vidfarm discover` | `GET /discover/feed` | browse inspiration/templates |
+| `vidfarm inspiration-add <url>` | `POST /discover/templates` | add your own source |
+| `vidfarm inspiration-rm <id>` | `DELETE /discover/templates/:id` | remove a private one |
+| `vidfarm inspiration-decompose <id>` | `POST /api/v1/inspirations/:id/decompose` | AI-decompose an inspiration |
+| `vidfarm fork <template_id>` | `POST /api/v1/compositions` | fork a template |
+| `vidfarm decompose <forkId>` | `POST .../compositions/:forkId/auto-decompose` | split source into scenes |
+| `vidfarm ghostcut <forkId>` | `GET .../compositions/:forkId/ghostcut` | subtitle-removal status |
+| `vidfarm snapshot <forkId>` | `POST .../compositions/:forkId/versions` | save composition fork version |
+| `vidfarm versions <forkId>` | `GET .../compositions/:forkId/versions` | list versions |
+| `vidfarm render <forkId> [--wait]` | `POST .../compositions/:forkId/export` | render video to MP4 |
+| `vidfarm render-status <forkId> <renderId>` | `GET .../compositions/:forkId/renders/:renderId` | poll a render |
+| `vidfarm visibility <forkId> <private\|public>` | `PATCH .../compositions/:forkId/visibility` | set visibility |
+| `vidfarm clone <forkId>` | `POST .../compositions/:forkId/clone` | clone a fork |
+| `vidfarm share-link <forkId>` | `POST .../compositions/:forkId/share-links` | mint a share URL |
+| `vidfarm approve --video <url> --caption "…"` | `POST /api/v1/approved/posts` | approve post (prints `share_url`) |
+| `vidfarm posts` / `vidfarm post <id>` | `GET /api/v1/approved/posts[/:id]` | browse approved posts |
+| `vidfarm schedule <postId> --at <iso> --to <dest>` | `POST /api/v1/approved/posts/:postId/schedules` | schedule a post |
+| `vidfarm schedules <postId>` | `GET /api/v1/approved/posts/:postId/schedules` | browse scheduled posts |
+| `vidfarm login <email>` / `vidfarm verify <email> <code>` | `POST /api/v1/user/request-otp` · `verify-otp` | get an API key |
+| `vidfarm whoami` | `GET /api/v1/user/me` | who am I |
+| `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys |
+| `vidfarm upload <file>` | `POST /api/v1/user/me/temporary-files/upload` | upload → durable URL |
+| `vidfarm download <url> [dest]` | (streams any URL to disk) | download media |
+
+**Frontend URLs are first-class output.** Every command that has a human-openable page (editor, discover, approved-post preview, share link) prints that prod frontend URL as a highlighted line. `render --wait` polls to completion and prints the final MP4 URL; `approve` prints the approved-post `share_url`. Add `--json` to any command for pure JSON (agent-friendly, no banners).
+
+**Uploads/downloads live in the devcli** because they are genuine multi-step / streaming flows: `upload` posts the file as multipart to the temporary-files route and prints the durable URL to drop into a composition or approved post; `download` streams any Vidfarm/media URL to disk.
+
+## Local dev loop (edit on disk)
 
 For iterating on a composition on disk (e.g. Claude Code editing HTML directly), pair the hosted editor with a local composition directory:
 

package/SKILL.platform.md

@@ -184,7 +184,7 @@ The editor is a single monolithic React component (~9k lines). It builds cleanly
 
 Publish flow:
 
-1. Client `POST /api/v1/compositions/:forkId/export` (the route is named `export`; the concept is "publish")
+1. Client `POST /api/v1/compositions/:forkId/export` (the route is named `export`; the editor button and devcli command are both **Render**; treat "render", "publish", and `/export` as the same operation)
 2. API stamps `data-composition-id="<forkId>@v<N>"` into the composition HTML, PUTs the stamped HTML to working, and reads composition.json
 3. API resolves the caller's provider keys (preflight check for required models)
 4. API creates a `job` record and invokes the `hyperframes_render` primitive Lambda
@@ -353,7 +353,7 @@ Legacy but still active:
 - Composition runtime script — `src/composition-runtime.ts`
 - Trackpad Editor — `demo/src/HyperframesStudioEditor.tsx`
 - Editor local-mode bootstrap — `demo/src/dev-mode.ts`
-- Devcli (`vidfarm-devcli`) — `src/cli.ts` (edit-mode fetch + banner), `src/dev-serve.ts` (raw HTTP shim)
+- Devcli (`vidfarm-devcli`) — `src/cli.ts` (edit-mode fetch + banner, the REST-wrapper commands, and the shared `apiRequest()` helper), `src/dev-serve.ts` (raw HTTP shim)
 - Auto-decompose logic — `src/hyperframes/composition.ts` (time-slice), `src/services/hyperframes.ts` (smart)
 - Publish flow — `src/app.ts` `publishCompositionToRenderer()`
 - Ghostcut — `src/services/ghostcut.ts`
@@ -361,7 +361,7 @@ Legacy but still active:
 
 ## Local editor dev loop
 
-`@mevdragon/vidfarm-devcli` (`src/cli.ts` + `src/dev-serve.ts`) pairs a local directory of composition files with the hosted Trackpad Editor so Claude Code, Codex, or a human can edit `composition.html` on disk and see instant preview reload in the browser.
+`@mevdragon/vidfarm-devcli` (`src/cli.ts` + `src/dev-serve.ts`) has two roles. First, it pairs a local directory of composition files with the hosted Trackpad Editor so Claude Code, Codex, or a human can edit `composition.html` on disk and see instant preview reload in the browser (the `edit`/`publish`/`dev-serve` commands, detailed below). Second, it wraps the **entire director REST flow** as 1:1 CLI commands — `discover`, `inspiration-add`, `fork`, `decompose`, `snapshot`, `render` (→ `/export`), `approve`, `schedule`, `posts`/`schedules`, `upload`/`download`, `login`/`whoami`/`provider-keys`, plus a raw `api <METHOD> <path>` passthrough. Every wrapper routes through a single `apiRequest()` helper (auth + host + JSON), so it never duplicates route logic; the command↔route table and the raw-REST-vs-devcli guidance live in `SKILL.director.md`. Each command prints its prod frontend URL (editor / discover / approved-post `share_url`) as a first-class output, and `--json` gives pure JSON for agents.
 
 ```bash
 # One-shot: fetch composition, start dev-serve, print editor URL.

package/dist/src/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { createWriteStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { spawnSync } from "node:child_process";
 import { Readable } from "node:stream";
@@ -11,34 +13,101 @@ import { pipeline } from "node:stream/promises";
 // starts a local dev-serve, and prints the editor URL to open in the browser.
 const DEFAULT_HOST = "https://vidfarm.cc";
 const DEFAULT_PORT = 4321;
-const HELP = `vidfarm-devcli — local editor bridge for the Vidfarm Trackpad Editor
+// Agent skill files the `update-skill` command can install from the live host
+// (`GET /skill/<name>`), falling back to the copy bundled in this npm package.
+const SKILL_TARGETS = {
+    "vidfarm-director": { route: "/skill/vidfarm-director", bundled: "SKILL.director.md" },
+    "vidfarm-platform": { route: "/skill/vidfarm-platform", bundled: "SKILL.platform.md" }
+};
+// Every command below is a thin wrapper over ONE Vidfarm REST call (the `→`
+// line documents the exact route). The devcli adds nothing the raw API can't
+// do — it just resolves your fork, sets the `vidfarm-api-key` header, prints
+// the prod frontend URL to open, and handles the multi-step upload/download +
+// render-polling flows that are awkward to do by hand. Prefer the raw REST API
+// (or `vidfarm api <METHOD> <path>`) whenever you want full control; reach for
+// the named commands when you want the ergonomics and the frontend links.
+const HELP = `vidfarm-devcli — command-line bridge for the Vidfarm video studio
+
+Every named command maps 1:1 to a single REST route (shown as → below). Use
+raw REST (or \`vidfarm api\`) when you want control; use named commands for the
+ergonomics + prod frontend links. Auth: --api-key <key> or VIDFARM_API_KEY.
 
 Usage:
-  vidfarm-devcli <template_id> [options]        Start local editor session
-  vidfarm-devcli publish <template_id> [opts]   Push local composition to your fork
-  vidfarm-devcli dev-serve [options]            Serve an existing local dir only
-  vidfarm-devcli --help                         Show this help
+  vidfarm <template_id> [opts]              Start local editor session (default)
+  vidfarm <command> [args] [opts]
+  vidfarm --help
 
-Options (edit mode):
-  --port <n>          Local dev-serve port (default: ${DEFAULT_PORT})
-  --dir <path>        Local composition directory (default: .vidfarm/<template_id>)
-  --host <url>        Vidfarm host to fetch from (default: ${DEFAULT_HOST})
-  --fork <id>         Fork id to fetch (default: auto-resolve for the current user)
+Local editor loop:
+  <template_id> [opts]      Fetch composition + media, dev-serve, print editor URL
+  publish [template_id]     Push local composition.html/json to your fork  → PUT/PATCH composition + POST versions
+  dev-serve                 Serve an existing local dir only (no fetch)
+
+Discover & inspiration (browse the viral-video catalog, add your own source):
+  discover                  List the template/inspiration feed          → GET  /discover/feed
+  inspiration-add <url>     Ingest a TikTok/YT/IG/X video as a template  → POST /discover/templates
+  inspiration-rm <id>       Delete a private inspiration/template you own → DELETE /discover/templates/:id
+  inspiration-decompose <id>  AI-decompose an inspiration into scenes     → POST /api/v1/inspirations/:id/decompose
+
+Composition lifecycle (fork → decompose → snapshot → render):
+  fork <template_id>        Fork a template into an editable composition → POST /api/v1/compositions
+  decompose <forkId>        Split the fork's source into scenes (smart)  → POST .../compositions/:forkId/auto-decompose
+  ghostcut <forkId>         Read subtitle-removal status (non-billing)   → GET  .../compositions/:forkId/ghostcut
+  versions <forkId>         List immutable version snapshots             → GET  .../compositions/:forkId/versions
+  snapshot <forkId>         Save the working state as a new version      → POST .../compositions/:forkId/versions
+  render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/export
+  render-status <forkId> <renderId>   Poll one render job               → GET  .../compositions/:forkId/renders/:renderId
+  visibility <forkId> <private|public>   Set fork visibility            → PATCH .../compositions/:forkId/visibility
+  clone <forkId>            Clone a fork as a new starting point         → POST .../compositions/:forkId/clone
+  share-link <forkId>       Mint a share-token URL for a fork            → POST .../compositions/:forkId/share-links
+
+Approve & schedule (publish a finished MP4 as a shareable post):
+  approve                   Approve media into a preview/share page      → POST /api/v1/approved/posts
+  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
+  schedules <postId>        Browse an approved post's schedules          → GET  /api/v1/approved/posts/:postId/schedules
+
+Account:
+  login <email>             Send an OTP code to email                    → POST /api/v1/user/request-otp
+  verify <email> <code>     Verify the OTP, print a fresh API key        → POST /api/v1/user/verify-otp
+  whoami                    Show the authenticated account               → GET  /api/v1/user/me
+  provider-keys             List saved AI provider keys                  → GET  /api/v1/user/me/provider-keys
+  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
+
+Files (multi-step flows the devcli handles for you):
+  upload <file>             Upload a local file, print its durable URL   → POST /api/v1/user/me/temporary-files/upload
+  download <url> [dest]     Stream any Vidfarm/media URL to disk
+
+Escape hatch — call ANY route directly:
+  api <METHOD> <path>       Raw REST call with auth + pretty errors
+    --data <json>           JSON request body (or --data-file <path>)
+    --query k=v             Repeatable query param
+  Examples:
+    vidfarm api GET /discover/feed
+    vidfarm api POST /api/v1/compositions --data '{"template_id":"template_..."}'
+
+Common options (any command):
+  --host <url>        Vidfarm host (default: ${DEFAULT_HOST})
   --api-key <key>     Vidfarm API key (or set VIDFARM_API_KEY)
   --share <token>     Share token for a shared fork (public read)
-  --refetch           Overwrite local composition files with the latest remote copy
+  --json              Print only the raw JSON response (agent-friendly)
 
-Options (publish mode):
+Editor-mode options:
+  --port <n>          Local dev-serve port (default: ${DEFAULT_PORT})
   --dir <path>        Local composition directory (default: .vidfarm/<template_id>)
-  --host <url>        Vidfarm host to publish to (default: ${DEFAULT_HOST})
-  --fork <id>         Fork id to publish into (default: auto-resolve for the current user)
-  --api-key <key>     Vidfarm API key (or set VIDFARM_API_KEY) — required to write
-  --message <text>    Optional message attached to the published version snapshot
-  --no-snapshot       Only update the working copy; skip the version snapshot
+  --fork <id>         Fork id (default: auto-resolve for the current user)
+  --refetch           Overwrite local composition files with the latest remote copy
 
-Options (dev-serve mode):
-  --dir <path>        Directory to serve (default: current dir)
-  --port <n>          Port to listen on (default: ${DEFAULT_PORT})
+Publish-mode options:
+  --message <text>    Message attached to the published version snapshot
+  --no-snapshot       Only update the working copy; skip the version snapshot
 `;
 void main().catch((error) => {
     console.error(error instanceof Error ? error.stack ?? error.message : String(error));
@@ -51,25 +120,222 @@ async function main() {
         return;
     }
     const command = argv[0];
-    if (command === "dev-serve") {
-        const { runDevServeCommand } = await import("./dev-serve.js");
-        await runDevServeCommand(argv.slice(1));
-        return;
+    const rest = argv.slice(1);
+    switch (command) {
+        case "dev-serve": {
+            const { runDevServeCommand } = await import("./dev-serve.js");
+            await runDevServeCommand(rest);
+            return;
+        }
+        case "edit":
+            await runEditCommand(rest);
+            return;
+        case "publish":
+            await runPublishCommand(rest);
+            return;
+        // Raw escape hatch + all the 1:1 REST wrappers.
+        case "api":
+            await runApiCommand(rest);
+            return;
+        case "discover":
+            await runDiscoverCommand(rest);
+            return;
+        case "inspiration-add":
+            await runInspirationAddCommand(rest);
+            return;
+        case "inspiration-rm":
+            await runInspirationRemoveCommand(rest);
+            return;
+        case "inspiration-decompose":
+            await runInspirationDecomposeCommand(rest);
+            return;
+        case "fork":
+            await runForkCommand(rest);
+            return;
+        case "decompose":
+            await runDecomposeCommand(rest);
+            return;
+        case "ghostcut":
+            await runGhostcutCommand(rest);
+            return;
+        case "versions":
+            await runVersionsCommand(rest);
+            return;
+        case "snapshot":
+            await runSnapshotCommand(rest);
+            return;
+        case "render":
+            await runRenderCommand(rest);
+            return;
+        case "render-status":
+            await runRenderStatusCommand(rest);
+            return;
+        case "visibility":
+            await runVisibilityCommand(rest);
+            return;
+        case "clone":
+            await runCloneCommand(rest);
+            return;
+        case "share-link":
+            await runShareLinkCommand(rest);
+            return;
+        case "approve":
+            await runApproveCommand(rest);
+            return;
+        case "posts":
+            await runPostsCommand(rest);
+            return;
+        case "post":
+            await runPostCommand(rest);
+            return;
+        case "schedule":
+            await runScheduleCommand(rest);
+            return;
+        case "schedules":
+            await runSchedulesCommand(rest);
+            return;
+        case "login":
+            await runLoginCommand(rest);
+            return;
+        case "verify":
+            await runVerifyCommand(rest);
+            return;
+        case "whoami":
+            await runWhoamiCommand(rest);
+            return;
+        case "update-skill":
+        case "skill":
+            await runUpdateSkillCommand(rest);
+            return;
+        case "provider-keys":
+            await runProviderKeysCommand(rest);
+            return;
+        case "add-provider-key":
+            await runAddProviderKeyCommand(rest);
+            return;
+        case "upload":
+            await runUploadCommand(rest);
+            return;
+        case "download":
+            await runDownloadCommand(rest);
+            return;
+        default:
+            if (!command.startsWith("-")) {
+                // Positional template id → default `edit` command.
+                await runEditCommand(argv);
+                return;
+            }
+            throw new Error(`Unknown option before command: ${command}\n\n${HELP}`);
     }
-    if (command === "edit") {
-        await runEditCommand(argv.slice(1));
-        return;
+}
+// ── REST plumbing shared by every wrapper command ───────────────────────────
+// One code path for auth + host + query + JSON. This is what makes the devcli a
+// thin shell over the REST API rather than a second implementation: the named
+// commands below just assemble a method/path/body and hand it here.
+const FRONTEND = "\x1b[1m\x1b[36m"; // bold cyan — reserved for openable URLs
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const RESET = "\x1b[0m";
+async function apiRequest(input) {
+    const url = new URL(input.path, input.host);
+    for (const [key, value] of Object.entries(input.query ?? {})) {
+        if (value !== undefined && value !== null && value !== "")
+            url.searchParams.set(key, value);
     }
-    if (command === "publish") {
-        await runPublishCommand(argv.slice(1));
-        return;
+    const headers = { ...buildAuthHeaders(input.auth), accept: "application/json" };
+    let body;
+    if (input.body !== undefined) {
+        headers["content-type"] = "application/json";
+        body = JSON.stringify(input.body);
+    }
+    const res = await fetch(url, { method: input.method.toUpperCase(), headers, body });
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        json = null;
     }
-    if (!command.startsWith("-")) {
-        // Positional template id → default `edit` command.
-        await runEditCommand(argv);
+    return { status: res.status, ok: res.ok, json, text };
+}
+// Named commands should fail loudly (unlike the read-tolerant edit fetch).
+function assertApiOk(result, action) {
+    if (result.ok)
+        return;
+    const detail = result.json && typeof result.json === "object" && typeof result.json.error === "string"
+        ? ` — ${result.json.error}`
+        : result.text
+            ? ` — ${result.text.slice(0, 300)}`
+            : "";
+    const hint = result.status === 401 || result.status === 403
+        ? " Check --api-key / VIDFARM_API_KEY and that you own this resource."
+        : result.status === 402
+            ? " The account is not on a paid plan (or the wallet is empty)."
+            : result.status === 429
+                ? " Rate-limited; wait and retry."
+                : "";
+    throw new Error(`${action} failed: ${result.status}${detail}.${hint}`);
+}
+// Resolve host + auth + output mode shared by every wrapper command. Adding
+// these to a parseArgs `options` block keeps the flags consistent everywhere.
+function commonOptions() {
+    return {
+        host: { type: "string", default: DEFAULT_HOST },
+        "api-key": { type: "string" },
+        share: { type: "string" },
+        json: { type: "boolean", default: false }
+    };
+}
+function commonContext(values) {
+    return {
+        host: trimTrailingSlash(String(values.host ?? DEFAULT_HOST)),
+        auth: {
+            apiKey: values["api-key"] ?? process.env.VIDFARM_API_KEY,
+            shareToken: values.share
+        },
+        json: Boolean(values.json)
+    };
+}
+function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+// Print the JSON result and, when not in --json mode, a highlighted list of the
+// prod frontend URLs a human can open. Frontend links are a first-class output.
+function emitResult(result, json, frontend) {
+    if (json) {
+        printJson(result.json ?? result.text);
         return;
     }
-    throw new Error(`Unknown option before command: ${command}\n\n${HELP}`);
+    printJson(result.json ?? result.text);
+    const links = (frontend ?? []).filter((entry) => Boolean(entry[1]));
+    if (links.length > 0) {
+        console.log("");
+        for (const [label, url] of links) {
+            console.log(`  ${BOLD}${label}${RESET}  ${FRONTEND}${url}${RESET}`);
+        }
+    }
+}
+// Frontend URL builders — these are the pages a director opens in a browser.
+function editorFrontendUrl(host, templateId, forkId) {
+    const base = `${host}/editor/${encodeURIComponent(templateId)}`;
+    return forkId ? `${base}?fork=${encodeURIComponent(forkId)}` : base;
+}
+function discoverFrontendUrl(host) {
+    return `${host}/discover`;
+}
+// Small arg helper: split "k=v" pairs for --query.
+function collectKeyValues(entries) {
+    const out = {};
+    for (const entry of entries ?? []) {
+        const eq = entry.indexOf("=");
+        if (eq === -1)
+            throw new Error(`--query expects k=v, got: ${entry}`);
+        out[entry.slice(0, eq)] = entry.slice(eq + 1);
+    }
+    return out;
 }
 async function runEditCommand(argv) {
     const parsed = parseArgs({
@@ -578,4 +844,561 @@ function printEditorBanner(input) {
 function trimTrailingSlash(value) {
     return value.replace(/\/+$/, "");
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ── Raw escape hatch: call any REST route ───────────────────────────────────
+async function runApiCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), data: { type: "string" }, "data-file": { type: "string" }, query: { type: "string", multiple: true } }
+    });
+    const method = parsed.positionals[0];
+    const routePath = parsed.positionals[1];
+    if (!method || !routePath) {
+        throw new Error(`api requires <METHOD> <path>.\n\nExample: vidfarm api GET /discover/feed`);
+    }
+    const ctx = commonContext(parsed.values);
+    let body;
+    if (parsed.values["data-file"]) {
+        body = JSON.parse(readFileSync(path.resolve(process.cwd(), String(parsed.values["data-file"])), "utf8"));
+    }
+    else if (parsed.values.data) {
+        body = JSON.parse(String(parsed.values.data));
+    }
+    const result = await apiRequest({
+        method,
+        host: ctx.host,
+        path: routePath,
+        auth: ctx.auth,
+        query: collectKeyValues(parsed.values.query),
+        body
+    });
+    if (!ctx.json) {
+        const color = result.ok ? GREEN : RED;
+        console.log(`${color}${method.toUpperCase()} ${routePath} → ${result.status}${RESET}`);
+    }
+    printJson(result.json ?? result.text);
+    if (!result.ok)
+        process.exitCode = 1;
+}
+// ── Discover & inspiration ──────────────────────────────────────────────────
+async function runDiscoverCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: false, options: { ...commonOptions(), limit: { type: "string" } } });
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/discover/feed", auth: ctx.auth, query: { limit: parsed.values.limit } });
+    assertApiOk(result, "discover");
+    emitResult(result, ctx.json, [["Browse ", discoverFrontendUrl(ctx.host)]]);
+}
+async function runInspirationAddCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), tagline: { type: "string" }, notes: { type: "string" } } });
+    const sourceUrl = parsed.positionals[0];
+    if (!sourceUrl)
+        throw new Error("inspiration-add requires a video URL (TikTok/YouTube/Instagram/X).");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/discover/templates",
+        auth: ctx.auth,
+        body: { source_url: sourceUrl, tagline: parsed.values.tagline, notes: parsed.values.notes }
+    });
+    assertApiOk(result, "inspiration-add");
+    emitResult(result, ctx.json, [["Discover ", discoverFrontendUrl(ctx.host)]]);
+}
+async function runInspirationRemoveCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const entryId = parsed.positionals[0];
+    if (!entryId)
+        throw new Error("inspiration-rm requires an inspiration_/template_ id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "DELETE", host: ctx.host, path: `/discover/templates/${encodeURIComponent(entryId)}`, auth: ctx.auth });
+    assertApiOk(result, "inspiration-rm");
+    emitResult(result, ctx.json);
+}
+async function runInspirationDecomposeCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), prompt: { type: "string" } } });
+    const inspirationId = parsed.positionals[0];
+    if (!inspirationId)
+        throw new Error("inspiration-decompose requires an inspiration id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: `/api/v1/inspirations/${encodeURIComponent(inspirationId)}/decompose`,
+        auth: ctx.auth,
+        body: { user_prompt: parsed.values.prompt ?? null }
+    });
+    assertApiOk(result, "inspiration-decompose");
+    emitResult(result, ctx.json);
+}
+// ── Composition lifecycle ───────────────────────────────────────────────────
+async function runForkCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), title: { type: "string" } } });
+    const templateId = parsed.positionals[0];
+    if (!templateId)
+        throw new Error("fork requires a template id (template_...).");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/api/v1/compositions",
+        auth: ctx.auth,
+        body: { template_id: templateId, title: parsed.values.title }
+    });
+    assertApiOk(result, "fork");
+    const forkId = result.json?.fork_id;
+    const tId = result.json?.template_id ?? templateId;
+    emitResult(result, ctx.json, [["Open editor ", forkId ? editorFrontendUrl(ctx.host, tId, forkId) : null]]);
+}
+async function runDecomposeCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), mode: { type: "string", default: "smart" }, prompt: { type: "string" } } });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("decompose requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/auto-decompose`,
+        auth: ctx.auth,
+        body: { mode: parsed.values.mode, user_prompt: parsed.values.prompt ?? null }
+    });
+    assertApiOk(result, "decompose");
+    if (!ctx.json && result.json?.ghostcut_pending) {
+        console.log(`${DIM}GhostCut subtitle-removal is running in the background — poll \`vidfarm api POST /api/v1/compositions/${forkId}/ghostcut-poll\` or GET .../ghostcut until done.${RESET}`);
+    }
+    emitResult(result, ctx.json);
+}
+async function runGhostcutCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("ghostcut requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/ghostcut`, auth: ctx.auth });
+    assertApiOk(result, "ghostcut");
+    emitResult(result, ctx.json);
+}
+async function runVersionsCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), limit: { type: "string" } } });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("versions requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/versions`, auth: ctx.auth, query: { limit: parsed.values.limit } });
+    assertApiOk(result, "versions");
+    emitResult(result, ctx.json);
+}
+async function runSnapshotCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), message: { type: "string" } } });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("snapshot requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "POST", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/versions`, auth: ctx.auth, body: { message: parsed.values.message ?? null } });
+    assertApiOk(result, "snapshot");
+    emitResult(result, ctx.json);
+}
+async function runRenderCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), title: { type: "string" }, tracer: { type: "string" }, wait: { type: "boolean", default: false } }
+    });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("render requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/export`,
+        auth: ctx.auth,
+        body: { title: parsed.values.title, tracer: parsed.values.tracer }
+    });
+    assertApiOk(result, "render");
+    const renderId = result.json?.renderId;
+    if (!parsed.values.wait || !renderId) {
+        if (!ctx.json && renderId) {
+            console.log(`${DIM}Poll with: vidfarm render-status ${forkId} ${renderId} (or add --wait next time).${RESET}`);
+        }
+        emitResult(result, ctx.json, [["Rendered MP4 ", result.json?.outputUrl]]);
+        return;
+    }
+    // --wait: poll the render job until it settles.
+    if (!ctx.json)
+        console.log(`${DIM}Rendering ${renderId}… polling every 5s.${RESET}`);
+    let last = result;
+    for (;;) {
+        await sleep(5000);
+        last = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/renders/${encodeURIComponent(renderId)}`, auth: ctx.auth });
+        assertApiOk(last, "render-status");
+        const status = String(last.json?.status ?? "");
+        if (!ctx.json) {
+            const pct = Math.round((Number(last.json?.progress ?? 0)) * 100);
+            console.log(`${DIM}  ${status} ${pct}%${RESET}`);
+        }
+        if (status === "SUCCEEDED" || status === "FAILED")
+            break;
+    }
+    emitResult(last, ctx.json, [["Rendered MP4 ", last.json?.outputUrl]]);
+    if (String(last.json?.status) === "FAILED")
+        process.exitCode = 1;
+}
+async function runRenderStatusCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const forkId = parsed.positionals[0];
+    const renderId = parsed.positionals[1];
+    if (!forkId || !renderId)
+        throw new Error("render-status requires <forkId> <renderId>.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/renders/${encodeURIComponent(renderId)}`, auth: ctx.auth });
+    assertApiOk(result, "render-status");
+    emitResult(result, ctx.json, [["Rendered MP4 ", result.json?.outputUrl]]);
+}
+async function runVisibilityCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const forkId = parsed.positionals[0];
+    const visibility = parsed.positionals[1];
+    if (!forkId || !visibility)
+        throw new Error("visibility requires <forkId> <private|public>.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "PATCH", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/visibility`, auth: ctx.auth, body: { visibility } });
+    assertApiOk(result, "visibility");
+    const templateId = result.json?.template_id;
+    emitResult(result, ctx.json, templateId ? [["Open editor ", editorFrontendUrl(ctx.host, templateId, forkId)]] : undefined);
+}
+async function runCloneCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), version: { type: "string" }, title: { type: "string" } } });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("clone requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/clone`,
+        auth: ctx.auth,
+        body: { parent_version: parsed.values.version, title: parsed.values.title }
+    });
+    assertApiOk(result, "clone");
+    const newForkId = result.json?.fork_id;
+    const templateId = result.json?.template_id;
+    emitResult(result, ctx.json, newForkId && templateId ? [["Open editor ", editorFrontendUrl(ctx.host, templateId, newForkId)]] : undefined);
+}
+async function runShareLinkCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), role: { type: "string", default: "viewer" }, expires: { type: "string" } } });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("share-link requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/share-links`,
+        auth: ctx.auth,
+        body: { role: parsed.values.role, expires_at: parsed.values.expires ?? null }
+    });
+    assertApiOk(result, "share-link");
+    emitResult(result, ctx.json, [["Share ", result.json?.share_url]]);
+}
+// ── Approve & schedule ──────────────────────────────────────────────────────
+async function runApproveCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: false,
+        options: {
+            ...commonOptions(),
+            video: { type: "string" },
+            media: { type: "string", multiple: true },
+            caption: { type: "string" },
+            title: { type: "string" },
+            pinned: { type: "string" },
+            tracer: { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const caption = parsed.values.caption;
+    if (!caption)
+        throw new Error("approve requires --caption <text>.");
+    const media = [];
+    if (parsed.values.video)
+        media.push({ url: parsed.values.video, kind: "video", role: "primary" });
+    for (const url of parsed.values.media ?? [])
+        media.push({ url });
+    if (media.length === 0) {
+        console.warn(`${DIM}[vidfarm] no --video / --media given; approving a text-only post.${RESET}`);
+    }
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/api/v1/approved/posts",
+        auth: ctx.auth,
+        body: {
+            caption,
+            title: parsed.values.title,
+            pinned_comment: parsed.values.pinned,
+            tracer: parsed.values.tracer,
+            media
+        }
+    });
+    assertApiOk(result, "approve");
+    // The approved-post preview page is the headline output: it's the prod
+    // frontend URL a human opens to see/share the finished post.
+    emitResult(result, ctx.json, [["Preview post ", result.json?.post?.share_url]]);
+}
+async function runPostsCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: false, options: { ...commonOptions(), limit: { type: "string" }, tracer: { type: "string" } } });
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/approved/posts", auth: ctx.auth, query: { limit: parsed.values.limit, tracer: parsed.values.tracer } });
+    assertApiOk(result, "posts");
+    emitResult(result, ctx.json);
+}
+async function runPostCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const postId = parsed.positionals[0];
+    if (!postId)
+        throw new Error("post requires a post id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/approved/posts/${encodeURIComponent(postId)}`, auth: ctx.auth });
+    assertApiOk(result, "post");
+    emitResult(result, ctx.json, [["Preview post ", result.json?.post?.share_url]]);
+}
+async function runScheduleCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), at: { type: "string" }, to: { type: "string" }, type: { type: "string", default: "flockposter" }, timezone: { type: "string" }, notes: { type: "string" } }
+    });
+    const postId = parsed.positionals[0];
+    if (!postId)
+        throw new Error("schedule requires a post id.");
+    if (!parsed.values.at)
+        throw new Error("schedule requires --at <ISO 8601 timestamp>.");
+    if (!parsed.values.to)
+        throw new Error("schedule requires --to <destination_id> (a FlockPoster channel or email).");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: `/api/v1/approved/posts/${encodeURIComponent(postId)}/schedules`,
+        auth: ctx.auth,
+        body: {
+            destination_type: parsed.values.type,
+            destination_id: parsed.values.to,
+            scheduled_at: parsed.values.at,
+            timezone: parsed.values.timezone,
+            additional_notes: parsed.values.notes
+        }
+    });
+    assertApiOk(result, "schedule");
+    emitResult(result, ctx.json);
+}
+async function runSchedulesCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const postId = parsed.positionals[0];
+    if (!postId)
+        throw new Error("schedules requires a post id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/approved/posts/${encodeURIComponent(postId)}/schedules`, auth: ctx.auth });
+    assertApiOk(result, "schedules");
+    emitResult(result, ctx.json);
+}
+// ── Account ─────────────────────────────────────────────────────────────────
+async function runLoginCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const email = parsed.positionals[0];
+    if (!email)
+        throw new Error("login requires an email address.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/user/request-otp", auth: ctx.auth, body: { email } });
+    assertApiOk(result, "login");
+    if (!ctx.json)
+        console.log(`${GREEN}OTP requested for ${email}. Run: vidfarm verify ${email} <code>${RESET}`);
+    emitResult(result, ctx.json);
+}
+async function runVerifyCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), name: { type: "string" } } });
+    const email = parsed.positionals[0];
+    const code = parsed.positionals[1];
+    if (!email || !code)
+        throw new Error("verify requires <email> <code>.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/user/verify-otp", auth: ctx.auth, body: { email, code, name: parsed.values.name } });
+    assertApiOk(result, "verify");
+    const apiKey = result.json?.apiKey;
+    if (!ctx.json && apiKey) {
+        console.log(`${GREEN}${BOLD}Save this API key:${RESET} ${apiKey}`);
+        console.log(`${DIM}export VIDFARM_API_KEY=${apiKey}${RESET}`);
+    }
+    emitResult(result, ctx.json);
+}
+async function runWhoamiCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: false, options: commonOptions() });
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me", auth: ctx.auth });
+    assertApiOk(result, "whoami");
+    emitResult(result, ctx.json);
+}
+async function runProviderKeysCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: false, options: commonOptions() });
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me/provider-keys", auth: ctx.auth });
+    assertApiOk(result, "provider-keys");
+    emitResult(result, ctx.json);
+}
+async function runAddProviderKeyCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), label: { type: "string" } } });
+    const provider = parsed.positionals[0];
+    const secret = parsed.positionals[1];
+    if (!provider || !secret)
+        throw new Error("add-provider-key requires <provider> <secret> (provider: openai|gemini|openrouter|perplexity).");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/user/me/provider-keys", auth: ctx.auth, body: { provider, secret, label: parsed.values.label } });
+    assertApiOk(result, "add-provider-key");
+    emitResult(result, ctx.json);
+}
+// ── Files ───────────────────────────────────────────────────────────────────
+// Upload is a genuine multi-step flow, so the devcli earns its keep here: it
+// posts the file as multipart/form-data to the temporary-files route and prints
+// the durable URL you can drop into a composition or an approved post.
+async function runUploadCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), folder: { type: "string" } } });
+    const filePath = parsed.positionals[0];
+    if (!filePath)
+        throw new Error("upload requires a local file path.");
+    const ctx = commonContext(parsed.values);
+    const abs = path.resolve(process.cwd(), filePath);
+    if (!existsSync(abs))
+        throw new Error(`No such file: ${abs}`);
+    const buffer = readFileSync(abs);
+    const form = new FormData();
+    form.append("file", new Blob([buffer]), path.basename(abs));
+    if (parsed.values.folder)
+        form.append("folder_path", String(parsed.values.folder));
+    const res = await fetch(new URL("/api/v1/user/me/temporary-files/upload", ctx.host), {
+        method: "POST",
+        headers: buildAuthHeaders(ctx.auth),
+        body: form
+    });
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        json = null;
+    }
+    const result = { status: res.status, ok: res.ok, json, text };
+    assertApiOk(result, "upload");
+    emitResult(result, ctx.json, [["Durable URL ", result.json?.file?.view_url ?? result.json?.file?.s3_url]]);
+}
+async function runDownloadCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const url = parsed.positionals[0];
+    if (!url)
+        throw new Error("download requires a URL.");
+    const ctx = commonContext(parsed.values);
+    const dest = parsed.positionals[1]
+        ? path.resolve(process.cwd(), parsed.positionals[1])
+        : path.resolve(process.cwd(), path.basename(new URL(url).pathname) || "download.bin");
+    const res = await fetch(url, { headers: buildAuthHeaders(ctx.auth) });
+    if (!res.ok || !res.body)
+        throw new Error(`download failed: ${res.status} ${res.statusText} (${url}).`);
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(dest));
+    const bytes = safeSize(dest);
+    if (ctx.json) {
+        printJson({ ok: true, url, path: dest, bytes });
+    }
+    else {
+        console.log(`${GREEN}Downloaded ${formatBytes(bytes)} → ${dest}${RESET}`);
+    }
+}
+// ── Agent skill ───────────────────────────────────────────────────────────────
+// Install the latest director skill onto disk as a Claude Code / agent skill so
+// the user's AI agent can read SKILL.director.md and act. We pull the freshest
+// copy from the live host (`GET /skill/<name>`) and fall back to the copy that
+// shipped inside this npm package when offline. Written as `<skill>/SKILL.md`.
+// Walk up from this module's directory to find a bundled skill file. Handles
+// both the published layout (dist/src/cli.js → package root) and running from
+// source (src/cli.ts → repo root).
+function locateBundledSkill(filename) {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i += 1) {
+        const candidate = path.join(dir, filename);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+async function fetchSkillContents(host, target) {
+    try {
+        const res = await fetch(new URL(target.route, host));
+        if (res.ok) {
+            const contents = await res.text();
+            if (contents.trim())
+                return { contents, source: "remote" };
+        }
+    }
+    catch {
+        // fall through to the bundled copy below
+    }
+    const bundledPath = locateBundledSkill(target.bundled);
+    if (bundledPath) {
+        return { contents: readFileSync(bundledPath, "utf8"), source: "bundled" };
+    }
+    throw new Error(`Could not fetch ${target.bundled} from ${host} and no bundled copy was found.`);
+}
+async function runUpdateSkillCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: false,
+        options: {
+            ...commonOptions(),
+            global: { type: "boolean", default: false },
+            dir: { type: "string" },
+            platform: { type: "boolean", default: false },
+            print: { type: "boolean", default: false }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const skillNames = ["vidfarm-director", ...(parsed.values.platform ? ["vidfarm-platform"] : [])];
+    if (parsed.values.print) {
+        for (const name of skillNames) {
+            const { contents } = await fetchSkillContents(ctx.host, SKILL_TARGETS[name]);
+            process.stdout.write(contents.endsWith("\n") ? contents : `${contents}\n`);
+        }
+        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;
+    }
+    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}`);
+}
 //# sourceMappingURL=cli.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.3.6",
+  "version": "0.4.1",
   "description": "Local bridge for the Vidfarm Trackpad Editor. Point it at a template id, edit composition.html on disk (Claude Code, Codex, etc.), preview live in the browser at https://vidfarm.cc/editor/.",
   "type": "module",
   "bin": {