@hypersocial/decks-cli 0.4.0 → 0.6.0

package/src/commands.mjs

@@ -9,6 +9,7 @@ import {
   VERSION,
 } from "./runtime.mjs";
 import * as ops from "./ops.mjs";
+import { presenterLine } from "./presenter.mjs";
 
 export const playbackLabel = (p) => p.narrationFinished ? "narration finished"
   : p.narrationStarted ? "narration started"
@@ -306,8 +307,9 @@ commands:
   deck list|stats|open|rm|forward
   deck forward on|off <slug>
                    whether viewers can forward the deck's links (on by default; a link's own setting wins)
-  deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style stage|bubble|glass|corner] [--dir <path>]
-                   scaffold decks/<slug>/: index.html (8 slides, or one per layout, player/v1), script.md, evidence.md
+  deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style stage|bubble|glass|corner] [--no-brand] [--dir <path>]
+                   scaffold decks/<slug>/: index.html (8 slides, or one per layout, player/v1), script.md, evidence.md,
+                   in your saved brand's colours, fonts and logo (--no-brand: the template's look)
                    layouts: hero, number, product, quote, compare, timeline, features, chart, team, closer
   check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--layout] [--json]
                    the narrated-deck gate: slides vs manifest, timing, captions, clip URLs,
@@ -320,7 +322,7 @@ commands:
                    file an image, video or font under the deck; prints its hosted URL
   guide [workflow|format|script|design|layouts|presenter|transitions|check]
                    the skill, one topic at a time (what deck_guide serves)
-  release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v]
+  release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v] [--captions-only (--hosted)]
                    on a committed deck: check → narrate → import → share new per --to
   share new|list|on|off|forward|mute|unmute|rm|url
     share new <slug> <recipient> [--qa] [--no-notify] [--allow-forward|--no-forward]
@@ -347,8 +349,17 @@ commands:
                    a PNG of a public web page (private and local addresses are refused)
   chart <spec.json|-> [--slug <deck>] [--name <name>] [--download <file>]
                    a branded SVG: { "kind": "bar|line|donut|number", "labels", "series", "values", "value", "palette" }
+  icons search <word...> [--limit 8] [--stroke-width 2] [--json]
+                   real icons from the Lucide library as inline SVG in currentColor (free, offline)
   icons <subject...> --style "<style>" [--palette "#hex,#hex"] [--slug <deck>] [--name <prefix>]
