@hypersocial/decks-cli 0.1.12 → 0.2.1

package/README.md

@@ -66,8 +66,111 @@ recipient archive|unarchive <name>
 import <html-or-zip-or-url> --slug <slug> [--title title] [--status draft|live|archived]
 skills install [--agent codex,claude-code] [--all-agents]
 activity [--deck <slug>] [--limit <n>] [--json]
+
+gen-video "<prompt>" [--image <url>] [--seconds 5] [--aspect 16:9|9:16] [--slug <deck>] [--name <name>] [--download <file>]
+video-job <jobId> [--json]
+
+narrate <deck-dir> [--slide <id>] [--voice <v>] [--slug <slug>] [--dry-run] [--json]
+voice list|clone|upload|rm
+
+deck new <slug> "<title>" --narrated [--dir <path>]
+check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--json]
+release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v]
 ```
 
+## Narrated decks
+
+`deck new --narrated` scaffolds `decks/<slug>/` (`index.html` with eight slides for
+the hosted player, `script.md`, `evidence.md`) and registers the draft. `narrate`
+renders it and sets the player's `data-manifest`. `check` is the gate: slide ids
+equal the manifest's clip ids in order; durations plus holds equal the declared
+total and stay under the cap (`maxTotalSeconds` in `script.md`, else 180 s); every
+clip's audio and timeline resolve with the right type; captions are in time,
+cover the clip text and run 4 to 85 characters; local `src`/`href` resolve inside
+the folder; the player is the pinned `player/v1`; `--forbid` phrases appear
+nowhere; every slide has a `data-note` and long titles a `data-title-mobile`.
+`release` refuses uncommitted changes in the deck folder, runs check and narrate
+(stopping for a commit if narration changed the folder), imports `index.html` with
+the local files it references, and creates one share per `--to`. The agent
+procedure is the "Author a narrated deck" section of the bundled skill.
+
+## Video clips
+
+`gen-video` generates a short clip on the Hyperdecks backend (fal, Kling v3 Standard)
+and prints its hosted MP4 URL: text-to-video from a prompt, or `--image <url>` to
+animate a still as the first frame (the clip keeps the still's aspect ratio). Clips are
+3–10 seconds (`--seconds`, default 5), 16:9 or 9:16 (`--aspect`), with no audio, so use
+them as `<video src="…" muted loop playsinline autoplay>`. `--slug` files the clip into
+that deck's assets as `video/mp4`. A clip takes one to a few minutes; the command waits,
+printing progress to stderr, and `video-job <jobId>` checks a job by id. Clips cost 3
+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
+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.
+
+```text
+narrate <deck-dir> [--slide <id>[,<id>]] [--voice <handle|name|id>] [--slug <slug>] [--dry-run] [--json]
+voice list [--json]
+```
+
+`script.md` is the deck script markup:
+
+```markdown
+---
+voice: selcuk
+maxTotalSeconds: 200
+normalize: hyper desk=hyperdecks
+---
+
+## hello
+hold: 1.1
+presenter: wave
+
+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.
+- 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
+  time of the word before it.
+- Voice tags (`[whispers]`, `[laughs]`, `[sighs]`, `[excited]`, …) are sent to the
+  voice and left out of the captions.
+- Unknown tags, a tag with no word before it, and headings with no matching section
+  fail with line numbers.
+
+`--dry-run` lists each slide, its hash and whether it would render. It renders nothing.
+A full run writes `<deck-dir>/narration/manifest.json` and prints the manifest URL and
+each clip's URL. Clips, timelines and the manifest are deck assets with
+content-addressed names (`narration-<id>-<hash>.mp3|json`), so re-narrating never
+breaks a URL a live deck already serves. If the transcript does not match the script,
+the slide fails and the message shows both strings. Add a `normalize` entry when the
+speech-to-text spells a name differently, or reword the line.
+
+## Voices
+
+Narration speaks in a voice you own. Clone yours from a short recording:
+
+```text
+voice clone <file...> --name <name>   1-3 mp3/m4a/wav recordings, 30 s to 3 min in total, 10 MB each
+voice list [--json]                   your voices: ready, cloning or failed
+voice upload <file...>                upload recordings, print sample ids (for the MCP clone_voice tool)
+voice rm <name|id>                    delete a voice, also at the provider
+```
+
+`voice clone` prints a consent statement and uploads nothing until you type
+`I consent`. Cloning runs on the backend with the platform's ElevenLabs key and costs
+credits, refunded if it fails (a recording that is too short, too long or not audio
+fails before the provider is called). Then `narrate <deck-dir> --voice <name>`.
+Deleting a voice removes it at the provider; decks already narrated with it keep playing.
+
 ## Development Target
 
 Production is the default because this CLI is for real recipient activity and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.1.12",
