@hypersocial/decks-cli 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "main": "./src/commands.mjs",

package/skills/hyperdecks/SKILL.md

@@ -56,6 +56,9 @@ returns a link; hand it to them, word for word, and wait.
 | Make one the default (the person named it) | `hyperdecks narrator default <name>` | `set_default_narrator` |
 | Remove one (confirm first) | `hyperdecks narrator remove <name>` | `remove_narrator` |
 | Change its voice (the person asked) | `hyperdecks narrator voice <name> <voice>` | `set_narrator_voice` |
+| Rename it (the person asked) | `hyperdecks narrator rename <name> <new name>` | `rename_narrator` |
+| Change its face to one of their avatars (the person named it) | `hyperdecks narrator face <name> <avatar>` | `set_narrator_face` |
+| Hear a voice or a narrator | `hyperdecks voice hear <voice>` (`--narrator <name>`) → `url`, `caption` | `hear_voice` |
 | One deck's own narrator | `hyperdecks deck narrator <slug> <name\|none\|default>` | `set_deck_narrator` |
 
 ### Avatars: who presents a deck in the user's voice
@@ -120,14 +123,17 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 
 | Step | CLI | MCP tool |
 |---|---|---|
+| Brand (once; every new deck starts from it) | `hyperdecks brand show` / `brand set` / `brand edit` | `get_brand` / `set_brand` |
 | Scaffold | `hyperdecks deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer]` | `new_deck` (`layouts`) |
 | Images | `hyperdecks gen-image "<prompt>" --slug <slug>` | `generate_image` |
 | Video clips | `hyperdecks gen-video "<prompt>" --slug <slug>` | `generate_video` |
 | Product screenshot | `hyperdecks screenshot <url> --slug <slug>` | `capture_url` |
 | Chart from numbers | `hyperdecks chart <spec.json> --slug <slug>` | `render_chart` |
-| Icon set | `hyperdecks icons <subject...> --style "<style>" --slug <slug>` | `generate_icon_set` |
+| Real icons (Lucide, inline SVG) | `hyperdecks icons search <word>` | `search_icons` |
+| Illustrated icon set | `hyperdecks icons <subject...> --style "<style>" --slug <slug>` | `generate_icon_set` |
 | Outside review (required before release) | `hyperdecks review <slug> --script decks/<slug>/script.md` | `review_deck` |
 | Your voice (once) | `hyperdecks voice clone <file...> --name <name>` | `clone_voice` |
+| Who narrates (ask the person first; see *Narrators*) | `hyperdecks deck narrator <slug> <name\|none\|default>` | `list_narrators`, then `set_deck_narrator` |
 | Narrate | `hyperdecks narrate decks/<slug>` | `narrate_deck` |
 | Check | `hyperdecks check decks/<slug>` | `check_deck` |
 | Ship | `hyperdecks release decks/<slug> --to "<name>" --email <e>` | `release_deck` |
@@ -296,13 +302,36 @@ plain, `on-ink`) so the slide changes read, and keep every number, source and
 label at full contrast. Change the palette and fonts once, in `:root`; every
 layout reads them.
 
+**Start from the brand.** The account keeps a brand: colours, fonts, a logo,
+a presenter style and a design.md (voice, do and don't). `deck new` and
+`new_deck` put its tokens in `:root` and its logo on the first slide, so read
+it first (`hyperdecks brand show --json`, `get_brand`) and write in its voice.
+An explicit request for this deck wins over the brand; `--no-brand`
+(`brand: false`) starts from the template's look. No brand yet? Offer to set
+one up: read the person's website (`capture_url`, its colours, fonts and logo),
+show them what you would save, and `brand set` / `set_brand` only after they
+agree.
+
+**Fonts: pick a pairing.** Fonts load from Google Fonts. Use one of the
+curated pairings below (display for titles, body for text, mono for kickers
+and labels) rather than whatever family comes to mind; `brand set --fonts <id>`
+saves one.
+
+<!-- font pairings -->
+
+**Icons: real ones first.** `hyperdecks icons search <word>` (`search_icons`)
+returns Lucide line icons as inline SVG stroked in `currentColor`, so they take
+the deck's colours: paste the `<svg>` in place of a features card's icon. Use
+`icons <subject...> --style` (`generate_icon_set`) only for illustrated icons
+in a style of your own.
+
 **Pick the layout from what the slide says.** Each layout's file in
 `templates/layouts/` opens with its slot side, presenter and the cues that
 suit it.
 
 | Layout | Use it for | Presenter, moves |
 |---|---|---|
-| `hero` | the opening, a section opener; the presenter is the visual, no `.art` unless it shows the real subject | stage, bottom-right; `[wave]`, `[look: h1]` |
+| `hero` | the opening, a section opener; the presenter is the visual, no `.art` unless it shows the real subject (check fails while the placeholder `<div class="art">` is in: swap it for an `<img class="art">` or delete it) | stage, bottom-right; `[wave]`, `[look: h1]` |
 | `number` | one number with its source: proof, traction, a delta | stage; `[look: #<id>-figure]` as it is said |
 | `product` | a screenshot in a browser frame (`.frame.phone` for a phone shot) with the point beside it | stage; `[look: #<id>-frame]`, `[reveal: #<id>-callout]` |
 | `quote` | a customer or user in their own words, quoted exactly | stage, bottom-left; `[look: #<id>-quote]` |
@@ -459,6 +488,7 @@ an internal codename). Messages and what to do:
 | `forbidden phrase` | remove it from the page, script or narration |
 | `slide <id>: needs a data-note` | add the source |
 | `slide <id>: title … needs a data-title-mobile` | add a shorter title |
