@officexapp/vidfarm-devcli 0.21.52 → 0.21.53

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

@@ -305,7 +305,7 @@ async function cmdMachines(auth, values) {
     }));
     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) {
@@ -461,7 +461,7 @@ async function cmdRingBell(auth, values) {
         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

package/dist/src/devcli/shared-folder.js

@@ -31,30 +31,53 @@ const GREEN = "\x1b[32m";
 const RESET = "\x1b[0m";
 export const SHARED_HELP = `vidfarm shared — use a folder someone shared with you (no account, no API key)
 
+  THE FAST PATH for a gigworker's agent: one command finds the footage by meaning
+  and puts it on disk.
+
+    vidfarm shared grab <link> "founder talking head, kitchen, no captions" --out ./assets
+
   shared info <link>               What the link is: folder, mode, what you may do
   shared ls <link> [subfolder]     Browse the shared folder                      → GET  /api/v1/share/:token/directory
+    --tree                         Walk every subfolder, not just this one
     --limit <n> --offset <n> --json
-  shared search <link> "<query>"   Find files by MEANING inside the share        → POST /api/v1/share/:token/directory/search
-    --subfolder <name> --limit <n> --json
+  shared search <link> "<query>"   Find files AND folders by MEANING             → POST /api/v1/share/:token/directory/search
+    --subfolder <name>             Search inside one subfolder only
+    --limit <n> --json
+  shared grab <link> "<query>"     Search by meaning, then DOWNLOAD the hits     → search + download
+    --limit <n>                    How many to take (default 5)
+    --out <dir>                    Where to write them (default ./)
+    --json
+  shared note <link> <file|folder> Read the VECTOR NOTE — what the thing is      → GET  /api/v1/share/:token/directory/note
+    --set "<text>"                 Write it (upload links may FILL an empty note;
+                                   only edit links / the owner may overwrite one)
+    --subfolder <name> --json
   shared mkdir <link> <subfolder>  Make a subfolder (upload/edit links only)     → POST /api/v1/share/:token/directory/folders
   shared put <link> <file…>        Upload files into the share (upload/edit)     → presign → PUT → finalize
     --subfolder <name>             Land them in a subfolder of the shared folder
+    --note "<text>"                Describe what you uploaded (vector-searchable)
     --json
-  shared get <link> <file-name>    Download one file out of the share
+  shared get <link> <name|path>    Download one file out of the share
     --subfolder <name>             Look inside a subfolder
     --out <dir|file>               Where to write it (default: this folder)
     --all                          Download every file in the folder instead
+    --tree                         With --all: walk subfolders too
 
   <link> is the URL you were given, or just the dsh_… token (then --host <url>).
 
   e.g. vidfarm shared info https://vidfarm.cc/directory/preview/dsh_abc/files/project1
-       vidfarm shared mkdir <link> yvette-batch-01
-       vidfarm shared put <link> clip-01.mp4 clip-02.mp4 --subfolder yvette-batch-01
-       vidfarm shared search <link> "founder talking head, no captions"
-       vidfarm shared get <link> brief.md --out ./work
+       vidfarm shared ls <link> --tree
+       vidfarm shared grab <link> "product close-up on a white desk" --limit 3 --out ./b-roll
+       vidfarm shared note <link> clip-01.mp4
+       vidfarm shared put <link> cut-v2.mp4 --subfolder yvette-batch-01 --note "Final cut, 9:16, captions burned in"
 
   Modes: read = browse + search · upload = + add files and subfolders (never delete)
-         edit = + rename and delete. Only /files and /temp shares accept uploads.`;
+         edit = + rename and delete. /files, /temp and /raws shares accept uploads;
+         a /raws share is a drop-box for footage. /projects and /approved are read-only.
+
+  VECTOR NOTES: every file and folder carries a plain-text note saying what it IS.
+  That note is what \`search\` and \`grab\` match on, so a folder full of IMG_4821.mp4
+  is only as findable as its notes. Read them before you pick; write one when you
+  upload, so the next agent can find your work.`;
 // Accepts a preview URL, an API URL, or a bare token. The trailing path of a
 // preview URL is kept as the default subfolder so a task brief can point at the
 // exact folder the worker should use.
@@ -125,6 +148,17 @@ async function sharePost(link, route, payload) {
         fail(`share ${route}`, response.status, body);
     return body;
 }
+async function sharePut(link, route, payload) {
+    const response = await fetch(apiBase(link) + route, {
+        method: "PUT",
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify(payload)
+    });
+    const body = await readJson(response);
+    if (!response.ok)
+        fail(`share ${route}`, response.status, body);
+    return body;
+}
 // The path a command works on: the link's own folder, plus an optional
 // --subfolder. Never an absolute path — a token cannot leave its own subtree.
 function targetPath(link, basePath, subfolder) {
@@ -144,6 +178,71 @@ async function loadShare(link, subfolder) {
     const listing = await shareGet(link, "/directory", { path: wanted });
     return { listing, basePath, path: wanted };
 }
+// Walk the share depth-first and return every folder + file under `startPath`.
+// A share is a small working folder, so a bounded full walk is cheaper for the
+// agent than N round-trips of guessing folder names.
+const SHARE_WALK_MAX_FOLDERS = 200;
+async function walkShare(link, startPath) {
+    const folders = [];
+    const files = [];
+    const queue = [startPath];
+    const seen = new Set();
+    while (queue.length && seen.size < SHARE_WALK_MAX_FOLDERS) {
+        const current = queue.shift();
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        const listing = await shareGet(link, "/directory", { path: current, limit: "500" });
+        for (const file of listing.files ?? [])
+            files.push(file);
+        for (const folder of listing.folders ?? []) {
+            folders.push(folder);
+            if (folder.path)
+                queue.push(folder.path);
+        }
+    }
+    return { folders, files };
+}
+/** One-line note preview for list output. */
+function noteLine(item) {
+    const note = typeof item?.note === "string" ? item.note.replace(/\s+/g, " ").trim() : "";
+    if (!note)
+        return "";
+    return note.length > 100 ? note.slice(0, 99) + "…" : note;
+}
+/** The "does this have a note?" marker, so a gap is visible at a glance. */
+function noteMark(item) {
+    if (item?.note === undefined)
+        return "  "; // backend carries no note
+    return item.note ? `${GREEN}✓${RESET} ` : `${DIM}✎${RESET} `;
+}
+function fileSize(item) {
+    return typeof item?.sizeBytes === "number" && item.sizeBytes > 0
+        ? `${(item.sizeBytes / (1024 * 1024)).toFixed(1)} MB`
+        : "";
+}
+/**
+ * Find one entry in the share by exact path, by file name, or by a name
+ * fragment — looking in the current folder first, then the whole subtree. This
+ * is what lets an agent act on a name it read out of a search result.
+ */
+async function resolveShareEntry(link, basePath, wanted, subfolder) {
+    const target = (wanted || "").trim();
+    if (!target)
+        throw new Error("Name a file or folder from the share.");
+    const here = targetPath(link, basePath, subfolder);
+    const local = await shareGet(link, "/directory", { path: here, limit: "500" });
+    const pools = [...(local.files ?? []), ...(local.folders ?? [])];
+    const exact = pools.find((it) => it.path === target || it.name === target);
+    if (exact)
+        return exact;
+    const walked = await walkShare(link, here);
+    const all = [...walked.files, ...walked.folders];
+    return (all.find((it) => it.path === target)
+        ?? all.find((it) => it.name === target)
+        ?? all.find((it) => String(it.name ?? "").toLowerCase().includes(target.toLowerCase()))
+        ?? (() => { throw new Error(`Nothing named "${target}" in ${here}. Browse it with: vidfarm shared ls <link> --tree`); })());
+}
 // ── commands ─────────────────────────────────────────────────────────────────
 function options() {
     return {
@@ -154,15 +253,19 @@ function options() {
         out: { type: "string" },
         limit: { type: "string" },
         offset: { type: "string" },
-        all: { type: "boolean" }
+        all: { type: "boolean" },
+        tree: { type: "boolean" },
+        set: { type: "string" },
+        note: { type: "string" },
+        "file-id": { type: "string" }
     };
 }
 function modeVerbs(mode) {
     if (mode === "edit")
-        return "browse · search · upload · make folders · rename · delete";
+        return "browse · search · upload · make folders · rename · delete · write any note";
     if (mode === "upload")
-        return "browse · search · upload · make folders (no delete)";
-    return "browse · search (read only)";
+        return "browse · search · upload · make folders · fill an EMPTY note (no delete, no overwrite)";
+    return "browse · search · read notes (read only)";
 }
 async function runInfo(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: options() });
@@ -177,6 +280,11 @@ async function runInfo(argv) {
     console.log(`  folder : ${basePath}`);
     console.log(`  mode   : ${mode} ${DIM}(${modeVerbs(mode)})${RESET}`);
     console.log(`  files  : ${(listing.files ?? []).length}   folders: ${(listing.folders ?? []).length}`);
+    const noted = (listing.files ?? []).filter((f) => f?.note).length;
+    const notable = (listing.files ?? []).filter((f) => f?.note !== undefined).length;
+    if (notable)
+        console.log(`  notes  : ${noted}/${notable} files described ${DIM}(search matches on these)${RESET}`);
+    console.log(`  ${DIM}Find footage by meaning : vidfarm shared grab <link> "<what you need>" --out ./assets${RESET}`);
     if (mode !== "read") {
         console.log(`  ${DIM}Make your own subfolder first: vidfarm shared mkdir <link> <your-name>${RESET}`);
     }
@@ -186,19 +294,42 @@ async function runLs(argv) {
     const link = parseSharedLink(parsed.positionals[0], parsed.values.host);
     const subfolder = parsed.values.subfolder ?? parsed.positionals[1];
     const { listing, path: shownPath } = await loadShare(link, subfolder);
+    const walked = parsed.values.tree ? await walkShare(link, shownPath) : null;
+    const folders = walked ? walked.folders : (listing.folders ?? []);
+    const files = walked ? walked.files : (listing.files ?? []);
     if (parsed.values.json) {
-        console.log(JSON.stringify(listing, null, 2));
+        console.log(JSON.stringify(walked ? { path: shownPath, share: listing.share, ...walked } : listing, null, 2));
         return;
     }
     console.log(`${BOLD}${shownPath}${RESET} ${DIM}(${listing.share?.mode ?? "read"} link)${RESET}`);
-    for (const folder of listing.folders ?? [])
-        console.log(`  ${BOLD}${folder.name}/${RESET}`);
-    for (const file of listing.files ?? []) {
-        const size = typeof file.sizeBytes === "number" ? `${(file.sizeBytes / (1024 * 1024)).toFixed(1)} MB` : "";
-        console.log(`  ${file.name}  ${DIM}${size}${RESET}`);
+    for (const folder of folders) {
+        console.log(`  ${noteMark(folder)}${BOLD}${walked ? folder.path : folder.name + "/"}${RESET}`);
+        const note = noteLine(folder);
+        if (note)
+            console.log(`      ${DIM}${note}${RESET}`);
     }
-    if (!(listing.folders ?? []).length && !(listing.files ?? []).length)
+    for (const file of files) {
+        const size = fileSize(file);
+        console.log(`  ${noteMark(file)}${walked ? file.path : file.name}  ${DIM}${size}${RESET}`);
+        const note = noteLine(file);
+        if (note)
+            console.log(`      ${DIM}${note}${RESET}`);
+    }
+    if (!folders.length && !files.length)
         console.log(`  ${DIM}empty${RESET}`);
+    else
+        console.log(`\n  ${DIM}${GREEN}✓${DIM} = has a vector note · ✎ = no note yet (read one with: vidfarm shared note <link> <name>)${RESET}`);
+}
+// Search the share by MEANING. Returns files AND folders — a well-noted folder
+// is a legitimate hit ("all the kitchen b-roll is in here").
+async function searchShare(link, argv) {
+    const scope = targetPath(link, argv.basePath, argv.subfolder);
+    const body = await sharePost(link, "/directory/search", {
+        query: argv.query,
+        path: scope,
+        ...(argv.limit != null && Number.isFinite(argv.limit) ? { limit: argv.limit } : {})
+    });
+    return { scope, body, results: body.results ?? body.items ?? [] };
 }
 async function runSearch(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: options() });
@@ -207,25 +338,112 @@ async function runSearch(argv) {
     if (!query)
         throw new Error('shared search needs a query: vidfarm shared search <link> "founder talking head"');
     const { basePath } = await loadShare(link);
-    const scope = targetPath(link, basePath, parsed.values.subfolder);
-    const limit = parsed.values.limit != null ? Number(parsed.values.limit) : undefined;
-    const body = await sharePost(link, "/directory/search", {
+    const { scope, body, results } = await searchShare(link, {
         query,
-        path: scope,
-        ...(limit != null && Number.isFinite(limit) ? { limit } : {})
+        basePath,
+        subfolder: parsed.values.subfolder,
+        limit: parsed.values.limit != null ? Number(parsed.values.limit) : undefined
     });
     if (parsed.values.json) {
         console.log(JSON.stringify(body, null, 2));
         return;
     }
-    const results = body.results ?? body.items ?? [];
+    const how = body.semantic === true ? "by meaning" : "keyword/path only (the owner has no embedding key)";
+    console.log(`${BOLD}"${query}"${RESET} ${DIM}in ${scope} · ${how}${RESET}  →  ${results.length} result(s)\n`);
     if (!results.length) {
-        console.log(`${DIM}No matches in ${scope}.${RESET}`);
+        console.log(`  ${DIM}No matches. Try \`vidfarm shared ls <link> --tree\` to see everything.${RESET}`);
+        return;
+    }
+    results.forEach((hit, i) => {
+        const score = typeof hit.score === "number" ? ` ${DIM}score=${hit.score.toFixed(3)}${RESET}` : "";
+        const kind = hit.kind === "folder" ? "dir " : "file";
+        console.log(`  ${String(i + 1).padStart(2)}. ${kind} ${noteMark(hit)}${hit.path ?? hit.name}${score}`);
+        const note = noteLine(hit);
+        if (note)
+            console.log(`      ${DIM}${note}${RESET}`);
+        const size = fileSize(hit);
+        if (size)
+            console.log(`      ${DIM}${size}${RESET}`);
+    });
+    console.log(`\n  ${DIM}Take them: vidfarm shared grab <link> "${query}" --out ./assets${RESET}`);
+}
+// search + download, in one command. This is the command a gigworker's agent
+// actually runs: "give me the footage that looks like X".
+async function runGrab(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: options() });
+    const link = parseSharedLink(parsed.positionals[0], parsed.values.host);
+    const query = parsed.positionals.slice(1).join(" ").trim();
+    if (!query)
+        throw new Error('shared grab needs a query: vidfarm shared grab <link> "kitchen b-roll" --out ./assets');
+    const limit = parsed.values.limit != null ? Number(parsed.values.limit) : 5;
+    const out = parsed.values.out || ".";
+    const { basePath } = await loadShare(link);
+    const { scope, results } = await searchShare(link, {
+        query,
+        basePath,
+        subfolder: parsed.values.subfolder,
+        limit: Number.isFinite(limit) ? limit : 5
+    });
+    const downloadable = results.filter((hit) => hit.kind !== "folder" && hit.viewUrl);
+    if (!downloadable.length) {
+        const folders = results.filter((hit) => hit.kind === "folder");
+        if (folders.length) {
+            console.log(`${DIM}Only folders matched. Look inside one: vidfarm shared ls <link> ${folders[0].path}${RESET}`);
+        }
+        else {
+            console.log(`${DIM}Nothing to download for "${query}" in ${scope}.${RESET}`);
+        }
         return;
     }
-    for (const hit of results) {
-        console.log(`  ${hit.name ?? hit.path}  ${DIM}${hit.path ?? ""}${RESET}`);
+    const taken = [];
+    for (const hit of downloadable) {
+        const dest = path.join(out, hit.name);
+        await downloadTo(hit.viewUrl, dest, link);
+        taken.push({ path: hit.path, name: hit.name, note: hit.note ?? null, file: dest, score: hit.score });
+        if (!parsed.values.json) {
+            console.log(`${GREEN}✓${RESET} ${dest}  ${DIM}${hit.path}${RESET}`);
+            const note = noteLine(hit);
+            if (note)
+                console.log(`    ${DIM}${note}${RESET}`);
+        }
     }
+    if (parsed.values.json)
+        console.log(JSON.stringify({ ok: true, query, scope, taken }, null, 2));
+    else
+        console.log(`\n  ${DIM}${taken.length} file(s) for "${query}"${RESET}`);
+}
+// Read or write the vector note of one entry in the share.
+async function runNote(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: options() });
+    const link = parseSharedLink(parsed.positionals[0], parsed.values.host);
+    const wanted = parsed.positionals.slice(1).join(" ").trim();
+    const { listing, basePath } = await loadShare(link);
+    const mode = listing.share?.mode ?? "read";
+    const entry = await resolveShareEntry(link, basePath, wanted, parsed.values.subfolder);
+    const setValue = parsed.values.set;
+    if (setValue == null) {
+        const body = await shareGet(link, "/directory/note", { path: entry.path, id: entry.id });
+        if (parsed.values.json) {
+            console.log(JSON.stringify(body, null, 2));
+            return;
+        }
+        console.log(`${BOLD}${entry.path}${RESET}`);
+        console.log(body.note ? `  ${body.note}` : `  ${DIM}(no vector note yet)${RESET}`);
+        if (body.can_edit)
+            console.log(`  ${DIM}Write one: vidfarm shared note <link> ${entry.name} --set "what this is"${RESET}`);
+        else if (mode === "upload")
+            console.log(`  ${DIM}This note is already written — an upload link may only fill an EMPTY note.${RESET}`);
+        return;
+    }
+    const body = await sharePut(link, "/directory/note", { path: entry.path, id: entry.id ?? null, note: setValue });
+    if (parsed.values.json) {
+        console.log(JSON.stringify(body, null, 2));
+        return;
+    }
+    console.log(`${GREEN}✓${RESET} note saved on ${BOLD}${entry.path}${RESET}`);
+    console.log(body.embedded
+        ? `  ${DIM}searchable by meaning${RESET}`
+        : `  ${DIM}saved, but keyword-search only — the folder's owner has no embedding key saved${RESET}`);
 }
 async function runMkdir(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: options() });
@@ -309,52 +527,118 @@ async function runPut(argv) {
     // The API wants the folder RELATIVE to the root (no /files prefix).
     const wanted = targetPath(link, basePath, subfolder);
     const folderPath = wanted.replace(/^\/(files|temp|raws|approved|projects)\/?/, "");
+    const note = parsed.values.note?.trim();
     const saved = [];
     for (const file of files) {
         const record = await uploadOne(link, file, folderPath);
         saved.push(record);
         if (!parsed.values.json)
             console.log(`${GREEN}✓${RESET} ${path.basename(file)} → ${BOLD}${wanted}${RESET}`);
+        // Say what you uploaded, so the next agent can find it by meaning. An
+        // upload link may fill an empty note, which a fresh upload always has —
+        // unless the server already auto-described it on the owner's AI key.
+        if (note) {
+            const uploadedPath = `${wanted.replace(/\/+$/, "")}/${record?.fileName ?? path.basename(file)}`;
+            await sharePut(link, "/directory/note", { path: uploadedPath, id: record?.id ?? null, note })
+                .then(() => { if (!parsed.values.json)
+                console.log(`    ${DIM}note saved${RESET}`); })
+                .catch((error) => {
+                if (!parsed.values.json)
+                    console.log(`    ${DIM}note not saved: ${error.message}${RESET}`);
+            });
+        }
     }
     if (parsed.values.json)
         console.log(JSON.stringify({ ok: true, uploaded: saved }, null, 2));
+    else if (!note) {
+        console.log(`\n  ${DIM}Tip: add --note "what this is" so the owner's agent can find it by meaning.${RESET}`);
+    }
 }
-async function downloadTo(url, outPath) {
-    const response = await fetch(url);
-    if (!response.ok)
-        throw new Error(`download failed: HTTP ${response.status}`);
-    const bytes = Buffer.from(await response.arrayBuffer());
-    mkdirSync(path.dirname(outPath), { recursive: true });
-    writeFileSync(outPath, bytes);
+// Fetch one file out of the share. A stored view URL is not always reachable as
+// written: it may be relative, or absolute against the host the owner's server
+// had configured when the file was saved (a self-hosted box, a moved domain).
+// The link we were handed is the host we KNOW answers, so fall back to it,
+// keeping the URL's own path.
+async function downloadTo(url, outPath, link) {
+    const candidates = [];
+    if (/^https?:\/\//i.test(url)) {
+        candidates.push(url);
+        if (link) {
+            try {
+                const parsed = new URL(url);
+                const viaLink = link.host + parsed.pathname + parsed.search;
+                if (viaLink !== url)
+                    candidates.push(viaLink);
+            }
+            catch { /* unparseable — the direct attempt is all we have */ }
+        }
+    }
+    else if (link) {
+        candidates.push(link.host + (url.startsWith("/") ? url : `/${url}`));
+    }
+    else {
+        candidates.push(url);
+    }
+    let lastError = "";
+    for (const candidate of candidates) {
+        try {
+            const response = await fetch(candidate);
+            if (!response.ok) {
+                lastError = `HTTP ${response.status}`;
+                continue;
+            }
+            const bytes = Buffer.from(await response.arrayBuffer());
+            mkdirSync(path.dirname(outPath), { recursive: true });
+            writeFileSync(outPath, bytes);
+            return;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+    }
+    throw new Error(`download failed (${lastError}): ${url}`);
 }
 async function runGet(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: options() });
     const link = parseSharedLink(parsed.positionals[0], parsed.values.host);
     const wantedName = parsed.positionals[1];
-    const { listing, path: shownPath } = await loadShare(link, parsed.values.subfolder);
-    const files = listing.files ?? [];
+    const { listing, basePath, path: shownPath } = await loadShare(link, parsed.values.subfolder);
     const out = parsed.values.out || ".";
     if (parsed.values.all || !wantedName) {
         if (!parsed.values.all)
             throw new Error("shared get needs a file name, or --all to take the whole folder.");
+        // --tree takes the whole subtree, mirroring the folder layout on disk so a
+        // deep share doesn't collapse into one flat directory of colliding names.
+        const files = parsed.values.tree ? (await walkShare(link, shownPath)).files : (listing.files ?? []);
+        let taken = 0;
         for (const file of files) {
             if (!file.viewUrl)
                 continue;
-            const dest = path.join(out, file.name);
-            await downloadTo(file.viewUrl, dest);
+            const relative = parsed.values.tree && typeof file.path === "string" && file.path.startsWith(shownPath)
+                ? file.path.slice(shownPath.length).replace(/^\/+/, "")
+                : file.name;
+            const dest = path.join(out, relative);
+            await downloadTo(file.viewUrl, dest, link);
+            taken += 1;
             console.log(`${GREEN}✓${RESET} ${dest}`);
         }
-        console.log(`${DIM}${files.length} file(s) from ${shownPath}${RESET}`);
+        console.log(`${DIM}${taken} file(s) from ${shownPath}${RESET}`);
         return;
     }
-    const match = files.find((f) => f.name === wantedName) || files.find((f) => String(f.name).includes(wantedName));
-    if (!match)
-        throw new Error(`No file named "${wantedName}" in ${shownPath}.`);
+    // Accepts a bare name, a name fragment, or the full canonical path a search
+    // result printed — an agent should never have to translate between them.
+    const match = await resolveShareEntry(link, basePath, wantedName, parsed.values.subfolder);
+    if (match.kind === "folder") {
+        throw new Error(`"${match.path}" is a folder. Take it with: vidfarm shared get <link> --all --tree --subfolder ${match.name}`);
+    }
     if (!match.viewUrl)
         throw new Error(`"${match.name}" has no downloadable URL.`);
     const dest = /\.[A-Za-z0-9]+$/.test(out) ? out : path.join(out, match.name);
-    await downloadTo(match.viewUrl, dest);
+    await downloadTo(match.viewUrl, dest, link);
     console.log(`${GREEN}✓${RESET} ${dest}`);
+    const note = noteLine(match);
+    if (note)
+        console.log(`  ${DIM}${note}${RESET}`);
 }
 export async function runSharedCommand(argv) {
     const sub = argv[0];
@@ -366,6 +650,11 @@ export async function runSharedCommand(argv) {
         case "list": return runLs(rest);
         case "search":
         case "find": return runSearch(rest);
+        case "grab":
+        case "fetch": return runGrab(rest);
+        case "note":
+        case "notes": return runNote(rest);
+        case "tree": return runLs([...rest, "--tree"]);
         case "mkdir":
         case "folder": return runMkdir(rest);
         case "put":

package/dist/src/devcli/skill-docs.js

@@ -117,8 +117,8 @@ export const PACK_TOPICS = [
         blurb: "The 5-stage ladder — what the viewer knows, what the video must do, and what it may ask for" },
     { topic: "problem-angles", aliases: ["angle", "lenses", "problem-angle"], doc: "references/content-ideas.md", heading: "The problem angles",
         blurb: "44 angles on the problem — hold the frame, change the angle when a topic is \"already covered\"" },
-    { topic: "meme-recaption", aliases: ["meme", "recaption", "meme-caption"], doc: "references/editor-workflows.md", heading: "Writing a meme recaption",
-        blurb: "Recaption a meme at a pain or a win the niche knows — the cold-viewer test" },
+    { topic: "meme-recaption", aliases: ["meme", "recaption", "meme-caption", "meme_recaption"], doc: "references/editor-workflows.md", heading: "Writing a meme recaption",
+        blurb: "Recaption a meme at a pain or a win the niche knows — the cold-viewer test. Building one from scratch? the full format is vidfarm.cc/experimental/meme-recaption.md" },
     { topic: "product-explainer", aliases: ["product-explainers"], doc: "harnesses/product-explainer.HARNESS.md",
         blurb: "The product-explainer harness — the bundled base for explaining what a product does" },
     { topic: "product-demo", aliases: ["demo"], doc: "harnesses/product-demo.HARNESS.md",