@hypersocial/decks-cli 0.2.1 → 0.3.0

package/README.md

@@ -2,12 +2,16 @@
 
 Command-line client for Hypersocial Decks live analytics and share management.
 
-Most users should install the friendlier package name:
+Most users should start with the friendlier package name:
 
 ```bash
-npx hyperdecks whoami
+npx hyperdecks init
 ```
 
+`init` signs you in, installs the skill into your agents, sets up a voice,
+builds and narrates a three-slide hello deck and prints its link. Re-running it
+resumes where it stopped; `--json --yes` is the agent form.
+
 This package targets production by default:
 
 ```bash
@@ -108,7 +112,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.
@@ -128,7 +132,7 @@ normalize: hyper desk=hyperdecks
 ---
 
 ## hello
-hold: 1.1
+hold: 1.5
 presenter: wave
 
 Hi, I'm Selçuk's mini avatar. [wave] This is Hyperdecks. [mood: excited]
@@ -137,6 +141,7 @@ Hi, I'm Selçuk's mini avatar. [wave] This is Hyperdecks. [mood: excited]
 - `## <slide-id>` is the slide's `<section id>` in `index.html`. Text before the first
   heading is notes for people and is ignored.
 - `hold`, `presenter` and `voice` lines directly under a heading are slide options.
+  `hold` is the pause in seconds after the line before the next slide (0.4 by default).
 - Sentences are the caption units, 4–85 characters each.
 - Stage tags (`[wave]`, `[mood: x]`, `[emote: x]`, `[reveal: x]`, `[play: x]`,
   `[pause: s]`, `[custom: name …]`) are not spoken. Each becomes a cue at the start

package/package.json

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

package/skills/hyperdecks/SKILL.md

@@ -11,6 +11,32 @@ Hyperdecks is the CLI and MCP surface for Hypersocial Decks live analytics,
 recipient links, and deck activity. Treat real recipient activity, live deck
 stats, customer-facing links, and "what happened" questions as production work.
 
+## First run
+
+When `hyperdecks whoami` says not authenticated, or `hyperdecks voice list`
+shows no ready voice, run the first-run command instead of working around it:
+
+```bash
+npx hyperdecks init --json --yes [--voice dash] [--name "<name>" --about "<one line>" --ask "<the ask>"]
+```
+
+It signs in, installs this skill, scaffolds a three-slide hello deck from the
+three answers, narrates it, releases one QA link and prints one JSON object
+(`status`, `steps`, `slug`, `deckDir`, `shareUrl`, `next`). Re-running it
+resumes where it stopped. Signed out, it first opens the sign-in page in the
+user's browser and waits up to 3 minutes: tell them to finish signing in there
+(a new account can be made on that page) before you run it, or have them run
+`npx hyperdecks login` first. Inside a git repository it puts the deck in
+`~/hyperdecks` rather than committing into that repository; `--dir` picks the
+folder. Relay every step whose `status` is `needs-human` to the user, word for
+word, and wait for them:
+
+- deck: it needs `--name`, `--about` and `--ask`; ask the user, do not invent them;
+- voice: cloning needs them to type their consent in a terminal (`hyperdecks
+  voice clone <file> --name <name>`), or to agree to the statement before you
+  call `clone_voice`. Never type or confirm consent for them. `--voice dash`
+  lets D.A.S.H., a character voice, present instead.
+
 ## Target Selection
 
 - Prefer production for real-world questions and actions. The published CLI is
@@ -53,13 +79,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` |
@@ -76,18 +107,31 @@ Write `decks/<slug>/evidence.md` as you go: one row per fact with the slide, the
 claim, the source (file path, thread, doc title) and its date. Never put a
 number on a slide that has no row.
 
+<!-- topic: format -->
 ### 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 +144,186 @@ 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.
 
+<!-- topic: presenter -->
+#### 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.
+
+<!-- topic: transitions -->
+#### Transitions
+
+Every slide enters with `drift` unless it says otherwise. Use another only
+where the slide's job matches its "use for"; never hand-write slide-change
+animation in the deck's own JS (it fights the player's timing).
+
+| Transition | Use for | What it does |
+|---|---|---|
+| `drift` (default) | most slides | the old slide drifts out, the new one in, its parts arriving title first |
+| `cut` | a punchline, a fast beat | instant |
+| `push` | the next step in a sequence | the new slide slides over; the old one sinks back and darkens |
+| `wipe` | a new section | a band in the deck's second colour, then one in ink, sweeps across and leaves the new slide |
+| `zoom <selector>` | going into the detail of one row, bar or card | the new slide opens out of that element on the slide before |
+| `morph` (carry over) | a number or title on both slides | the element travels into its new place and size |
+| `fly` | the deck's one big reveal | the presenter flies across and the new slide appears behind it |
+
+Set the deck's in script.md's front matter (`transition: drift`) or on the
+player tag (`data-transition`); a slide's under its `##` heading
+(`transition: push`) or as `data-transition` on its `<section>`, which wins.
+A slide's transition is how it enters; going back plays it in reverse.
+A `transition:` in script.md reaches the player through the manifest, so it
+takes effect after `narrate` (release runs it; nothing re-renders);
+`data-transition` in index.html takes effect at once. Zoom
+names its target on the slide before: `transition: zoom #dash-row`. Morph
+pairs elements by name: put `data-morph="saved"` on the element on both
+slides. Reduced motion turns every one into a short crossfade, and the
+narration never waits for a transition.
+
+`check` fails an unknown name, a `zoom` with no selector or one that matches
+nothing on the slide before, a `morph` with no `data-morph` name on both
+slides, and a second `fly`. It warns when a deck uses more than two kinds
+besides its default: pick one or two and keep them for the same job.
+
+Viewers can poke the live head: a click or tap makes it react (an "oof", a
+flinch) and a drag pulls it a little before it springs back, without pausing
+the narration.
+
+<!-- topic: design -->
+### 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.
+
+<!-- topic: script -->
 ### 3. Write slides and script
 
 - One idea per slide; the title states it.
