@hypersocial/decks-cli 0.2.1 → 0.2.2

package/README.md

@@ -108,7 +108,7 @@ credits per second, refunded if fal fails to produce the clip.
 ## Narration
 
 `narrate` turns a deck's `script.md` into voiced clips in your own voice, word-timed
-captions, 60 fps mouth frames and a deck manifest. Rendering runs on the Hyperdecks
+captions and a deck manifest (the player's live head lip-syncs from the audio). Rendering runs on the Hyperdecks
 backend with the platform's ElevenLabs key; the CLI only sends the script and polls.
 Each line is cached by a hash of its spoken text and voice, so after an edit only the
 slides whose words changed re-render.

package/package.json

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

package/skills/hyperdecks/SKILL.md

@@ -53,13 +53,18 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 
 | Step | CLI | MCP tool |
 |---|---|---|
-| Scaffold | `hyperdecks deck new <slug> "<title>" --narrated` | `new_deck` |
+| 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` |
+| 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` |
 | 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` |
+| Share-link poster | `hyperdecks poster <slug>` | `generate_deck_poster` |
 | Import only | `hyperdecks import <file> --slug <slug>` | `import_deck_from_url` |
 | One more link | `hyperdecks share new <slug> "<name>"` | `create_share` |
 | Who watched | `hyperdecks deck stats <slug>` | `deck_stats` |
@@ -79,15 +84,27 @@ number on a slide that has no row.
 ### 2. Scaffold
 
 ```bash
-hyperdecks deck new <slug> "<title>" --narrated     # writes decks/<slug>/, registers a draft you own
+hyperdecks deck new <slug> "<title>" --narrated --layouts hero,features,product,number,closer
+                                                     # one slide per layout, from the layout library
+hyperdecks deck new <slug> "<title>" --narrated [--presenter-style stage|bubble|glass|corner]
+                                                     # the plain eight-slide outline
 ```
 
+Both write `decks/<slug>/` and register a draft you own. Prefer `--layouts`:
+pick the layouts from the story (see **Design** below), in order; repeat one
+for more of the same (`number,number` gives slides `number` and `number-2`).
+
 Files, all in `decks/<slug>/`:
 
-- `index.html`: eight `<section class="slide" id="…">` slides (hello, problem,
-  why-now, idea, how, proof, ask, bye) and the hosted player script. Keep, cut or
-  add slides; keep the contract below.
-- `script.md`: the narration, one `## <slide-id>` block per slide.
+- `index.html`: the `<section class="slide" id="…">` slides and the hosted
+  player script. With `--layouts` each slide is a layout's section (ids like
+  `features`, inner ids like `features-f1`) and its CSS sits once in `<head>`;
+  without, eight outline slides (hello, problem, why-now, idea, how, proof, ask,
+  bye). Keep, cut or add slides; keep the contract below.
+- `script.md`: the narration, one `## <slide-id>` block per slide. With
+  `--layouts` each block starts as the layout's starter line with its `[go]` /
+  `[look]` cues already pointing at the slide's elements: rewrite the words,
+  keep the cues at the words they belong to.
 - `evidence.md`: the sources table. Private: release never uploads it.
 
 The deck contract (`check` enforces each line):
@@ -100,13 +117,145 @@ The deck contract (`check` enforces each line):
 - A title (first `<h1>`/`<h2>`) over 28 characters carries
   `data-title-mobile="<shorter>"`. The scaffold puts one on every title.
 - Each slide keeps its `<div class="narration-slot"></div>` (where the
-  presenter's face and caption bubble sit); the first slide has `data-intro`.
+  presenter's face and captions sit; the player glides the presenter there,
+  so put slots on different sides across slides, as the scaffold's
+  `.slot-left` does); the first slide has `data-intro`.
 - The player script stays
   `<script type="module" src="https://decks.hypersocial.ai/player/v1/player.js" data-manifest="…">`.
   `narrate` fills `data-manifest`; do not edit it by hand.
 - Local images and files sit inside the deck folder and are referenced
   relatively (`img/chart.png`). Hosted images (`gen-image` URLs) are fine too.
 
