@officexapp/vidfarm-devcli 0.21.51 → 0.21.53

package/dist/src/cli.js

@@ -1144,6 +1144,9 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
     --file-id <id>          Move a FILE; omit to move the folder (same root, e.g. /raws/demos → /raws/archive)
   directory copy <path> [<to-folder>] Duplicate a file/folder (shared S3 obj)  → POST /api/v1/user/me/directory/copy
     --file-id <id> --as <name>   Copy a FILE; omit --file-id to copy the folder; --as renames the copy
+  directory note <path>     Read/write the VECTOR NOTE of a file or FOLDER      → GET|PUT /api/v1/user/me/directory/note
+    --file-id <id>          Annotate a FILE; omit to annotate the FOLDER at <path>
+    --set "<text>"          What the thing IS, in plain words — embedded, so search finds it by meaning
   directory save-url <url>  Save a durable media URL INTO My Files at a folder → POST /api/v1/user/me/attachments/from-url
     --folder <path>         Destination folder under /files (e.g. inpaints, promos)
     --as <name>             Name the saved file · --notes <text> vector-embedded notes
@@ -1161,7 +1164,10 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
          vidfarm gigs proofs --status pending   ·   vidfarm gigs approve PRF_01H…
     (see: vidfarm gigs help)
   shared <sub> <link>       USE a link someone shared with you — NO account, NO API key
-    info · ls · search · mkdir · put · get     e.g. vidfarm shared put <link> clip.mp4 --subfolder batch-01
+    info · ls --tree · search · grab · note · mkdir · put · get
+    grab is the one to reach for: it finds footage by MEANING and downloads it in one step.
+    e.g. vidfarm shared grab <link> "founder talking head, kitchen" --out ./assets
+         vidfarm shared put <link> cut-v2.mp4 --subfolder batch-01 --note "Final cut, 9:16"
     (the gigworker/agent side of directory share; see: vidfarm shared help)
   put-file / get-file / files / annotate-file are the My Files (persistent) set;
   upload is the throwaway temp store for dropping media into a composition.
@@ -2741,7 +2747,7 @@ Rules:
 - When swapping visuals, match both the literal scene DNA and the narrative purpose of the beat.
 - For replacement graphics, screenshots, or still-like scenes, prefer AI image generation plus Ken Burns before paying for AI video unless static_vs_pivot says motion footage is load-bearing.
 - If narration must be customized, default to premium ElevenLabs first, then the user's own ElevenLabs path, then BYOK OpenAI/Gemini/OpenRouter. If captions or scenes were timed to the old VO, retime them to the new narration.