+| `slide <id>: the hero's art` / `the product screenshot` / `the chart … is still the layout's placeholder` | make the real file (`gen-image`, `screenshot <url>`, `chart <spec.json>`) and swap the element for the `<img>` the message names; or delete the hero's `<div class="art">` for no art |
 | `… presenter style "…" is not one of` | use stage, bubble, glass or corner |
 | `script.md line N: [go: …] matches nothing in slide <id>` | fix the selector, or add the element to that slide |
 | `… transition "…" is not one of` | use drift, cut, push, wipe, zoom `<selector>`, morph or fly |
@@ -486,8 +516,9 @@ the deck's QA link on desktop and phone and list each problem as `fix` or
 Pick image models by job: `gen-image` defaults to GPT Image 2.5; `--model
 nano-banana-2.1` is stronger on typography and photoreal scenes. `gen-video`
 defaults to MiniMax H3 Max (`--model kling-v3` is the fallback). Use `chart` for
-real numbers instead of a generated picture of a chart, and `icons` with the
-deck's palette for a set that matches.
+real numbers instead of a generated picture of a chart, `icons search` for
+real line icons, and `icons --style` with the deck's palette for an
+illustrated set that matches.
 
 ### 7. Release
 

package/skills/hyperdecks/chat.md

@@ -7,32 +7,76 @@ reaches a recipient until `release_deck`. Topics: call `deck_guide` with
 `format`, `script`, `design`, `layouts`, `presenter`, `transitions` or `check`
 before the step that needs it.
 
+## First time here?
+
+`get_started` with no answers says where the person stands (ready voices,
+narrators, credits) and the steps. No voice of their own: `clone_voice_link`
+(they record in the browser), or `clone_voice` with 1-3 recordings they attach
+in the chat, only after they agree to the consent statement, word for word.
+`hear_voice` plays a voice or a narrator in the chat. A face from a photo they
+attach: `avatar_from_photo { file }`, then `check_avatar_draft` until it hands
+back the link they approve it on. `rename_narrator` and `set_narrator_face`
+change a narrator when they ask. Then `get_started { name, about, ask, voice }`
+makes the hello deck; continue from step 5 below.
+
 ## The loop
 
 1. `deck_guide` (this page), then `deck_guide { topic: "layouts" }` to pick slides.
+   `get_brand` for the person's saved brand: write in its designMd's voice.
+   None yet and they have a website? Offer to set one up: `capture_url` the
+   site, read its colours, fonts and logo, show what you would save and
+   `set_brand` once they agree (`deck_guide { topic: "design" }` lists the
+   font pairings).
 2. `new_deck { slug, title, layouts }`: registers your draft and returns the
-   full text of every file plus a `previewUrl` (the draft, untracked).
+   full text of every file plus a `previewUrl` (the draft, untracked). It
+   starts in the saved brand's colours, fonts and logo (`brand` in the result
+   says what it took); `brand: false` gives the template's look.
 3. Images: `generate_image`, `render_chart`, `capture_url`, or
    `upload_deck_asset` for a picture the user gave you (a URL, or a file they
    uploaded). Each returns a hosted URL: put that URL in the HTML. A hosted deck
-   has no folder, so a relative path like `img/a.png` is an error.
+   has no folder, so a relative path like `img/a.png` is an error. The
+   layouts' stand-ins (hero's `<div class="art">`, product's
+   `<div class="shot">`, chart's placeholder `<svg>`) fail `check_deck` until
+   you swap each for an `<img>` of its real file, or delete the hero's art.
+   Icons: `search_icons { query }` returns real line icons as inline `<svg>`
+   in `currentColor`; paste one where a features card has its icon.
 4. `write_deck_source` to change a file: `edits: [{ find, replace }]` with
    exact text that occurs once (copy it from `get_deck_source`), or `content`
    to replace the file. Pass `baseRev` (the `rev` you last read) so a
    concurrent edit fails instead of being overwritten.