+  "version": "0.2.1",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "main": "./src/commands.mjs",
@@ -24,6 +24,7 @@
     "bin/",
     "src/",
     "skills/",
+    "templates/",
     "README.md"
   ],
   "engines": {
@@ -37,5 +38,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hypersocialinc/hyperdecks.git",
+    "directory": "packages/decks-cli"
   }
 }

package/skills/hyperdecks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hyperdecks
-description: Use when working with Hypersocial Decks, Hyperdecks CLI, production deck analytics, recipient share links, deck activity, MCP deck tools, or real-world/customer-facing deck checks. Prefer production for real activity and analytics; use development only for local implementation/testing when explicitly requested.
+description: Use when asked to make, narrate, check or ship a deck ("make me a narrated deck", "turn this into a deck and send it"), or when working with Hypersocial Decks, Hyperdecks CLI, production deck analytics, recipient share links, deck activity, MCP deck tools, or real-world/customer-facing deck checks. Prefer production for real activity and analytics; use development only for local implementation/testing when explicitly requested.
 ---
 
 # Hyperdecks
@@ -45,6 +45,158 @@ If authentication is missing, run or ask the user to run:
 hyperdecks login
 ```
 
+## Author a narrated deck
+
+The path from a brief to a share link, run by you, the agent. Every step is a
+CLI command (`hyperdecks …`, also installed as `decks`) and an MCP tool on the
+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` |
+| Images | `hyperdecks gen-image "<prompt>" --slug <slug>` | `generate_image` |
+| Video clips | `hyperdecks gen-video "<prompt>" --slug <slug>` | `generate_video` |
+| 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` |
+| 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` |
+| All activity | `hyperdecks activity --deck <slug>` | `activity_overview` |
+
+### 1. Ground it in the user's own material
+
+Build the deck from what you can already read in this session: files in the
+working directory, connected tools (email, Notion, Drive, Slack) and the earlier
+conversation. Do not ask the user to paste anything you could open yourself. Ask
+only for what no source holds (the audience, the ask, the deadline).
+
+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.
+
+### 2. Scaffold
+
+```bash
+hyperdecks deck new <slug> "<title>" --narrated     # writes decks/<slug>/, registers a draft you own
+```
+
+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.
+- `evidence.md`: the sources table. Private: release never uploads it.
+
+The deck contract (`check` enforces each line):
+
+- One `<section class="slide" id="<id>">` per slide; ids are lowercase,
+  unique, and in the same order as the `##` blocks in `script.md`.
+- Every slide has `data-note="<source of its facts>"`, e.g.
+  `data-note="Q3 numbers: finance-update.pdf, 2026-10-02"`. A slide with no
+  facts says so: `data-note="Title slide: no facts."`.
+- 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`.
+- 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.
+
+### 3. Write slides and script
+
+- One idea per slide; the title states it.
+- Anything not agreed yet is labelled **Proposed** on the slide and in the
+  narration ("This part is a proposal.").
+- 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.
+- Cues: `[reveal: #id]` reveals `.reveal#id` at the word before it; also
+  `[wave]`, `[mood: excited]`, `[pause: 0.5]`, `[custom: name]`.
+- 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).
+
+### 4. Narrate and read the guard
+
+```bash
+hyperdecks narrate decks/<slug> --dry-run   # what would render, and the characters of TTS
+hyperdecks narrate decks/<slug>             # renders changed slides, saves narration/manifest.json, sets data-manifest
+```
+
+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.
+
+### 5. Check
+
+```bash
+hyperdecks check decks/<slug> [--forbid "Other Co,codename"]
+```
+
+`--forbid` lists phrases that must not reach this audience (another customer,
+an internal codename). Messages and what to do:
+
+| Message starts with | Fix |
+|---|---|
+| `no slides` / `slide N has no id` | every slide is `<section class="slide" id="…">` |
+| `manifest … could not be read` | narrate again; the manifest URL is wrong or broken |
+| `clip <id>: duration …`, `needs its text`, `needs an audio URL` … / `timeline has no captions` | narrate again (a hand-edited or partial manifest) |
+| `slide ids (…) must equal the manifest clip ids` | reorder or rename slides or `##` blocks to match, narrate again |
+| `clip durations plus holds add up to` | narrate again (the manifest is stale or edited) |
+| `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>: 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` |
+| `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 |
+
+### 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.
+
+### 7. Release
+
+Commit the deck folder first: release refuses uncommitted changes so every
+release matches a commit.
+
+```bash
+git add decks/<slug> && git commit -m "deck: <slug>"      # include narration/ and any images
+hyperdecks release decks/<slug> --to "Me" --qa                       # your own viewing, untracked
+hyperdecks release decks/<slug> --to "Ana Diaz" --email ana@x.com --to "Sam"
+```
+
+Release runs check, then narrate (free when nothing changed). If narration
+changed the folder it stops: check, commit, release again. Files the page
+references must be tracked by git (an ignored `*.mp4` is refused). Then it imports
+`index.html` and the files it references (never `script.md`, `evidence.md` or
+`narration/`), marks the deck live and prints one `/v/<token>` link per `--to`
+(each `--email` pairs with the `--to` before it). Confirm recipients with the
+user before sending real links; send the links yourself only if asked.
+
+### 8. Report who watched
+
+```bash
+hyperdecks deck stats <slug>
+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.
+
 ## Safety
 
 - For read-only inspection, run commands directly and summarize the important

