@vosjs/cli 0.83.2 → 0.85.0

package/dist/{chunk-HDJFCTOG.js → chunk-NJBUBXFE.js}

@@ -148,9 +148,9 @@ function landedLines(l) {
 }
 
 // src/plugin/run.ts
-import { mkdir as mkdir13, readFile as readFile18, rm as rm6 } from "fs/promises";
-import { existsSync as existsSync30 } from "fs";
-import { dirname as dirname11, join as join33, resolve as resolve21 } from "path";
+import { mkdir as mkdir13, readFile as readFile19, rm as rm7 } from "fs/promises";
+import { existsSync as existsSync31 } from "fs";
+import { dirname as dirname12, join as join33, resolve as resolve22 } from "path";
 import {
   END_CARD_FROM as END_CARD_FROM2,
   docOutputDuration as docOutputDuration5,
@@ -4157,6 +4157,7 @@ import {
   sameMedia,
   spanOutputExtent as spanOutputExtent3
 } from "@vosjs/studio-core";
+import { rankBeds, trackBySlug } from "@vosjs/shared/music";
 
 // src/plugin/captionFit.ts
 var CAPTION_MAX = 3;
@@ -4289,10 +4290,30 @@ function proposeTransitions(input, kind) {
   }
   return { doc, count, skipped };
 }
