@vosjs/cli 0.61.0 → 0.63.0

package/dist/{chunk-C4P6MZJG.js → chunk-AKIPDSHE.js}

@@ -13,7 +13,6 @@ import {
 import {
   PREV_DOC_NAME,
   RECORDING_NAME,
-  docAudioRefs,
   docLayerRefs,
   docMediaRefs,
   dropScreencastFrames,
@@ -34,7 +33,7 @@ import {
   uploadDocRefs,
   uploadManifest,
   writeJson
-} from "./chunk-EZW6ZCEH.js";
+} from "./chunk-PT73CRXX.js";
 import {
   CREDENTIALS_PATH,
   MEDIA_HEAD_BYTES,
@@ -48,6 +47,7 @@ import {
   formatChanges,
   hasFlag,
   hostedAssetId,
+  localFile,
   manifestRefs,
   nameForType,
   numFlag2 as numFlag,
@@ -127,7 +127,7 @@ function landedLines(l) {
 
 // src/plugin/run.ts
 import { mkdir as mkdir9, readFile as readFile15, rm as rm3 } from "fs/promises";
-import { existsSync as existsSync23 } from "fs";
+import { existsSync as existsSync24 } from "fs";
 import { join as join26, resolve as resolve15 } from "path";
 import {
   END_CARD_FROM as END_CARD_FROM2,
@@ -146,6 +146,15 @@ function createReporter(json) {
     json,
     log: (msg) => {
       if (!json) process.stderr.write(`${msg}
+`);
+    },
+    warn: (msg) => {
+      if (json) {
+        process.stdout.write(
+          `${JSON.stringify({ event: "warning", message: msg })}
+`
+        );
+      } else process.stderr.write(`warning ${msg}
 `);
     },
     event: (obj) => {
@@ -2526,9 +2535,9 @@ function parsePath(path) {
       if (expectKey) bad();
       const j = path.indexOf("]", i);
       if (j < 0) bad();
-      const num = path.slice(i + 1, j);
-      if (!/^\d+$/.test(num)) bad();
-      segs.push({ key: Number(num) });
+      const num2 = path.slice(i + 1, j);
+      if (!/^\d+$/.test(num2)) bad();
+      segs.push({ key: Number(num2) });
       i = j + 1;
     } else {
       let j = i;
@@ -3911,11 +3920,11 @@ var DUPLICATE_BITS = 6;
 var POPULATED_INK = 0.12;
 function pickMoments(measured, opts = {}) {
   const minInk = opts.minInk ?? 0.06;
-  const relative3 = opts.relativeInk ?? 0.4;
+  const relative4 = opts.relativeInk ?? 0.4;
   const bits = opts.duplicateBits ?? DUPLICATE_BITS;
   const inks = measured.map((m) => m.ink).sort((a, b) => a - b);
   const median2 = inks[inks.length >> 1] ?? 0;
-  const floor = Math.max(minInk, Math.min(POPULATED_INK, median2 * relative3));
+  const floor = Math.max(minInk, Math.min(POPULATED_INK, median2 * relative4));
   const kept = [];
   const dropped = [];
   for (const m of measured) {
@@ -7473,10 +7482,10 @@ async function pullTake(dir, flags, r) {
 }
 
 // src/plugin/program.ts
-import { existsSync as existsSync13 } from "fs";
+import { existsSync as existsSync14 } from "fs";
 import { mkdir as mkdir7, readFile as readFile13, writeFile as writeFile9 } from "fs/promises";
 import { createInterface as createInterface2 } from "readline/promises";
-import { basename as basename2, dirname as dirname3, join as join15 } from "path";
+import { basename as basename3, dirname as dirname3, join as join15 } from "path";
 import {
   CURRENT_CONFIG_VERSION,
   migrateConfig,
@@ -7608,6 +7617,112 @@ async function handoffLogin(url, r, opts = {}) {
   throw new Error(`${said}${hint}`);
 }
 
+// src/plugin/programFiles.ts
+import { basename as basename2, extname as extname2, relative as relative2 } from "path";
+import { existsSync as existsSync13, realpathSync } from "fs";
+function isLocalName(value) {
+  if (/^(https?:|data:|blob:|asset:|media:)/.test(value)) return false;
+  if (value.startsWith("$")) return false;
+  if (value.startsWith("/")) return existsSync13(value);
+  return true;
+}
+var FILE_EXT = /\.(png|jpe?g|webp|gif|avif|svg|mp4|webm|mov|mp3|m4a|ogg|wav|flac|aac|glb|gltf|woff2?|ttf|otf|hdr|exr)$/i;
+function manifestName(file, taken) {
+  const stem = basename2(file, extname2(file)).replace(/[^A-Za-z0-9_]/g, "_").replace(/^(?=[0-9])/, "_") || "file";
+  let name = stem;
+  for (let n = 2; taken.has(name); n++) name = `${stem}_${n}`;
+  taken.add(name);
+  return name;
+}
+function liftNamedFiles(config, dir) {
+  const manifest = config.assets ?? {};
+  const taken = new Set(Object.keys(manifest));
+  const lifted = [];
+  const lift = (where, value, kind) => {
+    if (typeof value !== "string" || !value || !isLocalName(value)) return null;
+    const found = localFile(value, dir);
+    if ("refused" in found) {
+      if (found.refused.startsWith("which is outside")) {
+        throw new Error(`${where} names ${value}, ${found.refused}`);
+      }
+      return null;
+    }
+    const name = manifestName(value, taken);
+    manifest[name] = kind ? { ref: value, kind } : { ref: value };
+    lifted.push(`${where} \u2192 assets.${name}`);
+    return `$assets.${name}`;
+  };
+  const elements = Array.isArray(config.elements) ? config.elements : [];
+  elements.forEach((el, i) => {
+    const e = el;
+    if (!e || e.type === "text") return;
+    const next = lift(`elements[${i}].src`, e.src);
+    if (next) e.src = next;
+  });
+  const fonts = Array.isArray(config.fonts) ? config.fonts : [];
+  fonts.forEach((f, i) => {
+    const font = f;
+    const next = lift(`fonts[${i}].url`, font?.url, "font");
+    if (next) font.url = next;
+  });
+  if (lifted.length) config.assets = manifest;
+  return lifted;
+}
+function localDataRefs(config, dir) {
+  const refs = [];
+  const root = realpathSync(dir);
+  const walk = (value, where, set) => {
+    if (typeof value === "string") {
+      if (!isLocalName(value) || !FILE_EXT.test(value)) return;
+      const found = localFile(value, dir);
+      if ("refused" in found) return;
+      refs.push({ where, key: relative2(root, found.file), set });
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach(
+        (v, i) => walk(v, `${where}[${i}]`, (next) => {
+          value[i] = next;
+        })
+      );
+      return;
+    }
+    if (value && typeof value === "object") {
+      const obj = value;
+      for (const k of Object.keys(obj)) {
+        walk(obj[k], `${where}.${k}`, (next) => {
+          obj[k] = next;
+        });
+      }
+    }
+  };
+  walk(config.data, "data", () => {
+  });
+  return refs;
+}
+var FUNCTION_FIELDS = ["setup", "createContent", "createTimeline", "onFrame"];
+var QUOTED = /(['"`])([^'"`\n]{1,200}?)\1/g;
+function codeFileWarnings(config, dir) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const scan = (label, src) => {
+    if (typeof src !== "string") return;
+    for (const m of src.matchAll(QUOTED)) {
+      const value = m[2];
+      if (seen.has(value) || !isLocalName(value) || !FILE_EXT.test(value)) {
+        continue;
+      }
+      if ("refused" in localFile(value, dir)) continue;
+      seen.add(value);
+      out.push(
+        `${label} names ${value} in code, which no push can carry. Declare it: "assets": { "name": { "ref": "${value}" } }, and read ctx.assets.name`
+      );
+    }
+  };
+  for (const field of FUNCTION_FIELDS) scan(field, config[field]);
+  return out;
+}
+
 // src/plugin/program.ts
 var BOOLEAN_FLAGS2 = /* @__PURE__ */ new Set([
   "json",
@@ -7616,6 +7731,7 @@ var BOOLEAN_FLAGS2 = /* @__PURE__ */ new Set([
   "check",
   "yes",
   "claimable",
+  "share",
   "no-browser",
   "wait"
 ]);
@@ -7683,7 +7799,7 @@ function preflightConfig(parsed) {
 function resolveConfigPath(target) {
   if (target.endsWith(".json")) return target;
   const inDir = join15(target, "config.json");
-  if (existsSync13(inDir)) return inDir;
+  if (existsSync14(inDir)) return inDir;
   throw new UsageError(
     `${target} has no config.json (and is not a take \u2014 no doc.json)`
   );
@@ -7833,6 +7949,7 @@ async function createProgramVos(opts) {
       client: clientId()
     };
     if (opts.description) body.description = opts.description;
+    if (opts.prompt) body.prompt = opts.prompt;
     if (opts.tags?.length) body.tags = opts.tags;
     if (opts.folderId) body.folderId = opts.folderId;
     if (opts.remixOfId) body.remixOfId = opts.remixOfId;
@@ -7867,7 +7984,7 @@ async function cmdPushProgram(argv) {
   const target = positionals[0];
   if (!target) {
     throw new UsageError(
-      "vos push <config.json|take> [--vos id] [--title t] [--slug s] [--desc d] [--tags a,b] [--folder <id|slug>] [--remix-of id] [--note n] [--label l] [--base versionId] [--override id]..."
+      'vos push <config.json|take> [--vos id] [--title t] [--slug s] [--desc d] [--tags a,b] [--folder <id|slug>] [--remix-of id] [--note n] [--label l] [--base versionId] [--override id]... [--prompt "<the prompt that made it>"] [--claimable [--share]]'
     );
   }
   const source = resolveConfigPath(target);
@@ -7887,6 +8004,12 @@ async function cmdPushProgram(argv) {
   }
   const config = pre.config;
   const state = readSyncState(dir);
+  const prompt = strFlag(flags, "prompt");
+  if (flags.share === true && flags.claimable !== true) {
+    throw new UsageError(
+      '--share asks a claimable push to lead its claim page with "Claim and share". A key can never publish: open the watch page and set it to Unlisted or Public there'
+    );
+  }
   const vosFlag = strFlag(flags, "vos");
   const explicitVosId = vosFlag ? parseVosId(vosFlag) : null;
   const stillFlag = strFlag(flags, "still");
@@ -7897,7 +8020,8 @@ async function cmdPushProgram(argv) {
     await setProgramStill(dir, t);
     r.log(`cover: ${t}s (doc.json "still")`);
   }
-  for (const w of hostedLiteralWarnings(config)) r.log(`warning ${w}`);
+  for (const w of hostedLiteralWarnings(config)) r.warn(w);
+  for (const w of codeFileWarnings(config, dir)) r.warn(w);
   const programDoc = await readProgramDoc(dir, config);
   if (programDoc) {
     const lint = lintDoc(programDoc);
@@ -7905,7 +8029,7 @@ async function cmdPushProgram(argv) {
       throw new Error(`doc.json fails lint:
   ${lint.problems.join("\n  ")}`);
     }
-    for (const w of lint.warnings) r.log(`warning doc.json: ${w}`);
+    for (const w of lint.warnings) r.warn(`doc.json: ${w}`);
   }
   if (flags.claimable === true) {
     if (explicitVosId) {
@@ -7913,43 +8037,50 @@ async function cmdPushProgram(argv) {
         "--claimable creates a NEW claimable vos and cannot iterate (--vos). After the human claims it, iterate with their key: vos push --vos <id>"
       );
     }
-    const fallback = state?.title ? `${state.title} remix` : basename2(source).replace(/\.json$/i, "") || "vos program";
+    const fallback = state?.title ? `${state.title} remix` : basename3(source).replace(/\.json$/i, "") || "vos program";
     const title2 = (strFlag(flags, "title") ?? fallback).slice(0, 100);
-    let claimDoc = programDoc;
-    if (programDoc) {
-      const sound = soundOf(programDoc);
-      const local = docAudioRefs(sound);
-      if (local.length) {
-        const dropped = new Set(local.map((ref) => ref.key));
-        claimDoc = {
-          ...programDoc,
-          audio: (sound.audio ?? []).filter((a) => !dropped.has(a.key))
-        };
-        r.log(
-          `warning a claimable push carries no files, so ${local.length} local sound${local.length === 1 ? "" : "s"} (${[...dropped].join(", ")}) ${local.length === 1 ? "was" : "were"} left out. After the claim, push again with a key to add ${local.length === 1 ? "it" : "them"}`
-        );
+    const files2 = await collectFiles(config, programDoc, dir, r);
+    let uploadToken;
+    if (files2.count > 0) {
+      const opened = await apiJson(origin, "/api/claim/uploads", {
+        method: "POST"
+      });
+      if (opened.status !== 201) {
+        throw new Error(apiError("open a claim upload session", opened));
       }
-    }
-    const stay = localManifestRefs(config);
-    if (stay.length) {
-      throw new UsageError(
-        `a claimable push carries no files, and this program declares ${stay.length} local file${stay.length === 1 ? "" : "s"} (${stay.join(", ")}). Push with a key instead (vos login, then vos push ${source}), which uploads ${stay.length === 1 ? "it" : "them"}`
+      uploadToken = String(opened.body.uploadToken);
+      r.log(
+        `uploading ${files2.count} file${files2.count === 1 ? "" : "s"} with the claim`
       );
+      await files2.upload({
+        origin,
+        key: uploadToken,
+        door: "/api/claim/uploads/files"
+      });
     }
     const body = {
       title: title2,
-      config: storedProgramConfig(config, claimDoc)
+      config: storedProgramConfig(config, programDoc)
     };
+    if (uploadToken) body.uploadToken = uploadToken;
+    if (prompt) body.prompt = prompt;
+    if (flags.share === true) body.share = true;
     const slug = strFlag(flags, "slug");
     if (slug) body.slug = slug;
     const res = await apiJson(origin, "/api/claim", { method: "POST", body });
     if (res.status !== 201) throw new Error(apiError("claimable push", res));
-    serverWarnings(res.body, (l) => r.log(l));
+    serverWarnings(res.body, say(r));
     const claimUrl = String(res.body.claimUrl ?? "");
     const expiresAt = String(res.body.expiresAt ?? "");
     const created2 = res.body.vos ?? {};
     r.done(
-      { id: created2.id ?? null, title: title2, claimUrl, expiresAt },
+      {
+        id: created2.id ?? null,
+        title: title2,
+        claimUrl,
+        expiresAt,
+        ...uploadToken ? { files: files2.count } : {}
+      },
       `Claimable push created (${title2})
   claim:   ${claimUrl}
   expires: ${expiresAt} \u2014 unclaimed work is deleted after 72h
@@ -7961,15 +8092,8 @@ with their key: vos push ${source} --vos ${String(created2.id ?? "<id>")}`
   }
   const key = requireCredential(strFlag(flags, "key"));
   void flags.yes;
-  if (programDoc) {
-    await uploadDocRefs(
-      docLayerRefs(layersOf(programDoc)),
-      dir,
-      { origin, key },
-      (l) => r.log(l)
-    );
-  }
-  await uploadManifest(config, dir, { origin, key }, (l) => r.log(l));
+  const files = await collectFiles(config, programDoc, dir, r);
+  await files.upload({ origin, key });
   const overrides = [
     ...multi.override ?? [],
     ...strFlag(flags, "overrides")?.split(",") ?? []
@@ -8033,7 +8157,15 @@ with their key: vos push ${source} --vos ${String(created2.id ?? "<id>")}`
     }
     if (res.status !== 201)
       throw new Error(apiError(`push version to ${vosId}`, res));
-    serverWarnings(res.body, (l) => r.log(l));
+    serverWarnings(res.body, say(r));
+    if (prompt) {
+      const set = await apiJson(origin, `/api/vos/${vosId}`, {
+        method: "PATCH",
+        key,
+        body: { prompt }
+      });
+      if (set.status !== 200) r.warn(apiError("set the prompt", set));
+    }
     const version = res.body.version ?? {};
     if (typeof version.id === "string") {
       writeSyncState(dir, { vosId, versionId: version.id });
@@ -8045,7 +8177,7 @@ with their key: vos push ${source} --vos ${String(created2.id ?? "<id>")}`
       key,
       vosId,
       versionId: typeof version.id === "string" ? version.id : null,
-      log: (l) => r.log(l)
+      log: say(r)
     }) : null;
     r.done(
       {
@@ -8069,7 +8201,7 @@ ${landedLines(landed2)}` : "")
     return EXIT_OK;
   }
   const remixOfId = pushTarget.kind === "create" ? pushTarget.remixOfId : void 0;
-  const fallbackTitle = state?.title ? `${state.title} remix` : basename2(source).replace(/\.json$/i, "") || "vos remix";
+  const fallbackTitle = state?.title ? `${state.title} remix` : basename3(source).replace(/\.json$/i, "") || "vos remix";
   const title = (strFlag(flags, "title") ?? fallbackTitle).slice(0, 100);
   const folderId = folderRef ? resolveFolder(await listFolders(origin, key), folderRef).id : void 0;
   const created = await createProgramVos({
@@ -8081,6 +8213,7 @@ ${landedLines(landed2)}` : "")
     // (found seeding one-layer members: `--with` then said the vos carried
     // no doc).
     doc: programDoc ?? void 0,
+    prompt,
     title,
     slug: strFlag(flags, "slug"),
     description: desc,
@@ -8105,7 +8238,7 @@ ${landedLines(landed2)}` : "")
     key,
     vosId: created.id,
     versionId: created.currentVersionId,
-    log: (l) => r.log(l)
+    log: say(r)
   }) : null;
   r.done(
     {
@@ -8203,7 +8336,7 @@ async function cmdPullProgram(argv) {
     throw new Error(apiError(`fetch head config for ${vosId}`, cfg));
   const configPath = join15(dir, "config.json");
   let backedUp = false;
-  if (existsSync13(configPath)) {
+  if (existsSync14(configPath)) {
     await writeFile9(join15(dir, "config.backup.json"), await readFile13(configPath));
     backedUp = true;
   }
@@ -8308,6 +8441,27 @@ async function storeKey(key, origin, r) {
 function isTakeDir(target) {
   return directoryKind(target) === "take";
 }
+function say(r) {
+  return (line) => {
+    const m = /^\s*warning\s+(.*)$/s.exec(line);
+    if (m) r.warn(m[1]);
+    else r.log(line);
+  };
+}
+async function collectFiles(config, programDoc, dir, r) {
+  for (const line of liftNamedFiles(config, dir)) r.log(`  ${line}`);
+  const docRefs = programDoc ? docLayerRefs(layersOf(programDoc)) : [];
+  const dataRefs = localDataRefs(config, dir);
+  const count = docRefs.length + localManifestRefs(config).length + dataRefs.length;
+  return {
+    count,
+    upload: async (target) => {
+      await uploadDocRefs(docRefs, dir, target, say(r));
+      await uploadManifest(config, dir, target, say(r));
+      await uploadDocRefs(dataRefs, dir, target, say(r));
+    }
+  };
+}
 function soundOf(doc) {
   return { audio: Array.isArray(doc.audio) ? doc.audio : [] };
 }
@@ -8325,7 +8479,7 @@ function storedProgramConfig(config, programDoc) {
 }
 async function readProgramDoc(dir, config) {
   const docPath = join15(dir, "doc.json");
-  if (!existsSync13(docPath)) return null;
+  if (!existsSync14(docPath)) return null;
   const parsed = JSON.parse(await readFile13(docPath, "utf8"));
   if (typeof parsed !== "object" || parsed === null || "source" in parsed)
     return null;
@@ -8336,7 +8490,7 @@ async function readProgramDoc(dir, config) {
 async function setProgramStill(dir, t) {
   const docPath = join15(dir, "doc.json");
   let doc = { program: {}, audio: [] };
-  if (existsSync13(docPath)) {
+  if (existsSync14(docPath)) {
     const parsed = JSON.parse(await readFile13(docPath, "utf8"));
     if (!parsed || typeof parsed !== "object" || "source" in parsed)
       throw new UsageError(
@@ -8359,7 +8513,107 @@ async function writeProgramDoc(dir, hosted) {
 // src/plugin/asset.ts
 import { createHash as createHash2 } from "crypto";
 import { readFileSync as readFileSync3 } from "fs";
-import { basename as basename3 } from "path";
+import { basename as basename4 } from "path";
+
+// src/plugin/assetWords.ts
+function hostedFile(raw) {
+  const row = raw && typeof raw === "object" ? raw : {};
+  const text = (value, fallback = "") => typeof value === "string" ? value : fallback;
+  return {
+    ...row,
+    id: text(row.id),
+    kind: text(row.kind) || text(row.category, "file"),
+    filename: text(row.filename, "unnamed"),
+    size: typeof row.size === "number" ? row.size : 0
+  };
+}
+function bytesWords(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return "0 B";
+  if (bytes < 1024) return `${Math.round(bytes)} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  return `${value >= 100 ? Math.round(value) : value.toFixed(1)} ${units[unit]}`;
+}
+var num = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+function probeLine(file) {
+  const meta = file.metadata ?? {};
+  const parts = [file.kind];
+  const width = num(meta.width);
+  const height = num(meta.height);
+  if (width && height) parts.push(`${width}\xD7${height}`);
+  if (typeof meta.videoCodec === "string") parts.push(meta.videoCodec);
+  else if (typeof meta.audioCodec === "string" && file.kind === "audio") {
+    parts.push(meta.audioCodec);
+  }
+  const seconds = num(file.duration);
+  if (seconds && seconds > 0) {
+    parts.push(`${seconds >= 10 ? seconds.toFixed(1) : seconds.toFixed(2)} s`);
+  }
+  let line = parts.join(" ");
+  if (file.kind === "video" && meta.hasAudio === true) line += ", audio";
+  if (file.kind === "model") {
+    const meshes = num(meta.meshCount);
+    if (meshes !== null) line += ` ${meshes} mesh${meshes === 1 ? "" : "es"}`;
+  }
+  return line;
+}
+function manifestName2(filename) {
+  const stem = filename.replace(/\.[^.]+$/, "");
+  const name = stem.replace(/[^A-Za-z0-9_]+/g, "_").replace(/^_+|_+$/g, "").replace(/^(\d)/, "_$1");
+  return name || "file";
+}
+var MANIFEST_KINDS = /* @__PURE__ */ new Set([
+  "image",
+  "video",
+  "audio",
+  "model",
+  "font",
+  "hdr"
+]);
+function manifestLine(file) {
+  const kind = file.kind === "vector" ? "image" : file.kind;
+  const hint = MANIFEST_KINDS.has(kind) ? `, "kind": "${kind}"` : "";
+  return `"${manifestName2(file.filename)}": { "ref": "asset:${file.id}"${hint} }`;
+}
+function listRow(file) {
+  return [
+    file.id,
+    file.kind,
+    bytesWords(file.size),
+    file.kind === "recipe" ? "" : file.uses ? `used in ${file.uses}` : "not used",
+    file.intent === "attached" ? "attached" : "library",
+    file.filename
+  ];
+}
+function alignRows(rows) {
+  if (rows.length === 0) return [];
+  const widths = rows[0].map(
+    (_, col) => Math.max(...rows.map((row) => (row[col] ?? "").length))
+  );
+  return rows.map(
+    (row) => row.map(
+      (cell, col) => col === row.length - 1 ? cell : cell.padEnd(widths[col])
+    ).join("  ").trimEnd()
+  );
+}
+function nameFromUrl(url) {
+  try {
+    const last = decodeURIComponent(
+      new URL(url).pathname.split("/").filter(Boolean).pop() ?? ""
+    );
+    const clean = last.replace(/[^\w.\- ]+/g, "_").slice(0, 120);
+    return clean || "download";
+  } catch {
+    return "download";
+  }
+}
+
+// src/plugin/asset.ts
 var BOOLEAN_FLAGS3 = /* @__PURE__ */ new Set(["json", "help"]);
 async function cmdRename(argv) {
   const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS3);
@@ -8400,7 +8654,7 @@ async function cmdPush(argv) {
   const folder = folderRef ? resolveFolder(await listFolders(origin, key), folderRef) : null;
   const uploaded = [];
   for (const file of positionals) {
-    const name = basename3(file);
+    const name = basename4(file);
     const body = readFileSync3(file);
     const media = resolveMediaType({
       head: body.subarray(0, MEDIA_HEAD_BYTES),
@@ -8429,12 +8683,27 @@ async function cmdPush(argv) {
       filename: stored,
       kind: put.kind,
       url: put.url,
+      ref: put.ref,
+      size: put.size,
+      ...put.duration ? { duration: put.duration } : {},
+      ...put.metadata ? { metadata: put.metadata } : {},
       ...put.reused ? { reused: true } : {},
       ...put.notes.length ? { notes: put.notes } : {}
     });
+    const hosted = {
+      id: put.id,
+      kind: put.kind,
+      filename: stored,
+      size: put.size,
+      duration: put.duration,
+      metadata: put.metadata
+    };
     r.log(
-      `uploaded ${stored} (${put.id})${put.reused ? " \u2014 already on your shelf" : ""}  ${put.url}`
+      `uploaded ${stored}${put.reused ? " \u2014 already yours, nothing sent" : ""}`
     );
+    r.log(`  ${probeLine(hosted)}, ${bytesWords(put.size)}`);
+    r.log(`  ${put.ref}   ${put.url}`);
+    r.log(`  ${manifestLine(hosted)}`);
     for (const note of put.notes) r.log(`  note: ${note}`);
   }
   r.done(
@@ -8447,6 +8716,181 @@ async function cmdPush(argv) {
   );
   return EXIT_OK;
 }
+var IMPORT_MAX_BYTES = 512 * 1024 * 1024;
+async function cmdImport(argv) {
+  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS3);
+  const [url] = positionals;
+  if (!url || !/^https?:\/\//i.test(url)) {
+    throw new UsageError(
+      "vos asset import <http(s) url> [--name <file>] [--folder <slug>] [--license <text>] [--attribution <text>]"
+    );
+  }
+  const r = createReporter(flags.json === true);
+  const origin = platformOrigin({
+    origin: strFlag(flags, "origin"),
+    api: strFlag(flags, "api")
+  });
+  const key = requireCredential(strFlag(flags, "key"));
+  const folderRef = strFlag(flags, "folder");
+  const folder = folderRef ? resolveFolder(await listFolders(origin, key), folderRef) : null;
+  r.log(`fetching ${url}`);
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok)
+    throw new Error(`import ${url}: the address answered ${res.status}`);
+  const declared = Number(res.headers.get("content-length") ?? 0);
+  if (declared > IMPORT_MAX_BYTES) {
+    throw new Error(
+      `import ${url}: ${bytesWords(declared)} is over the ${bytesWords(IMPORT_MAX_BYTES)} an import carries. Download it and use vos asset push`
+    );
+  }
+  const body = new Uint8Array(await res.arrayBuffer());
+  if (body.length > IMPORT_MAX_BYTES) {
+    throw new Error(
+      `import ${url}: ${bytesWords(body.length)} is over the ${bytesWords(IMPORT_MAX_BYTES)} an import carries. Download it and use vos asset push`
+    );
+  }
+  const name = strFlag(flags, "name") ?? nameFromUrl(res.url || url);
+  const license = strFlag(flags, "license");
+  const attribution = strFlag(flags, "attribution");
+  let put;
+  try {
+    put = await uploadAsset({ origin, key }, body, {
+      filename: name,
+      contentHash: createHash2("sha256").update(body).digest("hex"),
+      intent: "library",
+      ...folder ? { folderId: folder.id } : {},
+      provenance: {
+        sourceUrl: res.url || url,
+        ...license ? { license } : {},
+        ...attribution ? { attribution } : {}
+      }
+    });
+  } catch (e) {
+    throw new Error(
+      `import ${name}: ${e instanceof Error ? e.message : String(e)}`
+    );
+  }
+  const hosted = {
+    id: put.id,
+    kind: put.kind,
+    filename: put.filename || name,
+    size: put.size,
+    duration: put.duration,
+    metadata: put.metadata
+  };
+  if (!license) {
+    r.log(
+      "note: no --license was given. Say what lets you use this file, so the next person can tell"
+    );
+  }
+  r.done(
+    {
+      id: put.id,
+      filename: hosted.filename,
+      kind: put.kind,
+      url: put.url,
+      ref: put.ref,
+      size: put.size,
+      sourceUrl: res.url || url,
+      ...license ? { license } : {},
+      ...attribution ? { attribution } : {},
+      ...put.reused ? { reused: true } : {},
+      ...put.notes.length ? { notes: put.notes } : {},
+      folder: folder?.slug ?? null
+    },
+    `imported ${hosted.filename}${put.reused ? " \u2014 already yours, nothing sent" : ""}
+  ${probeLine(hosted)}, ${bytesWords(put.size)}
+  ${put.ref}   ${put.url}
+  ${manifestLine(hosted)}`
+  );
+  return EXIT_OK;
+}
+async function cmdList2(argv) {
+  const { flags } = parseArgs(argv, BOOLEAN_FLAGS3);
+  const r = createReporter(flags.json === true);
+  const origin = platformOrigin({
+    origin: strFlag(flags, "origin"),
+    api: strFlag(flags, "api")
+  });
+  const key = requireCredential(strFlag(flags, "key"));
+  const params = new URLSearchParams({
+    limit: String(Math.min(200, Math.max(1, numFlag(flags, "limit", 50))))
+  });
+  for (const name of ["kind", "q", "sort", "scope"]) {
+    const value = strFlag(flags, name);
+    if (value) params.set(name, value);
+  }
+  const folderRef = strFlag(flags, "folder");
+  if (folderRef) {
+    params.set(
+      "folder",
+      folderRef === "none" ? "none" : resolveFolder(await listFolders(origin, key), folderRef).id
+    );
+  }
+  const res = await apiJson(origin, `/api/assets?${params}`, { key });
+  if (res.status !== 200) throw new Error(apiError("list assets", res));
+  const assets = (res.body.assets ?? []).map(hostedFile);
+  const total = typeof res.body.total === "number" ? res.body.total : assets.length;
+  r.done(
+    { assets, total, kinds: res.body.kinds ?? {} },
+    assets.length === 0 ? "no files" : `${alignRows(assets.map(listRow)).join("\n")}
+${assets.length} of ${total} file${total === 1 ? "" : "s"}${total > assets.length ? " (--limit for more, --q to search)" : ""}`
+  );
+  return EXIT_OK;
+}
+async function cmdUsage(argv) {
+  const { flags } = parseArgs(argv, BOOLEAN_FLAGS3);
+  const r = createReporter(flags.json === true);
+  const origin = platformOrigin({
+    origin: strFlag(flags, "origin"),
+    api: strFlag(flags, "api")
+  });
+  const key = requireCredential(strFlag(flags, "key"));
+  const res = await apiJson(origin, "/api/user/usage", { key });
+  if (res.status !== 200) throw new Error(apiError("read usage", res));
+  const usage = res.body.usage ?? {};
+  const limits = res.body.limits ?? {};
+  const held = Number(usage.assetBytes ?? 0);
+  const trash = Number(usage.trashBytes ?? 0);
+  const limit = Number(limits.storageBytes ?? 0);
+  const today = usage.uploadsToday ?? {};
+  const perKind = limits.uploadKinds ?? {};
+  const rates = Object.entries(today).filter(([kind]) => perKind[kind]?.perDay).map(([kind, n]) => `${kind} ${n} of ${perKind[kind].perDay}`);
+  r.done(
+    { plan: res.body.plan, usage, limits },
+    `${bytesWords(held)} of ${bytesWords(limit)} used` + (trash > 0 ? `, ${bytesWords(trash)} of it in Trash (a person empties Trash at vos.so/app/trash; deleting more frees nothing)` : "") + (rates.length ? `
+uploaded in the last 24 h: ${rates.join(", ")}` : "")
+  );
+  return EXIT_OK;
+}
+async function cmdWhy(argv) {
+  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS3);
+  const [assetId] = positionals;
+  if (!assetId) throw new UsageError("vos assets why <assetId>");
+  const r = createReporter(flags.json === true);
+  const origin = platformOrigin({
+    origin: strFlag(flags, "origin"),
+    api: strFlag(flags, "api")
+  });
+  const key = requireCredential(strFlag(flags, "key"));
+  const res = await apiJson(origin, `/api/assets/${assetId}`, { key });
+  if (res.status !== 200) throw new Error(apiError(`read ${assetId}`, res));
+  const asset = hostedFile(res.body.asset);
+  const usedIn = res.body.usedIn ?? [];
+  const how = (u) => [
+    u.head ? "in what plays now" : "",
+    u.versions ? `${u.versions} version${u.versions === 1 ? "" : "s"}` : "",
+    u.draft ? "an unsaved draft" : "",
+    u.trashed ? "in Trash" : ""
+  ].filter(Boolean).join(", ");
+  const lines = [
+    `${asset.filename}  ${probeLine(asset)}, ${bytesWords(asset.size)}`,
+    asset.removedAt ? `removed from vos.so: ${asset.removedReason ?? "no reason given"}` : usedIn.length === 0 ? asset.intent === "attached" ? "nothing uses it: an attached file that stays unused is collected after 7 days" : "nothing uses it: it stays because it is in your library" : `used by ${usedIn.length}:`,
+    ...usedIn.map((u) => `  ${u.vosId}  ${u.title || "Untitled"}  (${how(u)})`)
+  ];
+  r.done({ asset, usedIn }, lines.join("\n"));
+  return EXIT_OK;
+}
 async function cmdAsset(argv) {
   const sub = argv[0];
   const rest = argv.slice(1);
@@ -8455,15 +8899,24 @@ async function cmdAsset(argv) {
       return cmdRename(rest);
     case "push":
       return cmdPush(rest);
+    case "import":
+      return cmdImport(rest);
+    case "ls":
+    case "list":
+      return cmdList2(rest);
+    case "usage":
+      return cmdUsage(rest);
+    case "why":
+      return cmdWhy(rest);
     default:
       throw new UsageError(
-        "vos asset <rename|push> \u2014 rename one of your assets, or push files onto the shelf (vos asset push <file...> [--folder <slug>])"
+        "vos asset <push|import|rename> | vos assets <ls|usage|why> \u2014 add files to your library, or see what is in it (vos asset push <file...> [--folder <slug>])"
       );
   }
 }
 
 // src/plugin/remove.ts
-import { existsSync as existsSync14, rmSync as rmSync2, statSync as statSync3 } from "fs";
+import { existsSync as existsSync15, rmSync as rmSync2, statSync as statSync3 } from "fs";
 import { join as join16 } from "path";
 import { createInterface as createInterface3 } from "readline/promises";
 
@@ -8643,7 +9096,7 @@ async function cmdDelete(argv) {
     api: strFlag(flags, "api")
   }).replace(/\/+$/, "");
   const key = requireCredential(strFlag(flags, "key"));
-  const dir = existsSync14(target) && statSync3(target).isDirectory() ? target : null;
+  const dir = existsSync15(target) && statSync3(target).isDirectory() ? target : null;
   const vosId = dir ? readSyncState(dir)?.vosId : parseVosId(target);
   if (!vosId)
     throw new UsageError(
@@ -8711,7 +9164,7 @@ async function cmdDelete(argv) {
 
 // src/plugin/buildProgram.ts
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
-import { basename as basename4, dirname as dirname4, join as join17, resolve as resolve7 } from "path";
+import { basename as basename5, dirname as dirname4, join as join17, resolve as resolve7 } from "path";
 import { pathToFileURL } from "url";
 import { parse } from "acorn";
 import { fullAncestor } from "acorn-walk";
@@ -8919,7 +9372,7 @@ async function cmdBuild(argv) {
     throw new UsageError(
       `${source} exports no program: \`export default { version: 2, duration, camera, createContent, createTimeline, \u2026 }\``
     );
-  const built = buildProgram(program, basename4(file), text);
+  const built = buildProgram(program, basename5(file), text);
   for (const p of built.problems) r.log(`error ${p.fn}: ${p.message}`);
   if (built.problems.length) {
     r.done(
@@ -8946,7 +9399,7 @@ async function cmdBuild(argv) {
 
 // src/plugin/compare.ts
 import { spawnSync } from "child_process";
-import { existsSync as existsSync15, mkdirSync as mkdirSync2, statSync as statSync4, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync16, mkdirSync as mkdirSync2, statSync as statSync4, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname5, join as join18, resolve as resolve8 } from "path";
 var BOOLEAN_FLAGS7 = /* @__PURE__ */ new Set(["json", "help"]);
 function sampleTimes(duration, every) {
@@ -9014,7 +9467,7 @@ async function cmdCompare(argv) {
   const config = loaded.config;
   const duration = configDuration(config) ?? 5;
   const assets = await programAssets(config, {
-    baseDir: /^https?:\/\//.test(source) ? null : existsSync15(source) && statSync4(source).isDirectory() ? source : dirname5(source),
+    baseDir: /^https?:\/\//.test(source) ? null : existsSync16(source) && statSync4(source).isDirectory() ? source : dirname5(source),
     origin: platformOrigin({}),
     key: resolveCredential(),
     log: (line) => r.log(line)
@@ -9133,28 +9586,28 @@ async function cmdCompare(argv) {
 }
 
 // src/plugin/port.ts
-import { existsSync as existsSync19, mkdirSync as mkdirSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync20, mkdirSync as mkdirSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
 import { dirname as dirname8, join as join22, resolve as resolve11 } from "path";
 import { pathToFileURL as pathToFileURL3 } from "url";
 
 // src/plugin/portInventory.ts
 import { spawnSync as spawnSync2 } from "child_process";
 import {
-  existsSync as existsSync17,
+  existsSync as existsSync18,
   mkdirSync as mkdirSync3,
   readFileSync as readFileSync6,
   readdirSync as readdirSync4,
   statSync as statSync6
 } from "fs";
-import { dirname as dirname6, join as join20, relative as relative2, resolve as resolve9 } from "path";
+import { dirname as dirname6, join as join20, relative as relative3, resolve as resolve9 } from "path";
 import { pathToFileURL as pathToFileURL2 } from "url";
 import { findFontFamily as findFontFamily3 } from "@vosjs/shared";
 
 // src/plugin/portRemotion.ts
-import { existsSync as existsSync16, readFileSync as readFileSync5, readdirSync as readdirSync3, statSync as statSync5 } from "fs";
+import { existsSync as existsSync17, readFileSync as readFileSync5, readdirSync as readdirSync3, statSync as statSync5 } from "fs";
 import { createServer as createServer2 } from "http";
 import { createRequire } from "module";
-import { basename as basename5, extname as extname2, join as join19 } from "path";
+import { basename as basename6, extname as extname3, join as join19 } from "path";
 function themeColors(sources) {
   const out = {};
   const re = /\bconst\s+([A-Za-z_$][\w$]*)\s*(?::\s*string\s*)?=\s*['"](#[0-9a-fA-F]{3,8})['"]/g;
@@ -9227,7 +9680,7 @@ function sourceTexts(dir) {
     }
   };
   const src = join19(dir, "src");
-  walk(existsSync16(src) ? src : dir, 0);
+  walk(existsSync17(src) ? src : dir, 0);
   return out;
 }
 function entryPoint(dir) {
@@ -9239,7 +9692,7 @@ function entryPoint(dir) {
     "remotion/index.ts",
     "remotion/index.tsx"
   ])
-    if (existsSync16(join19(dir, p))) return join19(dir, p);
+    if (existsSync17(join19(dir, p))) return join19(dir, p);
   return null;
 }
 var TYPES = {
@@ -9332,10 +9785,10 @@ async function readRemotion(dir, log) {
   const server = createServer2((rq, rs) => {
     const path = decodeURIComponent(new URL(rq.url ?? "/", "http://x").pathname);
     let f = join19(out, path);
-    if (!f.startsWith(out) || !existsSync16(f) || statSync5(f).isDirectory())
+    if (!f.startsWith(out) || !existsSync17(f) || statSync5(f).isDirectory())
       f = join19(out, "index.html");
     rs.writeHead(200, {
-      "content-type": TYPES[extname2(f)] ?? "application/octet-stream"
+      "content-type": TYPES[extname3(f)] ?? "application/octet-stream"
     });
     rs.end(readFileSync5(f));
   }).listen(0, "127.0.0.1");
@@ -9434,8 +9887,8 @@ async function readRemotion(dir, log) {
     const sources = sourceTexts(dir);
     const publicDir = join19(dir, "public");
     const media = tree.audio.map((a) => {
-      const name = basename5(a.src.split("?")[0]);
-      const local = existsSync16(join19(publicDir, name)) ? `public/${name}` : a.src;
+      const name = basename6(a.src.split("?")[0]);
+      const local = existsSync17(join19(publicDir, name)) ? `public/${name}` : a.src;
       return {
         kind: "audio",
         src: local,
@@ -9476,9 +9929,9 @@ async function readRemotion(dir, log) {
 
 // src/plugin/portInventory.ts
 function detectEngine(dir) {
-  if (existsSync17(join20(dir, "hyperframes.json"))) return "hyperframes";
+  if (existsSync18(join20(dir, "hyperframes.json"))) return "hyperframes";
   const pkg = join20(dir, "package.json");
-  if (existsSync17(pkg)) {
+  if (existsSync18(pkg)) {
     try {
       const p = JSON.parse(readFileSync6(pkg, "utf8"));
       const deps = { ...p.dependencies ?? {}, ...p.devDependencies ?? {} };
@@ -9492,13 +9945,13 @@ function detectEngine(dir) {
   return "page";
 }
 function sourcePage(source) {
-  if (!existsSync17(source)) return null;
+  if (!existsSync18(source)) return null;
   if (statSync6(source).isFile()) return /\.html?$/i.test(source) ? source : null;
   const index = join20(source, "index.html");
-  return existsSync17(index) ? index : null;
+  return existsSync18(index) ? index : null;
 }
 function findRender(dir) {
-  const videos = (d) => existsSync17(d) ? readdirSync4(d).filter((f) => /\.(mp4|webm|mov)$/i.test(f)).map((f) => join20(d, f)) : [];
+  const videos = (d) => existsSync18(d) ? readdirSync4(d).filter((f) => /\.(mp4|webm|mov)$/i.test(f)).map((f) => join20(d, f)) : [];
   for (const d of [join20(dir, "renders"), join20(dir, "out"), dir]) {
     const found = videos(d);
     if (found.length) return found[0];
@@ -9770,7 +10223,7 @@ var SEEK_AND_READ = `((args) => {
 })`;
 async function readInventory(source, opts) {
   const abs = resolve9(source);
-  const dir = existsSync17(abs) && statSync6(abs).isDirectory() ? abs : dirname6(abs);
+  const dir = existsSync18(abs) && statSync6(abs).isDirectory() ? abs : dirname6(abs);
   const engine = detectEngine(dir);
   const page = sourcePage(abs);
   const render = opts.render === void 0 ? findRender(dir) : opts.render;
@@ -9900,7 +10353,7 @@ async function readInventory(source, opts) {
         if (ok)
           stills.push({
             t: Number(t.toFixed(2)),
-            file: relative2(opts.outDir, file)
+            file: relative3(opts.outDir, file)
           });
       }
     } else {
@@ -9911,7 +10364,7 @@ async function readInventory(source, opts) {
   }
   const scriptStrings = scriptStringsOf(read.scriptText);
   return {
-    source: relative2(process.cwd(), abs) || ".",
+    source: relative3(process.cwd(), abs) || ".",
     root: abs.endsWith(".html") ? dirname6(abs) : abs,
     engine,
     width: read.width,
@@ -9929,15 +10382,15 @@ async function readInventory(source, opts) {
     variables: read.variables,
     scriptStrings,
     uses: read.uses ?? sourceUses(read.scriptText ?? ""),
-    render: render ? relative2(process.cwd(), render) : null,
+    render: render ? relative3(process.cwd(), render) : null,
     stills
   };
 }
 
 // src/plugin/portScaffold.ts
 import { spawnSync as spawnSync3 } from "child_process";
-import { copyFileSync, existsSync as existsSync18, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
-import { basename as basename6, dirname as dirname7, join as join21, resolve as resolve10 } from "path";
+import { copyFileSync, existsSync as existsSync19, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
+import { basename as basename7, dirname as dirname7, join as join21, resolve as resolve10 } from "path";
 import { findFontFamily as findFontFamily4, fontFaceUrl, nearestFontWeight } from "@vosjs/shared";
 
 // src/plugin/painterLib.ts
@@ -10347,8 +10800,8 @@ function planScaffold(inv, opts) {
   const copies = [];
   inv.media.filter((m) => m.kind === "audio" && m.src).forEach((m, i) => {
     const from = resolve10(opts.sourceDir, m.src);
-    const name = basename6(from);
-    if (!existsSync18(from)) {
+    const name = basename7(from);
+    if (!existsSync19(from)) {
       report.push(
         `- the audio ${m.src} is not in the source folder; add it to doc.json by hand`
       );
@@ -10491,7 +10944,7 @@ ${sceneTodos}${springHint}
 }
 function reportText(inv, r) {
   const lines = [
-    `# Port report: ${inv.source === "." && inv.root ? basename6(inv.root) : inv.source}`,
+    `# Port report: ${inv.source === "." && inv.root ? basename7(inv.root) : inv.source}`,
     "",
     `${inv.engine} piece, ${inv.width}\xD7${inv.height}${inv.fps ? ` at ${inv.fps} fps` : ""}, ${inv.duration ?? "?"} s. A program has no size of its own: render it with \`--width ${inv.width} --height ${inv.height}\`.`,
     "",
@@ -10619,7 +11072,7 @@ async function scaffold(argv) {
   const { flags } = parseArgs(argv, BOOLEAN_FLAGS8);
   const r = createReporter(flags.json === true);
   const from = resolve11(strFlag(flags, "from") ?? join22("port", "inventory.json"));
-  if (!existsSync19(from))
+  if (!existsSync20(from))
     throw new UsageError(
       `no inventory at ${from}: run npx vos port inventory <source> first`
     );
@@ -10655,11 +11108,11 @@ function scaffoldSourceDir(inv) {
 // src/plugin/recipe.ts
 import { createHash as createHash3 } from "crypto";
 import { readFileSync as readFileSync8 } from "fs";
-import { basename as basename7 } from "path";
+import { basename as basename8 } from "path";
 var BOOLEAN_FLAGS9 = /* @__PURE__ */ new Set(["json", "help"]);
 var USAGE = "vos recipe push <file.md> (--folder <folderId|slug> | --asset <assetId>)";
 function recipeFilename(file) {
-  const name = basename7(file);
+  const name = basename8(file);
   if (!/\.md$/i.test(name)) {
     throw new UsageError(`a recipe is a markdown file \u2014 ${name} is not .md`);
   }
@@ -11311,8 +11764,8 @@ var quoteAttr = (s) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 function hrefSelector(href) {
   try {
     const u = new URL(href);
-    const relative3 = `${u.pathname}${u.search}${u.hash}`;
-    return `a[href=${quoteAttr(relative3)}], a[href=${quoteAttr(href)}]`;
+    const relative4 = `${u.pathname}${u.search}${u.hash}`;
+    return `a[href=${quoteAttr(relative4)}], a[href=${quoteAttr(href)}]`;
   } catch {
     return `a[href=${quoteAttr(href)}]`;
   }
@@ -11739,9 +12192,9 @@ async function cmdActionsScript(input, flags) {
 }
 
 // src/plugin/ingest.ts
-import { existsSync as existsSync20 } from "fs";
+import { existsSync as existsSync21 } from "fs";
 import { copyFile, mkdir as mkdir8, readFile as readFile14, stat as stat3 } from "fs/promises";
-import { basename as basename8, join as join23, resolve as resolve14 } from "path";
+import { basename as basename9, join as join23, resolve as resolve14 } from "path";
 import { inflateRawSync } from "zlib";
 import {
   cursorFromPlaywrightTrace,
@@ -11822,7 +12275,7 @@ async function copyRecording(src, dest, ext) {
   }
 }
 async function readTraceFile(path, offsetMs) {
-  const kind = traceKindOf(basename8(path));
+  const kind = traceKindOf(basename9(path));
   if (!kind) {
     throw new UsageError(
       `${path}: not a trace the recorder reads (trace.zip, .trace, .jsonl, .json or .csv)`
@@ -11843,7 +12296,7 @@ async function readTraceFile(path, offsetMs) {
     return cursorFromPlaywrightTrace(text2, { offsetMs });
   }
   const text = await readFile14(path, "utf8");
-  return cursorFromTrace(basename8(path), text, { offsetMs });
+  return cursorFromTrace(basename9(path), text, { offsetMs });
 }
 function parseViewport(v) {
   if (!v) return null;
@@ -11859,7 +12312,7 @@ async function cmdIngest(argv) {
       "vos ingest <video.webm|mp4> [--cursor <trace.zip|steps.jsonl|cursor.csv>] [--as footage|take] [--out take] [--offset <ms>] [--viewport WxH] [--background <slug|url|none>] [--json]"
     );
   const videoPath = resolve14(source);
-  if (!existsSync20(videoPath)) throw new UsageError(`${source}: no such file`);
+  if (!existsSync21(videoPath)) throw new UsageError(`${source}: no such file`);
   const r = createReporter(flags.json === true);
   const outDir = resolve14(strFlag(flags, "out") ?? "take");
   const offsetMs = numFlag(flags, "offset", 0);
@@ -11874,7 +12327,7 @@ async function cmdIngest(argv) {
       "note: finished footage opens bare, so --background is not used (pass --as take for the screen-recording card and its ground)"
     );
   const backdrop = footage ? null : await takeBackdrop(flags, r);
-  r.log(`probing ${basename8(videoPath)}\u2026`);
+  r.log(`probing ${basename9(videoPath)}\u2026`);
   const probed = await probeVideoFile(videoPath);
   if (!(probed.durationMs > 0)) {
     throw new UsageError(
@@ -11886,7 +12339,7 @@ async function cmdIngest(argv) {
     trace = await readTraceFile(resolve14(cursorPath), offsetMs);
     for (const n of trace.notes) r.log(`note: ${n}`);
   }
-  if (existsSync20(join23(outDir, "meta.json"))) {
+  if (existsSync21(join23(outDir, "meta.json"))) {
     const { prevDoc, kept } = await prepareReRecord(outDir);
     r.log(
       `note: re-ingesting into ${outDir}; kept ${kept.length ? kept.join(", ") : "nothing"}` + (prevDoc ? `; apply the previous cut with: vos plan ${outDir} --reuse` : "")
@@ -11923,13 +12376,13 @@ async function cmdIngest(argv) {
   const clicks = events.filter((e) => e.type === "down").length;
   const seconds = (probed.durationMs / 1e3).toFixed(1);
   const facts = `${seconds}s, ${probed.width}\xD7${probed.height} @ ${meta.fps} fps${probed.hasAudio ? ", audio" : ", no audio"}${remuxed ? "" : ", copied as is"}`;
-  const cursorLine = trace ? `${events.length} cursor events (${clicks} clicks) from ${basename8(cursorPath)}${trace.dropped ? `, ${trace.dropped} not placed` : ""}; ${plan.zoomAuto} zoom${plan.zoomAuto === 1 ? "" : "s"} planned` : "no cursor track, so nothing was planned";
+  const cursorLine = trace ? `${events.length} cursor events (${clicks} clicks) from ${basename9(cursorPath)}${trace.dropped ? `, ${trace.dropped} not placed` : ""}; ${plan.zoomAuto} zoom${plan.zoomAuto === 1 ? "" : "s"} planned` : "no cursor track, so nothing was planned";
   const opened = footage ? `opened as finished footage: no card, no browser bar, no drawn cursor, ${meta.fps > 30 ? 60 : 30} fps export (--as take for a screen recording's card)` : `opened as a screen recording: the card, its ground and the drawn cursor (--as footage to open it bare)`;
   const next = footage && !trace ? `Next: vos push ${outDir} --wait \u2014 it lands as it is; trim or add to it in the studio` : trace ? `Next: vos digest ${outDir} \u2014 look before you cut; edit doc.json; vos push ${outDir}` : `Add --cursor <trace> recorded beside the video (a Playwright trace.zip, stamped JSON records, or a t,x,y,type CSV) to plan zooms from its clicks; else place them by eye: vos frames ${outDir} --times 0,25%,50%,75%,100%, then edit doc.json`;
   r.done(
     {
       out: outDir,
-      recording: basename8(recording),
+      recording: basename9(recording),
       durationMs: probed.durationMs,
       width: probed.width,
       height: probed.height,
@@ -11938,7 +12391,7 @@ async function cmdIngest(argv) {
       hasAudio: probed.hasAudio,
       remuxed,
       cursor: trace ? {
-        file: basename8(cursorPath),
+        file: basename9(cursorPath),
         kind: trace.kind,
         events: events.length,
         clicks,
@@ -11950,7 +12403,7 @@ async function cmdIngest(argv) {
       backdrop: plan.backdrop ?? null,
       as: footage ? "footage" : "take"
     },
-    `Ingested ${basename8(videoPath)} \u2192 ${outDir}/${basename8(recording)} (${facts})
+    `Ingested ${basename9(videoPath)} \u2192 ${outDir}/${basename9(recording)} (${facts})
   ${opened}
   ${cursorLine}
   ${next}`
@@ -11962,7 +12415,7 @@ async function cmdIngest(argv) {
 import { spawnSync as spawnSync4 } from "child_process";
 import {
   cpSync,
-  existsSync as existsSync22,
+  existsSync as existsSync23,
   mkdirSync as mkdirSync6,
   readFileSync as readFileSync10,
   rmSync as rmSync3,
@@ -11973,7 +12426,7 @@ import { join as join25 } from "path";
 import { chromium as chromium2 } from "playwright";
 
 // src/plugin/machine.ts
-import { existsSync as existsSync21, readFileSync as readFileSync9, readdirSync as readdirSync5, statSync as statSync7 } from "fs";
+import { existsSync as existsSync22, readFileSync as readFileSync9, readdirSync as readdirSync5, statSync as statSync7 } from "fs";
 import { dirname as dirname9, join as join24 } from "path";
 var AGENT_NAMES = [
   "claude",
@@ -11994,7 +12447,7 @@ var HOME_DIRS = {
   copilot: [".copilot"]
 };
 function detectAgents(root, opts = {}) {
-  const exists = opts.exists ?? existsSync21;
+  const exists = opts.exists ?? existsSync22;
   const out = [];
   for (const agent of AGENT_NAMES) {
     for (const rel of PROJECT_DIRS[agent]) {
@@ -12041,7 +12494,7 @@ function skillsDirFor(home) {
 function fallbackSkillsHome(root) {
   return { agent: "codex", dir: join24(root, ".agents"), scope: "project" };
 }
-function installedSkills(dir, exists = existsSync21, list = (p) => {
+function installedSkills(dir, exists = existsSync22, list = (p) => {
   try {
     return readdirSync5(p);
   } catch {
@@ -12082,7 +12535,7 @@ ${RULES_BLOCK}
   }
   return { text, changed: text !== current };
 }
-function rulesFileFor(root, exists = existsSync21) {
+function rulesFileFor(root, exists = existsSync22) {
   const agents = join24(root, "AGENTS.md");
   if (exists(agents)) return agents;
   const claude = join24(root, "CLAUDE.md");
@@ -12189,12 +12642,12 @@ function bundledSkillsDir(from) {
   let dir = dirname9(from);
   for (let i = 0; i < 6; i++) {
     const pkg = join24(dir, "package.json");
-    if (existsSync21(pkg)) {
+    if (existsSync22(pkg)) {
       try {
         const name = JSON.parse(readFileSync9(pkg, "utf8")).name;
         if (name === "@vosjs/cli") {
           const skills = join24(dir, "skills");
-          return existsSync21(skills) && statSync7(skills).isDirectory() ? skills : null;
+          return existsSync22(skills) && statSync7(skills).isDirectory() ? skills : null;
         }
       } catch {
       }
@@ -12225,7 +12678,7 @@ function npx() {
 function bundledChromium() {
   try {
     const p = chromium2.executablePath();
-    return p && existsSync22(p) ? p : null;
+    return p && existsSync23(p) ? p : null;
   } catch {
     return null;
   }
@@ -12234,7 +12687,7 @@ function probe2() {
   return probeBrowser({
     platform: process.platform,
     env: process.env,
-    exists: existsSync22,
+    exists: existsSync23,
     bundled: bundledChromium
   });
 }
@@ -12373,7 +12826,7 @@ async function cmdSetup(argv) {
   let rules = null;
   if (!noRules) {
     const file = rulesFileFor(root);
-    const existing = existsSync22(file) ? readFileSync10(file, "utf8") : null;
+    const existing = existsSync23(file) ? readFileSync10(file, "utf8") : null;
     const { text, changed } = applyRulesBlock(existing);
     if (changed) writeFileSync6(file, text);
     rules = { file, changed };
@@ -12487,7 +12940,7 @@ async function cmdWhoami(argv) {
 function cmdLogout(argv) {
   const { flags } = parseArgs(argv, BOOLEAN_FLAGS11);
   const r = reporterFor(flags);
-  const had = existsSync22(CREDENTIALS_PATH);
+  const had = existsSync23(CREDENTIALS_PATH);
   rmSync3(CREDENTIALS_PATH, { force: true });
   const envKey = Boolean(process.env.VOS_API_KEY?.trim());
   r.done(
@@ -12649,10 +13102,26 @@ Platform (vos.so) \u2014 fetch, edit, push, pull, repeat
   vos asset push <file...> [--folder <folderId|slug>]
             add files to your library: models, pictures and SVGs, fonts,
             HDR maps, sound, video, captions and recipes. The platform
-            reads each file and answers what it is and the name it is
-            stored under; the same bytes twice are the same file. Prints
-            the url a doc.json key takes. GET /api/limits lists the
-            kinds, their size caps and their daily rates
+            reads each file and answers what it is; the same bytes twice
+            are the same file. Prints, per file, what was read, its
+            asset:<id>, the url a doc.json key takes, and the line that
+            declares it in a program's "assets"
+  vos asset import <url> [--name <file>] [--folder <slug>]
+                         [--license <text>] [--attribution <text>]
+            fetch a file from an address and add it, with where it came
+            from kept beside it. Say the license: it is what lets the
+            next person use the file
+  vos assets ls [--kind <kind>] [--folder <slug>|none] [--q <text>]
+                [--sort recent|size|name] [--limit <n>]
+            what is in your library: id, kind, size, whether a program
+            uses it, and whether it is a library file or attached to a
+            document
+  vos assets usage
+            storage held, of how much, and the part in Trash; uploads in
+            the last 24 hours per kind against each daily rate
+  vos assets why <assetId>
+            every program that uses a file, and how (in what plays now,
+            in history, in a draft): why it is kept
   vos recipe push <file.md> --folder <folderId|slug>
   vos recipe push <file.md> --asset <assetId>
             put a recipe (a plain .md) on the shelf: --folder creates it
@@ -12904,7 +13373,7 @@ function takeStorageState(flags) {
   const raw = strFlag(flags, "storage-state");
   if (!raw) return void 0;
   const path = resolve15(raw);
-  if (!existsSync23(path))
+  if (!existsSync24(path))
     throw new UsageError(`--storage-state: no such file: ${path}`);
   return path;
 }
@@ -12917,7 +13386,7 @@ function takeSessionName(flags, storageState) {
     throw new UsageError(
       "--session and --storage-state are two doors to one take: a persistent profile cannot take a storage state. Pass one"
     );
-  if (!existsSync23(sessionDir(name)))
+  if (!existsSync24(sessionDir(name)))
     throw new UsageError(
       `no session "${name}". Make one: vos session open <url> --name ${name} (a Chrome window opens; sign in and close it)`
     );
@@ -13140,7 +13609,7 @@ ${lines.join("\n")}
   }
   const paths = takePaths(outDir);
   const prepare = async () => {
-    if (existsSync23(join26(outDir, "meta.json"))) {
+    if (existsSync24(join26(outDir, "meta.json"))) {
       const { prevDoc, kept } = await prepareReRecord(outDir);
       r.log(
         `note: re-recording ${outDir} \u2014 kept ${kept.length ? kept.join(", ") : "nothing"}` + (prevDoc ? "; apply the previous cut to the new footage with: vos plan " + outDir + " --reuse" : "")
@@ -13244,7 +13713,7 @@ async function cmdCreate2(argv) {
   const headers = takeHeaders(multi);
   const paths = takePaths(outDir);
   const prepare = async () => {
-    if (existsSync23(join26(outDir, "meta.json"))) {
+    if (existsSync24(join26(outDir, "meta.json"))) {
       const { prevDoc, kept } = await prepareReRecord(outDir);
       r.log(
         `note: re-recording ${outDir} \u2014 kept ${kept.length ? kept.join(", ") : "nothing"}` + (prevDoc ? "; apply the previous cut to the new footage with: vos plan " + outDir + " --reuse" : "")
@@ -13357,7 +13826,7 @@ async function cmdPlan(argv) {
   let reuse;
   if (flags.reuse === true) {
     const from = resolve15(strFlag(flags, "from") ?? join26(dir, PREV_DOC_NAME));
-    if (!existsSync23(from)) {
+    if (!existsSync24(from)) {
       throw new UsageError(
         `--reuse: ${from} does not exist \u2014 a re-record into this take writes doc.prev.json, or pass --from <doc.json>`
       );
@@ -13368,7 +13837,7 @@ async function cmdPlan(argv) {
     };
   }
   const style = await resolveStyleRef(flags);
-  const hasDoc = existsSync23(join26(dir, "doc.json"));
+  const hasDoc = existsSync24(join26(dir, "doc.json"));
   const backdrop = hasDoc ? null : await takeBackdrop(flags, r);
   const release = await releaseInputs(dir, flags, r, multi.with ?? []);
   const motionWanted = !hasDoc || flags.motion === true || flags.fresh === true;
@@ -13796,11 +14265,11 @@ async function resolveStyleRef(flags) {
 }
 async function resolveDocRef(ref, flags, what) {
   const styleRef = ref;
-  const file = existsSync23(styleRef) ? resolve15(
+  const file = existsSync24(styleRef) ? resolve15(
     styleRef,
-    existsSync23(join26(styleRef, "doc.json")) ? "doc.json" : ""
+    existsSync24(join26(styleRef, "doc.json")) ? "doc.json" : ""
   ) : null;
-  if (file && existsSync23(file)) {
+  if (file && existsSync24(file)) {
     return {
       from: file,
       doc: migrateHostedDoc5(
@@ -13915,7 +14384,7 @@ async function cmdOpen(argv) {
   if (!dir) throw new UsageError("vos open <take> [--studio <url>]");
   const r = createReporter(flags.json === true);
   const take = await loadTake(dir);
-  if (!existsSync23(take.paths.recording)) {
+  if (!existsSync24(take.paths.recording)) {
     throw new UsageError(`${dir} has no recording \u2014 re-run record`);
   }
   const studio = (strFlag(flags, "studio") ?? platformOrigin()).replace(
@@ -13957,8 +14426,8 @@ async function cmdJudge(argv) {
     );
   const r = createReporter(flags.json === true);
   const kitFile = target.endsWith("kit.json") ? target : join26(target, "kit.json");
-  if (!existsSync23(kitFile)) throw new UsageError(`${kitFile}: no kit manifest`);
-  if (!existsSync23(against))
+  if (!existsSync24(kitFile)) throw new UsageError(`${kitFile}: no kit manifest`);
+  if (!existsSync24(against))
     throw new UsageError(`${against}: no reference manifest`);
   const result = await judgeKit(kitFile, against, strFlag(flags, "out"));
   const verdicts = JSON.parse(await readFile15(result.verdictFile, "utf8")).verdicts;
@@ -14080,7 +14549,7 @@ async function cmdValidate(argv) {
   const target = positionals[0];
   if (!target) throw new UsageError("vos validate <actions.json|take>");
   const r = createReporter(flags.json === true);
-  const kitTarget = target.endsWith("kit.json") ? target : existsSync23(join26(target, "kit.json")) && !isTakeDir(target) ? join26(target, "kit.json") : null;
+  const kitTarget = target.endsWith("kit.json") ? target : existsSync24(join26(target, "kit.json")) && !isTakeDir(target) ? join26(target, "kit.json") : null;
   if (kitTarget) {
     const picture = flags.picture === true;
     const verdict = await validateKit(kitTarget, { picture });
@@ -14112,7 +14581,7 @@ async function cmdValidate(argv) {
     r.done({ valid: true, target }, `${target}: valid actions file`);
     return EXIT_OK;
   }
-  if (!isTakeDir(target) && existsSync23(join26(target, "config.json"))) {
+  if (!isTakeDir(target) && existsSync24(join26(target, "config.json"))) {
     const parsed = JSON.parse(
       await readFile15(join26(target, "config.json"), "utf8")
     );
@@ -14155,7 +14624,7 @@ async function cmdValidate(argv) {
   const take = await loadTake(target);
   const problems = [];
   const warnings = [];
-  if (!existsSync23(take.paths.recording)) {
+  if (!existsSync24(take.paths.recording)) {
     problems.push("missing recording (re-run record)");
   } else {
     const mismatch = containerMismatch(
@@ -14428,6 +14897,7 @@ async function run(argv) {
       case "folder":
         return await cmdFolder(rest);
       case "asset":
+      case "assets":
         return await cmdAsset(rest);
       case "recipe":
         return await cmdRecipe(rest);
@@ -14507,7 +14977,7 @@ async function cmdSession(argv) {
       if (!arg) throw new UsageError(usage);
       const bad = sessionNameVerdict(arg);
       if (bad) throw new UsageError(bad);
-      if (!existsSync23(sessionDir(arg)))
+      if (!existsSync24(sessionDir(arg)))
         throw new UsageError(`no session "${arg}" (vos session list)`);
       const summary3 = await summarizeSession(arg);
       const url = strFlag(flags, "url");
@@ -14607,4 +15077,4 @@ export {
   verbHelp,
   run
 };
-//# sourceMappingURL=chunk-C4P6MZJG.js.map
+//# sourceMappingURL=chunk-AKIPDSHE.js.map