-5. `check_deck { slug }` until it passes (the narration errors clear in step 6).
-6. `narrate_deck { slug }` with no `script` narrates the stored `script.md`;
+5. `check_deck { slug }` until it passes (the narration errors clear in step 7).
+6. **Ask who narrates** before the first narrate, unless they already named
+   one. `list_narrators`, then offer their narrators (`hear_voice` to listen)
+   and D.A.S.H. If none of theirs has a face, say so: their voice alone plays
+   captions only, no face. Offer `new_narrator_link` (they make one, a face plus
+   their voice) or D.A.S.H. Then `set_deck_narrator { slug, narrator }`
+   (`none` only if they want captions only). Never pick for them.
+7. `narrate_deck { slug }` with no `script` narrates the stored `script.md`;
    poll `check_narration_job` until `done`. The draft's player tag then has its
-   `data-manifest`. No voice of their own yet? Pass `voice: "dash"`.
-7. `check_deck { slug }` again, then `review_deck { slug, draft: true }` and
+   `data-manifest`. Its `presenter` says who will present (`face: null` is
+   captions only, `reason` says why): tell the person. No voice of their own
+   yet? Pass `voice: "dash"`.
+8. `check_deck { slug }` again, then `review_deck { slug, draft: true }` and
    `check_review_job`: it shoots desktop and 390×844 phone frames, which is how
    you catch a slide that overflows a phone (the hosted check cannot measure
    layout).
-8. `release_deck { slug, qa: true }` gives the user a QA link to watch first.
+9. `release_deck { slug, qa: true }` gives the user a QA link to watch first.
    `release_deck { slug, recipients: [{ recipient, email }] }` makes one
    tracked link each. Release creates live links: confirm the recipients with
-   the user before you call it.
-9. Later: `list_shares`, `deck_stats`, `activity_overview`.
+   the user before you call it. In Claude and ChatGPT the result shows as a
+   deck card: the deck playing from its QA link (the draft before release),
+   with each share link and its opens. Never paste a recipient's link to "test"
+   it: opening it counts as their open. A release that would play captions
+   only, when nobody chose that, is refused: hand the person its Add narrator
+   link, or offer D.A.S.H., and pass `captionsOnly: true` only if they say so.
+   The result's `presenter` names who presents.
+10. Later: `list_shares` and `deck_stats` (both show the card),
+   `activity_overview`; `email_embed { token }` for the HTML that pastes into an
+   email as the deck's moving preview (it needs a recipient's link, not a QA
+   one); `set_share_notify` to mute a link's "opened" alerts;
+   `set_recipient_archived` to tidy the activity feed; `credits` for the
+   balance. `remove_deck` deletes a deck and breaks every link to it: confirm
+   with the user first.
 
 ## Rules that matter
 
@@ -42,8 +86,8 @@ before the step that needs it.
   scaffold wrote; never write `data-manifest` yourself.
 - Edit the draft freely: recipients keep seeing the last release until you call
   `release_deck` again. A release is refused when the check fails, when
-  narration is stale (narrate again first), or when the draft changed after
-  the check.
+  narration is stale (narrate again first), when the draft changed after
+  the check, or when it would play captions only and nobody chose that.
 - Files are capped at 800 KB each: use hosted image URLs, never inline base64.
 - Facts come from the user's material; put the source of each in `evidence.md`
   and the slide's `data-note`.

package/src/brand.mjs