package/src/check.mjs

@@ -0,0 +1,316 @@
+// hyperdecks check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--json]
+//
+// The narrated-deck integrity gate, ported from the Netflix presentation's
+// scripts/check.mjs and its variant builders. Every rule returns its message from
+// MESSAGES so the skill can document them and tests can match them exactly.
+// The rules are pure (htmlErrors, manifestErrors, timelineErrors); checkDeck does
+// the I/O: it reads the deck folder, fetches the manifest the player names and
+// every clip's audio and timeline. `fetch` and `exists` are injectable for tests.
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+export const PLAYER_V1 = "https://decks.hypersocial.ai/player/v1/player.js";
+export const DEFAULT_MAX_DURATION = 180;
+export const MOBILE_TITLE_CHARS = 28;
+export const CAPTION_MIN_CHARS = 4;
+export const CAPTION_MAX_CHARS = 85;
+
+export const MESSAGES = {
+  noPlayer: () => `no player script: add <script type="module" src="${PLAYER_V1}" data-manifest="…">`,
+  player: (src) => `player script must be ${PLAYER_V1} (got ${src})`,
+  noManifest: () => "the player script has no data-manifest: run `hyperdecks narrate <deck-dir>`, which sets it",
+  manifestUnavailable: (url, why) => `manifest ${url} could not be read (${why})`,
+  noSlides: () => 'no slides: each slide is a <section class="slide" id="…">',
+  clipField: (id, field) => `clip ${id}: ${field}`,
+  noCaptions: (id) => `clip ${id}: timeline has no captions`,
+  order: (slides, clips) => `slide ids (${slides.join(", ")}) must equal the manifest clip ids (${clips.join(", ")}), in order`,
+  total: (sum, declared) => `clip durations plus holds add up to ${sum}s but the manifest declares totalDuration ${declared}s`,
+  cap: (total, cap) => `narration runs ${total}s, over the ${cap}s cap (aim for 150 to 180 s)`,
+  url: (id, key, url, why) => `clip ${id}: ${key} ${url} ${why}`,
+  timing: (id, i, start, end, duration) => `clip ${id}: caption ${i + 1} runs ${start}s to ${end}s, outside 0 ≤ start < end ≤ ${duration}s + 0.1`,
+  words: (id) => `clip ${id}: caption words do not match the clip text (the captions must cover the whole narration)`,
+  captionLength: (id, i, text) => `clip ${id}: caption ${i + 1} is ${text.length} characters ("${text}"); captions must be ${CAPTION_MIN_CHARS} to ${CAPTION_MAX_CHARS}`,
+  localRef: (ref) => `local reference does not resolve: ${ref}`,
+  outsideRef: (ref) => `local reference leaves the deck folder: ${ref}`,
+  forbidden: (phrase, where) => `forbidden phrase "${phrase}" appears in ${where}`,
+  note: (id) => `slide ${id}: needs a data-note naming the source of its facts`,
+  mobileTitle: (id, title) => `slide ${id}: title "${title}" is over ${MOBILE_TITLE_CHARS} characters and needs a data-title-mobile`,
+  slideId: (n) => `slide ${n} has no id`,
+};
+
+const uncommented = (html) => html.replace(/<!--[\s\S]*?-->/g, "");
+const attr = (tag, name) => {
+  const m = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`).exec(tag);
+  return m ? (m[1] ?? m[2]) : null;
+};
+const round = (n) => Math.round(n * 100) / 100;
+const decode = (s) => s.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'");
+const textOf = (html) => decode(html.replace(/<[^>]+>/g, " ")).replace(/\s+/g, " ").trim();
+
+// Same normalization as the source check: accents folded, case and punctuation dropped.
+export const normalizeWords = (text) => text.normalize("NFKD").replace(/\p{Diacritic}/gu, "").toLowerCase().replace(/[^a-z0-9]/g, "");
+
+// `<section class="slide …">` blocks in document order: id, the opening tag, the
+// title (first <h1>/<h2>) and its opening tag.
+export function slides(html) {
+  return [...uncommented(html).matchAll(/(<section\b[^>]*\sclass="(?:[^"]*\s)?slide(?:\s[^"]*)?"[^>]*>)([\s\S]*?)<\/section>/g)].map(([, tag, body]) => {
+    const heading = /(<h[12]\b[^>]*>)([\s\S]*?)<\/h[12]>/.exec(body);
+    return { id: attr(tag, "id") ?? "", tag, body, title: heading ? textOf(heading[2]) : "", titleTag: heading?.[1] ?? "" };
+  });
+}
+
+export function playerScript(html) {
+  const tag = [...uncommented(html).matchAll(/<script\b[^>]*>/g)].map((m) => m[0]).find((t) => /\/player\/v\d+\/player\.js"/.test(t));
+  return tag ? { src: attr(tag, "src"), manifest: attr(tag, "data-manifest") || null } : null;
+}
+
+// Relative references: src, href and poster (either quote), srcset candidates and
+// CSS url(…) in style attributes and <style> blocks; everything that is not a URL
+// scheme, protocol-relative or a fragment. Query strings and fragments dropped.
+export function localRefs(html) {
+  const doc = uncommented(html);
+  const raw = [
+    ...[...doc.matchAll(/\s(?:src|href|poster)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)].map((m) => m[1] ?? m[2]),
+    ...[...doc.matchAll(/\ssrcset\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)].flatMap((m) => (m[1] ?? m[2]).split(",").map((c) => c.trim().split(/\s+/)[0])),
+    ...[...doc.matchAll(/url\(\s*(?:"([^"]*)"|'([^']*)'|([^)'"\s]+))\s*\)/gi)].map((m) => m[1] ?? m[2] ?? m[3]),
+  ];
+  const refs = raw.map((r) => decode(String(r ?? "")).trim().split("#")[0].split("?")[0]).filter(Boolean);
+  // Folder links (href="/", "./") are navigation, not files.
+  return [...new Set(refs.filter((r) => !/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(r) && !r.endsWith("/")))];
+}
+
+function phraseList(value) {
+  if (!value) return [];
+  if (typeof value === "string") return value.split(",").map((s) => s.trim()).filter(Boolean);
+  return value.map((s) => String(s).trim()).filter(Boolean);
+}
+
+// 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 = [];
+  const player = playerScript(html);
+  if (!player) errs.push(MESSAGES.noPlayer());
+  else if (player.src !== PLAYER_V1) errs.push(MESSAGES.player(player.src));
+  const all = slides(html);
+  if (!all.length) errs.push(MESSAGES.noSlides());
+  all.forEach((s, i) => {
+    const id = s.id || `${i + 1}`;
+    if (!s.id) errs.push(MESSAGES.slideId(i + 1));
+    if (!attr(s.tag, "data-note")?.trim()) errs.push(MESSAGES.note(id));
+    if (s.title.length > MOBILE_TITLE_CHARS && !attr(s.titleTag, "data-title-mobile") && !attr(s.tag, "data-title-mobile")) {
+      errs.push(MESSAGES.mobileTitle(id, s.title));
+    }
+  });
+  for (const ref of localRefs(html)) {
+    const found = exists(ref);
+    if (found === "outside") errs.push(MESSAGES.outsideRef(ref));
+    else if (!found) errs.push(MESSAGES.localRef(ref));
+  }
+  const page = textOf(uncommented(html).replace(/<(script|style)\b[\s\S]*?<\/\1>/g, " ")).toLowerCase();
+  for (const phrase of phraseList(forbid)) {
+    const p = phrase.toLowerCase();
+    if (page.includes(p) || uncommented(html).toLowerCase().includes(p)) errs.push(MESSAGES.forbidden(phrase, "index.html"));
+    if (script.toLowerCase().includes(p)) errs.push(MESSAGES.forbidden(phrase, "script.md"));
+  }
+  return errs;
+}
+
+// The manifest against the deck: order, total and cap. Clip text is checked for
+// forbidden phrases too, since that is what the audience hears.
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+const isStr = (v) => typeof v === "string" && v.trim().length > 0;
+
+// Fields every clip needs before its other rules mean anything.
+export function clipFieldErrors(clip, i) {
+  const id = isStr(clip?.id) ? clip.id : `#${i + 1}`;
+  const errs = [];
+  if (!isStr(clip?.id)) errs.push(MESSAGES.clipField(id, "needs an id"));
+  if (!(isNum(clip?.duration) && clip.duration > 0)) errs.push(MESSAGES.clipField(id, "duration must be a positive number of seconds"));
+  if (!(isNum(clip?.hold) && clip.hold >= 0)) errs.push(MESSAGES.clipField(id, "hold must be a number of seconds, 0 or more"));
+  if (!isStr(clip?.text)) errs.push(MESSAGES.clipField(id, "needs its text"));
+  for (const k of ["audio", "timeline"]) if (!isStr(clip?.[k])) errs.push(MESSAGES.clipField(id, `needs an ${k} URL`));
+  return errs;
+}
+
+export function manifestErrors(manifest, slideIds, { maxDuration = DEFAULT_MAX_DURATION, forbid = [] } = {}) {
+  const clips = Array.isArray(manifest?.clips) ? manifest.clips : [];
+  const clipIds = clips.map((c) => c?.id ?? "");
+  const errs = clips.flatMap(clipFieldErrors);
+  if (slideIds.length !== clipIds.length || slideIds.some((id, i) => id !== clipIds[i])) errs.push(MESSAGES.order(slideIds, clipIds));
+  const sum = round(clips.reduce((n, c) => n + (Number(c?.duration) || 0) + (Number(c?.hold) || 0), 0));
+  const declared = Number(manifest?.totalDuration);
+  if (!(Math.abs(sum - declared) < 0.01)) errs.push(MESSAGES.total(sum, manifest?.totalDuration));
+  if (Number.isFinite(declared) && declared > maxDuration) errs.push(MESSAGES.cap(round(declared), maxDuration));
+  for (const phrase of phraseList(forbid)) {
+    for (const c of clips) if (String(c?.text ?? "").toLowerCase().includes(phrase.toLowerCase())) errs.push(MESSAGES.forbidden(phrase, `clip ${c.id}`));
+  }
+  return errs;
+}
+
+// One clip's timeline: caption timing, coverage of the clip text, and length.
+export function timelineErrors(clip, timeline) {
+  const errs = [];
+  if (!Array.isArray(timeline?.captions) || !timeline.captions.length) return [MESSAGES.noCaptions(clip.id)];
+  const captions = timeline.captions.map((c) => (c && typeof c === "object" ? c : {}));
+  const duration = Number(clip.duration) || 0;
+  captions.forEach((c, i) => {
+    if (!(c.start >= 0 && c.end > c.start && c.end <= duration + 0.1)) errs.push(MESSAGES.timing(clip.id, i, c.start, c.end, duration));
+  });
+  const spoken = captions.flatMap((c) => (Array.isArray(c.words) ? c.words.map((w) => w?.text ?? "") : [])).join(" ");
+  if (normalizeWords(spoken) !== normalizeWords(String(clip.text ?? ""))) errs.push(MESSAGES.words(clip.id));
+  captions.forEach((c, i) => {
+    const text = String(c.text ?? "");
+    if (text.length < CAPTION_MIN_CHARS || text.length > CAPTION_MAX_CHARS) errs.push(MESSAGES.captionLength(clip.id, i, text));
+  });
+  return errs;
+}
+
+// The deck's own cap: `maxTotalSeconds` in script.md's front matter.
+export function scriptCap(script) {
+  const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(script)?.[1] ?? "";
+  const m = /^maxTotalSeconds:\s*([\d.]+)\s*$/m.exec(front);
+  return m ? Number(m[1]) : null;
+}
+
+// "<slug>" means ./decks/<slug> unless it names a folder itself.
+export function resolveDeckDir(arg, cwd = process.cwd()) {
+  if (!arg) throw new Error("usage: check <slug|deck-dir>");
+  const direct = resolve(cwd, arg);
+  if (existsSync(join(direct, "index.html"))) return direct;
+  const named = join(cwd, "decks", arg);
+  if (existsSync(join(named, "index.html"))) return named;
+  throw new Error(`no deck at ${direct} or ${named} (expected an index.html)`);
+}
+
+// A local ref resolves when it names a file inside the deck folder (after
+// following symlinks). Anything that climbs out is refused, so release never
+// uploads a file from elsewhere on the machine.
+export function deckFileResolver(deckDir) {
+  const root = realpathSync(deckDir);
+  return (ref) => {
+    let clean;
+    try {
+      clean = decodeURIComponent(ref);
+    } catch {
+      return false;
+    }
+    const path = isAbsolute(clean) ? join(root, clean) : resolve(root, clean);
+    const inside = (p) => p === root || p.startsWith(root + sep);
+    if (!inside(path)) return "outside";
+    if (!existsSync(path)) return false;
+    const real = realpathSync(path);
+    if (!inside(real)) return "outside";
+    if (relative(root, real).split(sep).some((part) => part.startsWith("."))) return "outside";
+    return lstatSync(real).isFile();
+  };
+}
+
+async function fetchCheck(fetchImpl, url, want) {
+  try {
+    const r = await fetchImpl(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!r.ok) {
+      await r.body?.cancel?.();
+      return { why: `returned HTTP ${r.status}` };
+    }
+    const type = (r.headers.get("content-type") || "").split(";")[0].trim();
+    if (!want.test(type)) {
+      await r.body?.cancel?.();
+      return { why: `is ${type || "untyped"}, expected ${want === AUDIO ? "audio/*" : "JSON"}` };
+    }
+    return { response: r };
+  } catch (e) {
+    return { why: `could not be fetched (${e.message})` };
+  }
+}
+const AUDIO = /^audio\//;
+const FETCH_TIMEOUT_MS = 30_000;
+const JSON_TYPE = /json/;
+
+// Run every rule on a deck folder. Returns { deckDir, slug, slides, totalDuration, errors }.
+export async function checkDeck(dirArg, opts = {}, { fetch: fetchImpl = globalThis.fetch, cwd } = {}) {
+  const deckDir = resolveDeckDir(dirArg, cwd);
+  const html = readFileSync(join(deckDir, "index.html"), "utf8");
+  const scriptPath = join(deckDir, "script.md");
+  const script = existsSync(scriptPath) ? readFileSync(scriptPath, "utf8") : "";
+  const forbid = phraseList(opts.forbid);
+  const flagCap = opts["max-duration"] ?? opts.maxDuration;
+  const maxDuration = Number(flagCap ?? scriptCap(script) ?? DEFAULT_MAX_DURATION);
+  if (!Number.isFinite(maxDuration) || maxDuration <= 0) {
+    throw new Error(flagCap !== undefined ? "--max-duration needs a number of seconds" : "maxTotalSeconds in script.md must be a number of seconds");
+  }
+
+  const errors = htmlErrors(html, { exists: deckFileResolver(deckDir), forbid, script });
+  const ids = slides(html).map((s) => s.id);
+  const player = playerScript(html);
+  let manifest = null;
+  if (player && !player.manifest) errors.push(MESSAGES.noManifest());
+  if (player?.manifest) {
+    const got = await fetchCheck(fetchImpl, player.manifest, JSON_TYPE);
+    if (got.why) errors.push(MESSAGES.manifestUnavailable(player.manifest, got.why));
+    else {
+      try {
+        manifest = await got.response.json();
+      } catch (e) {
+        errors.push(MESSAGES.manifestUnavailable(player.manifest, `not JSON: ${e.message}`));
+      }
+      if (manifest !== null && !(manifest && typeof manifest === "object" && Array.isArray(manifest.clips) && manifest.clips.length)) {
+        errors.push(MESSAGES.manifestUnavailable(player.manifest, "not a manifest: needs a non-empty clips array"));
+        manifest = null;
+      } else if (manifest === null && !errors.some((e) => e.startsWith(`manifest ${player.manifest}`))) {
+        errors.push(MESSAGES.manifestUnavailable(player.manifest, "not a manifest: needs a non-empty clips array"));
+      }
+    }
+  }
+  if (manifest) {
+    errors.push(...manifestErrors(manifest, ids, { maxDuration, forbid }));
+    for (const [i, clip] of manifest.clips.entries()) {
+      if (clipFieldErrors(clip, i).length) continue; // already reported
+      let audioUrl, timelineUrl;
+      try {
+        audioUrl = new URL(clip.audio, player.manifest).href;
+        timelineUrl = new URL(clip.timeline, player.manifest).href;
+      } catch {
+        errors.push(MESSAGES.clipField(clip.id, "audio and timeline must be URLs"));
+        continue;
+      }
+      const audio = await fetchCheck(fetchImpl, audioUrl, AUDIO);
+      if (audio.why) errors.push(MESSAGES.url(clip.id, "audio", audioUrl, audio.why));
+      else await audio.response.body?.cancel?.().catch(() => {});
+      const tl = await fetchCheck(fetchImpl, timelineUrl, JSON_TYPE);
+      if (tl.why) {
+        errors.push(MESSAGES.url(clip.id, "timeline", timelineUrl, tl.why));
+        continue;
+      }
+      let timeline;
+      try {
+        timeline = await tl.response.json();
+      } catch (e) {
+        errors.push(MESSAGES.url(clip.id, "timeline", timelineUrl, `is not JSON (${e.message})`));
+        continue;
+      }
+      errors.push(...timelineErrors(clip, timeline));
+    }
+  }
+  return {
+    deckDir,
+    slug: opts.slug || basename(deckDir),
+    slides: ids.length,
+    totalDuration: manifest ? Number(manifest.totalDuration) : null,
+    manifestUrl: player?.manifest ?? null,
+    passed: errors.length === 0,
+    errors,
+  };
+}
+
+export async function check(pos, opts = {}, { log = (line) => console.log(line), ...io } = {}) {
+  const result = await checkDeck(pos[0], opts, io);
+  if (!opts.json) {
+    log(`deck "${result.slug}": ${result.slides} slides${result.totalDuration != null ? `, ${result.totalDuration}s narrated` : ""}`);
+    if (result.errors.length) {
+      log(`✗ ${result.errors.length} issue(s):`);
+      for (const e of result.errors) log(`  - ${e}`);
+    } else log("✓ check passed");
+  }
+  return result;
+}