@hypersocial/decks-cli 0.2.2 → 0.3.1

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
@@ -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.2",
+  "version": "0.3.1",
   "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
@@ -69,6 +95,7 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | 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` |
+| What one person watched | `hyperdecks engagement "<name>" --deck <slug> --json` | `recipient_engagement` |
 
 ### 1. Ground it in the user's own material
 
@@ -81,6 +108,7 @@ 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
@@ -126,6 +154,7 @@ The deck contract (`check` enforces each line):
 - 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
@@ -144,6 +173,45 @@ 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
@@ -256,6 +324,7 @@ 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.
@@ -264,7 +333,7 @@ phone screenshots, the same `fix` bar.
 - 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
@@ -305,6 +374,7 @@ 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
@@ -340,6 +410,12 @@ an internal codename). Messages and what to do:
 | `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` |
 
@@ -396,6 +472,42 @@ 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.
 
+### 9. Follow up with a recipient
+
+When the user wants to follow up with someone, read what that person watched:
+
+```bash
+hyperdecks engagement "<name>" --deck <slug> --json   # MCP: recipient_engagement
+```
+
+Then draft the email:
+
+1. Lead with the slide they spent most time on (`summary.mostTime`) or
+   replayed (`replayedSlides`), and answer what that slide raises. Each
+   slide's `title` says what it is about.
+2. If they dropped off (`droppedOffOn`), offer the rest briefly, or a
+   2-minute call, rather than asking them to rewatch.
+3. If they never opened it (`summary.visits` is 0), write a short nudge
+   instead.
+
+Use what you know beyond the data: the email thread, who the person is, what
+was promised, and the user's voice. Never tell the recipient they were
+tracked: no "I saw you watched slide 7 three times", no percentages. The
+signal decides what to talk about; it is never something to quote. Put the
+draft in the user's mail tool (or show the text) and never send it without the
+user's go-ahead. `null` means a field was not recorded for that visit (older
+links), not zero.
+
+### 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`.