@@ -0,0 +1,171 @@
+// The account's brand (convex/brand.ts) applied to a new deck, and the curated
+// font pairings it can name. Text in, text out (no I/O), so the hosted MCP route
+// (new_deck) and the CLI (deck new) put the same brand on the same templates.
+//
+// A brand is { colors: { ink, paper, accent, accent2, card }, fonts: { display,
+// body, mono }, logoUrl, presenterStyle, designMd }; every field is optional and
+// an absent one keeps the template's own. designMd is guidance the agent reads;
+// only the tokens here touch the deck.
+
+// Weights each role loads: the templates set body text at 500, titles at 700
+// and labels in mono at 400/700. Every family below has these on Google Fonts.
+const ROLE_WEIGHTS = { display: "600;700", body: "400;500;700", mono: "400;700" };
+
+// 16 pairings, display + body + mono, each a family Google Fonts serves at the
+// role's weights. `use` is the one line an agent picks by.
+export const FONT_PAIRINGS = [
+  { id: "space", display: "Space Grotesk", body: "Space Grotesk", mono: "Space Mono", use: "The template's own: techy, playful, a startup demo." },
+  { id: "inter", display: "Inter", body: "Inter", mono: "JetBrains Mono", use: "Neutral product and SaaS; reads like the app itself." },
+  { id: "geist", display: "Geist", body: "Geist", mono: "Geist Mono", use: "Developer tools and infrastructure; crisp and modern." },
+  { id: "plex", display: "IBM Plex Sans", body: "IBM Plex Sans", mono: "IBM Plex Mono", use: "Enterprise, data and engineering; sober and precise." },
+  { id: "editorial", display: "Fraunces", body: "Inter", mono: "IBM Plex Mono", use: "Editorial and thoughtful: essays, research, a founder's letter." },
+  { id: "classic", display: "Playfair Display", body: "Source Sans 3", mono: "Source Code Pro", use: "Premium, luxury, finance or hospitality; classic contrast." },
+  { id: "newsroom", display: "Newsreader", body: "Public Sans", mono: "IBM Plex Mono", use: "Reports, policy and media; a newspaper's calm authority." },
+  { id: "bold", display: "Bricolage Grotesque", body: "DM Sans", mono: "DM Mono", use: "Consumer brands and launches; characterful and loud." },
+  { id: "friendly", display: "Plus Jakarta Sans", body: "Plus Jakarta Sans", mono: "Fira Code", use: "Friendly consumer and fintech apps; soft and approachable." },
+  { id: "geometric", display: "Sora", body: "Manrope", mono: "JetBrains Mono", use: "Web3, AI and future-facing products; geometric and clean." },
+  { id: "studio", display: "Syne", body: "Inter", mono: "Space Mono", use: "Design studios, agencies and portfolios; art-school edge." },
+  { id: "warm", display: "Outfit", body: "Nunito Sans", mono: "Red Hat Mono", use: "Education, health and community; warm and open." },
+  { id: "swiss", display: "Archivo", body: "Archivo", mono: "Azeret Mono", use: "Swiss-style grids, architecture and hardware; tight and rational." },
+  { id: "literary", display: "Libre Baskerville", body: "Lora", mono: "Courier Prime", use: "Books, writing, nonprofits; literary and humane." },
+  { id: "display", display: "Unbounded", body: "Hanken Grotesk", mono: "Martian Mono", use: "Events, gaming and culture; wide display type that shouts." },
+  { id: "grotesk", display: "Schibsted Grotesk", body: "Work Sans", mono: "Roboto Mono", use: "Marketplaces and media brands; confident and newsy." },
+];
+
+// Weights for families that do not have every role weight (load what exists).
+const FAMILY_WEIGHTS = { "Space Mono": "400;700", "DM Mono": "400;500", "Libre Baskerville": "400;700", "Courier Prime": "400;700", "Syne": "600;700" };
+
+const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+// A Google Fonts family name: letters, digits and spaces (e.g. "Source Sans 3").
+const FAMILY = /^[A-Za-z0-9][A-Za-z0-9 ]{0,59}$/;
+export const COLOR_KEYS = ["ink", "paper", "accent", "accent2", "card"];
+export const FONT_ROLES = ["display", "body", "mono"];
+const CSS_VAR = { ink: "--ink", paper: "--paper", accent: "--accent", accent2: "--accent-2", card: "--card" };
+const FALLBACK = { display: "system-ui, sans-serif", body: "system-ui, sans-serif", mono: "ui-monospace, monospace" };
+
+export const isHexColor = (s) => typeof s === "string" && HEX.test(s.trim());
+export const isFontFamily = (s) => typeof s === "string" && FAMILY.test(s.trim()) && !/ {2}/.test(s.trim());
+
+export function findPairing(id) {
+  const want = String(id ?? "").trim().toLowerCase();
+  return FONT_PAIRINGS.find((p) => p.id === want) ?? null;
+}
+
+// The Google Fonts stylesheet URL for one family at the weights its roles use
+// (a family that is both display and body loads both roles' weights).
+export function googleFontsUrl(family, roles = "body") {
+  const wanted = [roles].flat().flatMap((r) => (ROLE_WEIGHTS[r] ?? "400;700").split(";"));
+  const weights = FAMILY_WEIGHTS[family] ?? [...new Set(wanted)].sort().join(";");
+  return `https://fonts.googleapis.com/css2?family=${family.trim().replace(/ /g, "+")}:wght@${weights}&display=swap`;
+}
+
+// The pairings as markdown, for deck_guide { topic: "design" } and `hyperdecks brand fonts`.
+export function fontPairingsMarkdown() {
+  const rows = FONT_PAIRINGS.map((p) => `| \`${p.id}\` | ${p.display} | ${p.body} | ${p.mono} | ${p.use} |`);
+  return [
+    "Pick one, then either save it as the brand (`set_brand { fontPairing: \"<id>\" }`, `hyperdecks brand set --fonts <id>`) or set the deck's own fonts: link each family from Google Fonts (one `<link rel=\"stylesheet\">` each, at the weights shown in the URL) and set `--font` (body), `--mono` and, for titles, `--display` in `:root`.",
+    "",
+    "| id | display | body | mono | use for |",
+    "| --- | --- | --- | --- | --- |",
+    ...rows,
+    "",
+    "URL for one family: `https://fonts.googleapis.com/css2?family=<Name+With+Pluses>:wght@400;700&display=swap`.",
+  ].join("\n");
+}
+
+// Only the fields that are well formed: a brand read from the server (or a
+// test double) never puts anything but a hex colour, a family name or an
+// https URL into the deck.
+export function cleanBrand(brand) {
+  if (!brand || typeof brand !== "object") return null;
+  const colors = {};
+  for (const k of COLOR_KEYS) if (isHexColor(brand.colors?.[k])) colors[k] = brand.colors[k].trim().toLowerCase();
+  const fonts = {};
+  for (const r of FONT_ROLES) if (isFontFamily(brand.fonts?.[r])) fonts[r] = brand.fonts[r].trim();
+  const logoUrl = typeof brand.logoUrl === "string" && /^https:\/\/[^\s"'<>]+$/.test(brand.logoUrl) ? brand.logoUrl : undefined;
+  const presenterStyle = typeof brand.presenterStyle === "string" ? brand.presenterStyle : undefined;
+  const name = typeof brand.name === "string" && brand.name.trim() ? brand.name.trim().slice(0, 60) : undefined;
+  const hasDesignMd = typeof brand.designMd === "string" && !!brand.designMd.trim();
+  if (!Object.keys(colors).length && !Object.keys(fonts).length && !logoUrl && !presenterStyle && !hasDesignMd && !name) return null;
+  return { name, colors, fonts, logoUrl, presenterStyle, hasDesignMd };
+}
+
+const escapeAttr = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const fontStack = (family, role) => `"${family}", ${FALLBACK[role]}`;
+const LOGO_CSS = `
+  /* The brand's logo (hyperdecks brand), on the first slide. */
+  .brand-logo { align-self: flex-start; height: 56px; width: auto; max-width: 320px; object-fit: contain; position: relative; z-index: 1; }
+  @media (max-width: 650px) { .brand-logo { height: 32px; max-width: 180px; } }`;
+
+// index.html with the brand's colours, fonts and logo in place of the
+// template's. Tokens in the deck's `:root` are replaced (or added), the Google
+// Fonts link is swapped for the brand's families and the logo goes at the top
+// of the first slide. A brand with nothing set returns the html unchanged.
+export function applyBrand(html, brand) {
+  const b = cleanBrand(brand);
+  if (!b || (!Object.keys(b.colors).length && !Object.keys(b.fonts).length && !b.logoUrl)) return html;
+  // Our templates all have these; a template that lost them is a bug, not a brand-less deck.
+  const root = /:root\s*\{[^}]*--ink:[^}]*\}/.exec(html);
+  if (!root) throw new Error("applyBrand: the template has no :root block with --ink");
+  let block = root[0];
+  const set = (name, value) => {
+    const decl = new RegExp(`(${name}\\s*:\\s*)[^;}]*`);
+    block = decl.test(block) ? block.replace(decl, (_, k) => `${k}${value}`) : block.replace(/\s*\}$/, (end) => ` ${name}: ${value};${end}`);
+  };
+  for (const [k, v] of Object.entries(b.colors)) set(CSS_VAR[k], v);
+  if (b.fonts.body) set("--font", fontStack(b.fonts.body, "body"));
+  if (b.fonts.mono) set("--mono", fontStack(b.fonts.mono, "mono"));
+  if (b.fonts.display) set("--display", fontStack(b.fonts.display, "display"));
+  let out = html.slice(0, root.index) + block + html.slice(root.index + root[0].length);
+
+  const families = FONT_ROLES.filter((r) => b.fonts[r]).map((r) => [b.fonts[r], r]);
+  if (families.length) {
+    // Keep the template's link for the roles the brand leaves alone.
+    const kept = /<link rel="stylesheet" href="(https:\/\/fonts\.googleapis\.com\/css2\?[^"]*)">/.exec(out);
+    const rolesOf = new Map();
+    for (const [f, r] of families) rolesOf.set(f, [...(rolesOf.get(f) ?? []), r]);
+    const links = [...rolesOf].map(([f, roles]) => `<link rel="stylesheet" href="${escapeAttr(googleFontsUrl(f, roles))}">`);
+    if (kept && families.length < FONT_ROLES.length) links.unshift(kept[0]);
+    out = kept ? out.replace(kept[0], () => links.join("\n")) : out.replace("</head>", () => `${links.join("\n")}\n</head>`);
+  }
+  if (b.logoUrl) {
+    // The logo's rule goes in the style block that holds :root (not the loading state's).
+    const close = out.indexOf("</style>", out.indexOf(block));
+    if (close === -1) throw new Error("applyBrand: no </style> after the template's :root");
+    out = out.slice(0, close) + LOGO_CSS + "\n" + out.slice(close);
+    // The first real slide: the templates name `<section class="slide" id>` in comments too.
+    const inComment = (i) => out.lastIndexOf("<!--", i) > out.lastIndexOf("-->", i);
+    const first = [...out.matchAll(/<section\b[^>]*class="[^"]*\bslide\b[^"]*"[^>]*>/g)].find((m) => !inComment(m.index));
+    if (!first) throw new Error("applyBrand: the template has no <section class=\"slide\"> for the logo");
+    const img = `\n  <img class="brand-logo" src="${escapeAttr(b.logoUrl)}" alt="${escapeAttr(b.name ? `${b.name} logo` : "Logo")}">`;
+    out = out.slice(0, first.index + first[0].length) + img + out.slice(first.index + first[0].length);
+  }
+  return out;
+}
+
+// The brand a new deck starts from: { brand: null } when asked not to
+// (brand: false / --no-brand) or when nothing is saved. A failed read does not
+// stop the deck (making decks must not depend on the brand, e.g. during a
+// rollout); it starts in the template's look and readError says so.
+export async function brandForNewDeck(getBrand, useBrand) {
+  if (useBrand === false) return { brand: null };
+  try {
+    return { brand: cleanBrand(await getBrand()) };
+  } catch (e) {
+    return { brand: null, readError: String(e?.data ?? e?.message ?? e) };
+  }
+}
+
+// What a new deck took from the brand, for the agent to read back.
+export function brandSummary(b, readError) {
+  if (readError) return { applied: [], error: readError, note: `Could not read your saved brand (${readError}), so the deck has the template's look. Try get_brand (hyperdecks brand show); once it works, apply the brand's colours, fonts and logo yourself or make the deck again.` };
+  if (!b) return { applied: [], note: "No brand saved: the deck has the template's look. set_brand (hyperdecks brand set) saves one for every new deck." };
+  const applied = [
+    Object.keys(b.colors).length && "colors",
+    Object.keys(b.fonts).length && "fonts",
+    b.logoUrl && "logo",
+    b.presenterStyle && "presenterStyle",
+  ].filter(Boolean);
+  if (!applied.length) return { applied, note: "Your brand has no colours, fonts or logo yet, so the deck has the template's look. Read its designMd (get_brand / hyperdecks brand show) for voice and do's and don'ts." };
+  return { applied, note: "Started from your saved brand. Read its designMd (get_brand / hyperdecks brand show) for voice and do's and don'ts; an explicit request for this deck wins over the brand." };
+}