-- NO HTML SLOP. You are editing HTML, but the output is a social video, not a web page. THE TEST IS THE NATIVE-EDITOR TEST: could you have made this element with the tools inside TikTok's own editor? That toolset is a font, a color, a stroke/outline, a soft shadow, a tight text box, alignment, opacity, rotation, animation presets — plus stickers, emoji, drawn marks and clips. It has NO padded capsule, NO border, NO gradient fill, NO blur panel, NO card. If you reached past it, cut it. Never author landing-page furniture: CTA "buttons" (a filled/gradient rounded capsule with action copy like "Sign Up for a Free Trial →"), benefit chip/badge rows ("✓ No Credit Card Needed"), bordered/shadowed/frosted cards holding a headline + URL, gradient text fills, feature grids, bulleted lists, or web-default fonts (Inter/Roboto/Arial/system-ui). AND NOT A SINGLE PILL EITHER: one lonely rounded, padded, filled capsule around a static stat or label — "10 hrs / week", "STEP 2", "EP.01", "+40%" — is a web badge, and being the only one on screen does not make it native. The ONLY legitimate capsule in a video is the active-word spotlight/karaoke caption highlight, because it moves with the spoken word. Emphasize a stat the way the editor would: bigger, heavier, ALL-CAPS, an accent color, a hand-drawn circle or underline, or its own beat on screen. Rule of thumb on anything holding words: border-radius over ~8px PLUS a background fill PLUS padding = a badge; drop the fill or drop the radius until the band hugs the glyphs. None of this appears in a real TikTok, and nothing in a video is clickable — say it as timed text on the footage instead. Arrows, scribble/underline marks, italics, ALL-CAPS, single-word color pops, emoji, transparent cut-out stickers, and mock social UI (iMessage bubbles, comment cards) are all fine. Captions use an imported family (Montserrat default / TikTok Sans / Abel / Source Code Pro / Yesteryear) at weight 700-900, ~36-64px on a 1080-wide frame, inside the 8%-85% safe zone, with exactly one of four backgrounds: outline, plain, an active-word spotlight/karaoke pill, or a tight-hugging solid band (radius <=8px, no border/shadow/gradient/blur).
+- NO HTML SLOP. You are editing HTML, but the output is a social video, not a web page. THE TEST IS THE NATIVE-EDITOR TEST: could you have made this element with the tools inside TikTok's own editor? That toolset is a font, a color, a stroke/outline, a soft shadow, a tight text box, alignment, opacity, rotation, animation presets — plus stickers, emoji, drawn marks and clips. It has NO padded capsule, NO border, NO gradient fill, NO blur panel, NO card. If you reached past it, cut it. Never author landing-page furniture: CTA "buttons" (a filled/gradient rounded capsule with action copy like "Sign Up for a Free Trial →"), benefit chip/badge rows ("✓ No Credit Card Needed"), bordered/shadowed/frosted cards holding a headline + URL, gradient text fills, feature grids, bulleted lists, or web-default fonts (Inter/Roboto/Arial/system-ui). AND NOT A SINGLE PILL EITHER: one lonely rounded, padded, filled capsule around a static stat or label — "10 hrs / week", "STEP 2", "EP.01", "+40%" — is a web badge, and being the only one on screen does not make it native. The ONLY legitimate capsule in a video is the active-word spotlight/karaoke caption highlight, because it moves with the spoken word. Emphasize a stat the way the editor would: bigger, heavier, ALL-CAPS, an accent color, a hand-drawn circle or underline, or its own beat on screen. Rule of thumb on anything holding words: border-radius over ~8px PLUS a background fill PLUS padding = a badge; drop the fill or drop the radius until the band hugs the glyphs. None of this appears in a real TikTok, and nothing in a video is clickable — say it as timed text on the footage instead. Arrows, scribble/underline marks, italics, ALL-CAPS, single-word color pops, emoji, transparent cut-out stickers, and mock social UI (iMessage bubbles, comment cards) are all fine. Captions use one of the FIVE imported families and nothing else (Montserrat default / TikTok Sans / Abel / Source Code Pro / Yesteryear - the full regime, with a rendered specimen of each, is at https://vidfarm.cc/fonts) at weight 700-900, ~36-64px on a 1080-wide frame, inside the 8%-85% safe zone, with exactly one of four backgrounds: outline, plain, an active-word spotlight/karaoke pill, or a tight-hugging solid band (radius <=8px, no border/shadow/gradient/blur).
 - NO LAYOUT TEMPLATES — JUDGE THE WHOLE FRAME, NOT JUST THE ELEMENT. Every rule above judges one element, and a frame can pass element-by-element and still be a web page. The archetype is the MODAL: the backdrop dimmed and blurred out of focus, and floating on top of it a rounded bordered box holding a big headline, a smaller support line, and a fat CTA button. THE STACK IS THE TELL, NOT THE BOX — delete the border, the fill and the capsule, keep headline then subheadline then CTA centred in a well with even margins, and it STILL reads as a landing page, because a viewer recognizes the SHAPE before reading a single word. Banned at frame level: a modal/dialog staged on top of a backdrop that has been dimmed, blurred, greyed or scaled back (nothing in a video pops "above" the video); the hero triplet and its cousins (title + kicker + logo lockup, question + answer + URL); a full-frame dark wash used to stage a floating block (a legibility band on ONE caption is legal, a page-wide wash to stage a panel is not; likewise a blurred backdrop is fine alone — a blurred fill behind a 16:9 clip in a 9:16 frame is a real technique — but blur PLUS dimming is modal staging); nav strip / hero / three-up feature row / testimonial block / footer fine print; a blurred website screenshot used as the background plate (if the backdrop is a web page, the frame is a screen recording of a web page — show the real product UI full-bleed and in focus, or don't show it); a centred content column with even gutters and document margins. THE FIX IS ALWAYS TO UNSTACK IT INTO TIME: the headline is the hook at start:0, the support line lands on the next cut, the CTA is SPOKEN or a bare caption on the final frame. You lose nothing — a viewer reads one line at a time anyway — and you gain the pacing that makes it look shot rather than designed. Self-check before you place any text group: am I arranging words relative to EACH OTHER, or relative to the PICTURE? Relative to each other is a layout, which is web. Two on-screen text runs at once is the ceiling. Verify on real pixels: \`vidfarm stills . --at <t>\` — if the still could be a screenshot of a website, rebuild the beat. \`vidfarm qa\` catches only the mechanical half (layout-template, modal-scrim); the frame-level judgement is yours.
 - STRUCTURE BEFORE POLISH — THE FOUR CHARGES, WRITTEN BEFORE YOU TOUCH THE TIMELINE. Most agent-made videos fail on structure, not polish, because the timeline is the fun part so it gets built first and the words get retrofitted. Invert it: (1) HOOK — write the opening line as text first: a complete clause (subject + verb), no jargon, naming a SITUATION ("I've quit six businesses") not a label ("anonymity"); it goes on screen at start:0, because caption chunk 1 is read before any audio and muted autoplay is the default. Banned openings: throat-clearing ("so I was thinking", "here's the thing"), a logo, a title card, a fade from black, context before the claim. (2) LOOP — one open question by 0:10, said ON SCREEN, closing INSIDE this video (state the timestamp it closes at; if you can't, there is no loop), and the withheld answer must be one the viewer CANNOT supply themselves — a formally-correct loop with a guessable answer passes every mechanical check and dies in the field. (3) PAYOFF — shown, not summarized, ≥5 uninterrupted seconds, landing BEFORE the final beat; the payoff is not the CTA. (4) BAIT — one ask in the final beat and in the post caption; a keyword comment ask ("comment CLIPPER and I'll send the breakdown") is standard and allowed, but never "follow for part two", ragebait, or an earnings/health claim traded for the reply. Then build the timeline. Re-theming a decomposed template: viral_dna already names the source's hook/retention/payoff — rebuild each charge for the new subject, never flatten the loop into a product statement. Full craft harness: the vidfarm skill's references/hooks-and-virality.md. Checkable form: \`vidfarm harness show hooks\`.
 - ORIENT THE COLD VIEWER IN THE FIRST 3 SECONDS — THE VIEWER HAS NO CONTEXT AND DID NOT CHOOSE THIS VIDEO. Distinct from the hook: the hook makes them WANT to watch, orientation makes the watching POSSIBLE. A stranger mid-scroll must be able to answer three things by ~3s — what am I looking at (the CATEGORY noun), who is it for, and why is this on my screen (the situation). The failure is not a bad first frame, it is a good video that BEGINS AT BEAT TWO, and the author cannot see it because the author already knows what the thing is. Signatures, each a rebuild not a polish: a pronoun with no referent ("it just works", "this changes everything", "here's how they do it"); starting at step three (the process already running, the dashboard already full); a metaphor whose subject only lands at 6s; insider vocabulary, a product's own feature name, or an ACRONYM in the first line; a detail crop that reads as texture until you know the whole. Instead, the opening beat is BOTH channels at once: an EASY IMAGE (one large subject, already moving, legible at a glance and at thumbnail scale — a relevant die-cut sticker names the category before a word is read) AND an EASY LINE (first spoken sentence one clause, <=12 words, everyday words, concrete noun + verb, no subordinate clause, brand name said once plainly, and the CATEGORY named: "X is a language app that…"). Give the SITUATION, not the label — "the end of the month, and your receipts are in a shoebox" orients, "expense automation" does not. THIS IS NOT AN INTRO AND COSTS NO EXTRA SECONDS: it replaces the wind-up sentence, it never precedes it, and it never licenses a logo, a title card or a fade from black. Test it on the render, not the script: play the first 3 seconds ONLY to somebody with no context and stop — they should say what kind of thing it is and roughly who it is for. "Something about audio" is a fail. Fullest form: \`vidfarm harness show product-explainer\` (Rule 0).
@@ -11104,6 +11110,17 @@ const DIRECTORY_HELP = `vidfarm directory — browse the unified file tree (/fil
     e.g. vidfarm directory copy /raws/demos /raws/archive
          vidfarm directory copy /files/brand/logo.png /files/inbox --file-id att_123 --as logo-copy.png
 
+  directory note <path>            Read the VECTOR NOTE of a file or FOLDER          → GET /api/v1/user/me/directory/note
+    --file-id <id>                 Annotate a FILE; omit to annotate the FOLDER at <path>
+    --set "<text>"                 Write the note ("" clears it). It is embedded, so the
+                                   thing is findable by MEANING — a file name is not.
+    --json
+    e.g. vidfarm directory note /raws/AboutOffer/BRoll --set "Kitchen b-roll, no faces, 9:16"
+         vidfarm directory note /files/brand/logo.png --file-id att_123
+    Notes live on /files entries, /raws entries and FOLDERS in any writable root.
+    Uploads self-describe when the account has an AI key saved (skipped over 100 MB);
+    with no key the note is yours to type, and search falls back to keyword-only.
+
   directory save-url <url>         Save a durable media URL INTO My Files at a folder → POST /api/v1/user/me/attachments/from-url
     --folder <path>                Destination folder under /files (e.g. inpaints, promos)
     --as <name>                    Name the saved file (else derived from the URL)
@@ -11155,6 +11172,10 @@ async function runDirectoryCommand(argv) {
         case "copy":
         case "cp":
             return runDirectoryCopy(rest);
+        case "note":
+        case "notes":
+        case "annotate":
+            return runDirectoryNote(rest);
         case "save-url":
         case "from-url":
         case "import-url":
@@ -11247,6 +11268,55 @@ async function runDirectorySearch(argv) {
     }
     printDirectorySearch(merged, query, spaces.length > 1 ? "both" : spaces[0]);
 }
+// Read or write the VECTOR NOTE of a file or folder. The note is the plain-text
+// answer to "what is this?", embedded so search finds it from any phrasing —
+// which is the difference between a folder of IMG_4821.mp4 and a usable library.
+async function runDirectoryNote(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), "file-id": { type: "string" }, set: { type: "string" }, note: { type: "string" } }
+    });
+    const ctx = commonContext(parsed.values);
+    const targetPath = parsed.positionals[0];
+    if (!targetPath) {
+        throw new Error('directory note requires a path: vidfarm directory note /raws/BRoll [--file-id <id>] [--set "what this is"]');
+    }
+    const fileId = parsed.values["file-id"];
+    const next = parsed.values.set ?? parsed.values.note;
+    const space = targetSpaces(ctx.target)[0];
+    if (next == null) {
+        const result = await dispatch(ctx, { method: "GET", path: "/api/v1/user/me/directory/note", query: { path: targetPath, id: fileId } }, space);
+        assertApiOk(result, "directory note");
+        if (ctx.json) {
+            printJson(result.json ?? result.text);
+            return;
+        }
+        const note = result.json?.note;
+        console.log(`${BOLD}${targetPath}${RESET}`);
+        console.log(note ? `  ${note}` : `  ${DIM}(no vector note yet)${RESET}`);
+        if (!note)
+            console.log(`  ${DIM}Write one: vidfarm directory note ${targetPath}${fileId ? ` --file-id ${fileId}` : ""} --set "what this is"${RESET}`);
+        return;
+    }
+    const result = await dispatch(ctx, {
+        method: "PUT",
+        path: "/api/v1/user/me/directory/note",
+        body: { path: targetPath, ...(fileId ? { id: fileId } : {}), note: next }
+    }, space);
+    assertApiOk(result, "directory note");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    const saved = result.json?.note;
+    console.log(`${GREEN}✓${RESET} ${saved ? "note saved on" : "note cleared on"} ${BOLD}${targetPath}${RESET}`);
+    if (saved) {
+        console.log(result.json?.embedded
+            ? `  ${DIM}searchable by meaning${RESET}`
+            : `  ${DIM}saved, but keyword-search only — add a gemini/openai key to embed it${RESET}`);
+    }
+}
 async function runDirectoryRename(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -11568,6 +11638,20 @@ function mergeSearch(parts, limit) {
     };
 }
 // Compact "12.3s · 4.2 MB · video/mp4" line for a directory file item.
+// ── vector notes in list/search output ───────────────────────────────────────
+// The note is what a human (or an agent) recognises the item by, so it prints
+// under the name; the mark makes a MISSING note visible as a gap to fill.
+function noteLine(item) {
+    const note = typeof item?.note === "string" ? item.note.replace(/\s+/g, " ").trim() : "";
+    if (!note)
+        return "";
+    return note.length > 110 ? `${note.slice(0, 109)}…` : note;
+}
+function noteMark(item) {
+    if (item?.note === undefined)
+        return ""; // backend carries no note field
+    return item.note ? `${GREEN}✓${RESET} ` : `${DIM}✎${RESET} `;
+}
 function directoryFileMeta(item) {
     const parts = [];
     if (typeof item?.durationSec === "number" && item.durationSec > 0)
@@ -11598,11 +11682,17 @@ function printDirectoryListing(data, requestedPath, space) {
         console.log(`  ${DIM}(empty)${RESET}`);
     }
     for (const f of folders) {
-        console.log(`  ${DIM}dir ${RESET}  ${originBadge(f)}${f?.name ?? ""}/    ${DIM}${f?.path ?? ""}${RESET}`);
+        console.log(`  ${DIM}dir ${RESET}  ${noteMark(f)}${originBadge(f)}${f?.name ?? ""}/    ${DIM}${f?.path ?? ""}${RESET}`);
+        const note = noteLine(f);
+        if (note)
+            console.log(`        ${DIM}${note}${RESET}`);
     }
     for (const f of files) {
         const meta = directoryFileMeta(f);
-        console.log(`  file  ${originBadge(f)}${f?.name ?? ""}${meta ? `    ${DIM}${meta}${RESET}` : ""}    ${DIM}${f?.path ?? ""}${RESET}`);
+        console.log(`  file  ${noteMark(f)}${originBadge(f)}${f?.name ?? ""}${meta ? `    ${DIM}${meta}${RESET}` : ""}    ${DIM}${f?.path ?? ""}${RESET}`);
+        const note = noteLine(f);
+        if (note)
+            console.log(`        ${DIM}${note}${RESET}`);
         if (f?.viewUrl)
             console.log(`        ${FRONTEND}${f.viewUrl}${RESET}`);
     }
@@ -11623,7 +11713,10 @@ function printDirectorySearch(data, query, space) {
     results.forEach((r, i) => {
         const score = typeof r?.score === "number" ? ` ${DIM}score=${r.score.toFixed(3)}${RESET}` : "";
         const kind = r?.kind === "folder" ? "dir " : "file";
-        console.log(`  ${String(i + 1).padStart(2)}. ${kind}  ${originBadge(r)}${r?.path ?? r?.name ?? ""}${score}`);
+        console.log(`  ${String(i + 1).padStart(2)}. ${kind}  ${noteMark(r)}${originBadge(r)}${r?.path ?? r?.name ?? ""}${score}`);
+        const note = noteLine(r);
+        if (note)
+            console.log(`      ${DIM}${note}${RESET}`);
         const meta = directoryFileMeta(r);
         if (meta)
             console.log(`      ${DIM}${meta}${RESET}`);
@@ -11703,6 +11796,14 @@ async function runGetFileCommand(argv) {
 // Content can come from a local file (positional), inline --content, or piped stdin.
 // It is the write counterpart to `files`/`get-file` and the same store the /editor
 // AI copilot writes to via the browse_files write action.
+//
+// TRANSPORT: presign → PUT direct to S3 → finalize, exactly like `upload` and
+// `approve --video`. The multipart POST to /me/attachments/upload is only a
+// FALLBACK (local-storage `vidfarm serve` boxes, or an older server with no
+// presign route) because that path proxies the bytes through the API Lambda,
+// whose request body caps near 6 MB — a 9 MB multipart POST answers 413 before
+// the handler runs. The presigned PUT never touches Lambda, so it carries the
+// full 200 MB My Files ceiling.
 async function runPutFileCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -11746,24 +11847,90 @@ async function runPutFileCommand(argv) {
         throw new Error("put-file could not determine a file name. Pass --as <name>.");
     const contentType = guessContentType(fileName);
     const uploadPath = "/api/v1/user/me/attachments/upload";
+    const presignPath = "/api/v1/user/me/attachments/presign";
+    const finalizePath = "/api/v1/user/me/attachments";
+    const folder = parsed.values.folder ? String(parsed.values.folder) : undefined;
+    const notes = parsed.values.notes ? String(parsed.values.notes) : undefined;
     for (const space of targetSpaces(ctx.target)) {
+        // One request shape for both spaces: the local backend answers in-process,
+        // the cloud over HTTP. The presigned PUT itself always goes over the wire.
+        const call = async (apiPath, init) => {
+            if (space === "local") {
+                const { withLocalBackend } = await import("./devcli/local-backend.js");
+                const backend = await withLocalBackend({ home: ctx.home, apiKey: ctx.auth.apiKey });
+                return backend.app.request(apiPath, init);
+            }
+            return fetch(new URL(apiPath, ctx.host), init);
+        };
+        // Step 1: presign. An S3-backed box answers transport:"presigned".
+        let presignJson = null;
+        let presignStatus = 0;
+        try {
+            const presign = await call(presignPath, {
+                method: "POST",
+                headers: { ...buildAuthHeaders(ctx.auth), "content-type": "application/json" },
+                body: JSON.stringify({ file_name: fileName, content_type: contentType, size_bytes: buffer.byteLength, folder_path: folder })
+            });
+            presignStatus = presign.status;
+            presignJson = await presign.json().catch(() => null);
+            if (!presign.ok)
+                presignJson = null;
+        }
+        catch {
+            presignJson = null;
+        }
+        if (presignJson?.transport === "presigned" && presignJson?.upload?.url) {
+            // Step 2a: bytes go straight to storage — no Lambda body limit.
+            const put = await fetch(presignJson.upload.url, {
+                method: presignJson.upload.method || "PUT",
+                headers: presignJson.upload.headers || {},
+                body: new Uint8Array(buffer)
+            });
+            if (!put.ok)
+                throw new Error(`put-file (${space}): storage PUT failed with HTTP ${put.status}.`);
+            // Step 3: finalize — record the attachment now that the bytes landed.
+            const finalize = await call(finalizePath, {
+                method: "POST",
+                headers: { ...buildAuthHeaders(ctx.auth), "content-type": "application/json" },
+                body: JSON.stringify({
+                    attachment_id: presignJson.attachment_id,
+                    file_name: presignJson.file_name || fileName,
+                    content_type: presignJson.content_type || contentType,
+                    size_bytes: buffer.byteLength,
+                    storage_key: presignJson.storage_key,
+                    folder_path: presignJson.folder_path,
+                    notes
+                })
+            });
+            const finalizeText = await finalize.text();
+            let finalizeJson = null;
+            try {
+                finalizeJson = finalizeText ? JSON.parse(finalizeText) : null;
+            }
+            catch {
+                finalizeJson = null;
+            }
+            const finalizeResult = { status: finalize.status, ok: finalize.ok, json: finalizeJson, text: finalizeText };
+            assertApiOk(finalizeResult, `put-file finalize (${space})`);
+            emitResult(finalizeResult, ctx.json, [[`My Files [${space}]`, finalizeResult.json?.attachment?.viewUrl]]);
+            continue;
+        }
+        // Step 2b (fallback): no presigned transport (local storage driver) or no
+        // presign route at all. Multipart through the API — capped near 6 MB in the
+        // cloud, so refuse a big file here instead of eating a confusing 413.
+        if (space !== "local" && buffer.byteLength > 6 * 1024 * 1024) {
+            throw new Error(`put-file (${space}): presign unavailable (HTTP ${presignStatus || 0}) and ${formatBytes(buffer.byteLength)} exceeds the ~6 MB multipart limit. ` +
+                `Upgrade the server or retry when /me/attachments/presign is reachable.`);
+        }
         // FormData is single-use (its stream is consumed), so build a fresh one per
         // space when writing to both.
         const form = new FormData();
         form.append("file", new Blob([new Uint8Array(buffer)], contentType ? { type: contentType } : undefined), fileName);
-        if (parsed.values.folder)
-            form.append("folder_path", String(parsed.values.folder));
-        if (parsed.values.notes)
-            form.append("notes", String(parsed.values.notes));
-        let res;
-        if (space === "local") {
-            const { withLocalBackend } = await import("./devcli/local-backend.js");
-            const backend = await withLocalBackend({ home: ctx.home, apiKey: ctx.auth.apiKey });
-            res = await backend.app.request(uploadPath, { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
-        }
-        else {
-            res = await fetch(new URL(uploadPath, ctx.host), { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
-        }
+        if (folder)
+            form.append("folder_path", folder);
+        if (notes)
+            form.append("notes", notes);
+        const res = await call(uploadPath, { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
         const text = await res.text();
         let json = null;
         try {

package/dist/src/devcli/marketplace-gigs.js

@@ -215,10 +215,50 @@ async function listMachines(auth) {
             title: String(gig.title ?? gig.id ?? ""),
             gigId: String(gig.id ?? ""),
             distribution: gig.distribution ? String(gig.distribution) : undefined,
-            inviteUrl: typeof gig.invite_url === "string" ? gig.invite_url : null
+            // NOT the gig record's `invite_url` — that one carries no `?invite=`
+            // token, and an invite-only gig refuses a tokenless join. See
+            // resolveInviteUrl(): the real link lives on the invite itself.
+            inviteUrl: null
         };
     }).filter((m) => m.gigId);
 }
+/** True only for a join URL that carries an `?invite=` token. */
+function hasInviteToken(url) {
+    if (typeof url !== "string" || !url)
+        return false;
+    try {
+        return Boolean(new URL(url).searchParams.get("invite"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The machine's REUSABLE, tokened join link — the only link a gigworker can
+ * actually join through, and therefore the only valid `destination_url` for a
+ * bell. Reads the gig's invites (each gig ships an unlimited "default" one) and
+ * mints a fresh unlimited invite when none survives.
+ */
+async function resolveInviteUrl(auth, gigId) {
+    const pick = (invite) => {
+        if (hasInviteToken(invite?.invite_url))
+            return invite.invite_url;
+        if (invite?.token)
+            return `https://dollarplatoon.com/gig/${encodeURIComponent(gigId)}/join?invite=${encodeURIComponent(String(invite.token))}`;
+        return "";
+    };
+    const listed = await dp(auth, `/gigs/${gigId}/invites`).catch(() => ({}));
+    const invites = Array.isArray(listed.invites) ? listed.invites : [];
+    const reusable = invites.filter((i) => !i.revoked && !i.exhausted && !i.email && (i.max_uses === null || i.max_uses === undefined));
+    const chosen = reusable.find((i) => i.label === "default") ?? reusable[0];
+    if (chosen && pick(chosen))
+        return pick(chosen);
+    const minted = await dp(auth, `/gigs/${gigId}/invites`, {
+        method: "POST",
+        body: { max_uses: null, label: "vidfarm" }
+    }).catch(() => ({}));
+    return minted.invite ? pick(minted.invite) : "";
+}
 /** A gig id, a machine slug, or (default) the machine this command is about. */
 async function resolveGigId(auth, raw, fallbackSlug) {
     const value = (raw ?? "").trim();
@@ -258,9 +298,14 @@ function proofLink(proof) {
 // ── client commands ──────────────────────────────────────────────────────────
 async function cmdMachines(auth, values) {
     const machines = await listMachines(auth);
+    // Each machine's shareable link is its reusable INVITE, not the tokenless
+    // join URL the gig record carries — hand this one to a gigworker.
+    await Promise.all(machines.map(async (machine) => {
+        machine.inviteUrl = (await resolveInviteUrl(auth, machine.gigId).catch(() => "")) || null;
+    }));
     out(Boolean(values.json), { machines }, () => {
         if (!machines.length) {
-            console.log(`${DIM}No vending machines on this key yet. A paid vidfarm account gets two; open ${RESET}https://vidfarm.cc/marketplace/buyer${DIM} once to create them.${RESET}`);
+            console.log(`${DIM}No vending machines on this key yet. A paid vidfarm account gets two; open ${RESET}https://vidfarm.cc/marketplace${DIM} once to create them.${RESET}`);
             return;
         }
         for (const machine of machines) {
@@ -403,17 +448,20 @@ async function cmdRingBell(auth, values) {
     const machine = machines.find((m) => m.slug === slug);
     if (!machine)
         throw new Error(`No "${slug}" machine on this account. Run: vidfarm gigs machines`);
-    let destination = machine.inviteUrl ?? "";
-    if (!destination) {
-        // Registering the gig in the feed returns its reusable join link.
+    // The bell is only as good as its link: an agent that taps a tokenless
+    // ".../join" URL is refused at the door, so the destination is always the
+    // machine's reusable INVITE link.
+    let destination = await resolveInviteUrl(auth, machine.gigId);
+    if (!hasInviteToken(destination)) {
+        // Registering the gig in the feed returns its reusable join link too.
         const registered = await dp(auth, `/feeds/${VIDFARM_FEED_ID}/registry`, {
             method: "POST",
             body: { gig_id: machine.gigId, tags: ["vidfarm", "video", slug] }
         }).catch(() => ({}));
-        destination = registered.invite_url ?? "";
+        destination = hasInviteToken(registered.invite_url) ? registered.invite_url : "";
     }
     if (!destination)
-        throw new Error("That machine has no invite link yet — open it once on vidfarm.cc/marketplace/buyer.");
+        throw new Error("That machine has no invite link yet — open it once on vidfarm.cc/marketplace.");
     const result = await dp(auth, `/feeds/${VIDFARM_FEED_ID}/notifications`, {
         method: "POST",
         body: {

package/dist/src/devcli/qa-check.js

@@ -655,7 +655,7 @@ export function qaCompositionHtml(html) {
                     ? `Text layer in "${family}" — a website body font. This alone makes a frame read as a screenshot of a web page.`
                     : `Text layer in "${family}", outside the composition's imported font regime — it will silently fall back at render.`,
                 where: label(node, "text layer"),
-                fix: `Use an imported display family: Montserrat (default), TikTok Sans, Abel, Source Code Pro, or Yesteryear — e.g. \`vidfarm set-style <dir> --layer <key> --font-family Montserrat\`. Local renders auto-coerce this, but the editor preview will not match until you fix it.`
+                fix: `Use an imported display family: Montserrat (default), TikTok Sans, Abel, Source Code Pro, or Yesteryear — e.g. \`vidfarm set-style <dir> --layer <key> --font-family Montserrat\`. Local renders auto-coerce this, but the editor preview will not match until you fix it. The five families, each rendered as a real caption: https://vidfarm.cc/fonts`
             });
         }
         // Weight: the TikTok caption look is heavy. Light weights are a legitimate