@@ -115,9 +332,32 @@ The deck contract (`check` enforces each line):
 - Narration: short phrases, each sentence one caption of 4 to 85 characters
   (two lines in the bubble). Aim for 2.5 to 3 minutes in all; `maxTotalSeconds`
   in the front matter is the cap check uses (180 in the scaffold).
-- Holds: 1.1 s by default; `hold: 2` under the heading on interactive slides.
+- Holds: 0.4 s by default. Give a slide `hold: 1.5` when the viewer needs time to read a number, a chart or a reveal, and `hold: 2` 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).
@@ -133,12 +373,18 @@ A slide fails when the transcript does not match the script: read the error,
 reword the sentence (spell numbers and names the way they are said, or add a
 `normalize:` entry), and narrate again; only that slide re-renders.
 
+<!-- topic: check -->
 ### 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 +398,48 @@ 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 |
+| `… transition "…" is not one of` | use drift, cut, push, wipe, zoom `<selector>`, morph or fly |
+| `slide <id>: zoom target "…" matches nothing on the slide before it` | point the zoom at an element of the previous slide, or give that element the id |
+| `slide <id>: morph needs an element with the same data-morph` | put `data-morph="<name>"` on the carried element on both slides, or use drift |
+| `script.md says transition "…" but the manifest has "…"` | run `narrate` (no audio re-renders), or release, which runs it |
+| `fly is for the deck's one big moment` | keep `fly` on one slide; use drift or push on the others |
+| ⚠ `N kinds of transition besides the default` | use one or two kinds, each for its own job |
+| `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 +456,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
@@ -197,6 +471,16 @@ hyperdecks activity --deck <slug> --limit 10
 Tell the user who opened it, how far they got and whether the narration
 finished. QA links never count.
 
+### Hosted source (chat agents and the connector)
+
+A deck can also live on Hyperdecks with no folder: chat agents build it through
+the hosted MCP (`deck_guide`, `new_deck`, `get_deck_source`, `write_deck_source`,
+`upload_deck_asset`, `check_deck`, `release_deck`; see `chat.md`). Move between
+the two with `hyperdecks source pull <slug> [dir]` (the hosted draft into a
+folder) and `hyperdecks source push <slug> [dir]` (a folder's files back to the
+draft), `hyperdecks asset add <slug> <file|url>` for an image, `hyperdecks guide
+[topic]` for these sections, and `--hosted` on `deck new`, `check` and `release`.
+
 ## Safety
 
 - For read-only inspection, run commands directly and summarize the important

package/skills/hyperdecks/chat.md

@@ -0,0 +1,49 @@
+# Hyperdecks from a chat app (hosted MCP)
+
+You are building a narrated deck through the Hyperdecks connector: no terminal,
+no git, no folder. The deck's files (`index.html`, `script.md`, `evidence.md`)
+live on Hyperdecks as a draft; you read and edit them with tools, and nothing
+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.
+
+## The loop
+
+1. `deck_guide` (this page), then `deck_guide { topic: "layouts" }` to pick slides.
+2. `new_deck { slug, title, layouts }`: registers your draft and returns the
+   full text of every file plus a `previewUrl` (the draft, untracked).
+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.
+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`;
+   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
+   `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.
+   `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`.
+
+## Rules that matter
+
+- Every slide is `<section class="slide" id="…" data-note="<source of its facts>">`,
+  in the same order as the `## <id>` blocks in `script.md`.
+- Keep the player script tag and the `<style data-hd-loading>` block the
+  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.
+- 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`.