-                   a style-consistent set of transparent icons, one per subject (max 12)
+                   a style-consistent set of generated (illustrated) icons, one per subject (max 12)
+  brand [show]     your saved brand (colours, fonts, logo, design.md) that every new deck starts from
+  brand set [--accent "#hex"] [--ink|--paper|--accent-2|--card "#hex"] [--fonts <pairing>]
+            [--display|--body|--mono "<Google Fonts family>"] [--logo <url|file>] [--no-logo]
+            [--presenter-style s] [--design <file.md|->] [--name "<company>"]
+  brand edit       edit design.md (voice, do and don't) in $EDITOR
+  brand fonts      the curated font pairings (display + body + mono)
+  brand clear      forget the brand; new decks get the template look
   review <slug> [--script <script.md>] [--json]
                    GPT-6 Luna reviews every slide (desktop + phone screenshots) and lists what to fix
   review-job <jobId> [--json]
@@ -368,6 +379,8 @@ commands:
                    asks you to type "I consent" before anything is uploaded
   voice upload <file...>   upload recordings and print their sample ids (for the MCP clone_voice tool)
   voice rm <name|id>       delete a voice, also at the provider
+  voice hear <voice> | voice hear --narrator <name|id>
+                   a short sample of the voice: its clip URL and the line it says
   avatar [--json]          your avatars (who presents decks in your voice) and the default
   avatar new [--species <s>]   pick a species, then an avatar (s shuffles); --json or an agent gets a pick link
   avatar from-photo [file] [--save-to-minimoji]
@@ -381,6 +394,8 @@ commands:
   narrator default <name|id|dash>   make it the default
   narrator remove <name|id>         remove it; decks already shared keep working
   narrator voice <name|id> <voice>  change its voice (one of yours, or dash)
+  narrator rename <name|id> <new name>   rename it
+  narrator face <name|id> <avatar>  change its face (one of your avatars)
   deck narrator <slug> <name|id|none|default>   the deck's own narrator (none: captions only)
 
 global:
@@ -625,7 +640,7 @@ function commandTable(pos, rest, opts) {
       if (opts.hosted) {
         const { hostedNewDeck } = await import("./source.mjs");
         if (!opts.narrated) throw new Error("the published CLI scaffolds narrated decks only: add --narrated");
-        const out = await hostedNewDeck(opts, { slug: rest[0], title: rest[1], layouts: opts.layouts, presenterStyle: opts["presenter-style"] });
+        const out = await hostedNewDeck(opts, { slug: rest[0], title: rest[1], layouts: opts.layouts, presenterStyle: opts["presenter-style"], brand: !opts["no-brand"] });
         return void console.log(opts.json ? JSON.stringify(out, null, 2) : `✓ created hosted deck "${out.slug}" (rev ${out.rev})\n  preview: ${out.previewUrl}\n  edit locally: hyperdecks source pull ${out.slug}`);
       }
       const { deckNew } = await import("./scaffold.mjs");
@@ -648,9 +663,11 @@ function commandTable(pos, rest, opts) {
     release: async () => {
       if (opts.hosted) {
         const { hostedRelease } = await import("./source.mjs");
-        const out = await hostedRelease(opts, { slug: pos[1], recipients: opts.recipients, qa: opts.qa, title: opts.title, forbid: opts.forbid });
+        const out = await hostedRelease(opts, { slug: pos[1], recipients: opts.recipients, qa: opts.qa, title: opts.title, forbid: opts.forbid, captionsOnly: opts["captions-only"] });
         if (opts.json) return void console.log(JSON.stringify(out, null, 2));
         console.log(`✓ released ${out.slug} rev ${out.rev}\n  deck: ${out.deckUrl}`);
+        const who = presenterLine(out.presenter);
+        if (who) console.log(who);
         for (const s of out.shares) console.log(`✓ share for "${s.recipient}"${s.qa ? " (QA, untracked)" : ""} → ${s.url}`);
         return;
       }
@@ -766,6 +783,21 @@ function commandTable(pos, rest, opts) {
       const out = await ops.setNarratorVoice(opts, rest[0], rest.slice(1).join(" "));
       console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.name} speaks in ${out.voice} now`);
     },
+    "narrator rename": async () => {
+      if (rest.length < 2) throw new Error("usage: narrator rename <name|id> <new name>");
+      const out = await ops.renameNarrator(opts, rest[0], rest.slice(1).join(" "));
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.was} is ${out.name} now`);
+    },
+    "narrator face": async () => {
+      if (rest.length < 2) throw new Error("usage: narrator face <name|id> <avatar>");
+      const out = await ops.setNarratorFace(opts, rest[0], rest.slice(1).join(" "));
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.name} wears ${out.face} now`);
+    },
+    "voice hear": async () => {
+      if (!rest[0] && !opts.narrator) throw new Error("usage: voice hear <voice> | voice hear --narrator <name|id>");
+      const out = await ops.hearVoice(opts, opts.narrator ? { narrator: opts.narrator } : { voice: rest.join(" ") });
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `"${out.caption}"\n  ${out.url}`);
+    },
     "deck narrator": async () => {
       if (rest.length < 2) throw new Error("usage: deck narrator <slug> <name|id|none|default>");
       const out = await ops.setDeckNarrator(opts, rest[0], rest.slice(1).join(" "));
@@ -807,6 +839,20 @@ function commandTable(pos, rest, opts) {
     screenshot: () => screenshot(pos.slice(1), opts),
     chart: () => chart(pos.slice(1), opts),
     icons: () => icons(pos.slice(1), opts),
+    // The icon library (Lucide); `icons search … --style` still generates.
+    "icons search": async () => {
+      if (opts.style) return icons(pos.slice(1), opts);
+      if (!rest.length) throw new Error("usage: icons search <word...> [--limit N] [--stroke-width N] [--json]");
+      const { icons: searchIcons } = await import("./icons.mjs");
+      const out = await searchIcons(rest, opts);
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
+    brand: async () => (await import("./brandCli.mjs")).brandShow(opts),
+    "brand show": async () => (await import("./brandCli.mjs")).brandShow(opts),
+    "brand set": async () => (await import("./brandCli.mjs")).brandSet(opts),
+    "brand edit": async () => (await import("./brandCli.mjs")).brandEdit(opts),
+    "brand fonts": async () => (await import("./brandCli.mjs")).brandFonts(opts),
+    "brand clear": async () => (await import("./brandCli.mjs")).brandClear(opts),
     review: () => review(pos.slice(1), opts),
     "review-job": () => reviewJob(pos.slice(1), opts),
     poster: () => poster(pos.slice(1), opts),

package/src/files.mjs

@@ -19,6 +19,9 @@ const FILES = {
   "templates/layouts/quote.html": () => new URL("../templates/layouts/quote.html", import.meta.url),
   "templates/layouts/team.html": () => new URL("../templates/layouts/team.html", import.meta.url),
   "templates/layouts/timeline.html": () => new URL("../templates/layouts/timeline.html", import.meta.url),
+  "templates/icons/lucide.json": () => new URL("../templates/icons/lucide.json", import.meta.url),
+  "templates/first-deck/self.json": () => new URL("../templates/first-deck/self.json", import.meta.url),
+  "templates/first-deck/character.json": () => new URL("../templates/first-deck/character.json", import.meta.url),
   "skills/hyperdecks/SKILL.md": () => new URL("../skills/hyperdecks/SKILL.md", import.meta.url),
   "skills/hyperdecks/chat.md": () => new URL("../skills/hyperdecks/chat.md", import.meta.url),
 };

package/src/firstDeck.mjs

@@ -0,0 +1,107 @@
+// The first deck `hyperdecks init` (and the hosted get_started tool) makes: a
+// three-slide hello deck (hero, features, closer) filled from three answers.
+// No file or process I/O beyond the packaged templates, so the hosted MCP route
+// can bundle it.
+import { packageText } from "./files.mjs";
+import { slugify } from "./importer.mjs";
+
+export const FIRST_DECK_LAYOUTS = "hero,features,closer";
+export const DASH_AVATAR = "https://decks.hypersocial.ai/player/v1/dash-avatar.json";
+export const ANSWER_MAX = { name: 40, about: 80, ask: 80 };
+
+// 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(packageText(`templates/first-deck/${presenter === "dash" ? "character" : "self"}.json`));
+}
+
+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);
+    // No art: the presenter is the opening's visual, and check fails on the stand-in.
+    s = swap(s, /\s*<div class="art"[^>]*><\/div>/, "", "hero art");
+    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 };
+}

package/src/guide.mjs

@@ -6,6 +6,7 @@
 // each layout file's leading comment.
 import { packageText } from "./files.mjs";
 import { LAYOUTS, readLayout } from "./layouts.mjs";
+import { fontPairingsMarkdown } from "./brand.mjs";
 
 export const GUIDE_TOPICS = ["workflow", "format", "script", "design", "layouts", "presenter", "transitions", "check"];
 const CLI_NOTE = "_Written for the CLI. On the hosted MCP there is no folder: use the tool names in `deck_guide` (workflow), hosted URLs for every file, and write_deck_source for edits._\n\n";
@@ -43,7 +44,8 @@ export function deckGuide(topic = "workflow") {
   else {
     const section = skillSection(packageText("skills/hyperdecks/SKILL.md"), t);
     if (!section) throw new Error(`SKILL.md has no <!-- topic: ${t} --> section`);
-    text = CLI_NOTE + section;
+    // The design topic carries the curated font pairings (brand.mjs) in place of its marker.
+    text = CLI_NOTE + section.replace("<!-- font pairings -->", () => fontPairingsMarkdown());
   }
   return { topic: t, topics: GUIDE_TOPICS, text };
 }

package/src/hosted.mjs

@@ -3,7 +3,9 @@
 // (source.mjs) share these; no local file I/O, so the route can bundle them.
 import { api, client, target } from "./runtime.mjs";
 import { PRESENTER_STYLES } from "./checkRules.mjs";
-import { NARRATED_FILES, assembleLayoutDeck, fillTemplate } from "./layouts.mjs";
+import { NARRATED_FILES, assembleLayoutDeck, fillTemplate, parseLayouts } from "./layouts.mjs";
+import { applyBrand, brandForNewDeck, brandSummary } from "./brand.mjs";
+import { getBrand } from "./ops.mjs";
 
 export const SOURCE_FILES = Object.keys(NARRATED_FILES);
 const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
@@ -13,16 +15,22 @@ const urls = (opts, slug, previewToken) => {
 };
 
 // Scaffold the files (the same templates as deck new) and register the draft.
-export async function hostedNewDeck(opts, { slug, title, layouts, presenterStyle } = {}) {
+// The account's brand (colours, fonts, logo, presenter style) goes on the
+// template unless brand is false; an explicit presenterStyle wins over it.
+export async function hostedNewDeck(opts, { slug, title, layouts, presenterStyle, brand: useBrand } = {}) {
   if (!slug || !title) throw new Error("slug and title are required");
   if (!SLUG.test(slug)) throw new Error("slug must be lowercase letters, digits and dashes (max 64)");
   if (presenterStyle !== undefined && !PRESENTER_STYLES.includes(presenterStyle)) throw new Error(`presenterStyle must be one of ${PRESENTER_STYLES.join(", ")}`);
   const list = Array.isArray(layouts) ? layouts.join(",") : layouts;
+  if (list) parseLayouts(list);
+  const { brand, readError } = await brandForNewDeck(() => getBrand(opts), useBrand);
+  const style = presenterStyle ?? (PRESENTER_STYLES.includes(brand?.presenterStyle) ? brand.presenterStyle : undefined);
   const files = list
-    ? assembleLayoutDeck({ slug, title, presenterStyle, layouts: list })
-    : Object.fromEntries(Object.entries(NARRATED_FILES).map(([out, file]) => [out, fillTemplate(file, { slug, title, presenterStyle })]));
+    ? assembleLayoutDeck({ slug, title, presenterStyle: style, layouts: list })
+    : Object.fromEntries(Object.entries(NARRATED_FILES).map(([out, file]) => [out, fillTemplate(file, { slug, title, presenterStyle: style })]));
+  files["index.html"] = applyBrand(files["index.html"], brand);
   const made = await (await client(opts)).mutation(api.deckSources.create, { slug, title, files });
-  return { slug, rev: made.rev, files, ...urls(opts, slug, made.previewToken) };
+  return { slug, rev: made.rev, files, brand: brandSummary(brand, readError), ...urls(opts, slug, made.previewToken) };
 }
 
 export async function getDeckSource(opts, { slug, file } = {}) {
@@ -59,7 +67,7 @@ export async function hostedCheck(opts, { slug, forbid, maxDuration } = {}) {
   return (await client(opts)).action(api.deckSources.check, { slug, ...(list?.length ? { forbid: list } : {}), ...(maxDuration ? { maxDuration: Number(maxDuration) } : {}) });
 }
 
-export async function hostedRelease(opts, { slug, recipients, qa, title, forbid, rev, voice } = {}) {
+export async function hostedRelease(opts, { slug, recipients, qa, title, forbid, rev, voice, captionsOnly } = {}) {
   if (!slug) throw new Error("slug is required");
   const list = typeof forbid === "string" ? forbid.split(",").map((s) => s.trim()).filter(Boolean) : forbid;
   const args = { slug };
@@ -69,6 +77,7 @@ export async function hostedRelease(opts, { slug, recipients, qa, title, forbid,
   if (list?.length) args.forbid = list;
   if (rev !== undefined && rev !== null) args.rev = Number(rev);
   if (voice) args.voice = String(voice);
+  if (captionsOnly) args.captionsOnly = true;
   return (await client(opts)).action(api.deckSources.release, args);
 }
 

package/src/icons.mjs

@@ -0,0 +1,66 @@
+// hyperdecks icons search <word> [--limit N] [--stroke-width N]
+//
+// The icon library: Lucide's open-source line icons (ISC licence, vendored in
+// templates/icons/lucide.json by scripts/sync-icons.mjs). A search returns
+// inline SVG stroked in currentColor, so a pasted icon takes the colour of the
+// text around it, i.e. the deck's palette. No network and no credits; for
+// illustrated icons in a style of your own, `hyperdecks icons <subject...>
+// --style` (generate_icon_set) still draws them.
+import { packageText } from "./files.mjs";
+
+export const MAX_ICON_RESULTS = 24;
+const DEFAULT_RESULTS = 8;
+let library;
+const lib = () => (library ??= JSON.parse(packageText("templates/icons/lucide.json")));
+
+export function iconSvg(name, { strokeWidth = 2 } = {}) {
+  const icon = lib().icons[name];
+  if (!icon) return null;
+  const sw = Number(strokeWidth);
+  const width = Number.isFinite(sw) && sw > 0 && sw <= 4 ? sw : 2;
+  return `<svg class="icon lucide-${name}" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="${width}" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${icon[0]}</svg>`;
+}
+
+// Best matches first: the exact name, a name starting with or containing a
+// word, then an exact tag, then a tag containing a word. Several words rank by
+// how many of them match.
+export function searchIcons({ query, limit, strokeWidth } = {}) {
+  const words = String(query ?? "").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+  if (!words.length) throw new Error("search needs a word, e.g. rocket");
+  const n = Math.min(Math.max(Number(limit) || DEFAULT_RESULTS, 1), MAX_ICON_RESULTS);
+  const phrase = words.join("-");
+  const scored = [];
+  for (const [name, [, tagText]] of Object.entries(lib().icons)) {
+    const parts = name.split("-");
+    const tags = tagText ? tagText.split(",") : [];
+    let score = name === phrase ? 100 : 0;
+    for (const w of words) {
+      if (parts[0] === w) score += 12;
+      else if (parts.includes(w)) score += 10;
+      else if (name.includes(w)) score += 6;
+      else if (tags.includes(w)) score += 5;
+      else if (tags.some((t) => t.split(" ").includes(w))) score += 3;
+      else if (tags.some((t) => t.includes(w))) score += 1;
+    }
+    // Plainer icons first among equals: rocket before rocket-launch.
+    if (score) scored.push({ name, tags, score: score - parts.length * 0.1 });
+  }
+  scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+  return {
+    query: words.join(" "),
+    library: lib().source,
+    license: lib().license,
+    total: scored.length,
+    icons: scored.slice(0, n).map(({ name, tags }) => ({ name, tags, svg: iconSvg(name, { strokeWidth }) })),
+    usage: "Paste svg inline (e.g. in .l-features .card). It is stroked in currentColor: set `color` on it or its parent to put it in the deck's palette.",
+  };
+}
+
+export async function icons(pos, opts = {}, { log = (line) => console.log(line) } = {}) {
+  const out = searchIcons({ query: pos.join(" "), limit: opts.limit, strokeWidth: opts["stroke-width"] });
+  if (opts.json) return out;
+  if (!out.icons.length) log(`no icons match "${out.query}"; try a plainer word (e.g. chart, user, lock)`);
+  for (const icon of out.icons) log(`${icon.name}${icon.tags.length ? `  (${icon.tags.slice(0, 5).join(", ")})` : ""}\n${icon.svg}\n`);
+  if (out.icons.length) log(`${out.icons.length} of ${out.total} from ${out.library}. ${out.usage}`);
+  return out;
+}

package/src/init.mjs

@@ -6,7 +6,8 @@
 // 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.
+// In chat (no folder, no git) the hosted MCP's get_started tool walks the same
+// steps on a hosted draft (lib/getStarted.ts); the deck fill is shared (firstDeck.mjs).
 import { execFileSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -15,7 +16,7 @@ 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 { ANSWER_MAX, DASH_AVATAR, FIRST_DECK_LAYOUTS, cleanAnswer, fillFirstDeck, firstDeckCopy, firstDeckSlug } from "./firstDeck.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";
@@ -23,17 +24,13 @@ 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 { ANSWER_MAX, DASH_AVATAR, FIRST_DECK_LAYOUTS, cleanAnswer, fillFirstDeck, firstDeckCopy, firstDeckSlug };
 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";
@@ -66,100 +63,6 @@ export function writeState(path, all) {
 
 // ---- 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 ------------------------------------------------------------------
 

package/src/narrate.mjs

@@ -8,6 +8,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import * as ops from "./ops.mjs";
+import { presenterLine } from "./presenter.mjs";
 export { sectionIds, setManifestUrl } from "./checkRules.mjs";
 import { sectionIds, setManifestUrl } from "./checkRules.mjs";
 
@@ -46,10 +47,14 @@ export async function narrate(pos, opts = {}, { log = (line) => console.log(line
     for (const s of preview.slides) log(`${s.render ? "render" : s.cached ? "cached" : "skip  "}  ${s.id}  ${s.hash.slice(0, 12)}  ${s.chars} chars${s.presenterStyle ? `  presenter-style: ${s.presenterStyle}` : ""}`);
     const render = preview.slides.filter((s) => s.render);
     log(`${render.length} of ${preview.slides.length} slide(s) would render in voice "${preview.voice}", ~${render.reduce((n, s) => n + s.chars, 0)} characters of TTS`);
+    const who = presenterLine(preview.presenter);
+    if (who) log(who);
     return preview;
   }
-  const { jobId, slides } = await ops.narrateDeck(opts, fields);
+  const { jobId, slides, presenter } = await ops.narrateDeck(opts, fields);
   log(`narration job ${jobId}: ${slides.filter((s) => s.status === "render").length} to render, ${slides.filter((s) => s.status === "cached").length} cached`);
+  const who = presenterLine(presenter);
+  if (who) log(who);
   const seen = new Map();
   const job = await ops.pollNarrationJob(opts, jobId, {
     onProgress: (j) => {
@@ -63,6 +68,8 @@ export async function narrate(pos, opts = {}, { log = (line) => console.log(line
     },
   });
   if (job.status === "error") throw new Error(job.error || "narration failed");
+  // release reads who presents from here (older backends send no presenter).
+  if (presenter) job.presenter = presenter;
   if (!job.manifest) {
     log(`⚠ ${job.notice || "done, but no manifest was written"}`);
     return job;