-function pickTrack(catalog, ask) {
+function pickBed(catalog, ask, film) {
   if (!catalog || !ask || off(ask)) return null;
   const want = ask.trim().toLowerCase();
-  return catalog.tracks.find((t) => t.slug.toLowerCase() === want) ?? catalog.tracks.find((t) => (t.mood ?? "").toLowerCase() === want) ?? null;
+  const exact = trackBySlug(catalog.tracks, want);
+  if (exact) return { track: exact, via: "slug", ranked: null, runnerUp: null };
+  if (film) {
+    const oneWord = !/\s/.test(want);
+    const ranked = rankBeds(catalog.tracks, {
+      ...film,
+      ...oneWord ? { mood: want } : { words: want }
+    }).filter((r) => r.score !== null);
+    const named = oneWord ? catalog.tracks.some(
+      (t) => (t.mood ?? "").toLowerCase() === want || (t.tags ?? []).some((x) => x.toLowerCase() === want)
+    ) : ranked.some((r) => (r.scores?.fit ?? 0) > 0);
+    if (!named || !ranked.length) return null;
+    return {
+      track: ranked[0].track,
+      via: "ranked",
+      ranked: ranked[0],
+      runnerUp: ranked[1] ?? null
+    };
+  }
+  const first = catalog.tracks.find((t) => (t.mood ?? "").toLowerCase() === want) ?? null;
+  return first ? { track: first, via: "first", ranked: null, runnerUp: null } : null;
 }
 function clickTimes(doc, range2) {
   const rated = ratedSegments4(doc);
@@ -4533,26 +4554,32 @@ function proposeMotion(input, opts) {
   const clips = (doc.audio ?? []).filter(
     (a) => a.id !== BED_ID && !a.id.startsWith(CLICK_ID_PREFIX)
   );
-  const track = pickTrack(catalog, launch.music);
-  if (track) {
+  const picked = pickBed(catalog, launch.music, opts.film);
+  if (picked) {
+    const { track } = picked;
     const hasMic = !!doc.source.micKey;
     const fadeOut = Math.min(2.5, length * 0.15);
+    const place2 = picked.ranked?.placement ?? null;
+    const start = place2 ? place2.in : 0;
+    const covers = track.duration - start >= length;
     clips.push({
       id: BED_ID,
       key: track.url,
       name: track.title,
       start: 0,
-      in: 0,
-      out: Math.min(track.duration, length),
+      in: start,
+      out: place2 ? place2.out : Math.min(track.duration, length),
       duration: track.duration,
       gain: hasMic ? 0.35 : 0.5,
-      fadeIn: 0.6,
+      fadeIn: start > 0 ? 0.8 : 0.6,
       fadeOut,
-      loop: track.duration < length,
-      loopLen: track.duration < length ? Math.round(length * 1e3) / 1e3 : void 0,
+      loop: place2 ? place2.loop : !covers,
+      loopLen: place2 ? place2.loopLen : !covers ? Math.round(length * 1e3) / 1e3 : void 0,
       duck: hasMic
     });
-    notes.push(`bed ${track.slug}`);
+    notes.push(
+      picked.via === "ranked" && picked.ranked ? `bed ${track.slug} (${picked.ranked.reasons.slice(0, 2).join(", ") || "ranked"}${picked.runnerUp ? `; runner-up ${picked.runnerUp.slug}` : ""})` : `bed ${track.slug}`
+    );
   } else if (launch.music && !off(launch.music)) {
     skipped.push(
       `music "${launch.music}" is not a catalog track or mood${catalog ? "" : " (the catalog could not be read)"}`
@@ -6039,14 +6066,14 @@ function chromeTree(rows, pid) {
 }
 function readChromeTree(pid) {
   if (process.platform === "win32") return Promise.resolve(null);
-  return new Promise((resolve22) => {
+  return new Promise((resolve23) => {
     execFile2(
       "ps",
       ["-A", "-o", "pid=", "-o", "ppid=", "-o", "command="],
       { maxBuffer: 16 * 1024 * 1024, timeout: 5e3 },
       (err, stdout) => {
-        if (err) resolve22(null);
-        else resolve22(chromeTree(parseProcessTable(stdout), pid));
+        if (err) resolve23(null);
+        else resolve23(chromeTree(parseProcessTable(stdout), pid));
       }
     );
   });
@@ -6148,7 +6175,7 @@ function enterPressed() {
     } };
   const rl = createInterface({ input: process.stdin });
   const pressed = new Promise(
-    (resolve22) => rl.once("line", () => resolve22())
+    (resolve23) => rl.once("line", () => resolve23())
   );
   return { pressed, close: () => rl.close() };
 }
@@ -6321,14 +6348,14 @@ async function openSessionWindow(opts) {
   const child = spawn(exe, args, { stdio: "ignore" });
   let failed = null;
   let code = null;
-  const exited = new Promise((resolve22) => {
+  const exited = new Promise((resolve23) => {
     child.once("exit", (c) => {
       code = c;
-      resolve22();
+      resolve23();
     });
     child.once("error", (e) => {
       failed = e;
-      resolve22();
+      resolve23();
     });
   });
   try {
@@ -6776,12 +6803,13 @@ async function encodeRecording(browser, takeDir, onProgress) {
 // src/plugin/plan.ts
 import { existsSync as existsSync11 } from "fs";
 import { readFile as readFile9 } from "fs/promises";
-import { join as join11 } from "path";
+import { basename, join as join11 } from "path";
 import {
   DEFAULT_FRAME_STYLE,
   STYLE_FIELDS,
   copyLayout,
   copyStyle,
+  filmSummaryOf,
   isRejected,
   isStageClip,
   layoutOf,
@@ -7382,7 +7410,10 @@ async function planTake(dir, opts = {}) {
   withPageSound(doc, meta.media);
   let motion;
   if (opts.motion && (fresh || opts.motion.again)) {
-    const proposed = proposeMotion(doc, opts.motion);
+    const proposed = proposeMotion(doc, {
+      ...opts.motion,
+      film: filmSummaryOf(doc, { seed: basename(join11(dir)) })
+    });
     doc = proposed.doc;
     motion = {
       notes: proposed.notes,
@@ -7415,14 +7446,14 @@ import { createHash } from "crypto";
 import { existsSync as existsSync13, readFileSync as readFileSync3, readdirSync as readdirSync2 } from "fs";
 import { readFile as readFile11 } from "fs/promises";
 import { createInterface as createInterface2 } from "readline/promises";
-import { basename as basename2, join as join14 } from "path";
+import { basename as basename3, join as join14 } from "path";
 import { lowerToComposition as lowerToComposition3, migrateHostedDoc as migrateHostedDoc2 } from "@vosjs/studio-core";
 
 // src/plugin/takeScript.ts
 import { existsSync as existsSync12 } from "fs";
 import { readFile as readFile10, writeFile as writeFile6 } from "fs/promises";
 import { readFileSync as readFileSync2 } from "fs";
-import { basename, join as join12 } from "path";
+import { basename as basename2, join as join12 } from "path";
 function scriptFromText(text) {
   try {
     const v = JSON.parse(text);
@@ -7468,7 +7499,7 @@ function publicPeers(peers) {
     if (!p || typeof p !== "object") return p;
     const peer = p;
     if (typeof peer.storageState !== "string") return peer;
-    return { ...peer, storageState: basename(peer.storageState) };
+    return { ...peer, storageState: basename2(peer.storageState) };
   });
 }
 function embedScript(doc, dir) {
@@ -7926,10 +7957,19 @@ function printChanges(r, changes, protectedIds) {
     r.event({ event: "protected", nodes: protectedIds });
   }
 }
+var DESCRIPTION_MAX = 500;
+function descriptionProblem(desc) {
+  if (desc === void 0) return null;
+  if (!desc.trim())
+    return "--desc is empty: give the sentence that says what the video shows";
+  if (desc.length > DESCRIPTION_MAX)
+    return `--desc is ${desc.length} characters and a vos keeps ${DESCRIPTION_MAX}: shorten it`;
+  return null;
+}
 function takePushRefusal(ask) {
   if (ask.programOnly.length) {
     const list = ask.programOnly.map((f) => `--${f}`).join(", ");
-    return `${list} ${ask.programOnly.length > 1 ? "belong" : "belongs"} to a PROGRAM push (a config.json); a take push reads --vos, --title, --label, --note, --folder, --override and --yes`;
+    return `${list} ${ask.programOnly.length > 1 ? "belong" : "belongs"} to a PROGRAM push (a config.json); a take push reads --vos, --title, --desc, --prompt, --label, --note, --folder, --override and --yes`;
   }
   if (ask.vos !== void 0 && ask.trackedVosId !== null && ask.trackedVosId !== ask.vos)
     return `this take tracks vos ${ask.trackedVosId} (its vos.json), not ${ask.vos}. Drop --vos to push there, or remove vos.json to adopt ${ask.vos} instead`;
@@ -8089,7 +8129,7 @@ async function pushTake(dir, flags, r) {
   const lowered = lowerToComposition3(docForPush);
   const config = { ...lowered.config, data: lowered.data };
   if (!state) {
-    const title = flags.title ?? `Take ${basename2(dir)} ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`;
+    const title = flags.title ?? `Take ${basename3(dir)} ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`;
     const slug = `${title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "take"}-${Date.now().toString(36)}`;
     const created = await api(ctx, "/vos", {
       method: "POST",
@@ -8104,7 +8144,8 @@ async function pushTake(dir, flags, r) {
         ...folderId ? { folderId } : {},
         ...flags.label ? { label: flags.label } : {},
         ...flags.note ? { note: flags.note } : {},
-        ...flags.prompt ? { prompt: flags.prompt } : {}
+        ...flags.prompt ? { prompt: flags.prompt } : {},
+        ...flags.description ? { description: flags.description } : {}
       }
     });
     if (created.status !== 201) {
@@ -8155,14 +8196,18 @@ async function pushTake(dir, flags, r) {
     );
   }
   serverWarnings(pushed.json, (l) => r.log(l));
-  if (flags.prompt) {
+  const words2 = {
+    ...flags.prompt ? { prompt: flags.prompt } : {},
+    ...flags.description ? { description: flags.description } : {}
+  };
+  if (Object.keys(words2).length) {
     const set = await api(ctx, `/vos/${state.vosId}`, {
       method: "PATCH",
-      body: { prompt: flags.prompt }
+      body: words2
     });
     if (set.status !== 200)
       r.warn(
-        `could not set the prompt (${set.status}): ${String(set.json.error ?? "")}${detailLine(set.json)}`
+        `could not set the ${Object.keys(words2).join(" and ")} (${set.status}): ${String(set.json.error ?? "")}${detailLine(set.json)}`
       );
   }
   const version = pushed.json.version;
@@ -8276,7 +8321,7 @@ async function pullTake(dir, flags, r) {
   const doc = hostedDoc;
   const localRecording = takeMediaFile(dir, "recording", RECORDING_NAME);
   if (existsSync13(localRecording)) {
-    doc.source.videoKey = basename2(localRecording);
+    doc.source.videoKey = basename3(localRecording);
   }
   await writeJson(join14(dir, "doc.json"), doc, true);
   const media = flags.media ? await pullMedia(ctx, dir, doc, r.log) : void 0;
@@ -8376,10 +8421,11 @@ async function pushTakeClaimable(dir, flags, r) {
   }
   const lowered = lowerToComposition3(docForPush);
   const config = { ...lowered.config, data: lowered.data };
-  const title = (flags.title ?? (state?.title ? `${state.title} remix` : basename2(dir))).slice(0, 200);
+  const title = (flags.title ?? (state?.title ? `${state.title} remix` : basename3(dir))).slice(0, 200);
   const body = { title, config, doc: docForPush };
   if (state?.vosId) body.remixOfId = state.vosId;
   if (flags.prompt) body.prompt = flags.prompt;
+  if (flags.description) body.description = flags.description;
   if (flags.share) body.share = true;
   const origin = platformOrigin(flags);
   r.log(`creating a claimable push of ${title}\u2026`);
@@ -8403,7 +8449,7 @@ async function pushTakeClaimable(dir, flags, r) {
 import { existsSync as existsSync15 } from "fs";
 import { mkdir as mkdir7, readFile as readFile12 } from "fs/promises";
 import { createInterface as createInterface3 } from "readline/promises";
-import { basename as basename4, dirname as dirname2, join as join15 } from "path";
+import { basename as basename5, dirname as dirname2, join as join15 } from "path";
 import {
   CURRENT_CONFIG_VERSION,
   migrateConfig,
@@ -8412,7 +8458,7 @@ import {
 import { lowerProgramDoc, migrateHostedDoc as migrateHostedDoc3 } from "@vosjs/studio-core";
 
 // src/plugin/programFiles.ts
-import { basename as basename3, extname as extname2, relative as relative2 } from "path";
+import { basename as basename4, extname as extname2, relative as relative2 } from "path";
 import { existsSync as existsSync14, realpathSync as realpathSync2 } from "fs";
 function isLocalName(value) {
   if (/^(https?:|data:|blob:|asset:|media:)/.test(value)) return false;
@@ -8423,7 +8469,7 @@ function isLocalName(value) {
 }
 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 = basename3(file, extname2(file)).replace(/[^A-Za-z0-9_]/g, "_").replace(/^(?=[0-9])/, "_") || "file";
+  const stem = basename4(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);
@@ -8842,7 +8888,7 @@ 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` : basename4(source).replace(/\.json$/i, "") || "vos program";
+    const fallback = state?.title ? `${state.title} remix` : basename5(source).replace(/\.json$/i, "") || "vos program";
     const title2 = (strFlag(flags, "title") ?? fallback).slice(0, 100);
     const files2 = await collectFiles(config, programDoc, dir, r);
     let uploadToken;
@@ -8918,9 +8964,11 @@ with their key: vos push ${source} --vos ${String(created2.id ?? "<id>")}`
   });
   if (pushTarget.kind === "refuse") throw new UsageError(pushTarget.why);
   const vosId = pushTarget.kind === "version" ? pushTarget.vosId : null;
-  if (vosId && (desc || tagsFlag || folderRef)) {
+  const descProblem = descriptionProblem(desc);
+  if (descProblem) throw new UsageError(descProblem);
+  if (vosId && (tagsFlag || folderRef)) {
     throw new UsageError(
-      "--desc/--tags/--folder apply when CREATING a vos. On an existing one: vos folder move <id> --to <folder> for filing; edit title/description/tags on vos.so"
+      "--tags/--folder apply when CREATING a vos. On an existing one: vos folder move <id> --to <folder> for filing; edit tags on vos.so"
     );
   }
   if (vosId) {
@@ -8966,13 +9014,18 @@ 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, say(r));
-    if (prompt) {
+    const words2 = {
+      ...prompt ? { prompt } : {},
+      ...desc ? { description: desc } : {}
+    };
+    if (Object.keys(words2).length) {
       const set = await apiJson(origin, `/api/vos/${vosId}`, {
         method: "PATCH",
         key,
-        body: { prompt }
+        body: words2
       });
-      if (set.status !== 200) r.warn(apiError("set the prompt", set));
+      if (set.status !== 200)
+        r.warn(apiError(`set the ${Object.keys(words2).join(" and ")}`, set));
     }
     const version = res.body.version ?? {};
     if (typeof version.id === "string") {
@@ -9009,7 +9062,7 @@ ${landedLines(landed2)}` : "")
     return EXIT_OK;
   }
   const remixOfId = pushTarget.kind === "create" ? pushTarget.remixOfId : void 0;
-  const fallbackTitle = state?.title ? `${state.title} remix` : basename4(source).replace(/\.json$/i, "") || "vos remix";
+  const fallbackTitle = state?.title ? `${state.title} remix` : basename5(source).replace(/\.json$/i, "") || "vos remix";
   const title = (strFlag(flags, "title") ?? fallbackTitle).slice(0, 100);
   const pushFolder = folderRef ? await resolvePushFolder(origin, key, folderRef) : void 0;
   const folderId = pushFolder?.id;
@@ -9335,7 +9388,7 @@ async function writeProgramDoc(dir, hosted) {
 // src/plugin/asset.ts
 import { createHash as createHash2 } from "crypto";
 import { readFileSync as readFileSync4 } from "fs";
-import { basename as basename5 } from "path";
+import { basename as basename6 } from "path";
 
 // src/plugin/assetWords.ts
 function hostedFile(raw) {
@@ -9600,7 +9653,7 @@ async function cmdPush(argv) {
   const folder = folderRef ? resolveFolder(await listFolders(origin, key), folderRef) : null;
   const uploaded = [];
   for (const file of positionals) {
-    const name = basename5(file);
+    const name = basename6(file);
     const body = readFileSync4(file);
     const media = resolveMediaType({
       head: body.subarray(0, MEDIA_HEAD_BYTES),
@@ -10118,7 +10171,7 @@ function trackingCwd(vosId) {
 
 // src/plugin/buildProgram.ts
 import { readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "fs";
-import { basename as basename6, dirname as dirname3, join as join17, resolve as resolve8 } from "path";
+import { basename as basename7, dirname as dirname3, join as join17, resolve as resolve8 } from "path";
 import { pathToFileURL as pathToFileURL2 } from "url";
 import { parse } from "acorn";
 import { fullAncestor } from "acorn-walk";
@@ -10326,7 +10379,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, basename6(file), text);
+  const built = buildProgram(program, basename7(file), text);
   for (const p of built.problems) r.log(`error ${p.fn}: ${p.message}`);
   if (built.problems.length) {
     r.done(
@@ -10561,7 +10614,7 @@ import { findFontFamily as findFontFamily3 } from "@vosjs/shared";
 import { existsSync as existsSync18, readFileSync as readFileSync6, readdirSync as readdirSync3, statSync as statSync5 } from "fs";
 import { createServer as createServer2 } from "http";
 import { createRequire } from "module";
-import { basename as basename7, extname as extname3, join as join19 } from "path";
+import { basename as basename8, 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;
@@ -10841,7 +10894,7 @@ async function readRemotion(dir, log) {
     const sources = sourceTexts(dir);
     const publicDir = join19(dir, "public");
     const media = tree.audio.map((a) => {
-      const name = basename7(a.src.split("?")[0]);
+      const name = basename8(a.src.split("?")[0]);
       const local = existsSync18(join19(publicDir, name)) ? `public/${name}` : a.src;
       return {
         kind: "audio",
@@ -11344,7 +11397,7 @@ async function readInventory(source, opts) {
 // src/plugin/portScaffold.ts
 import { spawnSync as spawnSync3 } from "child_process";
 import { copyFileSync, existsSync as existsSync20, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
-import { basename as basename8, dirname as dirname6, join as join21, resolve as resolve11 } from "path";
+import { basename as basename9, dirname as dirname6, join as join21, resolve as resolve11 } from "path";
 import { findFontFamily as findFontFamily4, fontFaceUrl, nearestFontWeight } from "@vosjs/shared";
 
 // src/plugin/painterLib.ts
@@ -11754,7 +11807,7 @@ function planScaffold(inv, opts) {
   const copies = [];
   inv.media.filter((m) => m.kind === "audio" && m.src).forEach((m, i) => {
     const from = resolve11(opts.sourceDir, m.src);
-    const name = basename8(from);
+    const name = basename9(from);
     if (!existsSync20(from)) {
       report.push(
         `- the audio ${m.src} is not in the source folder; add it to doc.json by hand`
@@ -11907,7 +11960,7 @@ ${sceneTodos}${springHint}
 }
 function reportText(inv, r) {
   const lines = [
-    `# Port report: ${inv.source === "." && inv.root ? basename8(inv.root) : inv.source}`,
+    `# Port report: ${inv.source === "." && inv.root ? basename9(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}\`.`,
     "",
@@ -12071,11 +12124,11 @@ function scaffoldSourceDir(inv) {
 // src/plugin/recipe.ts
 import { createHash as createHash3 } from "crypto";
 import { readFileSync as readFileSync9 } from "fs";
-import { basename as basename9 } from "path";
+import { basename as basename10 } 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 = basename9(file);
+  const name = basename10(file);
   if (!/\.md$/i.test(name)) {
     throw new UsageError(`a recipe is a markdown file \u2014 ${name} is not .md`);
   }
@@ -13129,8 +13182,8 @@ async function cmdActions(argv) {
     if (!m) throw new UsageError("--viewport expects WxH, e.g. 1280x720");
     viewport = { width: Number(m[1]), height: Number(m[2]) };
   }
-  const { readFile: readFile19 } = await import("fs/promises");
-  const text = await readFile19(resolve14(input), "utf8");
+  const { readFile: readFile20 } = await import("fs/promises");
+  const text = await readFile20(resolve14(input), "utf8");
   const { records, problems } = parseAgentBrowserLog(text);
   for (const p of problems) r.log(`  ${p}`);
   const result = convertAgentBrowser(records, {
@@ -13167,9 +13220,9 @@ function summary2(result) {
 }
 async function cmdActionsScript(input, flags) {
   const r = createReporter(flags.json === true);
-  const { readFile: readFile19 } = await import("fs/promises");
+  const { readFile: readFile20 } = await import("fs/promises");
   const { shotList, formatShotList } = await import("./shotList-PL7XP6AC.js");
-  const raw = JSON.parse(await readFile19(resolve14(input), "utf8"));
+  const raw = JSON.parse(await readFile20(resolve14(input), "utf8"));
   const errors = validateActions(raw);
   if (errors.length) throw new UsageError(`${input}:
   ${errors.join("\n  ")}`);
@@ -13181,7 +13234,7 @@ async function cmdActionsScript(input, flags) {
 // src/plugin/ingest.ts
 import { existsSync as existsSync22 } from "fs";
 import { copyFile, mkdir as mkdir8, readFile as readFile13, stat as stat2 } from "fs/promises";
-import { basename as basename10, join as join23, resolve as resolve15 } from "path";
+import { basename as basename11, join as join23, resolve as resolve15 } from "path";
 
 // src/plugin/traceInflate.ts
 import { inflateRawSync } from "zlib";
@@ -13308,7 +13361,7 @@ async function copyRecording(src, dest, ext2) {
   }
 }
 async function readTraceFile(path, offsetMs) {
-  const kind = traceKindOf(basename10(path));
+  const kind = traceKindOf(basename11(path));
   if (!kind) {
     throw new UsageError(
       `${path}: not a trace the recorder reads (trace.zip, .trace, .jsonl, .json or .csv)`
@@ -13329,7 +13382,7 @@ async function readTraceFile(path, offsetMs) {
     return cursorFromPlaywrightTrace(text2, { offsetMs });
   }
   const text = await readFile13(path, "utf8");
-  return cursorFromTrace(basename10(path), text, { offsetMs });
+  return cursorFromTrace(basename11(path), text, { offsetMs });
 }
 function parseViewport(v) {
   if (!v) return null;
@@ -13360,7 +13413,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 ${basename10(videoPath)}\u2026`);
+  r.log(`probing ${basename11(videoPath)}\u2026`);
   const probed = await probeVideoFile(videoPath);
   if (!(probed.durationMs > 0)) {
     throw new UsageError(
@@ -13409,13 +13462,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 ${basename10(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 ${basename11(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: basename10(recording),
+      recording: basename11(recording),
       durationMs: probed.durationMs,
       width: probed.width,
       height: probed.height,
@@ -13424,7 +13477,7 @@ async function cmdIngest(argv) {
       hasAudio: probed.hasAudio,
       remuxed,
       cursor: trace ? {
-        file: basename10(cursorPath),
+        file: basename11(cursorPath),
         kind: trace.kind,
         events: events.length,
         clicks,
@@ -13436,7 +13489,7 @@ async function cmdIngest(argv) {
       backdrop: plan.backdrop ?? null,
       as: footage ? "footage" : "take"
     },
-    `Ingested ${basename10(videoPath)} \u2192 ${outDir}/${basename10(recording)} (${facts})
+    `Ingested ${basename11(videoPath)} \u2192 ${outDir}/${basename11(recording)} (${facts})
   ${opened}
   ${cursorLine}
   ${next}`
@@ -13448,7 +13501,7 @@ async function cmdIngest(argv) {
 import { createRequire as createRequire2 } from "module";
 import { existsSync as existsSync23 } from "fs";
 import { mkdir as mkdir9, readFile as readFile14, stat as stat3, writeFile as writeFile7 } from "fs/promises";
-import { basename as basename11, dirname as dirname8, extname as extname4, join as join24, resolve as resolve16 } from "path";
+import { basename as basename12, dirname as dirname8, extname as extname4, join as join24, resolve as resolve16 } from "path";
 import { ALL_FORMATS as ALL_FORMATS2, FilePathSource as FilePathSource2, Input as Input2 } from "mediabunny";
 
 // src/plugin/videoChecks.ts
@@ -13970,7 +14023,7 @@ async function checkVideo(browser, file, outDir) {
     void page.evaluate(decodeInPage, {
       mbCode: await mediabunnyBundle(),
       meterSrc: String(createLoudnessMeter),
-      videoUrl: `/${encodeURIComponent(basename11(file))}`,
+      videoUrl: `/${encodeURIComponent(basename12(file))}`,
       sampleFps,
       thumbW: side(facts.width),
       thumbH: side(facts.height),
@@ -14078,7 +14131,7 @@ async function cmdCheckVideo(argv) {
   const r = createReporter(flags.json === true);
   const strict = flags.strict === true;
   const outDir = resolve16(
-    strFlag(flags, "out") ?? join24(dirname8(file), `${basename11(file, extname4(file))}-check`)
+    strFlag(flags, "out") ?? join24(dirname8(file), `${basename12(file, extname4(file))}-check`)
   );
   const browser = await launchBrowser();
   try {
@@ -14096,7 +14149,7 @@ async function cmdCheckVideo(argv) {
 import { existsSync as existsSync26, readdirSync as readdirSync5, statSync as statSync7 } from "fs";
 import { copyFile as copyFile3, mkdir as mkdir11, readFile as readFile17, rm as rm4 } from "fs/promises";
 import {
-  basename as basename13,
+  basename as basename14,
   dirname as dirname9,
   isAbsolute as isAbsolute4,
   join as join27,
@@ -14127,13 +14180,15 @@ import {
   writeFile as writeFile8
 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
-import { basename as basename12, isAbsolute as isAbsolute3, join as join25, relative as relative4, resolve as resolve17, sep as sep3 } from "path";
+import { basename as basename13, isAbsolute as isAbsolute3, join as join25, relative as relative4, resolve as resolve17, sep as sep3 } from "path";
+import { rankBeds as rankBeds2 } from "@vosjs/shared/music";
 import {
   NORMALIZE_MAX_LUFS as NORMALIZE_MAX_LUFS2,
   NORMALIZE_MIN_LUFS as NORMALIZE_MIN_LUFS2,
   clipGain as clipGain2,
   docMediaList,
   docOutputDuration as docOutputDuration3,
+  filmSummaryOf as filmSummaryOf2,
   findStep as findStep2,
   ratedSegments as ratedSegments7,
   resolveAnchor as resolveAnchor4
@@ -14442,7 +14497,7 @@ async function measureInBrowser(path) {
   const bytes = await readFile15(path);
   if (bytes.length > BROWSER_DECODE_MAX_BYTES)
     throw new Error(
-      `${basename12(path)} is ${Math.round(bytes.length / 1048576)} MB, past the ${BROWSER_DECODE_MAX_BYTES / 1048576} MB the browser decode takes whole`
+      `${basename13(path)} is ${Math.round(bytes.length / 1048576)} MB, past the ${BROWSER_DECODE_MAX_BYTES / 1048576} MB the browser decode takes whole`
     );
   const browser = await launchBrowser();
   try {
@@ -14546,12 +14601,12 @@ async function resolveTrack(dir, ref, flags, dryRun) {
   if (existsSync24(local)) {
     const rel = relative4(resolve17(dir), local);
     const inside = !!rel && !rel.startsWith(`..${sep3}`) && rel !== ".." && !isAbsolute3(rel);
-    const key = inside ? rel.split(sep3).join("/") : `music/${basename12(local)}`;
+    const key = inside ? rel.split(sep3).join("/") : `music/${basename13(local)}`;
     if (!inside && !dryRun) {
       await mkdir10(join25(dir, "music"), { recursive: true });
       await copyFile2(local, join25(dir, key));
     }
-    return { path: local, key, name: basename12(local) };
+    return { path: local, key, name: basename13(local) };
   }
   const origin = platformOrigin({
     origin: strFlag(flags, "origin"),
@@ -14566,7 +14621,7 @@ async function resolveTrack(dir, ref, flags, dryRun) {
   const res = await fetch(track.url);
   if (!res.ok) throw new Error(`GET ${track.url} answered ${res.status}`);
   const tmp = await mkdtemp(join25(tmpdir2(), "vos-score-"));
-  const path = join25(tmp, basename12(new URL(track.url).pathname) || "track");
+  const path = join25(tmp, basename13(new URL(track.url).pathname) || "track");
   await writeFile8(path, new Uint8Array(await res.arrayBuffer()));
   return {
     path,
@@ -14576,7 +14631,7 @@ async function resolveTrack(dir, ref, flags, dryRun) {
   };
 }
 var BOOLEAN_FLAGS12 = /* @__PURE__ */ new Set(["json", "help", "dry-run"]);
-var USAGE2 = "vos score <take> --track <slug|file> [--at <step id|output seconds>] [--gain 0..1] [--normalize <lufs|off>] [--fade-in <s>] [--fade-out <s>] [--dry-run] [--json]";
+var USAGE2 = 'vos score <take> --track <slug|file|best> [--at <step id|output seconds>] [--mood <slug|tag>] [--words "\u2026"] [--gain 0..1] [--normalize <lufs|off>] [--fade-in <s>] [--fade-out <s>] [--dry-run] [--json]';
 async function cmdScore(argv) {
   const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS12);
   const dir = positionals[0];
@@ -14603,8 +14658,39 @@ async function cmdScore(argv) {
     throw new UsageError(`${dir} has no doc.json; run vos plan first`);
   const doc = take.doc;
   const atRaw = strFlag(flags, "at");
-  const at2 = atRaw !== void 0 ? resolveAt(doc, atRaw) : null;
-  const track = await resolveTrack(dir, trackRef, flags, dryRun);
+  let at2 = atRaw !== void 0 ? resolveAt(doc, atRaw) : null;
+  let chosen = trackRef;
+  if (trackRef === "best") {
+    const origin = platformOrigin({
+      origin: strFlag(flags, "origin"),
+      api: strFlag(flags, "api")
+    });
+    const catalog = await fetchMusicCatalog(origin);
+    const film2 = filmSummaryOf2(doc, {
+      seed: readSyncState(dir)?.vosId ?? basename13(resolve17(dir)),
+      ...at2 ? { payoff: at2.at } : {},
+      mood: strFlag(flags, "mood"),
+      words: strFlag(flags, "words")
+    });
+    const ranked = rankBeds2(catalog.tracks, film2).filter(
+      (x) => x.score !== null
+    );
+    const best = ranked[0];
+    if (!best)
+      throw new UsageError(
+        `no bed in the library fits this ${film2.duration.toFixed(1)}s film (every track refused); compose a score instead, or name a track with --track <slug>`
+      );
+    chosen = best.slug;
+    if (!at2 && film2.payoff !== void 0)
+      at2 = {
+        at: film2.payoff,
+        via: `the film's payoff (${film2.payoff.toFixed(2)}s)`
+      };
+    r.log(
+      `picked ${best.slug} (${best.reasons.join("; ") || "ranked first"})${ranked[1] ? `; runner-up ${ranked[1].slug}` : ""}`
+    );
+  }
+  const track = await resolveTrack(dir, chosen, flags, dryRun);
   let measured;
   try {
     r.log(`measuring ${track.name}\u2026`);
@@ -16198,7 +16284,7 @@ function joinDocs(parts, opts = {}) {
           {
             id,
             key: d.source.videoKey,
-            name: basename13(part.file.path),
+            name: basename14(part.file.path),
             start: round33(at2.start),
             in: round33(seg.in),
             out: round33(seg.out),
@@ -16443,7 +16529,7 @@ async function cmdJoin(argv) {
       const remuxed = await copyRecording(c.from, to, c.remux);
       if (!remuxed && c.remux !== "mov")
         plan.notes.push(
-          `could not read ${basename13(c.from)}'s audio in Node, so it was copied as it is; its length comes from the container`
+          `could not read ${basename14(c.from)}'s audio in Node, so it was copied as it is; its length comes from the container`
         );
     } else await copyFile3(c.from, to);
   }
@@ -16817,7 +16903,7 @@ async function cmdTakeInfo(argv) {
 // src/plugin/audio.ts
 import { mkdtemp as mkdtemp2, rm as rm5, writeFile as writeFile9 } from "fs/promises";
 import { tmpdir as tmpdir3 } from "os";
-import { basename as basename14, join as join29 } from "path";
+import { basename as basename15, join as join29 } from "path";
 import { clipGain as clipGain3 } from "@vosjs/studio-core";
 var USAGE4 = "vos audio measure <take> [--json]";
 async function fileFor(dir, key, fetchImpl) {
@@ -16830,7 +16916,7 @@ async function fileFor(dir, key, fetchImpl) {
     const res = await fetchImpl(key);
     if (!res.ok) return { skipped: `GET ${key} answered ${res.status}` };
     const tmp = await mkdtemp2(join29(tmpdir3(), "vos-audio-"));
-    const path = join29(tmp, basename14(new URL(key).pathname) || "audio");
+    const path = join29(tmp, basename15(new URL(key).pathname) || "audio");
     await writeFile9(path, new Uint8Array(await res.arrayBuffer()));
     return { path, cleanup: () => rm5(tmp, { recursive: true, force: true }) };
   }
@@ -16910,10 +16996,238 @@ async function cmdAudio(argv) {
   return failed.length ? EXIT_ERROR : EXIT_OK;
 }
 
+// src/plugin/musicCmd.ts
+import { existsSync as existsSync27, readFileSync as readFileSync10, statSync as statSync8 } from "fs";
+import { basename as basename16, resolve as resolve20 } from "path";
+import { rankBeds as rankBeds3, trackBySlug as trackBySlug2 } from "@vosjs/shared/music";
+import { filmSummaryOf as filmSummaryOf3, musicSlugsOfDoc } from "@vosjs/studio-core";
+var BOOLEAN_FLAGS14 = /* @__PURE__ */ new Set([
+  "json",
+  "help",
+  "loops",
+  "voice",
+  "no-voice",
+  "fade-in"
+]);
+var MULTI_FLAGS3 = /* @__PURE__ */ new Set(["like"]);
+var USAGE5 = 'vos music ls [--mood <slug>] [--vocals none|chops|lead] [--loops] [--bpm <lo>-<hi>] [--min-length <s>] [--q <words>] [--json]\nvos music pick <take|config.json> [--at <step id|seconds>] [--mood <slug|tag>] [--words "\u2026"] [--voice|--no-voice] [--like <vos id|slug>]... [--top <n>] [--json]';
+var mmss = (s) => {
+  const whole = Math.round(s);
+  return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}`;
+};
+var VOCAL_WORDS = {
+  none: "no vocals",
+  chops: "vocal chops",
+  lead: "sung lead"
+};
+function trackLine(t) {
+  const bpm = t.bpm === null || t.bpm === void 0 ? "\u2014" : `${t.bpm} bpm${t.beatConfidence === "low" ? "?" : t.beatConfidence === "confirmed" ? "" : ""}`;
+  return [
+    t.slug.padEnd(26),
+    (t.mood ?? "").padEnd(10),
+    mmss(t.duration).padStart(5),
+    bpm.padStart(10),
+    VOCAL_WORDS[t.vocals ?? "none"].padEnd(11),
+    t.loops ? "loops" : "     ",
+    t.description ? JSON.stringify(t.description) : ""
+  ].join("  ");
+}
+function bpmRange(raw) {
+  if (!raw) return null;
+  const m = /^(\d+(?:\.\d+)?)\s*-\s*(\d+(?:\.\d+)?)$/.exec(raw.trim());
+  if (m) return [Number(m[1]), Number(m[2])];
+  const one = Number(raw);
+  if (Number.isFinite(one)) return [one, Infinity];
+  throw new UsageError(`--bpm expects <lo>-<hi>, got "${raw}"`);
+}
+function filterTracks(tracks, f) {
+  const q = f.q?.toLowerCase().trim();
+  const words2 = q ? q.split(/\s+/).filter(Boolean) : [];
+  return tracks.filter((t) => {
+    if (t.removedAt) return false;
+    if (f.mood && (t.mood ?? "").toLowerCase() !== f.mood.toLowerCase()) {
+      if (!(t.tags ?? []).some((x) => x.toLowerCase() === f.mood.toLowerCase()))
+        return false;
+    }
+    if (f.vocals && (t.vocals ?? "none") !== f.vocals) return false;
+    if (f.loops && !t.loops) return false;
+    if (f.bpm) {
+      if (t.bpm === null || t.bpm === void 0) return false;
+      if (t.bpm < f.bpm[0] || t.bpm > f.bpm[1]) return false;
+    }
+    if (f.minLength !== void 0 && t.duration < f.minLength && !t.loops)
+      return false;
+    if (words2.length) {
+      const hay = [
+        t.slug,
+        t.title,
+        t.artist ?? "",
+        t.mood ?? "",
+        ...t.tags ?? [],
+        t.description ?? ""
+      ].join(" ").toLowerCase();
+      if (!words2.every((w) => hay.includes(w))) return false;
+    }
+    return true;
+  });
+}
+async function loadFilm(ref) {
+  const path = resolve20(ref);
+  if (!existsSync27(path)) throw new UsageError(`${ref}: no such take or file`);
+  if (statSync8(path).isDirectory()) {
+    const take = await loadTake(path);
+    if (!take.doc)
+      throw new UsageError(`${ref} has no doc.json; run vos plan first`);
+    const sync = readSyncState(path);
+    return { doc: take.doc, seed: sync?.vosId ?? basename16(path), dir: path };
+  }
+  let config;
+  try {
+    config = JSON.parse(readFileSync10(path, "utf8"));
+  } catch {
+    throw new UsageError(`${ref}: not a take directory or a JSON config`);
+  }
+  if (!config || typeof config !== "object" || !("version" in config))
+    throw new UsageError(`${ref}: a program's config.json carries a version`);
+  const doc = {
+    program: { config },
+    audio: [],
+    overlays: [],
+    objects: []
+  };
+  return { doc, seed: basename16(path, ".json"), dir: null };
+}
+async function likedSlugs(refs, origin) {
+  const slugs = /* @__PURE__ */ new Set();
+  const notes = [];
+  for (const ref of refs) {
+    const id = parseVosId(ref);
+    if (!id) {
+      slugs.add(ref.toLowerCase());
+      continue;
+    }
+    try {
+      const vos = await (await fetch(`${origin}/api/vos/${id}`)).json();
+      if (!vos.currentVersionId) throw new Error("no version");
+      const doc = await (await fetch(
+        `${origin}/api/vos/${id}/versions/${vos.currentVersionId}/doc`
+      )).json();
+      for (const s of musicSlugsOfDoc(doc)) slugs.add(s);
+    } catch {
+      notes.push(
+        `--like ${ref}: could not read that vos's document (is it public?)`
+      );
+    }
+  }
+  return { slugs: [...slugs], notes };
+}
+function scoreLine(take, r, film) {
+  const at2 = r.placement?.swellAt ?? film.payoff;
+  return `vos score ${take ?? "<take>"} --track ${r.slug}${at2 !== void 0 && at2 !== null ? ` --at ${at2}` : ""}`;
+}
+function pickWords(picks, all, film, take) {
+  const refused = all.filter((r) => r.score === null);
+  const head = `${film.duration.toFixed(1)}s film, ${film.cuts.length} cut${film.cuts.length === 1 ? "" : "s"}${film.payoff !== void 0 ? `, payoff at ${mmss(film.payoff)}` : ""}${film.voice ? ", a voice" : ""}${film.mood ? `, asked ${film.mood}` : ""}${film.words ? `, asked "${film.words}"` : ""}`;
+  if (!picks.length) {
+    return `${head}
+  No bed in the library fits: ${refused.length} refused (${[...new Set(refused.map((r) => r.refused))].slice(0, 3).join("; ")}). Compose a score instead (the vos-score skill), or ask with --words.`;
+  }
+  const lines = picks.map((r, i) => {
+    const t = r.track;
+    const facts = [
+      t.mood,
+      t.bpm !== null && t.bpm !== void 0 ? `${t.bpm} bpm${t.beatConfidence === "low" ? "?" : ""}` : null,
+      VOCAL_WORDS[t.vocals ?? "none"],
+      t.loops ? "loops" : null
+    ].filter(Boolean).join(", ");
+    return `  ${i + 1}. ${r.slug}  ${t.title}  ${(r.score ?? 0).toFixed(2)}  (${facts})
+     ${r.reasons.join("; ") || "fits"}
+     ${scoreLine(take, r, film)}`;
+  });
+  const tail = refused.length ? `
+  ${refused.length} refused: ${refused.slice(0, 4).map((r) => `${r.slug} (${r.refused})`).join("; ")}${refused.length > 4 ? "; \u2026" : ""}` : "";
+  return `${head}
+${lines.join("\n")}${tail}`;
+}
+async function cmdMusic(argv) {
+  const { positionals, flags, multi } = parseArgs(
+    argv,
+    BOOLEAN_FLAGS14,
+    MULTI_FLAGS3
+  );
+  const verb = positionals[0];
+  if (flags.help === true || !verb || !["ls", "pick"].includes(verb))
+    throw new UsageError(USAGE5);
+  const r = createReporter(flags.json === true);
+  const origin = platformOrigin({
+    origin: strFlag(flags, "origin"),
+    api: strFlag(flags, "api")
+  });
+  const catalog = await fetchMusicCatalog(origin);
+  if (verb === "ls") {
+    const vocals = strFlag(flags, "vocals");
+    if (vocals && !["none", "chops", "lead"].includes(vocals))
+      throw new UsageError("--vocals expects none, chops or lead");
+    const kept = filterTracks(catalog.tracks, {
+      mood: strFlag(flags, "mood"),
+      vocals,
+      loops: flags.loops === true,
+      bpm: bpmRange(strFlag(flags, "bpm")),
+      minLength: strFlag(flags, "min-length") !== void 0 ? numFlag(flags, "min-length", 0) : void 0,
+      q: strFlag(flags, "q")
+    });
+    r.done(
+      { origin, tracks: kept, total: catalog.tracks.length },
+      kept.length ? kept.map(trackLine).join("\n") : `No track matches; the library holds ${catalog.tracks.length} (GET ${origin}/api/music).`
+    );
+    return EXIT_OK;
+  }
+  const ref = positionals[1];
+  if (!ref) throw new UsageError(USAGE5);
+  const { doc, seed, dir } = await loadFilm(ref);
+  const atRaw = strFlag(flags, "at");
+  const at2 = atRaw !== void 0 ? resolveAt(doc, atRaw) : null;
+  if (flags.voice === true && flags["no-voice"] === true)
+    throw new UsageError("--voice and --no-voice together say nothing");
+  const liked = await likedSlugs(multi.like ?? [], origin);
+  const film = filmSummaryOf3(doc, {
+    seed,
+    ...at2 ? { payoff: at2.at } : {},
+    ...flags.voice === true ? { voice: true } : flags["no-voice"] === true ? { voice: false } : {},
+    mood: strFlag(flags, "mood"),
+    words: strFlag(flags, "words"),
+    like: liked.slugs,
+    fadeIn: flags["fade-in"] === true
+  });
+  const top = Math.max(1, Math.round(numFlag(flags, "top", 3)));
+  const all = rankBeds3(catalog.tracks, film);
+  const picks = all.filter((x) => x.score !== null).slice(0, top);
+  for (const n of liked.notes) r.warn(n);
+  const asked = strFlag(flags, "mood");
+  if (asked && trackBySlug2(catalog.tracks, asked))
+    r.warn(
+      `--mood ${asked} is a track's slug; to place that track, run vos score --track ${asked}`
+    );
+  r.done(
+    {
+      origin,
+      film,
+      picks: picks.map((x) => ({
+        ...x,
+        command: scoreLine(dir ? ref : null, x, film)
+      })),
+      all
+    },
+    pickWords(picks, all, film, dir ? ref : null)
+  );
+  return EXIT_OK;
+}
+
 // src/plugin/look.ts
-import { mkdir as mkdir12 } from "fs/promises";
-import { existsSync as existsSync27 } from "fs";
-import { join as join30, resolve as resolve20 } from "path";
+import { mkdir as mkdir12, mkdtemp as mkdtemp3, readFile as readFile18, rm as rm6 } from "fs/promises";
+import { existsSync as existsSync28 } from "fs";
+import { tmpdir as tmpdir4 } from "os";
+import { dirname as dirname10, join as join30, resolve as resolve21 } from "path";
 import { headersFor, urlSchemeProblem } from "@vosjs/render-core/record";
 function quote(value) {
   return `"${value.replace(/\s+/g, " ").replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
@@ -17316,19 +17630,19 @@ async function lookAt(page, url, opts) {
   });
   const ran = [];
   if (!wall || wall.level === "soft") {
-    for (const step2 of opts.steps ?? []) {
-      const all = page.locator(step2.selector);
+    for (const step of opts.steps ?? []) {
+      const all = page.locator(step.selector);
       const target = all.first();
       try {
         await target.waitFor({ state: "visible", timeout: STEP_TIMEOUT_MS });
       } catch {
         throw new UsageError(
-          `--${step2.do} ${step2.selector}: no visible element matches it after ${STEP_TIMEOUT_MS / 1e3} s. Look without the step and take a selector from the list`
+          `--${step.do} ${step.selector}: no visible element matches it after ${STEP_TIMEOUT_MS / 1e3} s. Look without the step and take a selector from the list`
         );
       }
       const count = await all.count();
       const note = count > 1 ? `the first of ${count} matches` : void 0;
-      if (step2.do === "click") {
+      if (step.do === "click") {
         const words2 = await target.evaluate(
           (el) => [
             el.getAttribute("aria-label"),
@@ -17344,25 +17658,37 @@ async function lookAt(page, url, opts) {
         if (word) {
           const label = words2.find((w) => spendWord([w])) ?? word;
           throw new LookRefusal(
-            refusalLine(step2.selector, label.slice(0, 60), word)
+            refusalLine(step.selector, label.slice(0, 60), word)
           );
         }
-        log(`click ${step2.selector}${note ? ` (${note})` : ""}`);
+        log(`click ${step.selector}${note ? ` (${note})` : ""}`);
         await target.click({ timeout: STEP_TIMEOUT_MS });
       } else {
         log(
-          `type ${step2.text.length} chars into ${step2.selector}${note ? ` (${note})` : ""}`
+          `type ${step.text.length} chars into ${step.selector}${note ? ` (${note})` : ""}`
         );
-        await target.fill(step2.text, { timeout: STEP_TIMEOUT_MS });
+        await target.fill(step.text, { timeout: STEP_TIMEOUT_MS });
       }
       ran.push({
-        do: step2.do,
-        selector: step2.selector,
+        do: step.do,
+        selector: step.selector,
         ...note ? { note } : {}
       });
       settled = await settle(page);
     }
   }
+  return inspectPage(page, {
+    url,
+    outDir: opts.outDir,
+    waitMs: opts.waitMs,
+    wall,
+    steps: ran,
+    settled
+  });
+}
+async function inspectPage(page, opts) {
+  const { url, wall, settled } = opts;
+  const ran = opts.steps;
   if (opts.waitMs && opts.waitMs > 0) await page.waitForTimeout(opts.waitMs);
   await mkdir12(opts.outDir, { recursive: true });
   const screenshot = join30(opts.outDir, "look.png");
@@ -17420,7 +17746,27 @@ async function lookAt(page, url, opts) {
     settled
   };
 }
-var USAGE5 = "vos look <url> [--session <name> | --storage-state <file>] [--viewport WxH] [--headed] [--click <selector>]... [--type <selector>=<text>]... [--wait <ms>] [--out <dir>] [--json]";
+var USAGE6 = "vos look <url> [--session <name> | --storage-state <file>] [--viewport WxH] [--headed] [--click <selector>]... [--type <selector>=<text>]... [--wait <ms>] [--out <dir>] [--json]\n       vos look [url] --actions actions.json --until <step id> [--session <name> | --storage-state <file>] [--viewport WxH] [--headed] [--wait <ms>] [--out <dir>] [--json]";
+function untilProblem(given, steps) {
+  if (given.until !== void 0 && given.actions === void 0)
+    return "--until names a step of a script: pass the script with --actions actions.json";
+  if (given.actions === void 0) return null;
+  if (given.clicks)
+    return "--actions walks the script; --click and --type walk by hand. Pass one";
+  if (given.until === void 0)
+    return "--actions needs --until <step id>: the step whose page you want to see";
+  if (!steps) return null;
+  if (steps.some((s) => s.id === given.until)) return null;
+  const ids = steps.map((s) => s.id).filter((id) => !!id);
+  return `--until ${given.until}: no step in ${given.actions} has that id. ${ids.length ? `Its ids: ${ids.join(", ")}` : 'Its steps have no ids; give the step you want an "id"'}`;
+}
+function walkedSteps(steps) {
+  return steps.map((s) => ({
+    do: s.id ? `${s.do} (${s.id})` : s.do,
+    selector: s.selector ?? "",
+    ...s.skipped ? { note: `SKIPPED: ${s.reason ?? "not found"}` } : s.guard ? { note: `guarded (${s.guard}), hovered, not pressed` } : {}
+  }));
+}
 function lookReport(r) {
   const inDialog = r.controls.filter((c) => c.inDialog).length;
   const head = `Looked at ${r.landed} (${r.viewport.width}\xD7${r.viewport.height}): ${r.screenshot}${r.settled ? "" : "\n  note: the page never held still for 0.8 s; looked at it as it was"}`;
@@ -17449,21 +17795,39 @@ async function cmdLook(argv) {
   );
   void multi.click;
   void multi.type;
-  const url = positionals[0];
-  if (!url) throw new UsageError(USAGE5);
+  const actionsArg = strFlag(flags, "actions");
+  const untilId = strFlag(flags, "until");
+  const early = untilProblem({
+    actions: actionsArg,
+    until: untilId,
+    clicks: steps.length
+  });
+  if (early) throw new UsageError(early);
+  let actions;
+  if (actionsArg) {
+    actions = await loadLookActions(resolve21(actionsArg));
+    const bad = untilProblem(
+      { actions: actionsArg, until: untilId, clicks: 0 },
+      actions.steps
+    );
+    if (bad) throw new UsageError(bad);
+  }
+  const url = positionals[0] ?? actions?.url;
+  if (!url) throw new UsageError(USAGE6);
   const scheme = urlSchemeProblem(url);
   if (scheme) throw new UsageError(scheme);
   const r = createReporter(flags.json === true);
-  const viewport = parseViewport2(strFlag(flags, "viewport"));
-  const outDir = resolve20(strFlag(flags, "out") ?? "look");
+  const viewportFlag = strFlag(flags, "viewport");
+  const viewport = !viewportFlag && actions?.viewport ? actions.viewport : parseViewport2(viewportFlag);
+  const outDir = resolve21(strFlag(flags, "out") ?? "look");
   const headed = flags.headed === true;
   const waitRaw = strFlag(flags, "wait");
   const waitMs = waitRaw === void 0 ? 0 : Number(waitRaw);
   if (!Number.isFinite(waitMs) || waitMs < 0 || waitMs > 6e4)
     throw new UsageError("--wait expects milliseconds, 0 to 60000");
   const storageRaw = strFlag(flags, "storage-state");
-  const storageState = storageRaw ? resolve20(storageRaw) : void 0;
-  if (storageState && !existsSync27(storageState))
+  const storageState = storageRaw ? resolve21(storageRaw) : void 0;
+  if (storageState && !existsSync28(storageState))
     throw new UsageError(`--storage-state: no such file: ${storageState}`);
   const sessionName = strFlag(flags, "session");
   if (sessionName) {
@@ -17473,7 +17837,7 @@ async function cmdLook(argv) {
       throw new UsageError(
         "--session and --storage-state are two doors to one page: a persistent profile cannot take a storage state. Pass one"
       );
-    if (!existsSync27(sessionDir(sessionName)))
+    if (!existsSync28(sessionDir(sessionName)))
       throw new UsageError(
         `no session "${sessionName}". Make one: vos session open <url> --name ${sessionName} (a Chrome window opens; sign in and close it)`
       );
@@ -17485,6 +17849,22 @@ async function cmdLook(argv) {
     throw new UsageError(e instanceof Error ? e.message : String(e));
   }
   const browserArgs = (multi["browser-arg"] ?? []).filter(Boolean);
+  if (actions && untilId && actionsArg)
+    return lookUntil({
+      r,
+      url,
+      actions,
+      actionsPath: resolve21(actionsArg),
+      untilId,
+      viewport,
+      outDir,
+      waitMs,
+      headed,
+      storageState,
+      sessionName,
+      headers,
+      browserArgs
+    });
   const inContext = async (ctx) => {
     if (Object.keys(headers).length)
       await ctx.route("**/*", async (route) => {
@@ -17531,14 +17911,116 @@ async function cmdLook(argv) {
   );
   return result.wall?.level === "hard" ? EXIT_WALL : EXIT_OK;
 }
+async function loadLookActions(file) {
+  let raw;
+  try {
+    raw = JSON.parse(await readFile18(file, "utf8"));
+  } catch (e) {
+    throw new UsageError(
+      `--actions ${file}: ${e instanceof Error ? e.message : String(e)}`
+    );
+  }
+  const errors = validateActions(raw);
+  if (!errors.length) errors.push(...jsSyntaxProblems(raw));
+  if (errors.length)
+    throw new UsageError(`invalid actions file:
+  ${errors.join("\n  ")}`);
+  return raw;
+}
+async function lookUntil(o) {
+  const { r } = o;
+  const actions = { ...o.actions, viewport: o.viewport };
+  let wall = null;
+  let looked = null;
+  const scratch = await mkdtemp3(join30(tmpdir4(), "vos-look-"));
+  r.log(
+    `walking ${o.actionsPath} to step ${o.untilId} (a rehearsal: guarded steps hovered, never pressed)\u2026`
+  );
+  const browser = await launchBrowser(o.browserArgs, { headless: !o.headed });
+  let rec;
+  try {
+    const walk = (context2) => recordTake(browser, o.url, actions, takePaths(scratch), r.log, {
+      actionsDir: dirname10(o.actionsPath),
+      storageState: o.storageState,
+      headers: o.headers,
+      context: context2,
+      dryRun: true,
+      stopOnHang: true,
+      onEvent: (e) => r.event(e),
+      onArrival: (arrival) => {
+        const verdict = wallVerdict(arrival);
+        if (verdict && verdict.level === "hard") throw new WallError(verdict);
+        if (verdict) r.log(`   WARNING: ${verdict.message}`);
+        wall = verdict;
+        return verdict;
+      },
+      until: {
+        id: o.untilId,
+        at: async (raw) => {
+          const page = raw;
+          const settled = await settle(page);
+          looked = await inspectPage(page, {
+            url: o.url,
+            outDir: o.outDir,
+            waitMs: o.waitMs,
+            wall,
+            steps: [],
+            settled
+          });
+        }
+      }
+    });
+    rec = o.sessionName ? await withSession(o.sessionName, (ctx) => walk(ctx), {
+      headless: !o.headed,
+      viewport: o.viewport
+    }) : await walk(void 0);
+  } finally {
+    await browser.close();
+    await rm6(scratch, { recursive: true, force: true });
+  }
+  const result = looked;
+  const ran = walkedSteps(rec.meta.steps ?? []);
+  const skipped = rec.skipped.length;
+  const teardown = rec.teardown ? `
+  ${teardownLine(rec.teardown)}` : "";
+  if (!result) {
+    const why = rec.stopped ? rec.stopped.reason : "the walk ended before it reached that step";
+    r.done(
+      {
+        ok: false,
+        until: o.untilId,
+        steps: ran,
+        skipped: rec.skipped,
+        ...rec.teardown ? { teardown: rec.teardown } : {}
+      },
+      `NOT LOOKED: step ${o.untilId} was never reached: ${why}.${ran.length ? `
+  walked: ${ran.map((s) => `${s.do}${s.selector ? ` ${s.selector}` : ""}${s.note ? ` (${s.note})` : ""}`).join(", then ")}` : ""}
+  Rehearse the script (vos record --actions ${o.actionsPath} --dry-run) to see where it stops.${teardown}`
+    );
+    return EXIT_USAGE;
+  }
+  const full = { ...result, steps: ran };
+  const warn = skipped ? `
+  WARNING: ${skipped} step${skipped === 1 ? " was" : "s were"} SKIPPED on the way, so this may not be the page the script reaches. Fix ${skipped === 1 ? "it" : "them"}, then look again.` : "";
+  r.done(
+    {
+      ok: skipped === 0 && (!full.wall || full.wall.level === "soft"),
+      until: o.untilId,
+      ...full,
+      ...rec.teardown ? { teardown: rec.teardown } : {}
+    },
+    `${lookReport(full)}${warn}${teardown}`
+  );
+  return skipped ? EXIT_USAGE : EXIT_OK;
+}
 
 // src/plugin/machineCmd.ts
 import { spawnSync as spawnSync4 } from "child_process";
 import {
   cpSync,
-  existsSync as existsSync29,
+  existsSync as existsSync30,
   mkdirSync as mkdirSync6,
-  readFileSync as readFileSync11,
+  readFileSync as readFileSync12,
   rmSync as rmSync3,
   writeFileSync as writeFileSync6
 } from "fs";
@@ -17547,8 +18029,8 @@ import { join as join32 } from "path";
 import { chromium as chromium2 } from "playwright";
 
 // src/plugin/machine.ts
-import { existsSync as existsSync28, readFileSync as readFileSync10, readdirSync as readdirSync6, statSync as statSync8 } from "fs";
-import { dirname as dirname10, join as join31 } from "path";
+import { existsSync as existsSync29, readFileSync as readFileSync11, readdirSync as readdirSync6, statSync as statSync9 } from "fs";
+import { dirname as dirname11, join as join31 } from "path";
 var AGENT_NAMES = [
   "claude",
   "cursor",
@@ -17568,7 +18050,7 @@ var HOME_DIRS = {
   copilot: [".copilot"]
 };
 function detectAgents(root, opts = {}) {
-  const exists = opts.exists ?? existsSync28;
+  const exists = opts.exists ?? existsSync29;
   const out = [];
   for (const agent of AGENT_NAMES) {
     for (const rel of PROJECT_DIRS[agent]) {
@@ -17615,7 +18097,7 @@ function skillsDirFor(home) {
 function fallbackSkillsHome(root) {
   return { agent: "codex", dir: join31(root, ".agents"), scope: "project" };
 }
-function installedSkills(dir, exists = existsSync28, list = (p) => {
+function installedSkills(dir, exists = existsSync29, list = (p) => {
   try {
     return readdirSync6(p);
   } catch {
@@ -17656,7 +18138,7 @@ ${RULES_BLOCK}
   }
   return { text, changed: text !== current };
 }
-function rulesFileFor(root, exists = existsSync28) {
+function rulesFileFor(root, exists = existsSync29) {
   const agents = join31(root, "AGENTS.md");
   if (exists(agents)) return agents;
   const claude = join31(root, "CLAUDE.md");
@@ -17761,27 +18243,27 @@ function doctorReport(facts) {
 }
 function bundledSkillsVersion(dir) {
   try {
-    const v = readFileSync10(join31(dir, "VERSION"), "utf8").trim();
+    const v = readFileSync11(join31(dir, "VERSION"), "utf8").trim();
     return /^\d+\.\d+\.\d+$/.test(v) ? v : null;
   } catch {
     return null;
   }
 }
 function bundledSkillsDir(from) {
-  let dir = dirname10(from);
+  let dir = dirname11(from);
   for (let i = 0; i < 6; i++) {
     const pkg = join31(dir, "package.json");
-    if (existsSync28(pkg)) {
+    if (existsSync29(pkg)) {
       try {
-        const name = JSON.parse(readFileSync10(pkg, "utf8")).name;
+        const name = JSON.parse(readFileSync11(pkg, "utf8")).name;
         if (name === "@vosjs/cli") {
           const skills = join31(dir, "skills");
-          return existsSync28(skills) && statSync8(skills).isDirectory() ? skills : null;
+          return existsSync29(skills) && statSync9(skills).isDirectory() ? skills : null;
         }
       } catch {
       }
     }
-    const up = dirname10(dir);
+    const up = dirname11(dir);
     if (up === dir) break;
     dir = up;
   }
@@ -17789,7 +18271,7 @@ function bundledSkillsDir(from) {
 }
 
 // src/plugin/machineCmd.ts
-var BOOLEAN_FLAGS14 = /* @__PURE__ */ new Set([
+var BOOLEAN_FLAGS15 = /* @__PURE__ */ new Set([
   "json",
   "help",
   "global",
@@ -17812,7 +18294,7 @@ function npx() {
 function bundledChromium() {
   try {
     const p = chromium2.executablePath();
-    return p && existsSync29(p) ? p : null;
+    return p && existsSync30(p) ? p : null;
   } catch {
     return null;
   }
@@ -17821,7 +18303,7 @@ function probe2() {
   return probeBrowser({
     platform: process.platform,
     env: process.env,
-    exists: existsSync29,
+    exists: existsSync30,
     bundled: bundledChromium
   });
 }
@@ -17872,7 +18354,7 @@ async function doctorFacts(opts) {
   };
 }
 async function cmdSetup(argv) {
-  const { flags } = parseArgs(argv, BOOLEAN_FLAGS14);
+  const { flags } = parseArgs(argv, BOOLEAN_FLAGS15);
   const r = reporterFor(flags);
   const root = process.cwd();
   const global = flags.global === true;
@@ -17974,7 +18456,7 @@ async function cmdSetup(argv) {
   let rules = null;
   if (!noRules) {
     const file = rulesFileFor(root);
-    const existing = existsSync29(file) ? readFileSync11(file, "utf8") : null;
+    const existing = existsSync30(file) ? readFileSync12(file, "utf8") : null;
     const { text, changed } = applyRulesBlock(existing);
     if (changed) writeFileSync6(file, text);
     rules = { file, changed };
@@ -18005,7 +18487,7 @@ Next: ${report.next_step}`
   return report.ok ? EXIT_OK : EXIT_NO_BROWSER;
 }
 async function cmdDoctor(argv) {
-  const { flags } = parseArgs(argv, BOOLEAN_FLAGS14);
+  const { flags } = parseArgs(argv, BOOLEAN_FLAGS15);
   const r = reporterFor(flags);
   const root = process.cwd();
   const homes = detectAgents(root, { home: homedir2(), global: true });
@@ -18024,7 +18506,7 @@ Next: ${report.next_step}`
   return report.ok ? EXIT_OK : EXIT_NO_BROWSER;
 }
 async function cmdWhoami(argv) {
-  const { flags } = parseArgs(argv, BOOLEAN_FLAGS14);
+  const { flags } = parseArgs(argv, BOOLEAN_FLAGS15);
   const r = reporterFor(flags);
   const origin = platformOrigin({
     origin: strFlag(flags, "origin"),
@@ -18086,9 +18568,9 @@ async function cmdWhoami(argv) {
   return EXIT_OK;
 }
 function cmdLogout(argv) {
-  const { flags } = parseArgs(argv, BOOLEAN_FLAGS14);
+  const { flags } = parseArgs(argv, BOOLEAN_FLAGS15);
   const r = reporterFor(flags);
-  const had = existsSync29(CREDENTIALS_PATH);
+  const had = existsSync30(CREDENTIALS_PATH);
   rmSync3(CREDENTIALS_PATH, { force: true });
   const envKey = Boolean(process.env.VOS_API_KEY?.trim());
   r.done(
@@ -18104,7 +18586,7 @@ function cmdLogout(argv) {
 }
 
 // src/plugin/run.ts
-var BOOLEAN_FLAGS15 = /* @__PURE__ */ new Set([
+var BOOLEAN_FLAGS16 = /* @__PURE__ */ new Set([
   "json",
   "help",
   "wait",
@@ -18168,8 +18650,12 @@ Take pipeline
   vos join <take> <take|file.mp4>... --out <dir> [--keep-edits|--force] [--captions] [--zooms per-beat] [--mute <file>]... [--json]
             several takes (and plain video files) as ONE take, cut in argument order: the first is the primary (its frame, cursor, export and sound), each next one a media m1, m2, \u2026 with its footage copied, its spans tagged and renamed, its layers moved to where it now starts; a file opens full-bleed and its own sound plays as an audio clip (--mute <file> leaves it out). --captions lands every step's caption anchored to its step, starting as the step begins (anchor.at "start"), each ending with its clip. --zooms per-beat keeps a beat's zoom on its steps marked "zoom": true (as vos plan --zooms per-beat). The result must pass vos validate before anything is written
             --keep-edits joins again over an edited joined take and keeps its edits: inputs are matched to their media by source file (join.json records each input's path and footage hash), a kept input keeps its id and everything on it (segments in their edited order, spans, rejections, anchored layers, its sound), the frame, export, styles and still stay, a new input is joined fresh under a new id (and only it is captioned or re-planned), a re-recorded input (changed footage at its path, or the same script at a new one) keeps its edits re-timed by its steps as vos plan --reuse does, and an input that is gone takes its edits with it, each named. A new input's segments go before the next kept input's; reordering the kept inputs regroups the segments in argument order. The first input must stay the primary. --force replaces the take instead
-  vos score <take> --track <slug|file> [--at <step id|output seconds>] [--gain 0..1] [--normalize <lufs|off>] [--fade-in <s>] [--fade-out <s>] [--dry-run] [--json]
-            the film's music as one audio clip (id score): reads the track's loudness, finds its strongest swell and offsets the track so the swell lands at --at (a step, resolved through the cut, or output seconds); without --at it starts where the track first rises above its median level. The clip carries its measured loudness and a target, --normalize (default -16 LUFS), with --gain (default 0.5) a trim on it; --normalize off plays it at --gain alone
+  vos music ls [--mood <slug>] [--vocals none|chops|lead] [--loops] [--bpm <lo>-<hi>] [--min-length <s>] [--q <words>] [--json]
+            the library as an agent reads it, one line per track: slug, genre, length, tempo (a ? on an uncertain beat), vocals, loops, the sentence a person wrote. The facts are GET /api/music's
+  vos music pick <take|config.json> [--at <step id|seconds>] [--mood <slug|tag>] [--words "\u2026"] [--voice|--no-voice] [--like <vos id|slug>]... [--top 3] [--json]
+            the beds that fit THIS film, best first, each with its reasons and the vos score line that places it: the film's length, its cuts (captions, joins, page changes, zoom marks), its payoff (--at, else the last step marked "zoom": true, else the last cut) and its voice are read from the document and every track is scored (a swell on the payoff, cuts on the beat, the asked mood or words, calm under a voice, an ending that meets the film's) after the hard rules (covers the film or loops, no quiet intro under frame one, no sung lead under a voice). --json carries every track, the refused with their reason. Ties fall to the take, so two films asking the same thing get different beds
+  vos score <take> --track <slug|file|best> [--at <step id|output seconds>] [--mood <slug|tag>] [--words "\u2026"] [--gain 0..1] [--normalize <lufs|off>] [--fade-in <s>] [--fade-out <s>] [--dry-run] [--json]
+            the film's music as one audio clip (id score): reads the track's loudness, finds its strongest swell and offsets the track so the swell lands at --at (a step, resolved through the cut, or output seconds); without --at it starts where the track first rises above its median level. --track best runs vos music pick and places its first pick, its payoff as --at unless one is given. The clip carries its measured loudness and a target, --normalize (default -16 LUFS), with --gain (default 0.5) a trim on it; --normalize off plays it at --gain alone
   vos audio measure <take> [--json]
             every audio clip's loudness (BS.1770 integrated LUFS and sample peak, the meter check-video reads a render with), written beside it in doc.json as loudness { lufs, peakDb, at, src }; a clip's normalize (a target in LUFS, -30..-6) plays it at the gain that reaches it, past 1 if need be, capped so its peak stays under -1 dBFS, and only once it is measured for its own key
   vos port inventory <page.html|project dir> [--render <their render.mp4>] [--out port] [--json]
@@ -18503,7 +18989,7 @@ lint-gated, so a bad override fails like a bad doc.json):
                        first ready loop (the house backdrop the studio opens on), or a flat ground offline
 `;
 async function loadActions(file) {
-  const raw = JSON.parse(await readFile18(file, "utf8"));
+  const raw = JSON.parse(await readFile19(file, "utf8"));
   const errors = validateActions(raw);
   if (!errors.length) errors.push(...jsSyntaxProblems(raw));
   if (errors.length)
@@ -18669,8 +19155,8 @@ function takeBrowserArgs(multi) {
 function takeStorageState(flags) {
   const raw = strFlag(flags, "storage-state");
   if (!raw) return void 0;
-  const path = resolve21(raw);
-  if (!existsSync30(path))
+  const path = resolve22(raw);
+  if (!existsSync31(path))
     throw new UsageError(`--storage-state: no such file: ${path}`);
   return path;
 }
@@ -18683,7 +19169,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 (!existsSync30(sessionDir(name)))
+  if (!existsSync31(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)`
     );
@@ -18701,14 +19187,14 @@ async function inSession(name, actions, fn) {
 }
 function reRecord(outDir, flags, r) {
   const wantsReuse = flags.reuse === true;
-  if (wantsReuse && !existsSync30(join33(outDir, "doc.json")))
+  if (wantsReuse && !existsSync31(join33(outDir, "doc.json")))
     throw new UsageError(
       `--reuse: ${outDir} has no cut to keep (no doc.json); record without --reuse`
     );
   let previousCut = null;
   return {
     prepare: async () => {
-      if (existsSync30(join33(outDir, "meta.json"))) {
+      if (existsSync31(join33(outDir, "meta.json"))) {
         const { prevDoc, kept } = await prepareReRecord(outDir);
         if (prevDoc) previousCut = join33(outDir, PREV_DOC_NAME);
         r.log(
@@ -18725,7 +19211,7 @@ function reRecord(outDir, flags, r) {
         ...from ? {
           reuse: {
             from,
-            doc: JSON.parse(await readFile18(from, "utf8"))
+            doc: JSON.parse(await readFile19(from, "utf8"))
           }
         } : {}
       });
@@ -18796,7 +19282,7 @@ function wallGate(flags, r, opts) {
 async function cmdRecord(argv) {
   const { positionals, flags, multi } = parseArgs(
     argv,
-    BOOLEAN_FLAGS15,
+    BOOLEAN_FLAGS16,
     MULTI_FLAGS2
   );
   const actionsPath = strFlag(flags, "actions") ?? positionals[0];
@@ -18812,7 +19298,7 @@ async function cmdRecord(argv) {
   const scheme = urlSchemeProblem2(url);
   if (scheme) throw new UsageError(scheme);
   announceEnvNames(actions, r);
-  const outDir = resolve21(strFlag(flags, "out") ?? "take");
+  const outDir = resolve22(strFlag(flags, "out") ?? "take");
   const storageState = takeStorageState(flags);
   const sessionName = takeSessionName(flags, storageState);
   const browserArgs = takeBrowserArgs(multi);
@@ -18832,7 +19318,7 @@ async function cmdRecord(argv) {
       );
     const hostedActions = await scriptForHost(
       actions,
-      dirname11(resolve21(actionsPath))
+      dirname12(resolve22(actionsPath))
     ).catch((e) => {
       throw new UsageError(e instanceof Error ? e.message : String(e));
     });
@@ -18942,7 +19428,7 @@ async function cmdRecord(argv) {
         sessionName,
         actions,
         (context2) => recordTake(browser2, url, actions, takePaths(outDir), r.log, {
-          actionsDir: dirname11(resolve21(actionsPath)),
+          actionsDir: dirname12(resolve22(actionsPath)),
           storageState,
           headers,
           context: context2,
@@ -19008,7 +19494,7 @@ async function cmdRecord(argv) {
         ...flags["allow-wall"] === true ? ["--allow-wall"] : [],
         ...confirm.map((c) => `--confirm ${c}`),
         // A take that already has a cut keeps it on the new footage.
-        ...existsSync30(join33(outDir, "doc.json")) ? ["--reuse"] : []
+        ...existsSync31(join33(outDir, "doc.json")) ? ["--reuse"] : []
       ].join(" ");
       const nextOut = strFlag(flags, "out") ?? "take";
       const guardNote = !unconfirmed.ok ? unconfirmed.unconfirmed.length ? ` (it refuses until you add ${unconfirmed.unconfirmed.map((id) => `--confirm ${id}`).join(" ")}: ${unconfirmed.unconfirmed.length === 1 ? "that step spends" : "those steps spend"} something real)` : ` (${unconfirmed.unknown.map((c) => `--confirm ${c}`).join(", ")} names no guarded step)` : "";
@@ -19050,7 +19536,7 @@ ${lines.join("\n")}
       sessionName,
       actions,
       (context2) => recordTake(browser, url, actions, paths, r.log, {
-        actionsDir: dirname11(resolve21(actionsPath)),
+        actionsDir: dirname12(resolve22(actionsPath)),
         maxDurationSeconds,
         storageState,
         headers,
@@ -19148,7 +19634,7 @@ ${lines.join("\n")}
 async function cmdCreate2(argv) {
   const { positionals, flags, multi } = parseArgs(
     argv,
-    BOOLEAN_FLAGS15,
+    BOOLEAN_FLAGS16,
     MULTI_FLAGS2
   );
   const actionsPath = strFlag(flags, "actions");
@@ -19165,7 +19651,7 @@ async function cmdCreate2(argv) {
   const scheme = urlSchemeProblem2(url);
   if (scheme) throw new UsageError(scheme);
   announceEnvNames(actions, r);
-  const outDir = resolve21(strFlag(flags, "out") ?? "take");
+  const outDir = resolve22(strFlag(flags, "out") ?? "take");
   const format = videoFormat(strFlag(flags, "format"), positionals[0]);
   const out = positionals[0] ?? join33(outDir, `out.${format}`);
   const parallel = numFlag(flags, "parallel", 1);
@@ -19189,7 +19675,7 @@ async function cmdCreate2(argv) {
       sessionName,
       actions,
       (context2) => recordTake(browser, url, actions, paths, r.log, {
-        actionsDir: dirname11(resolve21(actionsPath)),
+        actionsDir: dirname12(resolve22(actionsPath)),
         maxDurationSeconds,
         storageState,
         headers,
@@ -19306,7 +19792,7 @@ async function cmdPlan(argvIn) {
   const argv = bareCaptionsFlag(argvIn);
   const { positionals, flags, multi } = parseArgs(
     argv,
-    BOOLEAN_FLAGS15,
+    BOOLEAN_FLAGS16,
     /* @__PURE__ */ new Set(["with"])
   );
   const dir = positionals[0];
@@ -19316,24 +19802,24 @@ async function cmdPlan(argvIn) {
     );
   const r = createReporter(flags.json === true);
   if (flags.fresh === true) {
-    await rm6(join33(dir, "doc.json"), { force: true });
+    await rm7(join33(dir, "doc.json"), { force: true });
     r.log("note: --fresh discarded the existing doc.json");
   }
   let reuse;
   if (flags.reuse === true) {
-    const from = resolve21(strFlag(flags, "from") ?? join33(dir, PREV_DOC_NAME));
-    if (!existsSync30(from)) {
+    const from = resolve22(strFlag(flags, "from") ?? join33(dir, PREV_DOC_NAME));
+    if (!existsSync31(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>`
       );
     }
     reuse = {
       from,
-      doc: JSON.parse(await readFile18(from, "utf8"))
+      doc: JSON.parse(await readFile19(from, "utf8"))
     };
   }
   const style = await resolveStyleRef(flags);
-  const hasDoc = existsSync30(join33(dir, "doc.json"));
+  const hasDoc = existsSync31(join33(dir, "doc.json"));
   const backdrop = hasDoc ? null : await takeBackdrop(flags, r);
   const release = await releaseInputs(dir, flags, r, multi.with ?? []);
   const stepCaptions = strFlag(flags, "captions") === "steps";
@@ -19413,7 +19899,7 @@ async function cmdPlan(argvIn) {
     ${s.reuse.flagged.join("\n    ")}` : "") : "";
   r.done(
     {
-      take: resolve21(dir),
+      take: resolve22(dir),
       fresh: s.fresh,
       cursorKept: s.cursorKept,
       zoomAuto,
@@ -19542,7 +20028,7 @@ async function releaseInputs(dir, flags, r, withRefs = []) {
 async function cmdRender(argv) {
   const { positionals, flags, multi } = parseArgs(
     argv,
-    BOOLEAN_FLAGS15,
+    BOOLEAN_FLAGS16,
     MULTI_FLAGS2
   );
   const dir = positionals[0];
@@ -19610,7 +20096,7 @@ async function cmdRender(argv) {
 async function cmdFrames(argv) {
   const { positionals, flags, multi } = parseArgs(
     argv,
-    BOOLEAN_FLAGS15,
+    BOOLEAN_FLAGS16,
     MULTI_FLAGS2
   );
   const dir = positionals[0];
@@ -19693,7 +20179,7 @@ async function cmdFrames(argv) {
 async function cmdDeliver(argv) {
   const { positionals, flags, multi } = parseArgs(
     argv,
-    BOOLEAN_FLAGS15,
+    BOOLEAN_FLAGS16,
     MULTI_FLAGS2
   );
   const dir = positionals[0];
@@ -19793,15 +20279,15 @@ async function resolveStyleRef(flags) {
 }
 async function resolveDocRef(ref, flags, what) {
   const styleRef = ref;
-  const file = existsSync30(styleRef) ? resolve21(
+  const file = existsSync31(styleRef) ? resolve22(
     styleRef,
-    existsSync30(join33(styleRef, "doc.json")) ? "doc.json" : ""
+    existsSync31(join33(styleRef, "doc.json")) ? "doc.json" : ""
   ) : null;
-  if (file && existsSync30(file)) {
+  if (file && existsSync31(file)) {
     return {
       from: file,
       doc: migrateHostedDoc4(
-        JSON.parse(await readFile18(file, "utf8"))
+        JSON.parse(await readFile19(file, "utf8"))
       )
     };
   }
@@ -19843,7 +20329,7 @@ async function officialTemplate(origin, ref) {
   }
 }
 async function cmdDigest(argv) {
-  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS15);
+  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS16);
   const dir = positionals[0];
   if (!dir)
     throw new UsageError(
@@ -19853,7 +20339,7 @@ async function cmdDigest(argv) {
   const take = await loadTake(dir);
   if (!take.doc) throw new UsageError(`${dir} has no doc.json \u2014 run plan first`);
   const transcriptPath = strFlag(flags, "transcript");
-  const transcript = transcriptPath ? parseTranscript(JSON.parse(await readFile18(transcriptPath, "utf8"))) : null;
+  const transcript = transcriptPath ? parseTranscript(JSON.parse(await readFile19(transcriptPath, "utf8"))) : null;
   const style = await resolveStyleRef(flags);
   const noFrames = flags["no-frames"] === true;
   let browser = null;
@@ -19907,19 +20393,19 @@ async function cmdDigest(argv) {
   }
 }
 async function cmdOpen(argv) {
-  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS15);
+  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS16);
   const dir = positionals[0];
   if (!dir) throw new UsageError("vos open <take> [--studio <url>]");
   const r = createReporter(flags.json === true);
   const take = await loadTake(dir);
-  if (!existsSync30(take.paths.recording)) {
+  if (!existsSync31(take.paths.recording)) {
     throw new UsageError(`${dir} has no recording \u2014 re-run record`);
   }
   const studio = (strFlag(flags, "studio") ?? platformOrigin()).replace(
     /\/+$/,
     ""
   );
-  const server = await startTakeServer(resolve21(dir), {});
+  const server = await startTakeServer(resolve22(dir), {});
   const url = `${studio}/studio?take=${encodeURIComponent(server.base)}`;
   r.event({ event: "open", server: server.base, url });
   r.log(`take served at ${server.base}`);
@@ -19942,7 +20428,7 @@ async function cmdOpen(argv) {
   return EXIT_OK;
 }
 async function cmdCallout(argv) {
-  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS15);
+  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS16);
   const dir = positionals[0];
   const shape = positionals[1];
   if (!dir || !shape || !isCalloutShape(shape))
@@ -19966,7 +20452,7 @@ async function cmdCallout(argv) {
       `no register: put a BRAND.md beside the take (vos brand <url> --out BRAND.md; its bgA and accent are the ground and the accent), or pass --ground #hex --accent #hex`
     );
   const codeFile = strFlag(flags, "code-file");
-  const code = codeFile ? await readFile18(codeFile, "utf8") : strFlag(flags, "code");
+  const code = codeFile ? await readFile19(codeFile, "utf8") : strFlag(flags, "code");
   const words2 = {
     kicker: strFlag(flags, "kicker"),
     title: strFlag(flags, "title"),
@@ -20041,11 +20527,11 @@ async function cmdCallout(argv) {
   return EXIT_OK;
 }
 async function cmdValidate(argv) {
-  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS15);
+  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS16);
   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 : existsSync30(join33(target, "kit.json")) && !isTakeDir(target) ? join33(target, "kit.json") : null;
+  const kitTarget = target.endsWith("kit.json") ? target : existsSync31(join33(target, "kit.json")) && !isTakeDir(target) ? join33(target, "kit.json") : null;
   if (kitTarget) {
     const picture = flags.picture === true;
     const verdict = await validateKit(kitTarget, { picture });
@@ -20077,9 +20563,9 @@ async function cmdValidate(argv) {
     r.done({ valid: true, target }, `${target}: valid actions file`);
     return EXIT_OK;
   }
-  if (!isTakeDir(target) && existsSync30(join33(target, "config.json"))) {
+  if (!isTakeDir(target) && existsSync31(join33(target, "config.json"))) {
     const parsed = JSON.parse(
-      await readFile18(join33(target, "config.json"), "utf8")
+      await readFile19(join33(target, "config.json"), "utf8")
     );
     const pre = preflightConfig(parsed);
     const problems2 = pre.ok ? [] : pre.issues.map((i) => `config.json: ${i}`);
@@ -20121,7 +20607,7 @@ async function cmdValidate(argv) {
   const problems = [];
   const warnings = [];
   const notes = [];
-  if (!existsSync30(take.paths.recording)) {
+  if (!existsSync31(take.paths.recording)) {
     problems.push("missing recording (re-run record)");
   } else {
     const mismatch = containerMismatch(
@@ -20162,7 +20648,7 @@ async function cmdValidate(argv) {
       const found = localFile(rel, target);
       if (!("refused" in found)) continue;
       problems.push(
-        existsSync30(resolve21(target, rel)) ? `doc.json: ${ref.where}: ${ref.key} ${found.refused}` : `doc.json: ${ref.where}: ${ref.key} is not a file in the take, so a render plays the film without it (put the file there, or fix the key)`
+        existsSync31(resolve22(target, rel)) ? `doc.json: ${ref.where}: ${ref.key} ${found.refused}` : `doc.json: ${ref.where}: ${ref.key} is not a file in the take, so a render plays the film without it (put the file there, or fix the key)`
       );
     }
     if (flags.picture === true && (take.doc.overlays ?? []).some((o) => o.kind === "html")) {
@@ -20231,22 +20717,25 @@ async function cmdValidate(argv) {
 async function cmdPush3(argv) {
   const { positionals, flags, multi } = parseArgs(
     argv,
-    BOOLEAN_FLAGS15,
+    BOOLEAN_FLAGS16,
     MULTI_FLAGS2
   );
   const dir = positionals[0];
   if (!dir)
     throw new UsageError(
-      "vos push <take> [--vos|--title|--label|--note|--prompt|--folder|--override|--yes|--key|--api|--bake|--claimable [--share]]"
+      "vos push <take> [--vos|--title|--desc|--label|--note|--prompt|--folder|--override|--yes|--key|--api|--bake|--claimable [--share]]"
     );
   const refusal = takePushRefusal({
     vos: strFlag(flags, "vos"),
-    trackedVosId: readSyncState(resolve21(dir))?.vosId ?? null,
-    programOnly: ["slug", "desc", "tags", "base", "remix-of", "still"].filter(
+    trackedVosId: readSyncState(resolve22(dir))?.vosId ?? null,
+    programOnly: ["slug", "tags", "base", "remix-of", "still"].filter(
       (name) => hasFlag(flags, name)
     )
   });
   if (refusal) throw new UsageError(refusal);
+  const description = strFlag(flags, "desc");
+  const descProblem = descriptionProblem(description);
+  if (descProblem) throw new UsageError(descProblem);
   const r = createReporter(flags.json === true);
   if (flags.claimable === true) {
     const iterating = ["vos", "folder", "override", "base"].filter(
@@ -20257,12 +20746,13 @@ async function cmdPush3(argv) {
         `--claimable creates a NEW claimable vos; ${iterating.map((f) => `--${f}`).join(", ")} ${iterating.length > 1 ? "apply" : "applies"} to a keyed push`
       );
     const claim = await pushTakeClaimable(
-      resolve21(dir),
+      resolve22(dir),
       {
         api: strFlag(flags, "api"),
         origin: strFlag(flags, "origin"),
         title: strFlag(flags, "title"),
         prompt: strFlag(flags, "prompt"),
+        description,
         share: flags.share === true,
         bake: flags.bake === true
       },
@@ -20280,7 +20770,7 @@ reference and the only credential.`
   }
   const overrides = multi.override;
   const result = await pushTake(
-    resolve21(dir),
+    resolve22(dir),
     {
       key: strFlag(flags, "key"),
       api: strFlag(flags, "api"),
@@ -20293,6 +20783,7 @@ reference and the only credential.`
       folder: strFlag(flags, "folder"),
       overrides,
       prompt: strFlag(flags, "prompt"),
+      description,
       bake: flags.bake === true
     },
     r
@@ -20331,11 +20822,11 @@ ${landedLines(landed)}` : "")
   return EXIT_OK;
 }
 async function cmdPull2(argv) {
-  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS15, MULTI_FLAGS2);
+  const { positionals, flags } = parseArgs(argv, BOOLEAN_FLAGS16, MULTI_FLAGS2);
   const dir = positionals[0] ?? ".";
   const r = createReporter(flags.json === true);
   const result = await pullTake(
-    resolve21(dir),
+    resolve22(dir),
     {
       key: strFlag(flags, "key"),
       api: strFlag(flags, "api"),
@@ -20470,6 +20961,8 @@ async function run(argv) {
         return await cmdScore(rest);
       case "audio":
         return await cmdAudio(rest);
+      case "music":
+        return await cmdMusic(rest);
       case "look":
         return await cmdLook(rest);
       default:
@@ -20512,7 +21005,7 @@ function verdictExit(v, strict, none) {
 async function cmdSession(argv) {
   const { positionals, flags } = parseArgs(
     argv,
-    /* @__PURE__ */ new Set([...BOOLEAN_FLAGS15, "headed"])
+    /* @__PURE__ */ new Set([...BOOLEAN_FLAGS16, "headed"])
   );
   const [sub, arg] = positionals;
   const r = createReporter(flags.json === true);
@@ -20557,7 +21050,7 @@ async function cmdSession(argv) {
       if (!arg) throw new UsageError(usage);
       const bad = sessionNameVerdict(arg);
       if (bad) throw new UsageError(bad);
-      if (!existsSync30(sessionDir(arg)))
+      if (!existsSync31(sessionDir(arg)))
         throw new UsageError(`no session "${arg}" (vos session list)`);
       const summary3 = await summarizeSession(arg);
       const url = strFlag(flags, "url");
@@ -20591,7 +21084,7 @@ async function cmdSession(argv) {
       if (!arg || !scriptPath) throw new UsageError(usage);
       const bad = sessionNameVerdict(arg);
       if (bad) throw new UsageError(bad);
-      if (!existsSync30(sessionDir(arg)))
+      if (!existsSync31(sessionDir(arg)))
         throw new UsageError(`no session "${arg}" (vos session list)`);
       const url = strFlag(flags, "url");
       if (url && !/^https?:\/\//.test(url))
@@ -20684,4 +21177,4 @@ export {
   verbHelp,
   run
 };
-//# sourceMappingURL=chunk-HDJFCTOG.js.map
+//# sourceMappingURL=chunk-NJBUBXFE.js.map