@vosjs/cli 0.83.1 → 0.84.0

package/dist/{chunk-5VGIQKVT.js → chunk-DM7ADA77.js}

@@ -10,7 +10,7 @@ import {
   reencodeStill,
   renderStill,
   videoFormat
-} from "./chunk-B373NVJE.js";
+} from "./chunk-Q47FUCYN.js";
 import {
   PREV_DOC_NAME,
   PasteFileRefusal,
@@ -46,7 +46,7 @@ import {
   uploadDocRefs,
   uploadManifest,
   writeJson
-} from "./chunk-352AC3V6.js";
+} from "./chunk-M5ZBQFPG.js";
 import {
   CREDENTIALS_PATH,
   MEDIA_HEAD_BYTES,
@@ -70,6 +70,7 @@ import {
   parseArgs2 as parseArgs,
   parseVosId,
   platformOrigin,
+  prepareOutput,
   programAssets,
   promptHint,
   readSyncState,
@@ -82,8 +83,10 @@ import {
   strFlag,
   writeCredential,
   writeFileSafe,
+  writeOutput,
+  writeOutputSync,
   writeSyncState
-} from "./chunk-J3KHIZCH.js";
+} from "./chunk-EPSYIF2S.js";
 import {
   deadLine,
   deadWarns
@@ -145,9 +148,9 @@ function landedLines(l) {
 }
 
 // src/plugin/run.ts
-import { mkdir as mkdir13, readFile as readFile18, rm as rm6 } from "fs/promises";
+import { mkdir as mkdir13, readFile as readFile19, rm as rm7 } from "fs/promises";
 import { existsSync as existsSync30 } from "fs";
-import { dirname as dirname11, join as join33, resolve as resolve21 } from "path";
+import { dirname as dirname12, join as join33, resolve as resolve21 } from "path";
 import {
   END_CARD_FROM as END_CARD_FROM2,
   docOutputDuration as docOutputDuration5,
@@ -4017,7 +4020,7 @@ async function writeIndexJson(result) {
 }
 
 // src/plugin/deliver.ts
-import { mkdir as mkdir3, writeFile as writeFile5 } from "fs/promises";
+import { mkdir as mkdir3, writeFile as writeFile4 } from "fs/promises";
 import { join as join4, relative, resolve as resolve4 } from "path";
 import { existsSync as existsSync4 } from "fs";
 import { readFile as readFile4 } from "fs/promises";
@@ -4034,7 +4037,6 @@ import {
 } from "@vosjs/studio-core";
 
 // src/plugin/renderTake.ts
-import { writeFile as writeFile4 } from "fs/promises";
 import { compileVosConfig as compileVosConfig2 } from "@vosjs/core";
 import {
   audioProducerCode,
@@ -4051,6 +4053,7 @@ async function renderTake(browser, dir, outFile, opts) {
   const take = await loadTake(dir);
   if (!take.doc) throw new Error(`${dir} has no doc.json \u2014 run plan first`);
   const doc = take.doc;
+  await prepareOutput(outFile);
   if (opts.overrides && hasOverrides(opts.overrides)) {
     await resolveBackdropSlug(opts.overrides);
     applyAndValidate(doc, opts.overrides);
@@ -4123,7 +4126,7 @@ async function renderTake(browser, dir, outFile, opts) {
     } : void 0,
     onProgress: opts.onProgress
   });
-  await writeFile4(outFile, result.bytes);
+  await writeOutput(outFile, result.bytes);
   return {
     out: outFile,
     bytes: result.bytes.length,
@@ -4820,7 +4823,7 @@ async function deliverTake(browser, dir, opts) {
     assets
   };
   const kitFile = join4(outDir, "kit.json");
-  await writeFile5(kitFile, JSON.stringify(kit, null, 2));
+  await writeFile4(kitFile, JSON.stringify(kit, null, 2));
   return { kit, kitFile, outDir };
 }
 
@@ -4968,7 +4971,7 @@ async function handoffLogin(url, r, opts = {}) {
 }
 
 // src/plugin/markAsset.ts
-import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile6 } from "fs/promises";
+import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile5 } from "fs/promises";
 import { existsSync as existsSync5 } from "fs";
 import { isAbsolute, join as join5, resolve as resolve5 } from "path";
 function markExtension(url) {
@@ -5069,7 +5072,7 @@ async function fetchBrandMarks(takeDir, roles) {
       return null;
     }
     await mkdir4(join5(takeDir, "brand"), { recursive: true });
-    await writeFile6(join5(takeDir, "brand", `${name}.${ext2}`), bytes);
+    await writeFile5(join5(takeDir, "brand", `${name}.${ext2}`), bytes);
     return { key: `/brand/${name}.${ext2}`, aspect };
   };
   out.light = await one("logoUrl", "mark");
@@ -7417,7 +7420,7 @@ import { lowerToComposition as lowerToComposition3, migrateHostedDoc as migrateH
 
 // src/plugin/takeScript.ts
 import { existsSync as existsSync12 } from "fs";
-import { readFile as readFile10, writeFile as writeFile7 } from "fs/promises";
+import { readFile as readFile10, writeFile as writeFile6 } from "fs/promises";
 import { readFileSync as readFileSync2 } from "fs";
 import { basename, join as join12 } from "path";
 function scriptFromText(text) {
@@ -7478,7 +7481,7 @@ async function writeScriptBeside(dir, doc) {
   const path = join12(dir, "actions.json");
   const text = scriptToWrite(doc, existsSync12(path));
   if (text === null) return false;
-  await writeFile7(path, text, "utf8");
+  await writeFile6(path, text, "utf8");
   return true;
 }
 async function readScript(dir) {
@@ -7923,10 +7926,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`;
@@ -8101,7 +8113,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) {
@@ -8152,14 +8165,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;
@@ -8377,6 +8394,7 @@ async function pushTakeClaimable(dir, flags, r) {
   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`);
@@ -8915,9 +8933,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) {
@@ -8963,13 +8983,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") {
@@ -10335,7 +10360,7 @@ async function cmdBuild(argv) {
   const out = resolve8(
     strFlag(flags, "out") ?? join17(dirname3(file), "config.json")
   );
-  writeFileSync2(out, JSON.stringify(built.config, null, 2) + "\n");
+  writeOutputSync(out, JSON.stringify(built.config, null, 2) + "\n");
   const sidecar = out.replace(/\.json$/, "") + ".sources.json";
   writeFileSync2(sidecar, JSON.stringify(built.sources, null, 2) + "\n");
   for (const [fn, at2] of Object.entries(built.sources)) {
@@ -12153,7 +12178,6 @@ async function cmdRecipe(argv) {
 }
 
 // src/plugin/brand.ts
-import { writeFile as writeFile8 } from "fs/promises";
 import { resolve as resolve13 } from "path";
 import { parseFrontmatter as parseFrontmatter2 } from "@vosjs/shared/frontmatter";
 import { lookKindForGround } from "@vosjs/studio-core";
@@ -12476,6 +12500,7 @@ async function cmdBrand(argv) {
   if (refused) throw new UsageError(refused);
   const r = createReporter(flags.json === true);
   const out = resolve13(strFlag(flags, "out") ?? "BRAND.md");
+  await prepareOutput(out);
   r.log(`reading ${origin}/design.md and /llms.txt\u2026`);
   const [designText, llmsText] = await Promise.all([
     fetchText(`${origin}/design.md`),
@@ -12509,7 +12534,7 @@ async function cmdBrand(argv) {
     composition,
     llms?.claim ?? design?.description ?? null
   );
-  await writeFile8(out, md);
+  await writeOutput(out, md);
   const k = composition.kit;
   r.done(
     {
@@ -12647,7 +12672,6 @@ async function recordHosted(input) {
 import { urlSchemeProblem as urlSchemeProblem2 } from "@vosjs/render-core/record";
 
 // src/plugin/agentBrowser.ts
-import { writeFile as writeFile9 } from "fs/promises";
 import { resolve as resolve14 } from "path";
 function parseAgentBrowserLog(text) {
   const records = [];
@@ -13127,8 +13151,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, {
@@ -13145,7 +13169,7 @@ async function cmdActions(argv) {
     );
     return EXIT_ERROR;
   }
-  await writeFile9(out, `${JSON.stringify(result.actions, null, 2)}
+  await writeOutput(out, `${JSON.stringify(result.actions, null, 2)}
 `);
   r.done(
     { ok: true, out, url: result.actions.url ?? null, ...summary2(result) },
@@ -13165,9 +13189,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  ")}`);
@@ -13445,7 +13469,7 @@ async function cmdIngest(argv) {
 // src/plugin/checkVideo.ts
 import { createRequire as createRequire2 } from "module";
 import { existsSync as existsSync23 } from "fs";
-import { mkdir as mkdir9, readFile as readFile14, stat as stat3, writeFile as writeFile10 } from "fs/promises";
+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 { ALL_FORMATS as ALL_FORMATS2, FilePathSource as FilePathSource2, Input as Input2 } from "mediabunny";
 
@@ -13992,8 +14016,8 @@ async function checkVideo(browser, file, outDir) {
   await mkdir9(outDir, { recursive: true });
   const firstFile = join24(outDir, "first.png");
   const lastFile = join24(outDir, "last.png");
-  await writeFile10(firstFile, Buffer.from(done.firstPng, "base64"));
-  await writeFile10(lastFile, Buffer.from(done.lastPng, "base64"));
+  await writeFile7(firstFile, Buffer.from(done.firstPng, "base64"));
+  await writeFile7(lastFile, Buffer.from(done.lastPng, "base64"));
   const changes = sceneChanges2(
     done.times,
     done.changes,
@@ -14039,7 +14063,7 @@ async function checkVideo(browser, file, outDir) {
     warnings,
     outDir
   };
-  await writeFile10(
+  await writeFile7(
     join24(outDir, "check.json"),
     `${JSON.stringify(result, null, 2)}
 `
@@ -14122,7 +14146,7 @@ import {
   mkdtemp,
   readFile as readFile15,
   rm as rm3,
-  writeFile as writeFile11
+  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";
@@ -14565,7 +14589,7 @@ async function resolveTrack(dir, ref, flags, dryRun) {
   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");
-  await writeFile11(path, new Uint8Array(await res.arrayBuffer()));
+  await writeFile8(path, new Uint8Array(await res.arrayBuffer()));
   return {
     path,
     key: track.url,
@@ -16813,7 +16837,7 @@ async function cmdTakeInfo(argv) {
 }
 
 // src/plugin/audio.ts
-import { mkdtemp as mkdtemp2, rm as rm5, writeFile as writeFile12 } from "fs/promises";
+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 { clipGain as clipGain3 } from "@vosjs/studio-core";
@@ -16829,7 +16853,7 @@ async function fileFor(dir, key, fetchImpl) {
     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");
-    await writeFile12(path, new Uint8Array(await res.arrayBuffer()));
+    await writeFile9(path, new Uint8Array(await res.arrayBuffer()));
     return { path, cleanup: () => rm5(tmp, { recursive: true, force: true }) };
   }
   return {
@@ -16909,9 +16933,10 @@ async function cmdAudio(argv) {
 }
 
 // src/plugin/look.ts
-import { mkdir as mkdir12 } from "fs/promises";
+import { mkdir as mkdir12, mkdtemp as mkdtemp3, readFile as readFile18, rm as rm6 } from "fs/promises";
 import { existsSync as existsSync27 } from "fs";
-import { join as join30, resolve as resolve20 } from "path";
+import { tmpdir as tmpdir4 } from "os";
+import { dirname as dirname10, join as join30, resolve as resolve20 } from "path";
 import { headersFor, urlSchemeProblem } from "@vosjs/render-core/record";
 function quote(value) {
   return `"${value.replace(/\s+/g, " ").replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
@@ -17314,19 +17339,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"),
@@ -17342,25 +17367,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");
@@ -17418,7 +17455,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 USAGE5 = "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"}`;
@@ -17447,12 +17504,30 @@ async function cmdLook(argv) {
   );
   void multi.click;
   void multi.type;
-  const url = positionals[0];
+  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(resolve20(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(USAGE5);
   const scheme = urlSchemeProblem(url);
   if (scheme) throw new UsageError(scheme);
   const r = createReporter(flags.json === true);
-  const viewport = parseViewport2(strFlag(flags, "viewport"));
+  const viewportFlag = strFlag(flags, "viewport");
+  const viewport = !viewportFlag && actions?.viewport ? actions.viewport : parseViewport2(viewportFlag);
   const outDir = resolve20(strFlag(flags, "out") ?? "look");
   const headed = flags.headed === true;
   const waitRaw = strFlag(flags, "wait");
@@ -17483,6 +17558,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: resolve20(actionsArg),
+      untilId,
+      viewport,
+      outDir,
+      waitMs,
+      headed,
+      storageState,
+      sessionName,
+      headers,
+      browserArgs
+    });
   const inContext = async (ctx) => {
     if (Object.keys(headers).length)
       await ctx.route("**/*", async (route) => {
@@ -17529,6 +17620,108 @@ 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";
@@ -17546,7 +17739,7 @@ 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 { dirname as dirname11, join as join31 } from "path";
 var AGENT_NAMES = [
   "claude",
   "cursor",
@@ -17766,7 +17959,7 @@ function bundledSkillsVersion(dir) {
   }
 }
 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)) {
@@ -17779,7 +17972,7 @@ function bundledSkillsDir(from) {
       } catch {
       }
     }
-    const up = dirname10(dir);
+    const up = dirname11(dir);
     if (up === dir) break;
     dir = up;
   }
@@ -18501,7 +18694,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)
@@ -18723,7 +18916,7 @@ function reRecord(outDir, flags, r) {
         ...from ? {
           reuse: {
             from,
-            doc: JSON.parse(await readFile18(from, "utf8"))
+            doc: JSON.parse(await readFile19(from, "utf8"))
           }
         } : {}
       });
@@ -18830,7 +19023,7 @@ async function cmdRecord(argv) {
       );
     const hostedActions = await scriptForHost(
       actions,
-      dirname11(resolve21(actionsPath))
+      dirname12(resolve21(actionsPath))
     ).catch((e) => {
       throw new UsageError(e instanceof Error ? e.message : String(e));
     });
@@ -18940,7 +19133,7 @@ async function cmdRecord(argv) {
         sessionName,
         actions,
         (context2) => recordTake(browser2, url, actions, takePaths(outDir), r.log, {
-          actionsDir: dirname11(resolve21(actionsPath)),
+          actionsDir: dirname12(resolve21(actionsPath)),
           storageState,
           headers,
           context: context2,
@@ -19048,7 +19241,7 @@ ${lines.join("\n")}
       sessionName,
       actions,
       (context2) => recordTake(browser, url, actions, paths, r.log, {
-        actionsDir: dirname11(resolve21(actionsPath)),
+        actionsDir: dirname12(resolve21(actionsPath)),
         maxDurationSeconds,
         storageState,
         headers,
@@ -19187,7 +19380,7 @@ async function cmdCreate2(argv) {
       sessionName,
       actions,
       (context2) => recordTake(browser, url, actions, paths, r.log, {
-        actionsDir: dirname11(resolve21(actionsPath)),
+        actionsDir: dirname12(resolve21(actionsPath)),
         maxDurationSeconds,
         storageState,
         headers,
@@ -19314,7 +19507,7 @@ 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;
@@ -19327,7 +19520,7 @@ async function cmdPlan(argvIn) {
     }
     reuse = {
       from,
-      doc: JSON.parse(await readFile18(from, "utf8"))
+      doc: JSON.parse(await readFile19(from, "utf8"))
     };
   }
   const style = await resolveStyleRef(flags);
@@ -19799,7 +19992,7 @@ async function resolveDocRef(ref, flags, what) {
     return {
       from: file,
       doc: migrateHostedDoc4(
-        JSON.parse(await readFile18(file, "utf8"))
+        JSON.parse(await readFile19(file, "utf8"))
       )
     };
   }
@@ -19851,7 +20044,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;
@@ -19964,7 +20157,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"),
@@ -20077,7 +20270,7 @@ async function cmdValidate(argv) {
   }
   if (!isTakeDir(target) && existsSync30(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}`);
@@ -20235,16 +20428,19 @@ async function cmdPush3(argv) {
   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(
+    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(
@@ -20261,6 +20457,7 @@ async function cmdPush3(argv) {
         origin: strFlag(flags, "origin"),
         title: strFlag(flags, "title"),
         prompt: strFlag(flags, "prompt"),
+        description,
         share: flags.share === true,
         bake: flags.bake === true
       },
@@ -20291,6 +20488,7 @@ reference and the only credential.`
       folder: strFlag(flags, "folder"),
       overrides,
       prompt: strFlag(flags, "prompt"),
+      description,
       bake: flags.bake === true
     },
     r
@@ -20682,4 +20880,4 @@ export {
   verbHelp,
   run
 };
-//# sourceMappingURL=chunk-5VGIQKVT.js.map
+//# sourceMappingURL=chunk-DM7ADA77.js.map