package/src/brandCli.mjs

@@ -0,0 +1,127 @@
+// hyperdecks brand show|set|edit|fonts|clear
+//
+// The account's brand (convex/brand.ts): colours, fonts, a logo and a
+// design.md that every new deck (deck new, new_deck) starts from.
+//   brand show                       the saved brand (--json for all of it)
+//   brand set [--accent #hex] [--ink …] [--paper …] [--accent-2 …] [--card …]
+//             [--fonts <pairing>] [--display "<family>"] [--body …] [--mono …]
+//             [--logo <url|file>] [--no-logo] [--presenter-style s]
+//             [--design <file.md|->] [--name "<company>"]
+//   brand edit                       design.md in $VISUAL / $EDITOR, saved on exit
+//   brand fonts                      the curated font pairings
+//   brand clear                      forget the brand (new decks get the template look)
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { extname, join } from "node:path";
+import * as ops from "./ops.mjs";
+import { FONT_PAIRINGS } from "./brand.mjs";
+
+const LOGO_TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif", ".svg": "image/svg+xml", ".avif": "image/avif" };
+const COLOR_FLAGS = { ink: "ink", paper: "paper", accent: "accent", "accent-2": "accent2", card: "card" };
+const FONT_FLAGS = ["display", "body", "mono"];
+const SET_USAGE = 'usage: brand set [--accent "#hex"] [--ink …] [--paper …] [--accent-2 …] [--card …] [--fonts <pairing>] [--display "<family>"] [--body …] [--mono …] [--logo <url|file>] [--no-logo] [--presenter-style stage|bubble|glass|corner] [--design <file.md|->] [--name "<company>"]';
+
+export function brandLines(b) {
+  if (!b) return ["no brand saved: new decks get the template look", "  set one: hyperdecks brand set --accent \"#ff5a1f\" --fonts editorial --logo ./logo.svg"];
+  const colors = Object.entries(b.colors ?? {}).map(([k, v]) => `${k} ${v}`).join(", ");
+  const fonts = Object.entries(b.fonts ?? {}).map(([k, v]) => `${k} ${v}`).join(", ");
+  const design = b.designMd ? `${b.designMd.split("\n").length} lines (hyperdecks brand show --json, or brand edit)` : "(none: hyperdecks brand edit)";
+  return [
+    ...(b.name ? [`name:      ${b.name}`] : []),
+    `colours:   ${colors || "(template)"}`,
+    `fonts:     ${fonts || "(template)"}`,
+    `logo:      ${b.logoUrl ?? "(none)"}`,
+    `presenter: ${b.presenterStyle ?? "(template)"}`,
+    `design.md: ${design}`,
+  ];
+}
+
+const flag = (opts, k) => (opts[k] === undefined || opts[k] === true ? undefined : String(opts[k]));
+
+// brand set's flags as setBrand's arguments; a --logo that is not a URL is a file.
+export function brandArgs(opts, { readFile = readFileSync, stdin = () => readFileSync(0, "utf8") } = {}) {
+  const colors = {};
+  for (const [f, k] of Object.entries(COLOR_FLAGS)) if (flag(opts, f) !== undefined) colors[k] = flag(opts, f);
+  const fonts = {};
+  for (const r of FONT_FLAGS) if (flag(opts, r) !== undefined) fonts[r] = flag(opts, r);
+  const args = {};
+  if (Object.keys(colors).length) args.colors = colors;
+  if (Object.keys(fonts).length) args.fonts = fonts;
+  if (flag(opts, "fonts") !== undefined) args.fontPairing = flag(opts, "fonts");
+  if (flag(opts, "name") !== undefined) args.name = flag(opts, "name");
+  if (flag(opts, "presenter-style") !== undefined) args.presenterStyle = flag(opts, "presenter-style");
+  const design = flag(opts, "design");
+  if (design !== undefined) args.designMd = design === "-" ? stdin() : readFile(design, "utf8");
+  const logo = flag(opts, "logo");
+  if (logo !== undefined) {
+    if (/^https?:\/\//i.test(logo)) args.logoUrl = logo;
+    else {
+      const type = LOGO_TYPES[extname(logo).toLowerCase()];
+      if (!type) throw new Error(`--logo ${logo}: use a .png, .jpg, .webp, .gif, .svg or .avif file, or an image URL`);
+      args.logoBytes = readFile(logo);
+      args.logoType = type;
+    }
+  }
+  if (opts["no-logo"]) args.clearLogo = true;
+  return args;
+}
+
+export async function brandShow(opts = {}, { log = (line) => console.log(line) } = {}) {
+  const b = await ops.getBrand(opts);
+  if (opts.json) log(JSON.stringify(b, null, 2));
+  else for (const line of brandLines(b)) log(line);
+  return b;
+}
+
+export async function brandSet(opts = {}, { log = (line) => console.log(line), ...io } = {}) {
+  const args = brandArgs(opts, io);
+  if (!Object.keys(args).length) throw new Error(SET_USAGE);
+  const b = await ops.setBrand(opts, args);
+  if (opts.json) log(JSON.stringify(b, null, 2));
+  else for (const line of ["✓ brand saved; new decks start from it", ...brandLines(b)]) log(line);
+  return b;
+}
+
+// design.md in the person's editor; saved only when it changed.
+export async function brandEdit(opts = {}, { log = (line) => console.log(line), spawn = spawnSync, env = process.env } = {}) {
+  const b = await ops.getBrand(opts);
+  const before = b?.designMd ?? "# Brand\n\nVoice: …\n\nDo:\n- …\n\nDon't:\n- …\n";
+  const dir = mkdtempSync(join(tmpdir(), "hyperdecks-brand-"));
+  const file = join(dir, "design.md");
+  writeFileSync(file, before);
+  const editor = env.VISUAL || env.EDITOR || "vi";
+  const ran = spawn(`${editor} "${file}"`, { stdio: "inherit", shell: true });
+  const after = existsSync(file) ? readFileSync(file, "utf8") : before;
+  if (ran.error || ran.status !== 0 || after === before) {
+    rmSync(dir, { recursive: true, force: true });
+    if (ran.error) throw new Error(`could not start ${editor}: ${ran.error.message}`);
+    if (ran.status !== 0) throw new Error(`${editor} exited with ${ran.signal ?? ran.status}; design.md not saved`);
+    log("design.md unchanged");
+    return b;
+  }
+  let saved;
+  try {
+    saved = await ops.setBrand(opts, { designMd: after });
+  } catch (e) {
+    // Keep what they wrote: the temp file stays, and the error says where.
+    throw new Error(`design.md not saved (${ops.errorText(e)}); your text is still in ${file}. Retry with: hyperdecks brand set --design ${file}`);
+  }
+  rmSync(dir, { recursive: true, force: true });
+  log("✓ design.md saved");
+  return saved;
+}
+
+export function brandFonts(opts = {}, { log = (line) => console.log(line) } = {}) {
+  const out = ops.listFontPairings();
+  if (opts.json) log(JSON.stringify(out, null, 2));
+  else for (const p of FONT_PAIRINGS) log(`${p.id.padEnd(10)} ${`${p.display} / ${p.body} / ${p.mono}`.padEnd(54)} ${p.use}`);
+  if (!opts.json) log("\nhyperdecks brand set --fonts <id>");
+  return out;
+}
+
+export async function brandClear(opts = {}, { log = (line) => console.log(line) } = {}) {
+  const out = await ops.clearBrand(opts);
+  log(opts.json ? JSON.stringify(out) : "✓ brand cleared; new decks get the template look");
+  return out;
+}

package/src/checkRules.mjs

@@ -47,6 +47,8 @@ export const MESSAGES = {
   morphPair: (id, prev) => `slide ${id}: morph needs an element with the same data-morph="<name>" on this slide and the one before it (${prev})`,
   transitionStale: (where, script, manifest) => `${where}: script.md says transition "${script}" but the manifest has "${manifest}": run \`hyperdecks narrate\` so the player gets it`,
   flyTwice: (ids) => `fly is for the deck's one big moment, but slides ${ids.join(", ")} all use it`,
+  // A layout's stand-in left in: `how` is the tool (hosted) or command (CLI) that makes the real file.
+  placeholder: (id, what, el, how, img) => `slide ${id}: ${what} is still the layout's placeholder (${el}); ${how}, then put it in as ${img}`,
   // Warnings (check --layout): the deck still passes.
   layoutUnchecked: (why) => `layout not checked: ${why}`,
   hotlink: (url) => `${url} is hotlinked from another site and can vanish after release; upload it with upload_deck_asset`,
@@ -271,10 +273,40 @@ export function phraseList(value) {
   return value.map((s) => String(s).trim()).filter(Boolean);
 }
 
+// Layout stand-ins a deck must swap for its own file, found by the templates'
+// own markers: the empty div (or the chart's labelled svg). A div that holds
+// its own picture, or gets one from a url() in its style or a <style> rule
+// naming its class, is the deck's art. A deck that wants none removes it.
+const PLACEHOLDERS = [
+  {
+    layout: "l-hero", tag: "div", cls: "art", what: "the hero's art", img: '<img class="art" src="…" alt="">, or delete the div for no art (the presenter is the visual)',
+    how: { hosted: "make a picture of the real subject with generate_image", cli: "make a picture of the real subject with `hyperdecks gen-image \"<prompt>\"`" },
+  },
+  {
+    layout: "l-product", tag: "div", cls: "shot", what: "the product screenshot", img: '<img class="shot" src="…" alt="…">',
+    how: { hosted: "capture the real page with capture_url", cli: "capture the real page with `hyperdecks screenshot <url>`" },
+  },
+  {
+    layout: "l-chart", tag: "svg", cls: "chart", label: /placeholder/i, what: "the chart (made-up numbers)", img: '<img class="chart" src="…" alt="…">',
+    how: { hosted: "draw the real data with render_chart", cli: "draw the real data with `hyperdecks chart <spec.json>`" },
+  },
+];
+const classes = (tag) => (attr(tag, "class") ?? "").split(/\s+/).filter(Boolean);
+export function placeholderErrors(html, { hosted = false } = {}) {
+  const css = [...uncommented(html).matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].map((m) => m[1].replace(/\/\*[\s\S]*?\*\//g, "")).join("\n");
+  const styled = (cls) => [...css.matchAll(/([^{}]*)\{([^{}]*)\}/g)].some(([, sel, body]) => new RegExp(`\\.${cls}(?![\\w-])`).test(sel) && /url\(/i.test(body));
+  return slides(html).flatMap((s, i) => {
+    const layouts = classes(s.tag);
+    return PLACEHOLDERS.filter((p) => layouts.includes(p.layout) && !(p.tag === "div" && styled(p.cls)) && [...s.body.matchAll(new RegExp(`(<${p.tag}\\b[^>]*>)([\\s\\S]*?)</${p.tag}>`, "gi"))].some(([, tag, inner]) =>
+      classes(tag).includes(p.cls) && (p.label ? p.label.test(attr(tag, "aria-label") ?? "") : !inner.trim() && !/url\(/i.test(attr(tag, "style") ?? ""))))
+      .map((p) => MESSAGES.placeholder(s.id || `${i + 1}`, p.what, `<${p.tag} class="${p.cls}">`, hosted ? p.how.hosted : p.how.cli, p.img));
+  });
+}
+
 // Everything checkable from the deck's own files. `exists(ref)` answers whether a
 // local reference resolves inside the deck folder: true, false or "outside".
-export function htmlErrors(html, { exists = () => true, forbid = [], script = "" } = {}) {
-  const errs = [...presenterStyleErrors(html, script), ...transitionErrors(html, script), ...cueSelectorErrors(html, script)];
+export function htmlErrors(html, { exists = () => true, forbid = [], script = "", hosted = false } = {}) {
+  const errs = [...presenterStyleErrors(html, script), ...transitionErrors(html, script), ...cueSelectorErrors(html, script), ...placeholderErrors(html, { hosted })];
   const player = playerScript(html);
   if (!player) errs.push(MESSAGES.noPlayer());
   else if (player.src !== PLAYER_V1) errs.push(MESSAGES.player(player.src));
@@ -486,7 +518,7 @@ export async function checkSources({ html, script = "" }, opts = {}, { fetch: fe
     throw new Error(flagCap !== undefined ? "--max-duration needs a number of seconds" : "maxTotalSeconds in script.md must be a number of seconds");
   }
   const exists = opts.hosted ? () => "hosted" : (opts.exists ?? (() => true));
-  const errors = htmlErrors(html, { exists, forbid, script });
+  const errors = htmlErrors(html, { exists, forbid, script, hosted: !!opts.hosted });
   const ids = slides(html).map((s) => s.id);
   const player = playerScript(html);
   let manifest = null;