@hypersocial/decks-cli 0.2.2 → 0.3.0

package/src/layouts.mjs

@@ -0,0 +1,71 @@
+// The deck templates as text: the narrated outline and the layout library, filled
+// for a slug and title. No file I/O beyond reading the packaged templates, so the
+// hosted MCP route (new_deck) and the CLI (deck new) assemble the same deck.
+import { packageText } from "./files.mjs";
+
+export const NARRATED_FILES = { "index.html": "narrated-deck.html", "script.md": "script.md", "evidence.md": "evidence.md" };
+// The library, in a sensible deck order; `--layouts` takes any order and repeats.
+export const LAYOUTS = ["hero", "number", "product", "quote", "compare", "timeline", "features", "chart", "team", "closer"];
+const LAYOUT_ALIASES = { "big-number": "number", "product-shot": "product", comparison: "compare", "three-up": "features" };
+
+const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+// Template text with __SLUG__ / __TITLE__ filled; HTML gets an escaped title.
+// Without a presenter style the player tag carries none (the player's default).
+export function fillTemplate(file, { slug, title, presenterStyle }) {
+  const text = packageText(`templates/${file}`);
+  const t = /\.html$/.test(file) ? escapeHtml(title) : title;
+  const styled = presenterStyle ? text.split("__PRESENTER_STYLE__").join(presenterStyle) : text.replace(/\s*data-presenter-style="__PRESENTER_STYLE__"/g, "");
+  return styled.split("__SLUG__").join(slug).split("__TITLE__").join(t);
+}
+
+// One layout file: a leading comment of `key: value` lines (layout, summary,
+// use, slot, presenter, cues, script), its <style> and its <section>.
+export function readLayout(name) {
+  const text = packageText(`templates/layouts/${name}.html`);
+  const head = /^<!--([\s\S]*?)-->/.exec(text);
+  const style = /<style>[\s\S]*?<\/style>/.exec(text);
+  const section = /<section\b[\s\S]*<\/section>/.exec(text);
+  if (!head || !style || !section) throw new Error(`layout ${name}: needs a leading comment, a <style> and a <section>`);
+  const meta = {};
+  for (const line of head[1].split("\n")) {
+    const m = /^([a-z]+):\s*(.*)$/.exec(line.trim());
+    if (m) meta[m[1]] = m[2];
+  }
+  return { name, meta, style: style[0], section: section[0] };
+}
+
+export function parseLayouts(list) {
+  const names = String(list).split(",").map((n) => n.trim().toLowerCase()).filter(Boolean).map((n) => LAYOUT_ALIASES[n] ?? n);
+  const unknown = names.filter((n) => !LAYOUTS.includes(n));
+  if (unknown.length) throw new Error(`unknown layout${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}: pick from ${LAYOUTS.join(", ")}`);
+  if (!names.length) throw new Error(`--layouts needs at least one of ${LAYOUTS.join(", ")}`);
+  return names;
+}
+
+// index.html, script.md and evidence.md for a deck of `layouts`, one slide
+// each, in order. A layout used twice gets ids hero, hero-2, …; ids inside a
+// slide start with its id, so its cues stay unique.
+export function assembleLayoutDeck({ slug, title, presenterStyle, layouts }) {
+  const names = parseLayouts(layouts);
+  const used = new Map();
+  const slides = names.map((name) => {
+    const n = (used.get(name) ?? 0) + 1;
+    used.set(name, n);
+    return { layout: readLayout(name), id: n === 1 ? name : `${name}-${n}` };
+  });
+  const fill = (text, id, t) => text.split("__ID__").join(id).split("__SLUG__").join(slug).split("__TITLE__").join(t);
+  const sections = slides.map(({ layout, id }, i) => {
+    let html = fill(layout.section, id, escapeHtml(title));
+    if (i === 0 && !/\sdata-intro=/.test(html.slice(0, html.indexOf(">")))) html = html.replace("<section ", '<section data-intro="Hi! Press play." ');
+    return `<!-- layout: ${layout.name}. ${layout.meta.summary ?? ""} -->\n${html}`;
+  });
+  const styles = [...new Set(names)].map((name) => `<!-- layout: ${name} -->\n${readLayout(name).style}`);
+  const shell = fillTemplate("layouts/_deck.html", { slug, title, presenterStyle });
+  // Function replacements: a "$" in the title or a layout is text, not a replacement pattern.
+  const html = shell.replace("<!-- LAYOUT STYLES -->", () => styles.join("\n")).replace("<!-- SLIDES -->", () => sections.join("\n\n"));
+  const intro = fillTemplate("script.md", { slug, title }).split(/\n## /)[0].trimEnd();
+  const script = `${intro}\n\n${slides.map(({ layout, id }) => `## ${id}\n${fill(layout.meta.script ?? "", id, title)}`).join("\n\n")}\n`;
+  return { "index.html": html, "script.md": script, "evidence.md": fillTemplate("evidence.md", { slug, title }) };
+}
+

package/src/narrate.mjs

@@ -8,18 +8,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import * as ops from "./ops.mjs";
-
-// Same rule as sectionIds() in lib/deckScript.ts (the published CLI cannot import it).
-export const sectionIds = (html) => [...html.matchAll(/<section\b[^>]*?\sid\s*=\s*["']([^"']+)["']/gi)].map((m) => m[1]);
-
-// Set data-manifest on the hosted player's <script> tag; html is unchanged when
-// there is no player tag or it already names this URL.
-export function setManifestUrl(html, url) {
-  return html.replace(/<script\b[^>]*\/player\/v\d+\/player\.js"[^>]*>/, (tag) =>
-    /\sdata-manifest\s*=\s*"[^"]*"/.test(tag)
-      ? tag.replace(/(\sdata-manifest\s*=\s*)"[^"]*"/, (_, lead) => `${lead}"${url}"`)
-      : tag.replace(/\s*>$/, () => ` data-manifest="${url}">`));
-}
+export { sectionIds, setManifestUrl } from "./checkRules.mjs";
+import { sectionIds, setManifestUrl } from "./checkRules.mjs";
 
 function slideList(value) {
   const ids = value.split(",").map((s) => s.trim()).filter(Boolean);

package/src/ops.mjs

@@ -181,6 +181,7 @@ export async function reviewDeck(opts, fields = {}) {
   if (!fields.slug) throw new Error("slug is required");
   const args = { slug: String(fields.slug) };
   if (fields.script) args.script = String(fields.script);
+  if (fields.draft) args.draft = true;
   return (await client(opts)).action(api.review.reviewDeck, args);
 }
 
@@ -245,8 +246,9 @@ export async function pollVideoJob(opts, jobId, { intervalMs = 5000, timeoutMs =
 // thin client calls shared by the CLI `narrate` command and the MCP tools.
 function narrationArgs(fields = {}) {
   if (!fields.slug) throw new Error("slug is required");
-  if (!fields.script) throw new Error("script is required (the deck's script.md)");
-  const args = { slug: String(fields.slug), script: String(fields.script) };
+  // No script: narrate the deck's hosted script.md (deckSources), and the
+  // finished job writes the manifest URL into the hosted draft.
+  const args = fields.script ? { slug: String(fields.slug), script: String(fields.script) } : { slug: String(fields.slug), fromSource: true };
   if (fields.voice) args.voice = String(fields.voice);
   if (fields.slides) {
     if (!fields.slides.length) throw new Error("slides is empty; omit it to narrate every slide");

package/src/runtime.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 
-export const VERSION = "0.2.2";
+export const VERSION = "0.3.0";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -24,6 +24,16 @@ export const api = {
     generateUploadUrl: makeFunctionReference("assets:generateUploadUrl"),
     saveAsset: makeFunctionReference("assets:saveAsset"),
   },
+  assetsNode: {
+    importAssetFromUrl: makeFunctionReference("assetsNode:importAssetFromUrl"),
+  },
+  deckSources: {
+    create: makeFunctionReference("deckSources:create"),
+    get: makeFunctionReference("deckSources:get"),
+    write: makeFunctionReference("deckSources:write"),
+    check: makeFunctionReference("deckSources:check"),
+    release: makeFunctionReference("deckSources:release"),
+  },
   activity: {
     overview: makeFunctionReference("activity:overview"),
     setArchived: makeFunctionReference("activity:setArchived"),
@@ -89,7 +99,7 @@ export const api = {
   },
 };
 
-const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "help", "version", "all-agents", "global", "project", "transparent", "upload", "dry-run", "narrated", "layout", "full-page", "force"]);
+const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "help", "version", "all-agents", "global", "project", "transparent", "upload", "dry-run", "narrated", "layout", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open"]);
 // release's recipients, in order: each --to starts one, and an --email right
 // after it belongs to it (`--to A --email a --to B`). Collected as opts.recipients;
 // opts.email stays the last --email for the other commands (share new).
@@ -274,7 +284,42 @@ function splitAgents(value) {
   return String(value || "").split(/[,\s]+/).filter(Boolean);
 }
 
-export function installHyperdecksSkill(opts = {}, extraArgs = []) {
+export const DEFAULT_AGENTS = ["codex", "claude-code"];
+
+// Agents `npx skills` installs into, keyed by its agent id: the directory whose
+// presence means the agent is installed (the same test `npx skills` uses) and
+// where its global skills live. From skills@1.7 (dist/cli.mjs, agent table).
+export function agentTable({ home = homedir(), env = process.env } = {}) {
+  const config = env.XDG_CONFIG_HOME || join(home, ".config");
+  const claude = env.CLAUDE_CONFIG_DIR || join(home, ".claude");
+  return [
+    { id: "claude-code", label: "Claude Code", home: claude, skills: join(claude, "skills") },
+    { id: "codex", label: "Codex", home: env.CODEX_HOME || join(home, ".codex"), skills: join(home, ".agents", "skills") },
+    { id: "cursor", label: "Cursor", home: join(home, ".cursor"), skills: join(home, ".cursor", "skills") },
+    { id: "gemini-cli", label: "Gemini CLI", home: join(home, ".gemini"), skills: join(home, ".gemini", "skills") },
+    { id: "opencode", label: "OpenCode", home: join(config, "opencode"), skills: join(config, "opencode", "skills") },
+    { id: "windsurf", label: "Windsurf", home: join(home, ".codeium", "windsurf"), skills: join(home, ".codeium", "windsurf", "skills") },
+    { id: "github-copilot", label: "GitHub Copilot", home: join(home, ".copilot"), skills: join(home, ".copilot", "skills") },
+  ];
+}
+
+// The agents whose home directory exists on this machine.
+export function detectAgents({ home, env, exists = existsSync } = {}) {
+  return agentTable({ home, env }).filter((a) => exists(a.home)).map((a) => a.id);
+}
+
+// Which agents an install targets: --all-agents, --agent, or the detected ones
+// (today's codex,claude-code when none is found).
+export function chooseAgents(opts = {}, extraArgs = [], detect = {}) {
+  if (opts["all-agents"]) return { agents: ["*"], source: "all" };
+  if (opts.agent) return { agents: [...splitAgents(opts.agent), ...extraArgs.flatMap(splitAgents)], source: "flag" };
+  const found = detectAgents(detect);
+  return found.length ? { agents: found, source: "detected" } : { agents: DEFAULT_AGENTS, source: "default" };
+}
+
+// `quiet` pipes `npx skills` output instead of inheriting the terminal (init
+// --json keeps stdout for its one JSON object); a failure then carries its tail.
+export function installHyperdecksSkill(opts = {}, extraArgs = [], { spawn = spawnSync, quiet = false, log = (line) => console.log(line), home, env } = {}) {
   const skillDir = join(PACKAGED_SKILLS_DIR, "hyperdecks");
   if (!existsSync(skillDir)) {
     throw new Error(`packaged hyperdecks skill not found at ${skillDir}`);
@@ -292,19 +337,19 @@ export function installHyperdecksSkill(opts = {}, extraArgs = []) {
     throw new Error(`unexpected argument(s): ${extraArgs.join(" ")}; pass agent ids with --agent`);
   }
 
-  const agents = opts["all-agents"]
-    ? ["*"]
-    : [...splitAgents(opts.agent || "codex,claude-code"), ...extraArgs.flatMap(splitAgents)];
+  const { agents, source } = chooseAgents(opts, extraArgs, { home, env });
+  if (source === "default" && !quiet) log(`no agent found in your home directory; installing for ${agents.join(", ")}`);
   const args = ["-y", "skills@latest", "add", PACKAGED_SKILLS_DIR, "-g"];
   args.push("-a", ...agents, "-s", "hyperdecks", "--copy", "-y", "--full-depth");
 
   const command = process.platform === "win32" ? "npx.cmd" : "npx";
-  const result = spawnSync(command, args, { stdio: "inherit" });
+  const result = spawn(command, args, quiet ? { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" } : { stdio: "inherit" });
   if (result.error) throw result.error;
   if (result.status !== 0) {
-    throw new Error(`skills add failed with exit code ${result.status}`);
+    const tail = quiet ? `${result.stdout || ""}\n${result.stderr || ""}`.trim().split("\n").filter((l) => l.trim() && !/^npm warn/i.test(l)).slice(-3).join(" ") : "";
+    throw new Error(`skills add failed with exit code ${result.status}${tail ? `: ${tail}` : ""}`);
   }
-  return { installed: true };
+  return { installed: true, agents, source };
 }
 
 async function verifyAndStampEmail(t, opts) {
@@ -316,14 +361,14 @@ async function verifyAndStampEmail(t, opts) {
   return who;
 }
 
-export async function login(opts) {
+export async function login(opts, { log = (line) => console.log(line), open = openBrowser } = {}) {
   const t = target(opts);
 
   if (opts.token) {
     saveCred(t.name, { refreshToken: opts.token, convexUrl: t.convexUrl, brokerBase: t.brokerBase });
     try {
       const who = await verifyAndStampEmail(t, opts);
-      console.log(`OK logged in to ${t.name}${who.email ? ` as ${who.email}` : ""}`);
+      log(`OK logged in to ${t.name}${who.email ? ` as ${who.email}` : ""}`);
     } catch (e) {
       clearCred(t.name);
       throw e;
@@ -381,14 +426,14 @@ export async function login(opts) {
     server.listen(0, "127.0.0.1", () => {
       const { port } = server.address();
       const url = `${t.brokerBase}/cli/authorize?port=${port}&state=${state}`;
-      console.log(`Opening your browser to sign in (${t.name})...\n  ${url}\nIf it does not open, paste that URL into your browser.`);
-      openBrowser(url);
+      log(`Opening your browser to sign in (${t.name})...\n  ${url}\nIf it does not open, paste that URL into your browser.`);
+      open(url);
     });
     timer = setTimeout(() => finish(new Error("login timed out after 3 min")), 180000);
   });
 
   const who = await verifyAndStampEmail(t, opts);
-  console.log(`OK logged in to ${t.name}${who.email ? ` as ${who.email}` : ""}`);
+  log(`OK logged in to ${t.name}${who.email ? ` as ${who.email}` : ""}`);
 }
 
 export async function logout(opts) {

package/src/scaffold.mjs

@@ -5,82 +5,17 @@
 // templates/layouts/), script.md (the narration) and evidence.md (where each
 // fact comes from), then registers the deck as a draft you own so narrate can
 // render into it.
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 import * as ops from "./ops.mjs";
-import { PRESENTER_STYLES } from "./check.mjs";
+import { PRESENTER_STYLES } from "./checkRules.mjs";
+import { LAYOUTS, NARRATED_FILES, assembleLayoutDeck, fillTemplate } from "./layouts.mjs";
+
+export { LAYOUTS, NARRATED_FILES, assembleLayoutDeck, fillTemplate, parseLayouts, readLayout } from "./layouts.mjs";
 
-export const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "templates");
-export const NARRATED_FILES = { "index.html": "narrated-deck.html", "script.md": "script.md", "evidence.md": "evidence.md" };
 const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
-export const LAYOUT_DIR = join(TEMPLATE_DIR, "layouts");
-// The library, in a sensible deck order; `--layouts` takes any order and repeats.
-export const LAYOUTS = ["hero", "number", "product", "quote", "compare", "timeline", "features", "chart", "team", "closer"];
-const LAYOUT_ALIASES = { "big-number": "number", "product-shot": "product", comparison: "compare", "three-up": "features" };
 const USAGE = 'usage: deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style <stage|bubble|glass|corner>] [--dir <path>]';
 
-const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-
-// Template text with __SLUG__ / __TITLE__ filled; HTML gets an escaped title.
-// Without a presenter style the player tag carries none (the player's default).
-export function fillTemplate(file, { slug, title, presenterStyle }) {
-  const text = readFileSync(join(TEMPLATE_DIR, file), "utf8");
-  const t = /\.html$/.test(file) ? escapeHtml(title) : title;
-  const styled = presenterStyle ? text.split("__PRESENTER_STYLE__").join(presenterStyle) : text.replace(/\s*data-presenter-style="__PRESENTER_STYLE__"/g, "");
-  return styled.split("__SLUG__").join(slug).split("__TITLE__").join(t);
-}
-
-// One layout file: a leading comment of `key: value` lines (layout, summary,
-// use, slot, presenter, cues, script), its <style> and its <section>.
-export function readLayout(name) {
-  const text = readFileSync(join(LAYOUT_DIR, `${name}.html`), "utf8");
-  const head = /^<!--([\s\S]*?)-->/.exec(text);
-  const style = /<style>[\s\S]*?<\/style>/.exec(text);
-  const section = /<section\b[\s\S]*<\/section>/.exec(text);
-  if (!head || !style || !section) throw new Error(`layout ${name}: needs a leading comment, a <style> and a <section>`);
-  const meta = {};
-  for (const line of head[1].split("\n")) {
-    const m = /^([a-z]+):\s*(.*)$/.exec(line.trim());
-    if (m) meta[m[1]] = m[2];
-  }
-  return { name, meta, style: style[0], section: section[0] };
-}
-
-export function parseLayouts(list) {
-  const names = String(list).split(",").map((n) => n.trim().toLowerCase()).filter(Boolean).map((n) => LAYOUT_ALIASES[n] ?? n);
-  const unknown = names.filter((n) => !LAYOUTS.includes(n));
-  if (unknown.length) throw new Error(`unknown layout${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}: pick from ${LAYOUTS.join(", ")}`);
-  if (!names.length) throw new Error(`--layouts needs at least one of ${LAYOUTS.join(", ")}`);
-  return names;
-}
-
-// index.html, script.md and evidence.md for a deck of `layouts`, one slide
-// each, in order. A layout used twice gets ids hero, hero-2, …; ids inside a
-// slide start with its id, so its cues stay unique.
-export function assembleLayoutDeck({ slug, title, presenterStyle, layouts }) {
-  const names = parseLayouts(layouts);
-  const used = new Map();
-  const slides = names.map((name) => {
-    const n = (used.get(name) ?? 0) + 1;
-    used.set(name, n);
-    return { layout: readLayout(name), id: n === 1 ? name : `${name}-${n}` };
-  });
-  const fill = (text, id, t) => text.split("__ID__").join(id).split("__SLUG__").join(slug).split("__TITLE__").join(t);
-  const sections = slides.map(({ layout, id }, i) => {
-    let html = fill(layout.section, id, escapeHtml(title));
-    if (i === 0 && !/\sdata-intro=/.test(html.slice(0, html.indexOf(">")))) html = html.replace("<section ", '<section data-intro="Hi! Press play." ');
-    return `<!-- layout: ${layout.name}. ${layout.meta.summary ?? ""} -->\n${html}`;
-  });
-  const styles = [...new Set(names)].map((name) => `<!-- layout: ${name} -->\n${readLayout(name).style}`);
-  const shell = fillTemplate("layouts/_deck.html", { slug, title, presenterStyle });
-  // Function replacements: a "$" in the title or a layout is text, not a replacement pattern.
-  const html = shell.replace("<!-- LAYOUT STYLES -->", () => styles.join("\n")).replace("<!-- SLIDES -->", () => sections.join("\n\n"));
-  const intro = fillTemplate("script.md", { slug, title }).split(/\n## /)[0].trimEnd();
-  const script = `${intro}\n\n${slides.map(({ layout, id }) => `## ${id}\n${fill(layout.meta.script ?? "", id, title)}`).join("\n\n")}\n`;
-  return { "index.html": html, "script.md": script, "evidence.md": fillTemplate("evidence.md", { slug, title }) };
-}
-
 export async function deckNew(pos, opts = {}, { log = (line) => console.log(line), cwd = process.cwd() } = {}) {
   const [slug, title] = pos;
   if (!slug || !title) throw new Error(USAGE);
@@ -90,7 +25,7 @@ export async function deckNew(pos, opts = {}, { log = (line) => console.log(line
     throw new Error(`--presenter-style must be one of ${PRESENTER_STYLES.join(", ")}`);
   }
   if (!SLUG.test(slug)) throw new Error("slug must be lowercase letters, digits and dashes (max 64)");
-  const dir = resolve(cwd, typeof opts.dir === "string" ? opts.dir : join("decks", slug));
+  const dir = resolve(/*turbopackIgnore: true*/ cwd, typeof opts.dir === "string" ? opts.dir : join("decks", slug));
   if (existsSync(dir)) throw new Error(`${dir} already exists; pick another slug or --dir`);
   if (opts.layouts === true) throw new Error(`--layouts needs a list, e.g. --layouts ${LAYOUTS.slice(0, 3).join(",")},closer`);
   const files = opts.layouts !== undefined
@@ -99,7 +34,7 @@ export async function deckNew(pos, opts = {}, { log = (line) => console.log(line
   await ops.createDeck(opts, { slug, title });
   try {
     mkdirSync(dir, { recursive: true });
-    for (const [out, text] of files) writeFileSync(join(dir, out), text);
+    for (const [out, text] of files) writeFileSync(join(/*turbopackIgnore: true*/ dir, out), text);
   } catch (e) {
     rmSync(dir, { recursive: true, force: true });
     throw new Error(`deck ${slug} is registered but its files could not be written (${e.message}); remove the draft with \`hyperdecks deck rm ${slug}\` and run deck new again`);

package/src/source.mjs

@@ -0,0 +1,69 @@
+// The hosted deck source (convex/deckSources.ts): a deck's files kept on
+// Hyperdecks as a draft, for chat agents on the remote MCP and for
+//   hyperdecks deck new <slug> "<title>" --narrated --hosted [--layouts …]
+//   hyperdecks source pull <slug> [dir]     the draft into a folder
+//   hyperdecks source push <slug> [dir] [--base-rev N]   a folder's files to the draft
+//   hyperdecks check <slug> --hosted
+//   hyperdecks release <slug> --hosted [--to "<name>" [--email e]]... [--qa]
+//   hyperdecks asset add <slug> <file|url> [--name n]
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+import { api, client, uploadBytes } from "./runtime.mjs";
+import { SOURCE_FILES, getDeckSource, uploadDeckAsset, writeDeckSource } from "./hosted.mjs";
+
+export * from "./hosted.mjs";
+
+// ---- CLI ------------------------------------------------------------------
+
+export async function sourcePull(pos, opts = {}, { log = (line) => console.log(line), cwd = process.cwd() } = {}) {
+  const [slug, dirArg] = pos;
+  if (!slug) throw new Error("usage: source pull <slug> [dir]");
+  const dir = resolve(/*turbopackIgnore: true*/ cwd, dirArg ?? join("decks", slug));
+  const got = await getDeckSource(opts, { slug });
+  mkdirSync(dir, { recursive: true });
+  const written = [];
+  for (const [file, text] of Object.entries(got.files)) {
+    if (typeof text !== "string") continue;
+    writeFileSync(join(/*turbopackIgnore: true*/ dir, file), text);
+    written.push(file);
+  }
+  log(`✓ pulled ${slug} rev ${got.rev} → ${dir} (${written.join(", ")})\n  push it back with: hyperdecks source push ${slug} ${dirArg ?? dir} --base-rev ${got.rev}`);
+  return { slug, rev: got.rev, dir, files: written };
+}
+
+export async function sourcePush(pos, opts = {}, { log = (line) => console.log(line), cwd = process.cwd() } = {}) {
+  const [slug, dirArg] = pos;
+  if (!slug) throw new Error("usage: source push <slug> [dir] [--base-rev N]");
+  const dir = resolve(/*turbopackIgnore: true*/ cwd, dirArg ?? join("decks", slug));
+  const files = SOURCE_FILES.filter((f) => existsSync(join(/*turbopackIgnore: true*/ dir, f)));
+  if (!files.includes("index.html")) throw new Error(`no index.html in ${dir}`);
+  let baseRev = opts["base-rev"] !== undefined ? Number(opts["base-rev"]) : undefined;
+  let rev;
+  for (const file of files) {
+    ({ rev } = await writeDeckSource(opts, { slug, file, content: readFileSync(join(/*turbopackIgnore: true*/ dir, file), "utf8"), baseRev }));
+    baseRev = baseRev === undefined ? undefined : rev; // each write moves the rev
+  }
+  log(`✓ pushed ${files.join(", ")} to ${slug}: rev ${rev}`);
+  return { slug, rev, files };
+}
+
+const TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".avif": "image/avif", ".svg": "image/svg+xml", ".mp4": "video/mp4", ".webm": "video/webm", ".woff2": "font/woff2", ".woff": "font/woff" };
+
+export async function assetAdd(pos, opts = {}, { log = (line) => console.log(line), cwd = process.cwd() } = {}) {
+  const [slug, from] = pos;
+  if (!slug || !from) throw new Error("usage: asset add <slug> <file|url> [--name <name>]");
+  let out;
+  if (/^https?:\/\//i.test(from)) out = await uploadDeckAsset(opts, { slug, name: opts.name, url: from });
+  else {
+    const path = resolve(/*turbopackIgnore: true*/ cwd, from);
+    const contentType = TYPES[extname(path).toLowerCase()];
+    if (!contentType) throw new Error(`${from}: asset add takes images, video and fonts (${Object.keys(TYPES).join(" ")})`);
+    const c = await client(opts);
+    const bytes = readFileSync(path);
+    const storageId = await uploadBytes(c, bytes, contentType);
+    const saved = await c.mutation(api.assets.saveAsset, { name: String(opts.name || basename(path)), storageId, contentType, deckSlug: slug });
+    out = { url: saved.url, name: saved.name, contentType, bytes: bytes.byteLength };
+  }
+  log(out.url);
+  return out;
+}

package/src/voice.mjs

@@ -11,6 +11,17 @@ import * as ops from "./ops.mjs";
 // Same text as convex/lib/voice/consent.ts (the published CLI cannot import it).
 export const CONSENT_STATEMENT = "I confirm this is my own voice and I consent to it being cloned for narrating my decks";
 export const CONSENT_PHRASE = "I consent";
+// About 45 s read aloud at an easy pace (init prints it to record). Plain
+// sentences with varied sounds, questions and numbers give the clone range.
+export const READING_PASSAGE = [
+  "Hi, this is a recording of my own voice, for my Hyperdecks presenter.",
+  "I'm reading at my normal pace, the way I would talk to a friend across the table.",
+  "Some days start slowly, with coffee and a long list. Others start with a phone call at seven thirty.",
+  "Either way, I like to get to the point: what's the problem, who has it, and what would make it better?",
+  "When I show people my work, I want them to hear me, not a robot.",
+  "So here are a few numbers, said clearly: twelve, forty-five, three hundred, and two thousand and six.",
+  "Thanks for listening. That's the end of my sample.",
+].join(" ");
 export const MAX_SAMPLES = 3;
 export const MAX_SAMPLE_BYTES = 10 * 1024 * 1024;
 const TYPES = { ".mp3": "audio/mpeg", ".m4a": "audio/mp4", ".wav": "audio/wav" };

package/templates/first-deck/character.json

@@ -0,0 +1,26 @@
+{
+  "about": "The first deck `hyperdecks init` makes when D.A.S.H. presents: the same three slides, introduced in the third person. D.A.S.H. quotes the answers rather than rephrasing them, so no pronoun is guessed from a name.",
+  "hero": {
+    "kicker": "Meet",
+    "title": "Meet __NAME__.",
+    "lead": "__WHAT__",
+    "script": "Hi, [wave] I'm D.A.S.H. [look: h1] I'm here to introduce __NAME__."
+  },
+  "features": {
+    "kicker": "In short",
+    "title": "Three things to know.",
+    "cards": [
+      { "name": "Who", "line": "__NAME__" },
+      { "name": "What", "line": "__WHAT__" },
+      { "name": "The ask", "line": "__ASK__" }
+    ],
+    "script": "Three quick things. [go: #features-f1] Who this is. [go: #features-f2] What __NAME__ does, in their own words. __WHAT__ [go: #features-f3] And what __NAME__ would love from you. [go: slot]"
+  },
+  "closer": {
+    "title": "Thanks.",
+    "lead": "What __NAME__ would love from you:",
+    "cta": "__ASK__",
+    "contact": "Presented by D.A.S.H. on hyperdecks.ai",
+    "script": "Here's the ask. [go: #closer-cta] __ASK__ Thanks [go: slot] for watching! [wave]"
+  }
+}

package/templates/first-deck/self.json

@@ -0,0 +1,26 @@
+{
+  "about": "The first deck `hyperdecks init` makes, in your own voice: three slides from your three answers. __NAME__, __WHAT__ and __ASK__ are the answers; text is escaped before it goes into index.html.",
+  "hero": {
+    "kicker": "Hello",
+    "title": "Hi, I'm __NAME__.",
+    "lead": "__WHAT__",
+    "script": "Hi, [wave] I'm __NAME__. [look: h1] Thanks for taking a minute to watch this."
+  },
+  "features": {
+    "kicker": "In short",
+    "title": "Me, in three cards.",
+    "cards": [
+      { "name": "Who", "line": "__NAME__" },
+      { "name": "What I do", "line": "__WHAT__" },
+      { "name": "My ask", "line": "__ASK__" }
+    ],
+    "script": "Here's me, in three cards. [go: #features-f1] Who I am. [go: #features-f2] What I do. __WHAT__ [go: #features-f3] And what I'd love from you. [go: slot]"
+  },
+  "closer": {
+    "title": "Thanks.",
+    "lead": "One thing I'd love from you:",
+    "cta": "__ASK__",
+    "contact": "Made with hyperdecks.ai",
+    "script": "So here's my ask. [go: #closer-cta] __ASK__ Thanks [go: slot] for watching! [wave]"
+  }
+}

package/templates/script.md

@@ -1,5 +1,6 @@
 ---
 maxTotalSeconds: 180
+transition: drift
 ---
 
 # __TITLE__ — narration script
@@ -7,12 +8,16 @@ maxTotalSeconds: 180
 One `## <slide-id>` block per slide, in slide order; the id is the slide's
 `<section id>` in index.html. Each sentence is one caption: keep it a short
 phrase (4 to 85 characters, two lines in the bubble). Aim for 150 to 180 s in
-all. Holds: 1.1 s by default, `hold: 2` on interactive slides. Stage tags become
+all. Holds: 0.4 s by default, `hold: 1.5` for a number, chart or reveal,
+`hold: 2` on interactive slides. Stage tags become
 cues at the word before them: [wave], [mood: excited], [reveal: #detail],
 [go: #detail] (the presenter flies beside it; [go: slot] brings it home),
 [look: h2] (the head looks at it), [custom: confetti]. `presenterStyle: stage`
 above sets the deck's presenter; `presenter-style: corner` under a heading sets
-one slide's. With no `voice:` above, your first ready voice narrates.
+one slide's. `transition: drift` above is how every slide enters;
+`transition: push` (cut, wipe, zoom #id, morph, fly) under a heading changes
+one slide's: see "Transitions" in the skill. With no `voice:` above, your first
+ready voice narrates.
 
     hyperdecks narrate decks/__SLUG__ --dry-run
     hyperdecks narrate decks/__SLUG__