@hypersocial/decks-cli 0.5.0 → 0.7.0

package/package.json

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

package/skills/hyperdecks/SKILL.md

@@ -123,14 +123,18 @@ 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` |
+| Import a brand (website, .pptx/.potx, .pdf, a deck; preview first) | `hyperdecks brand import <url\|file\|slug>` | `import_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` |
@@ -223,6 +227,9 @@ its `##` heading.
 | `glass` | dark or busy slides: head and captions on one frosted panel |
 | `corner` | the slide is the point (a product shot, a chart, a demo): small head bottom-right, subtitles along the bottom |
 
+The live head's face follows script cues too (`[nod]`, `[look #card]`,
+`[smile]`, `[gesture: lightbulb]`; see the script topic); a still face ignores them.
+
 Below 650 px stage and glass become corner on their own. Run
 `hyperdecks check <deck> --layout` to be warned about any slide whose presenter
 would cover its title.
@@ -299,13 +306,39 @@ 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
+import it from what they already have: `hyperdecks brand import
+<url|file.pptx|file.pdf|deck-slug>` (`import_brand`) reads the real colours,
+fonts and logo (a PowerPoint's theme exactly) and returns a preview link, a
+sample slide in that brand, and a token. Always show them the preview and
+ask; save with `brand set --draft <token>` (`set_brand { draft }`) only after
+they say yes.
+
+**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]` |
@@ -345,7 +378,26 @@ where there is room so slide changes move the presenter.
   palette hexes, "no text"). `--model nano-banana-2.1` when the image must
   carry legible type.
 - Video: `gen-video` for a short loop behind a hero or a product moment, with
-  `[play: video]` at its word; never needed for a deck to work.
+  `[play: video]` at its word; never needed for a deck to work. A clip that
+  plays on repeat should be made with `--loop` (`loop: true`): it starts and
+  ends on the same frame, so there is no jump at the seam. Give it `--image`
+  to loop a still you already have; without one a keyframe is rendered first.
+- Moving cut-outs: `--transparent` (`transparent: true`) mattes the
+  background out, the moving version of a `gen-image --transparent` PNG: a
+  spinning part, a product turning, over the slide's own background. Use it
+  with `--loop` and a subject on a plain background. It returns a VP9 WebM
+  with alpha (Chrome, Firefox, Edge) and a stacked-alpha MP4 that the hosted
+  player draws on a canvas in Safari and on iOS, which ignore WebM alpha. The
+  job's `markup` is the tag to paste, as is:
+
+  ```html
+  <video muted loop playsinline autoplay crossorigin="anonymous"
+    src="(video.url)" data-alpha-stacked="(video.stacked.url)"></video>
+  ```
+
+  Keep `crossorigin` and `data-alpha-stacked`: the player needs both. A deck
+  without the hosted player shows the clip in a box in Safari. A transparent
+  clip costs 2 credits a second more than an opaque one.
 - People: real photos only with permission; initials otherwise.
 
 **Motion.** The presenter's moves are the deck's motion; keep everything else
@@ -399,6 +451,12 @@ phone screenshots, the same `fix` bar.
   showcase is a slide of stacked cards, one point each, with a `go` to each
   card at the word that starts it: `Write [go: #step-1] the slides, write
   [go: #step-2] what you'd say`. Give each card an id.
+- Face: the live head already moves with the speech (eyes, brows, a nod on a
+  falling end); add a few face cues only where they carry the point, each on
+  the word before it: `This is the big one [nod] and here [look #m3] is the
+  proof.` / `Not a slide tool [shake], a presenter.` / `Then it clicked
+  [gesture: lightbulb].` / `Really? [brow up] Yes [smile].` A still or
+  captions-only presenter ignores them.
 
 | Cue | Effect |
 |---|---|
@@ -408,7 +466,12 @@ phone screenshots, the same `fix` bar.
 | `[pause: 0.5]` | a beat of silence (≤ 5 s) |
 | `[play: video]` / `[pause: video]` | play or pause the slide's video |
 | `[go: .list]` / `[go: slot]` | fly beside `.list` / back to the slot |
-| `[look: h2]` | look at the title |
+| `[look: h2]` / `[look #card]` | look at the title / the card, then back |
+| `[look viewer]` / `[look away]` | look back at the viewer / glance aside |
+| `[nod]` / `[shake]` | a nod or head shake that suits the mood |
+| `[brow up]` / `[brow down]` | raise or lower the brows |
+| `[smile]` / `[think]` | `[mood: happy]` / `[mood: thinking]` |
+| `[gesture: <id>]` | one of the head's tracks: `knowing-nod`, `ponder-tilt`, `lightbulb`, `side-eye-hmm`, `chuckle-bob`, `sunny-nod`, `double-take`… (check lists them all) |
 | `[custom: name]` | only the slide's controller sees it |
 - `voice: dash` narrates with D.A.S.H.'s own robot voice, a synthetic
   character voice (not a clone of anyone) any account may use, for decks that
@@ -462,6 +525,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 |
@@ -488,9 +552,11 @@ 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.
+defaults to MiniMax H3 Max (`--model kling-v3` is the fallback); `--loop` and
+`--transparent` work with both. Use `chart` for
+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

@@ -22,32 +22,67 @@ 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? Offer to import it from what they have: `import_brand` with
+   their website (`url`), a PowerPoint or PDF they attach (`file`) or one of
+   their decks (`slug`). It reads the real colours, fonts and logo and returns
+   a `previewUrl` (a sample slide in that brand) and a `token`. Always give
+   them the preview link, say what it found (and its notes), and ask; only
+   after a yes call `set_brand { draft: token }`. Never save without the yes.
+   (`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.
+   For motion, `generate_video` (poll `check_video_job`): `loop: true` for a
+   clip that repeats with no jump, `transparent: true` for a moving cut-out
+   over the slide. Paste the finished job's `markup` as is (a transparent
+   clip's `<video>` names a second file in `data-alpha-stacked`, which the
+   player shows in Safari and on iOS).
+   `deck_guide { topic: "design" }` says when each fits.
 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"`. To direct the face, put a few cues in
+   script.md on the words that carry the point (`[nod]`, `[look #card]`,
+   `[smile]`, `[gesture: lightbulb]`; `deck_guide script` lists them) and
+   narrate again.
+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. 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.
-9. Later: `list_shares` and `deck_stats` (both show the card),
+   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;
@@ -63,8 +98,8 @@ makes the hello deck; continue from step 5 below.
   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,166 @@
+// 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>"]
+//             [--draft <token>]      (a brand import, saved after you saw its preview)
+//   brand import <url|file|slug>     read a brand from a website, a .pptx / .potx /
+//                                    .pdf or one of your decks into a draft + preview
+//   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 { basename, 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 [--draft <token>] [--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;
+  if (flag(opts, "draft") !== undefined) args.draft = flag(opts, "draft");
+  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;
+}
+
+// What `brand import` read, for the terminal.
+export function importLines(d) {
+  const colors = Object.entries(d.colors ?? {}).map(([k, v]) => `${k} ${v}`).join(", ");
+  const fonts = Object.entries(d.fonts ?? {}).map(([k, v]) => `${k} ${v}`).join(", ");
+  return [
+    `read from ${d.source?.kind} ${d.source?.ref}`,
+    ...(d.name ? [`name:      ${d.name}`] : []),
+    `colours:   ${colors || "(none found)"}`,
+    `fonts:     ${fonts || "(none found)"}`,
+    `logo:      ${d.logoUrl ?? "(none found)"}`,
+    ...(d.notes ?? []).map((n) => `  · ${n}`),
+    "",
+    `preview:   ${d.previewUrl}`,
+    `Nothing is saved yet. To make it your brand: hyperdecks brand set --draft ${d.token}`,
+  ];
+}
+
+// brand import <url|file|slug>: an http(s) URL or a domain is a website, an
+// existing path a file, anything else one of your deck slugs.
+export async function brandImport(from, opts = {}, { log = (line) => console.log(line), readFile = readFileSync, exists = existsSync } = {}) {
+  const src = String(from ?? "").trim();
+  if (!src) throw new Error("usage: brand import <https://your.site | deck.pptx | brand.pdf | deck-slug> [--json]");
+  let args;
+  if (/^https?:\/\//i.test(src)) args = { url: src };
+  else if (exists(src)) args = { bytes: new Uint8Array(readFile(src)), fileName: basename(src) };
+  else if (/\.(pptx|potx|pdf)$/i.test(src)) throw new Error(`${src}: no such file`);
+  else if (/^[a-z0-9][a-z0-9-]*$/.test(src)) args = { slug: src };
+  else if (/^[\w-]+(\.[\w-]+)+(\/.*)?$/.test(src)) args = { url: `https://${src}` };
+  else throw new Error(`${src}: not a URL, a file or a deck slug`);
+  const d = await ops.importBrand(opts, args);
+  if (opts.json) log(JSON.stringify(d, null, 2));
+  else for (const line of importLines(d)) log(line);
+  return d;
+}