+#### Which presenter style
+
+Set the deck's on the player tag (`data-presenter-style="stage"`) or in
+script.md's front matter (`presenterStyle: stage`); override one slide with
+`data-presenter-style` on its `<section>` or `presenter-style: corner` under
+its `##` heading.
+
+| Style | Pick it when |
+|---|---|
+| `stage` (default with the live head) | the presenter carries the deck: a founder pitch, a walkthrough. Large unframed head, lower-third captions; leave ~500 px beside the text for it |
+| `bubble` (default otherwise) | a light aside; the face in a circle with a speech bubble |
+| `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 |
+
+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.
+
+### Design: make it look good
+
+A narrated deck is only as convincing as it looks. Design before you write the
+narration, and check the result at both widths (step 6).
+
+**One idea per slide.** The title states the idea as a sentence a listener
+could repeat ("Narration renders in two minutes", not "Speed"). Everything
+else on the slide supports that sentence; if it needs a second idea, it is a
+second slide. Five to nine slides carry a three-minute deck.
+
+**Type scale.** The layout shell defines it in `:root`; use the tokens, not
+new sizes:
+
+| Token | Stage (1600×900) | Phone | For |
+|---|---|---|---|
+| `--t-display` | 128px | 54px | one hero line or a closing word, at most once per slide |
+| `--t-title` | 84px | 38px | the slide's title |
+| `--t-sub` | 56px | 28px | a title beside a visual, a number's label |
+| `--t-lead` | 30px | 17px | one supporting sentence |
+| `--t-body` | 24px | 15px | list items, card text |
+| `--t-label` | 17px | 12px | kickers, sources, captions (mono, uppercase) |
+
+Nothing on a slide below 17px at stage size (a screenshot's frame chrome aside). A title over 28 characters needs
+`data-title-mobile`; write the short version as a real sentence.
+
+**Colour and contrast.** Three colours do the work: `--ink`, `--paper` and one
+`--accent` (a second, `--accent-2`, only for a chart's other series, an
+illustration or a placeholder face). Text is ink on paper or accent, or paper on ink: never accent
+on paper, never grey on a colour. Alternate slide grounds (`on-accent`,
+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.
+
+**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]` |
+| `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]` |
+| `compare` | before/after, them/us, three parallel lines each | stage; `[look: #<id>-before]`, `[go: #<id>-after]` |
+| `timeline` | four milestones: history, a roadmap, a process | stage; `[go: #<id>-m1]` … `m4`, `[go: slot]` |
+| `features` | three things it does, an icon each | stage; `[go: #<id>-f1]` … `f3`, `[go: slot]` |
+| `chart` | real numbers drawn with `chart`, the takeaway beside | stage; `[look: #<id>-chart]`, `[reveal: #<id>-takeaway]` |
+| `team` | up to four people, faces only with permission | stage; `[go: #<id>-p1]` … `p4`, `[go: slot]` |
+| `closer` | the end: one line and one action (a command, a link) | stage, bottom-left; `[go: #<id>-cta]`, `[go: slot]`, `[wave]` |
+
+Presenter style follows the deck (step 2, *Which presenter style*): `stage`
+when the presenter carries the story, which is what the layouts are drawn for
+(they keep the slot's corner clear); `corner` on a slide where a big
+visual is the point and moves are not needed; `glass` on a dark or busy
+picture. Two layouts (`quote`, `closer`) sit left; put a `slot-left` on others
+where there is room so slide changes move the presenter.
+
+**Visuals: real first, generated second.**
+
+- Product: `hyperdecks screenshot <url>` (`capture_url`) into `product`'s
+  `.shot`; crop to what the narration talks about. Never mock a UI that
+  exists.
+- Numbers: `hyperdecks chart <spec.json>` (`render_chart`) in the deck's
+  palette into `chart`'s `.chart`, the source in `data-note` and evidence.md.
+  Never a generated picture of a chart.
+- **No decorative imagery.** Generic illustration (stages, speech bubbles,
+  floating shapes, abstract "tech" art, clip-art metaphors) makes a deck look
+  cheap. A visual earns its place only if it shows something real from the
+  story: the product, the data, a concrete situation or object. When in doubt,
+  leave it out: one big statement in type beats a picture of nothing. The
+  presenter is the hero of the opening slide; don't put art behind it.
+- Icons: only when they label something the viewer must tell apart at a
+  glance. Three short statements set large usually beat three icon cards.
+- Images: `gen-image` (`generate_image`) only for a concrete subject the
+  deck is about (a product in use, a place, a real object), never a metaphor.
+  One style per deck, described the same way every time (subject, medium,
+  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.
+- People: real photos only with permission; initials otherwise.
+
+**Motion.** The presenter's moves are the deck's motion; keep everything else
+still.
+
+- `[go]` when the narration walks through items (cards, milestones, people,
+  the action on the closer): one `go` per item at the word that starts it,
+  then `[go: slot]` before the slide ends. Never more than one `go` per
+  sentence; never a `go` on a slide in `corner` style.
+- `[look]` for a glance: the title as it is read, a number as it is said, a
+  screenshot as the narration turns to it.
+- `[reveal]` for the one detail that should not be read before it is said (a
+  takeaway, a callout); not for every line.
+- `[wave]` once at the start and once at the end.
+- No CSS animation on slides beyond `.reveal`; the player animates the slide
+  change.
+
+**Review before release (required).** After `check` passes and the deck is
+imported, run `hyperdecks review <slug> --script decks/<slug>/script.md`
+(`review_deck`, then poll `check_review_job`). Act on every finding:
+
+- `fix`: change the slide or the script, re-import (or `release --qa`), and
+  review again until no `fix` is left. Do not release with a `fix` open.
+- `consider`: apply it when it serves the slide's one idea; otherwise note in
+  your reply to the user why you left it.
+- A finding you disagree with (a deliberate choice, a misread screenshot):
+  say so to the user with the reason instead of silently ignoring it.
+
+If review cannot run (no credits, the service is down), say so to the user and
+do the step 6 screenshot pass yourself as the reviewer: the same desktop and
+phone screenshots, the same `fix` bar.
+
 ### 3. Write slides and script
 
 - One idea per slide; the title states it.
@@ -118,6 +267,29 @@ The deck contract (`check` enforces each line):
 - Holds: 1.1 s by default; `hold: 2` under the heading on interactive slides.
 - Cues: `[reveal: #id]` reveals `.reveal#id` at the word before it; also
   `[wave]`, `[mood: excited]`, `[pause: 0.5]`, `[custom: name]`.
+- Moves, to point at part of a slide: `[go: <selector>]` flies the presenter
+  beside that element (the side with room) until the next `go`, the slide's
+  end, or `[go: slot]`; `[look: <selector>]` turns the head toward it without
+  moving. One selector each, matched inside that slide; check fails one that
+  matches nothing. Use `go` when the narration walks through a list or chart,
+  `look` for a glance at a title or number. Not in `corner` style. The best
+  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.
+
+| Cue | Effect |
+|---|---|
+| `[wave]` | the presenter greets (the live head's joy emote) |
+| `[mood: excited]` / `[emote: name]` | the head's mood or emote |
+| `[reveal: #id]` | adds `is-revealed` to `#id` |
+| `[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 |
+| `[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
+  D.A.S.H. presents. It works once the deployment sets `CHARACTER_VOICE_DASH`.
 - No `voice:` in the front matter means the user's first ready voice. If
   `hyperdecks voice list` shows none, ask the user to record one and run
   `voice clone` (it asks them for consent; never clone anyone else's voice).
@@ -136,9 +308,14 @@ reword the sentence (spell numbers and names the way they are said, or add a
 ### 5. Check
 
 ```bash
-hyperdecks check decks/<slug> [--forbid "Other Co,codename"]
+hyperdecks check decks/<slug> [--forbid "Other Co,codename"] [--layout]
 ```
 
+`--layout` lays each slide out in Chromium (needs `hyperdecks preview setup`).
+At the stage size it warns, without failing, when a slide's presenter would
+overlap its title. On a 390×844 phone (the share player's 374×736 slide card)
+it fails any slide whose content overflows: the player never scrolls a slide.
+
 `--forbid` lists phrases that must not reach this audience (another customer,
 an internal codename). Messages and what to do:
 
@@ -152,25 +329,42 @@ an internal codename). Messages and what to do:
 | `narration runs …s, over the …s cap` | shorten the script |
 | `clip <id>: audio …` / `clip <id>: timeline …` | narrate again; the asset is missing or wrong |
 | `clip <id>: caption N runs` | narrate that slide again (`--slide <id>`) |
-| `clip <id>: caption words do not match` | narrate that slide again |
+| `clip <id>: captions do not cover the clip text` | narrate that slide again |
 | `clip <id>: caption N is … characters` | split or join sentences in that block |
 | `local reference does not resolve` / `leaves the deck folder` | move the file into the deck folder or fix the path |
 | `player script must be` / `no player script` | restore the player/v1 script tag |
 | `the player script has no data-manifest` | run `narrate` |
+| `no loading state` | copy the template's `<style data-hd-loading>` block (and the preload lines above it) into `<head>`; set `--hd-ground` / `--hd-ground-ink` to the first slide's colours |
 | `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 |
+| `… 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 |
+| `slide <id>: its content runs …px past the slide on a 390×844 phone` | trim that slide on phones: smaller type, fewer items, or hide decoration in its `@media (max-width: 650px)` rules (an `#id` rule outranks them; restate it there) |
+| ⚠ `slide <id>: the … presenter would overlap the title` | move that slide's `.narration-slot`, pad the text away from it, or use `corner` |
 
 ### 6. Look at it, at both widths
 
 Serve the folder (`npx serve decks/<slug>` or `python3 -m http.server -d decks/<slug>`)
 and screenshot it with Playwright at 1440×900 and 390×844, every slide
-(`#scene=<id>`). Look at both: nothing clipped, the bubble clear of the text, the
-mobile titles in use. Fix and repeat until both read well.
+(`#scene=<id>`). Look at both: nothing clipped, the presenter and its captions
+clear of the text, the mobile titles in use. Fix and repeat until both read well.
+
+Then the required review (see **Design**, *Review before release*): once the
+deck is imported, `hyperdecks review <slug> --script decks/<slug>/script.md`
+(`review_deck`, then `check_review_job`) has GPT-6 Luna look at every slide of
+the deck's QA link on desktop and phone and list each problem as `fix` or
+`consider` with a concrete suggestion. Release only when no `fix` is left.
+
+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.
 
 ### 7. Release
 
-Commit the deck folder first: release refuses uncommitted changes so every
+Only after `check` passes and the last review has no `fix` finding. Commit the deck folder first: release refuses uncommitted changes so every
 release matches a commit.
 
 ```bash
@@ -187,6 +381,11 @@ references must be tracked by git (an ignored `*.mp4` is refused). Then it impor
 (each `--email` pairs with the `--to` before it). Confirm recipients with the
 user before sending real links; send the links yourself only if asked.
 
+Release also makes the deck's share-link poster (its first slide with a Play
+badge, shown when a link is pasted into Slack, iMessage or email, and on the
+dashboard card) within a minute. When the first slide changed look, check it
+with `hyperdecks poster <slug>` (`generate_deck_poster`), which prints its URL.
+
 ### 8. Report who watched
 
 ```bash