@hypersocial/decks-cli 0.2.2 → 0.3.0

package/src/init.mjs

@@ -0,0 +1,605 @@
+// hyperdecks init [--yes] [--json] [--agent <id>]... [--all-agents] [--voice dash] [--name n --about a --ask k] [--dir d]
+//                 [--no-voice] [--no-skill] [--no-release] [--no-open]
+//
+// The first run, start to finish: sign in, install the skill, get a voice,
+// scaffold a three-slide hello deck from three answers, narrate it, release one
+// QA link and print it. Every step checks real state before it acts, so running
+// init again resumes where it stopped and changes nothing once it is complete.
+// Each step returns { step, status: "done" | "skipped" | "ran" | "needs-human", detail }.
+// CLI-only, like login: there is no MCP tool for it.
+import { execFileSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import * as ops from "./ops.mjs";
+import { slugify } from "./importer.mjs";
+import { agentTable, api, chooseAgents, client, CRED_DIR, installHyperdecksSkill, login as runLogin, openBrowser, target } from "./runtime.mjs";
+import { READING_PASSAGE, voiceClone as runVoiceClone } from "./voice.mjs";
+import { assembleLayoutDeck, deckNew as runDeckNew } from "./scaffold.mjs";
+import { narrate as runNarrate } from "./narrate.mjs";
+import { release as runRelease } from "./release.mjs";
+
+export const STATE_FILE = join(CRED_DIR, "init.json");
+export const FIRST_DECK_LAYOUTS = "hero,features,closer";
+export const DASH_AVATAR = "https://decks.hypersocial.ai/player/v1/dash-avatar.json";
+// Same numbers as convex/lib/tokenCost.ts (the published CLI cannot import it).
+export const VOICE_CLONE_COST = 10;
+export const STARTER_GRANT = 30;
+export const ANSWER_MAX = { name: 40, about: 80, ask: 80 };
+const SKILL_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "skills", "hyperdecks");
+// CLI-only, so read next to the package rather than through files.mjs (the hosted route's list).
+const FIRST_DECK_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "first-deck");
+const CHARACTERS = ["dash", "d.a.s.h."];
+const RESUME = "npx hyperdecks init";
+export const AGENT_VOICE_HELP = "ask the user to run `npx hyperdecks voice clone <file> --name <name>` in a terminal, " +
+  "or upload with `voice upload` and call `clone_voice` after they agree to the statement; " +
+  "or run init again with `--voice dash` to let D.A.S.H. present";
+
+const isCharacter = (voice) => CHARACTERS.includes(String(voice ?? "").trim().toLowerCase());
+const step = (name, status, detail, extra = {}) => ({ step: name, status, detail, ...extra });
+
+// ---- local state ----------------------------------------------------------
+
+// init.json: per deployment, the deck init made and its release. No credentials.
+export function readState(path = STATE_FILE) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return {};
+    throw e;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${path} is not valid JSON; fix it, or delete it to start over (init then makes a new deck)`);
+  }
+}
+
+export function writeState(path, all) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, JSON.stringify(all, null, 2) + "\n", { mode: 0o600 });
+}
+
+// ---- answers and the first deck -------------------------------------------
+
+// One answer as it goes on a slide and into the script: one line, no stage-tag
+// brackets, ending in a full stop so it is its own caption.
+export function cleanAnswer(key, value) {
+  const text = String(value ?? "").replace(/[[\]]/g, "").replace(/\s+/g, " ").trim();
+  if (text.length < 2) throw new Error(`--${key} needs an answer`);
+  if (text.length > ANSWER_MAX[key]) throw new Error(`--${key} is ${text.length} characters; keep it to ${ANSWER_MAX[key]} so it fits a caption`);
+  return key === "name" ? text.replace(/[.!?]+$/, "") : /[.!?…]$/.test(text) ? text : `${text}.`;
+}
+
+export const firstDeckSlug = (email) => `hello-${slugify(String(email ?? "").split("@")[0]) || "there"}`.slice(0, 58).replace(/-+$/, "");
+
+const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+export function firstDeckCopy(presenter) {
+  return JSON.parse(readFileSync(join(FIRST_DECK_DIR, `${presenter === "dash" ? "character" : "self"}.json`), "utf8"));
+}
+
+function slots(text, answers, html) {
+  const map = { __NAME__: answers.name, __WHAT__: answers.about, __ASK__: answers.ask };
+  return text.replace(/__NAME__|__WHAT__|__ASK__/g, (k) => (html ? escapeHtml(map[k]) : map[k]));
+}
+
+// Replace exactly one match, or fail loudly: a layout change must not ship a deck
+// that still says "One sentence on what this deck is about."
+function swap(html, pattern, to, what) {
+  let hit = 0;
+  const out = html.replace(pattern, (...m) => (hit++, typeof to === "function" ? to(...m) : to));
+  if (hit !== 1) throw new Error(`first deck: the ${what} in the layout template changed (${hit} matches); update init's first-deck fill`);
+  return out;
+}
+
+function section(html, id, edit) {
+  return swap(html, new RegExp(`<section\\b[^>]*\\sid="${id}"[\\s\\S]*?</section>`), (s) => edit(s), `#${id} slide`);
+}
+
+// index.html and script.md of the scaffolded hero,features,closer deck, filled
+// with the answers: no template copy is left, and no generated imagery.
+export function fillFirstDeck({ html, title, answers, presenter, voice }) {
+  const copy = firstDeckCopy(presenter);
+  const h = (t) => slots(t, answers, true);
+  const note = (s) => swap(s, /\sdata-note="[^"]*"/, ' data-note="From your init answers."', "data-note");
+  let out = section(html, "hero", (s) => {
+    s = note(s);
+    s = swap(s, /<div class="kicker">[^<]*<\/div>/, `<div class="kicker">${h(copy.hero.kicker)}</div>`, "hero kicker");
+    s = swap(s, /<h1 class="tt"[^>]*>[\s\S]*?<\/h1>/, `<h1 class="tt" data-title-mobile="${h(copy.hero.title)}">${h(copy.hero.title)}</h1>`, "hero title");
+    return swap(s, /<p class="lead">[\s\S]*?<\/p>/, `<p class="lead">${h(copy.hero.lead)}</p>`, "hero lead");
+  });
+  out = section(out, "features", (s) => {
+    s = note(s);
+    s = swap(s, /<div class="kicker">[^<]*<\/div>/, `<div class="kicker">${h(copy.features.kicker)}</div>`, "features kicker");
+    s = swap(s, /<h2 class="tt"[^>]*>[\s\S]*?<\/h2>/, `<h2 class="tt" data-title-mobile="${h(copy.features.title)}">${h(copy.features.title)}</h2>`, "features title");
+    copy.features.cards.forEach((card, i) => {
+      s = swap(s, new RegExp(`(<li class="card" id="features-f${i + 1}">[\\s\\S]*?</svg>)<b>[^<]*</b><p>[^<]*</p>`), (_, icon) => `${icon}<b>${h(card.name)}</b><p>${h(card.line)}</p>`, `features card ${i + 1}`);
+    });
+    return s;
+  });
+  out = section(out, "closer", (s) => {
+    s = note(s);
+    s = swap(s, /<h2 class="tt"[^>]*>[\s\S]*?<\/h2>/, `<h2 class="tt" data-title-mobile="${h(copy.closer.title)}">${h(copy.closer.title)}</h2>`, "closer title");
+    s = swap(s, /<p class="lead">[\s\S]*?<\/p>/, `<p class="lead">${h(copy.closer.lead)}</p>`, "closer lead");
+    s = swap(s, /<a class="cta"[^>]*>[\s\S]*?<\/a>/, `<p class="cta" id="closer-cta">${h(copy.closer.cta)}</p>`, "closer call to action");
+    return swap(s, /<div class="contact muted">[^<]*<\/div>/, `<div class="contact muted">${h(copy.closer.contact)}</div>`, "closer contact");
+  });
+  // A character's live head presents its own deck; a person's voice ships with
+  // captions only (data-presenter="none"), never on a character's face.
+  if (presenter === "dash") {
+    out = swap(out, /(<script type="module" src="https:\/\/decks\.hypersocial\.ai\/player\/v1\/player\.js"[^>]*?)\sdata-presenter="none"/, (_, tag) => `${tag} data-presenter="head" data-avatar="${DASH_AVATAR}"`, "player tag");
+  }
+  const s = (t) => slots(t, answers, false);
+  const script = `---
+voice: ${voice}
+maxTotalSeconds: 90
+transition: drift
+---
+
+# ${title} — narration script
+
+Written by \`hyperdecks init\` from your three answers. Make it yours: rewrite
+these lines and the slides in index.html, then
+
+    hyperdecks narrate .
+    hyperdecks release . --to "<name>"
+
+## hero
+${s(copy.hero.script)}
+
+## features
+${s(copy.features.script)}
+
+## closer
+${s(copy.closer.script)}
+`;
+  return { html: out, script };
+}
+
+// ---- git ------------------------------------------------------------------
+
+function git(cwd, args, extra = {}) {
+  return execFileSync("git", ["-C", cwd, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...extra }).trim();
+}
+
+export function insideRepo(dir) {
+  try {
+    return git(dir, ["rev-parse", "--is-inside-work-tree"]) === "true";
+  } catch {
+    return false;
+  }
+}
+
+// Commit only the deck folder, whatever else the repository has staged. A
+// machine with no git identity commits as the signed-in account.
+export function commitDeck(deckDir, message, who = {}) {
+  git(deckDir, ["add", "--", "."]);
+  if (!git(deckDir, ["status", "--porcelain", "--", "."])) return false;
+  const id = [];
+  if (!gitConfig(deckDir, "user.email")) id.push("-c", `user.email=${who.email || "hyperdecks@localhost"}`);
+  if (!gitConfig(deckDir, "user.name")) id.push("-c", `user.name=${who.name || "Hyperdecks"}`);
+  execFileSync("git", ["-C", deckDir, ...id, "-c", "commit.gpgsign=false", "commit", "-q", "-m", message, "--", "."], { stdio: ["ignore", "pipe", "pipe"] });
+  return true;
+}
+
+function gitConfig(dir, key) {
+  try {
+    return git(dir, ["config", key]);
+  } catch {
+    return "";
+  }
+}
+
+// ---- skill ----------------------------------------------------------------
+
+function filesUnder(dir, base = dir) {
+  return readdirSync(dir).flatMap((name) => {
+    const p = join(dir, name);
+    return statSync(p).isDirectory() ? filesUnder(p, base) : [relative(base, p)];
+  }).sort();
+}
+
+// A hash of every file in a skill folder; null when it is not there.
+export function skillHash(dir) {
+  if (!existsSync(join(dir, "SKILL.md"))) return null;
+  const h = createHash("sha256");
+  for (const f of filesUnder(dir)) h.update(f).update("\0").update(readFileSync(join(dir, f))).update("\0");
+  return h.digest("hex");
+}
+
+// ---- prompts --------------------------------------------------------------
+
+// Ctrl-C or Ctrl-D cancels init: it never reads as an empty answer (which
+// would mean "yes" or the default choice).
+export const CANCELLED = `init cancelled; run \`${RESUME}\` again to pick up where it stopped`;
+export async function askLine(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  let answered = false;
+  try {
+    return await new Promise((resolve, reject) => {
+      rl.once("close", () => answered || reject(new Error(CANCELLED)));
+      rl.once("SIGINT", () => rl.close());
+      rl.question(question).then((a) => { answered = true; resolve(a); }, () => reject(new Error(CANCELLED)));
+    });
+  } finally {
+    rl.close();
+  }
+}
+
+// Paths dragged into a terminal: space separated, with backslash escapes or quotes.
+export function parseDroppedPaths(line) {
+  const out = [];
+  let cur = "";
+  let quote = null;
+  let any = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === quote) quote = null;
+      else cur += c;
+    } else if (c === "'" || c === '"') {
+      quote = c;
+      any = true;
+    } else if (c === "\\" && i + 1 < line.length) {
+      cur += line[++i];
+      any = true;
+    } else if (/\s/.test(c)) {
+      if (cur || any) out.push(cur);
+      cur = "";
+      any = false;
+    } else cur += c;
+  }
+  if (cur || any) out.push(cur);
+  return out.filter(Boolean);
+}
+
+// ---- the run --------------------------------------------------------------
+
+export async function init(pos = [], opts = {}, io = {}) {
+  const {
+    log = (line) => console.log(line),
+    ask = askLine,
+    interactive = !opts.json && !opts.yes && !!process.stdin.isTTY && !!process.stdout.isTTY,
+    login = runLogin,
+    installSkill = installHyperdecksSkill,
+    spawn,
+    voiceClone = runVoiceClone,
+    deckNew = runDeckNew,
+    narrate = runNarrate,
+    release = runRelease,
+    open = openBrowser,
+    statePath = STATE_FILE,
+    cwd = process.cwd(),
+    home = homedir(),
+    env = process.env,
+    random = () => randomBytes(2).toString("hex"),
+    fetch,
+  } = io;
+  if (pos.length) throw new Error(`unexpected argument(s): ${pos.join(" ")}; init takes flags only (hyperdecks init --help)`);
+  for (const k of ["voice", "name", "about", "ask", "dir"]) if (k in opts && typeof opts[k] !== "string") throw new Error(`--${k} requires a value`);
+  if (opts.voice !== undefined && opts["no-voice"]) throw new Error("use either --voice or --no-voice, not both");
+
+  const t = target(opts);
+  // Only the flags that pick the backend and credential reach the steps' own commands.
+  const base = Object.fromEntries(["prod", "dev", "convex", "broker", "token", "admin", "client"].filter((k) => opts[k] !== undefined).map((k) => [k, opts[k]]));
+  const all = readState(statePath);
+  const state = { ...(all[t.name] || {}) };
+  const save = (patch) => {
+    Object.assign(state, patch, { deployment: t.name });
+    writeState(statePath, { ...readState(statePath), [t.name]: state });
+  };
+  const steps = [];
+  const sub = (line) => log(String(line).split("\n").map((l) => `    ${l}`).join("\n"));
+  const mark = { done: "✓", ran: "✓", skipped: "–", "needs-human": "!" };
+  const record = (s) => {
+    steps.push(s);
+    log(`${mark[s.status] ?? "·"} ${s.detail}`);
+    return s;
+  };
+  const finish = (status, extra = {}) => {
+    const next = nextSteps(state);
+    if (status === "incomplete") log(`\nNot finished yet. When that is done, run \`${RESUME}\` again: it picks up where it stopped.`);
+    return { status, steps, slug: state.slug ?? null, deckDir: state.deckDir ?? null, shareUrl: state.shareUrl ?? null, next, ...extra };
+  };
+
+  // 1. Sign in.
+  let who = await whoamiOrNull(base, env);
+  if (who?.email) record(step("sign-in", "done", `signed in as ${who.email}`));
+  else {
+    if (!opts.token && !env.HSDECKS_TOKEN) log("No account yet? You can create one on the page that opens.");
+    try {
+      await login(base, { log: sub, open });
+    } catch (e) {
+      const why = ops.errorText(e);
+      throw new Error(/timed out/.test(why) ? `${why}. If the page said sign-up is closed: sign-up is invite only for now, write to hello@hypersocial.ai` : why);
+    }
+    who = await whoamiOrNull(base, env);
+    if (!who?.email) throw new Error("signed in, but the backend did not return your account; run `hyperdecks whoami`");
+    record(step("sign-in", "ran", `signed in as ${who.email}`));
+  }
+  if (state.email && state.email !== who.email) {
+    // Another account's deck is not this one's to resume.
+    for (const k of ["slug", "deckDir", "releasedAt", "shareUrl", "shareToken", "presenter", "voice"]) delete state[k];
+  }
+  save({ email: who.email, startedAt: state.startedAt ?? new Date().toISOString() });
+
+  // 2. The skill. Its failure never stops init: the deck does not need it.
+  record(await skillStep(opts, { interactive, ask, installSkill, spawn, home, env, sub }));
+
+  // 3. A voice.
+  const voiceStep = await chooseVoice(base, opts, { interactive, ask, voiceClone, sub, log, state, who });
+  record(voiceStep);
+  if (voiceStep.status === "needs-human") return finish("incomplete");
+  const { voice, presenter } = voiceStep;
+
+  // 4. The first deck.
+  const scaffold = await scaffoldStep(base, opts, { state, who, voice, presenter, interactive, ask, deckNew, cwd, home, random, sub, log, save });
+  record(scaffold);
+  if (scaffold.status === "needs-human") return finish("incomplete");
+
+  // 5. Narrate, then commit, so release finds a committed deck with a manifest.
+  record(await narrateStep(base, state, { narrate, who, sub }));
+
+  // 6. Check and release one QA link for yourself.
+  const shipped = await releaseStep(base, opts, state, { release, sub, save, fetch });
+  record(shipped);
+  if (shipped.status === "skipped") return finish("complete");
+
+  // 7. The link, opened, and what to do next.
+  log(`\nYour deck: ${state.shareUrl}`);
+  log("This link is yours to watch: it is QA, so its views are not tracked.");
+  if (!opts["no-open"]) open(state.shareUrl);
+  log("\nNext:");
+  for (const n of nextSteps(state)) log(`  ${n}`);
+  return finish("complete");
+}
+
+function nextSteps(state) {
+  if (!state.slug) return [RESUME];
+  return [
+    `hyperdecks share new ${state.slug} "<name>"   a tracked link for each person you send it to`,
+    `Paste into your agent: "Make my hello deck yours: open ${state.deckDir}, ask me what I'm working on, and rewrite index.html and script.md around it. Keep three slides and about 40 seconds, then run hyperdecks release ${state.deckDir} --to \\"Me\\" --qa."`,
+    "hyperdecks activity   who watched, and how far they got",
+  ];
+}
+
+async function whoamiOrNull(base, env) {
+  try {
+    return await ops.whoami(base);
+  } catch (e) {
+    const why = ops.errorText(e);
+    // No credential, or one the broker refuses (revoked): sign in again. An
+    // outage (5xx, 429, no answer) is reported, not mistaken for signed out.
+    if (!/^not authenticated|auth exchange failed \((401|403)\)|credential was rejected/i.test(why)) throw e;
+    if (!base.token && env.HSDECKS_TOKEN) throw new Error(`HSDECKS_TOKEN was rejected (${why}); unset it or replace it, then run init again`);
+    if (base.token) throw new Error(`--token was rejected (${why})`);
+    return null;
+  }
+}
+
+async function skillStep(opts, { interactive, ask, installSkill, spawn, home, env, sub }) {
+  if (opts["no-skill"]) return step("skill", "skipped", "skill: skipped (--no-skill)");
+  let chosen;
+  try {
+    chosen = chooseAgents(opts, [], { home, env });
+  } catch (e) {
+    return step("skill", "skipped", `skill: not installed (${e.message})`, { warning: true });
+  }
+  const table = agentTable({ home, env });
+  const label = (id) => table.find((a) => a.id === id)?.label ?? id;
+  let agents = chosen.agents;
+  if (chosen.source === "default") sub(`no agent found in your home directory; installing for ${agents.map(label).join(", ")}`);
+  const packaged = skillHash(SKILL_DIR);
+  // An install is current when every chosen agent's copy matches the packaged skill.
+  const current = (id) => {
+    const dir = table.find((a) => a.id === id)?.skills;
+    return !!dir && skillHash(join(dir, "hyperdecks")) === packaged;
+  };
+  if (agents[0] !== "*" && agents.every(current)) return step("skill", "done", `skill installed for ${agents.map(label).join(", ")}`);
+  if (agents[0] !== "*") agents = agents.filter((id) => !current(id));
+  if (interactive && chosen.source !== "flag") {
+    const names = agents[0] === "*" ? "every agent" : agents.map(label).join(", ");
+    const answer = (await ask(`Install the Hyperdecks skill for ${names}? [Y/n] `)).trim().toLowerCase();
+    if (answer && !answer.startsWith("y")) return step("skill", "skipped", "skill: skipped; install it later with `hyperdecks skills install`");
+  }
+  sub("installing with npx skills…");
+  try {
+    installSkill({ ...(agents[0] === "*" ? { "all-agents": true } : { agent: agents.join(",") }) }, [], { quiet: true, spawn, home, env });
+  } catch (e) {
+    return step("skill", "skipped", `skill: not installed (${e.message}); the deck does not need it, try \`hyperdecks skills install\` later`, { warning: true });
+  }
+  // Agents init has no folder for (a valid `npx skills` id outside agentTable) are trusted on its exit code.
+  const missing = agents[0] === "*" ? [] : agents.filter((id) => table.some((a) => a.id === id) && !current(id));
+  if (missing.length) {
+    const where = missing.map((id) => `${label(id)} (${table.find((a) => a.id === id)?.skills})`).join(", ");
+    return step("skill", "skipped", `skill: npx skills finished but the skill is not in ${where}; try \`hyperdecks skills install\``, { warning: true });
+  }
+  return step("skill", "ran", `skill installed for ${agents[0] === "*" ? "every agent" : agents.map(label).join(", ")}`, { agents });
+}
+
+// A ledger with no rows means the starter grant has not landed yet: it does on
+// the first spend, so a new account can afford its first clone.
+async function spendable(base) {
+  const { balance } = await ops.creditsBalance(base);
+  if (balance > 0) return balance;
+  const ledger = await ops.creditsLedger(base, 1);
+  return ledger.length ? balance : STARTER_GRANT;
+}
+
+async function chooseVoice(base, opts, { interactive, ask, voiceClone, sub, log, state, who }) {
+  const dash = () => step("voice", "done", "D.A.S.H. presents, in the dash character voice", { voice: "dash", presenter: "dash" });
+  if (isCharacter(opts.voice)) return dash();
+  const voices = await ops.listVoices(base);
+  const own = (v) => step("voice", "done", `voice "${v.name}" is ready`, { voice: v.name, presenter: "self" });
+  if (opts.voice) {
+    const want = opts.voice.trim().toLowerCase();
+    const hit = voices.find((v) => v.id === opts.voice || v.name.toLowerCase() === want || v.handle?.toLowerCase() === want);
+    if (!hit) throw new Error(`--voice ${opts.voice} is not one of your voices (${voices.map((v) => v.name).join(", ") || "none yet"}); use --voice dash for D.A.S.H.`);
+    if (hit.status === "ready") return own(hit);
+    // The voice asked for, or nothing: never a different one in its place.
+    const v = hit.status === "pending" ? (sub(`voice "${hit.name}" is still cloning; waiting for it…`), await ops.pollVoice(base, hit.id)) : hit;
+    if (v.status === "ready") return { ...own(v), status: "ran" };
+    throw new Error(`voice "${hit.name}" is not ready (${v.status}${v.error ? `: ${v.error}` : ""}); clone it again or pick another --voice`);
+  }
+  // The deck init already made keeps the voice it was written for.
+  if (state.presenter === "dash" && state.slug) return dash();
+  const ready = voices.find((v) => v.status === "ready");
+  if (ready) return own(ready);
+  const pending = voices.find((v) => v.status === "pending");
+  let failed = "";
+  if (pending) {
+    sub(`voice "${pending.name}" is still cloning; waiting for it…`);
+    const v = await ops.pollVoice(base, pending.id);
+    if (v.status === "ready") return { ...own(v), status: "ran" };
+    failed = `voice "${v.name}" failed (${v.error}); `;
+    sub(failed);
+  }
+  const later = (why) => step("voice", "needs-human", `voice: ${why}. Run \`${RESUME}\` when you have one`);
+  if (opts["no-voice"]) return later("skipped for now (--no-voice)");
+  if (!interactive) return step("voice", "needs-human", `voice: ${failed}none ready yet; ${AGENT_VOICE_HELP}`);
+
+  for (;;) {
+    log("\nYour deck needs a voice to narrate it. Pick one:");
+    log(`  1. Clone my voice (${VOICE_CLONE_COST} credits, refunded if it fails)`);
+    log("  2. Let D.A.S.H. present it (free; a character, introducing you)");
+    log("  3. Later");
+    const pick = (await ask("Choose 1, 2 or 3 [1]: ")).trim() || "1";
+    if (pick === "2") return dash();
+    if (pick === "3") return later("not chosen yet");
+    if (pick !== "1") continue;
+    const credits = await spendable(base);
+    if (credits < VOICE_CLONE_COST) {
+      log(`Cloning a voice costs ${VOICE_CLONE_COST} credits and you have ${credits}. D.A.S.H. is free.`);
+      continue;
+    }
+    log(`\nRecord yourself reading this aloud (about 45 seconds), with Voice Memos, QuickTime or your phone:\n\n  ${READING_PASSAGE}\n`);
+    log("Save it as .m4a, .mp3 or .wav (up to 3 files, 10 MB each), then drag the file(s) into this terminal.");
+    const files = parseDroppedPaths(await ask("Recording(s): "));
+    if (!files.length) continue;
+    const name = (await ask(`Name for this voice [${who.email.split("@")[0]}]: `)).trim() || who.email.split("@")[0];
+    try {
+      const v = await voiceClone(files, { ...base, name }, { ask, log: sub });
+      return step("voice", "ran", `voice "${v.name}" is ready`, { voice: v.name, presenter: "self" });
+    } catch (e) {
+      log(`Voice clone did not finish: ${ops.errorText(e)}`);
+      // A clone still running (a poll timeout) is already paid for: wait for it, never start another.
+      const still = (await ops.listVoices(base)).find((v) => v.status === "pending");
+      if (still) return step("voice", "needs-human", `voice: "${still.name}" is still cloning. Run \`${RESUME}\` in a few minutes`);
+    }
+  }
+}
+
+async function deckOwnedBy(base, slug, who) {
+  const deck = await (await client(base)).query(api.decks.get, { slug });
+  return deck ? { exists: true, mine: deck.ownerId === who.subject } : { exists: false, mine: false };
+}
+
+async function scaffoldStep(base, opts, { state, who, voice, presenter, interactive, ask, deckNew, cwd, home, random, sub, log, save }) {
+  // A deck init registered but did not finish writing (interrupted before its
+  // commit) is resumed under the same slug, not orphaned for a suffixed one.
+  const resumable = !!state.slug && !!state.deckDir && existsSync(join(state.deckDir, "index.html")) && (await deckOwnedBy(base, state.slug, who)).mine;
+  if (resumable && state.scaffolded) return step("scaffold", "done", `deck "${state.slug}" → ${state.deckDir}`);
+  const keys = ["name", "about", "ask"];
+  const questions = { name: "Your name: ", about: "What you do, in one line: ", ask: "What should people do after watching? " };
+  if (!interactive && !keys.every((k) => opts[k] !== undefined)) {
+    return step("scaffold", "needs-human", "deck: pass --name, --about and --ask (your name, what you do in one line, what people should do after watching)");
+  }
+  if (interactive && !keys.every((k) => opts[k] !== undefined)) log("\nThree quick questions for your first deck (you can rewrite it later):");
+  const answers = {};
+  for (const k of keys) {
+    if (opts[k] !== undefined) answers[k] = cleanAnswer(k, opts[k]);
+    while (answers[k] === undefined) {
+      try {
+        answers[k] = cleanAnswer(k, await ask(questions[k]));
+      } catch (e) {
+        log(`  ${e.message.replace(/^--\w+/, "That")}`);
+      }
+    }
+  }
+
+  // Slugs are global: on a clash, a short random suffix.
+  // The default folder is ./hyperdecks, except inside someone's repository (an
+  // agent's working directory, usually): init never commits onto their branch
+  // unasked, so the deck goes in ~/hyperdecks, a repository of its own.
+  const ownDir = typeof opts.dir === "string";
+  const inProject = !resumable && !ownDir && insideRepo(cwd);
+  const root = resumable ? dirname(state.deckDir) : ownDir ? dirname(resolve(cwd, opts.dir)) : join(inProject ? home : cwd, "hyperdecks");
+  if (inProject) sub(`${cwd} is a git repository, so the deck goes in ${root} rather than committing into it (--dir picks another folder)`);
+  let slug = resumable ? state.slug : firstDeckSlug(who.email);
+  for (let i = 0; !resumable; i++) {
+    const dir = typeof opts.dir === "string" ? resolve(cwd, opts.dir) : join(root, slug);
+    if (!(await deckOwnedBy(base, slug, who)).exists && (typeof opts.dir === "string" || !existsSync(dir))) break;
+    if (i >= 5) throw new Error(`could not find a free deck slug near ${firstDeckSlug(who.email)}; pass --dir`);
+    slug = `${firstDeckSlug(who.email)}-${random()}`;
+  }
+  const deckDir = resumable ? state.deckDir : ownDir ? resolve(cwd, opts.dir) : join(root, slug);
+  mkdirSync(root, { recursive: true });
+  const title = `Hello from ${answers.name}`;
+  if (!resumable) {
+    // Recorded first, so a run killed inside deck new resumes this slug.
+    for (const k of ["releasedAt", "shareUrl", "shareToken"]) delete state[k];
+    save({ slug, deckDir, scaffolded: false });
+    await deckNew([slug, title], { ...base, narrated: true, layouts: FIRST_DECK_LAYOUTS, dir: deckDir }, { log: () => {}, cwd });
+  }
+  // release ships a committed deck. A --dir outside any repository becomes one
+  // itself (never its parent, which may be your home folder).
+  if (!insideRepo(deckDir)) {
+    const repo = ownDir || resumable ? deckDir : root;
+    sub(`release ships a committed deck, so ${repo} becomes a git repository`);
+    git(repo, ["init", "-q"]);
+  }
+  // Filled from the layout template every time, so a half-written folder is overwritten whole.
+  const fresh = assembleLayoutDeck({ slug, title, layouts: FIRST_DECK_LAYOUTS });
+  const filled = fillFirstDeck({ html: fresh["index.html"], title, answers, presenter, voice });
+  writeFileSync(join(deckDir, "index.html"), filled.html);
+  writeFileSync(join(deckDir, "script.md"), filled.script);
+  writeFileSync(join(deckDir, "evidence.md"), fresh["evidence.md"]);
+  commitDeck(deckDir, "hyperdecks: first deck", { email: who.email, name: answers.name });
+  save({ slug, deckDir, presenter, voice, scaffolded: true });
+  return step("scaffold", "ran", `deck "${slug}" → ${deckDir}`);
+}
+
+async function narrateStep(base, state, { narrate, who, sub }) {
+  const html = () => readFileSync(join(state.deckDir, "index.html"), "utf8");
+  const hasManifest = () => /\sdata-manifest="https?:\/\/[^"]+"/.test(html()) && existsSync(join(state.deckDir, "narration", "manifest.json"));
+  const opts = { ...base, slug: state.slug };
+  if (hasManifest()) {
+    const preview = await narrate([state.deckDir], { ...opts, "dry-run": true }, { log: () => {} });
+    if (!preview.slides.some((s) => s.render)) {
+      // An earlier run may have stopped between narrating and committing.
+      const committed = commitDeck(state.deckDir, "hyperdecks: narrate", { email: who.email });
+      return step("narrate", committed ? "ran" : "done", "narration is current");
+    }
+  }
+  const job = await narrate([state.deckDir], opts, { log: sub });
+  if (!job?.manifestUrl) throw new Error(`narration finished without a manifest (${job?.notice || "no manifest URL"}); run \`${RESUME}\` again`);
+  commitDeck(state.deckDir, "hyperdecks: narrate", { email: who.email });
+  return step("narrate", "ran", `narrated: ${job.manifest?.clips?.length ?? "all"} slides, ${job.manifest?.totalDuration ?? "?"}s`);
+}
+
+async function releaseStep(base, opts, state, { release, sub, save, fetch }) {
+  const shares = await ops.listShares(base, state.slug);
+  if (state.releasedAt && state.shareToken && shares.some((s) => s.token === state.shareToken)) return step("release", "done", `released: ${state.shareUrl}`);
+  // A run killed after release made its link but before init.json recorded it.
+  const mine = !state.releasedAt && shares.find((s) => s.qa && s.recipient === "Me" && s.enabled);
+  if (mine) {
+    const url = `${target(base).shareBase}/v/${mine.token}`;
+    save({ releasedAt: new Date().toISOString(), shareUrl: url, shareToken: mine.token });
+    return step("release", "done", `released: ${url}`);
+  }
+  if (opts["no-release"]) {
+    const { checkDeck } = await import("./check.mjs");
+    const checked = await checkDeck(state.deckDir, {}, fetch ? { fetch } : {});
+    if (checked.errors.length) throw new Error(`check failed for ${state.slug}:\n${checked.errors.map((e) => `  - ${e}`).join("\n")}`);
+    return step("release", "skipped", `check passed; not released (--no-release): hyperdecks release ${state.deckDir} --to "Me" --qa`);
+  }
+  const out = await release([state.deckDir], { ...base, slug: state.slug, recipients: [{ recipient: "Me" }], qa: true }, { log: sub });
+  const url = out.shares[0].url;
+  save({ releasedAt: new Date().toISOString(), shareUrl: url, shareToken: url.split("/v/").pop() });
+  return step("release", "ran", `released: ${url}`);
+}