retake-demos 0.2.2 → 0.4.0

package/skill/SKILL.md

@@ -62,10 +62,53 @@ say so in one line and stop.
    names actually on screen? Anything in shot that shouldn't be (dev
    badges, leftover data, cut-off text)? Wrong story or failed step →
    `edit`, run again. More than four rounds → ask the person.
-8. When it is right: `run` with `preview=false` once (full quality), then
+8. **Before the expensive take, if it is expensive, show them the draft.**
+   `run` prints an estimate before capture. If it said this is a long take
+   (over ~2.5 minutes), do not go straight to full quality: `ask` them,
+   naming the demo and pointing at the draft in the Retake window, and say
+   what the full take will cost. Something like *"Draft is ready — 40s, 6
+   scenes, in the window. Full quality is about 7 minutes of recording.
+   Worth spending, or change something first?"*
+   - **Their taste is the thing you cannot check.** Every mechanical
+     problem is already caught by `dry` and the take's own checks. What a
+     person sees that no checker will is whether the story lands, whether
+     the payoff reads, whether it looks right for their product. Getting
+     that verdict on a cheap draft is the whole point.
+   - **Short take?** Skip the gate. Asking someone to approve a 30-second
+     recording costs them more than just recording it.
+   - **Nobody there to ask?** Never block and never guess. Leave the draft,
+     `done` with what you have and what it would cost, and let them start
+     the expensive one when they are back.
+9. When they say go: `run` with `preview=false` once (full quality), then
    `done` with one sentence. Outputs: `demo.mp4`, `stills/` (one PNG per
    scene), `proof-log.md`.
 
+## What a change costs — read this before re-recording anything
+
+The one mistake that wastes real time is reaching for a new recording when a
+re-render would do. Almost nothing needs the camera twice.
+
+| You want to change | Do this | Cost |
+|---|---|---|
+| size, shape, format (landscape → square → vertical) | `render` with another preset | seconds |
+| a caption's words, the speed, a zoom, cards, music | edit the manifest, `render` | seconds |
+| **where** a caption or still sits in time | `nudge: <ms>` on the scene, then `render` | seconds |
+| which frame is the poster | click a frame in the window, or `--scene` | seconds |
+| the ENDING of a demo | `run --from <scene>` | the tail only |
+| one beat, iterating | `run --until <scene>` | the head only |
+| the steps themselves — what the demo DOES | full `run` | the whole thing |
+
+Only the last row needs the camera for the whole demo. If you are about to
+re-record and your reason is not in that last row, you are paying for
+something you already have.
+
+`nudge` and `--from` are the two most recently added and the two most often
+missed. `nudge: -1500` moves a scene's marker 1.5s earlier in the finished
+video — caption, still and thumbnail follow it. `--from <scene>` runs the
+earlier steps at full speed off camera so the app reaches the right state,
+then starts recording there; a seven-minute demo whose last third changed
+costs ninety seconds instead of seven minutes.
+
 ## Style — how the person wants their videos to look
 
 Do not ask about knobs before the first take — nobody has opinions about
@@ -77,23 +120,244 @@ zooms or caption tone until they have seen one. Two moves instead:
    → landscape, still camera, a hold on the payoff. Skip the question if
    the project's style note already answers it.
 2. **The first take is the menu.** Record the calm default as a preview,
-   let them watch it, then offer two or three concrete alternatives as
-   sentences ("Square for a post? Captions off? Zoom on the result?").
-   Whatever they choose, save it with `style` so it never comes up again.
+   let them watch it, then one line — no list, no questions before it:
+   "Want it different? A zoom on the result, cursor off, square for a post —
+   say so and I'll re-render." Whatever they choose, save it with `style`
+   so it never comes up again in this project. Never ask about zoom or
+   cursor before they have seen a take.
+
+**Which kind of take is this? Get it from the destination, never from the
+subject.** Write it into the manifest as `mode:`, and default to `demo`.
+
+- **`mode: demo`** — it proves how the thing works. A client walkthrough IS
+  a demo. So is a PR review, a bug repro, a docs clip, a lesson, "show the
+  team", "send it to the customer", "so they can see the flow". Nothing in
+  the frame but the product doing the thing. No title card, no music, no
+  callouts. Most takes are this.
+- **`mode: launch`** — it presents the product to strangers, in public: a
+  launch, a post, an ad, a landing page, Product Hunt, "for X", a trailer.
+  Only then are a title card, music, emphasis and a branded ending on the
+  table, and each still has to earn its second.
+
+The tell is the audience, not the polish: *someone who already wants to
+know how it works* → demo. *Someone who has to be given a reason to care*
+→ launch. If the person has not said, ask the one destination question and
+take `demo` if they shrug. **Never upgrade a demo to a launch on your own**
+— `validate` warns when a demo carries launch furniture, and that warning
+means you guessed.
+
+A launch cut ends with THEIR product, never with Retake. Retake branding
+belongs only in a video that presents Retake.
+
+**Two kinds of take, one file — and the destination decides.** The default
+is the plain cut: still camera, cursor, captions, nothing else. That is
+correct for PRs, clients, docs, lessons — most takes. When the person's
+answer to "where is this going?" is a launch, a post, or anything public
+and promotional, offer the produced cut in ONE sentence: "Want the launch
+treatment — title card, a callout on the payoff, the waits compressed,
+the captions read aloud, square or vertical for the feed, and music if
+you give me a track?" Never apply it unasked, and
+never ask about its parts one by one.
+
+The produced cut, when they say yes (all render-time except typing):
+- `intro: { title, subtitle }` and usually `outro:` (the product name or URL)
+- one `callout` on the payoff moment, not more
+- the destination's shape: `post-square` or `post-vertical`
+- `compressIdle: true` — the app's waits shown as ~1.5s each; the person's
+  pacing `wait`s are never touched
+- **voiceover: leave it off.** It needs `script:` (one continuous script,
+  synthesized as one performance) AND `approved: true`, which only a person
+  who has HEARD it can set. Reading the captions line by line resets prosody
+  at every scene — that is a defect in the shape, not the voice. A silent cut
+  beats an unapproved synthetic voice. Offer narration only if they ask for
+  it, and let them listen before it ships.
+- `typing: brisk` — fast keys, the pauses carry the meaning (re-record)
+- `music: <file>` only if they hand you a file or point at one on disk.
+  Retake bundles no tracks (licensing) — say: "give me an mp3 you have the
+  rights to; CC0 tracks live at freepd.com or pixabay.com/music". Skip
+  music without complaint if they shrug.
 
 Anything they would tell a videographer maps to a knob, in plain English:
 
+- "add a title card" / "give it a cover" → `intro: { title, subtitle }`
+  (and `outro:`) — render-time, and it also writes two poster candidates:
+  cover.png (the card) and cover-titled.png (a real frame with the title on
+  it, which is what stops a scroll)
+- "the thumbnail is wrong" → they pick the poster themselves in the window
+  (any frame, any still, a cover, or their own image). Point them at it
+  rather than re-rendering; `outputs.thumbnail: { scene }` only sets the
+  starting guess.
+- "point at it" / "highlight the button" → a `callout` step with a label —
+  at most one per scene, and only where the caption alone is not enough
+
 - "no zooms" / "keep the camera still" → `camera: static` on scenes
 - "hide the cursor" → `cursor: false`
 - "no captions" / "shorter captions" → captions off, or rewrite them
 - "slower" / "hold the ending" → `pauseAfter`, scene `holdMs`, end waits
-- "square" / "vertical" / "for X" → preset `post-square` / `post-vertical`
+- "square" / "vertical" / "for X" → preset `post-square` / `post-vertical`,
+  and this is a RE-RENDER of the take you already have, never a re-record:
+  `retake render outputs/<name> --preset post-square`. Size is not recorded.
+- **Never set `viewport`.** The preset owns the size — one preset, one
+  output shape, every time. A manifest that sets its own viewport comes out
+  a different shape from every other demo of the same app, and players
+  letterbox it. `validate` warns.
 
-The default is already calm: still camera, cursor shown, plain captions.
+The default is calm and real: still camera (`camera: static` is the
+manifest default — write `auto` only when asked), cursor shown, plain
+captions.
 The first time the person expresses taste, save it with the `style` tool
 (or write `demos/style.md`) — every later draft in the project reads it, so
 they never have to say it twice. Their stated taste always beats defaults.
 
+## The person may never have seen Retake — walk them
+
+Assume a first-timer: your agent installed Retake for them and they know
+nothing about a window, a workspace or a `.env`. So, every time:
+
+- **Say where to look, with the link.** At the start of a demo: "I'll record
+  this with Retake. You can watch at http://localhost:4310 (run `retake ui`
+  if it isn't open) — the video, stills and a step-by-step log land there."
+  Never assume the window is open or that they know the address.
+- **One thing at a time, in their words.** When you need them to act (type a
+  demo account, log in by hand, start their app), say exactly what to do,
+  where, and how you'll know it's done: "…press Save to .env, then tell me
+  it's done." Then wait for them to say so. Do not go quiet — a tool that
+  waits on them is your cue to speak, not to sit.
+- **Close the loop.** When the take is done: the one-line result, where the
+  file is, and the one thing they can change without a re-record (speed,
+  captions, format). Offer, don't pile on.
+
+## Logins — most real demos start behind one
+
+You will never see a password, and you never need to. The whole method:
+
+1. **Notice it early.** `read_project` reports sign-in fields; `scout` shows a
+   password input; or the person says so. Do not draft a manifest that
+   pretends the app is open.
+2. **Call `secrets` with the NAMES** you will use — `APP_USER`, `APP_PASSWORD`,
+   and `APP_TOTP_SECRET` if the site asks for an authenticator code — and one
+   sentence of why. It returns immediately with the words to say: a form is
+   open in the window at a link, or a one-line terminal command. **Relay
+   those words in full, link included**, then stop and wait for "done". Call
+   `secrets` again; it answers "set" and you carry on. The values went
+   straight into the workspace `.env` — you never saw them.
+3. **Write the sign-in under `auth.setup`**, referencing `${APP_USER}` and
+   `${APP_PASSWORD}` with `secret: true`, and set `auth.storageState` to
+   `.auth/<name>.json`. The login runs before the camera and is trimmed off;
+   the session is saved and later takes skip the login entirely. A failed
+   sign-in is never saved as a session, so a wrong password stops the take
+   instead of recording a logged-out one.
+4. **Authenticator codes:** `text: "${TOTP:APP_TOTP_SECRET}"` — Retake
+   computes the six-digit code at the moment it fills the field.
+5. **SMS codes, SSO, captchas, anything only a human can do:** do not try.
+   Tell the person: "run `retake signin demos/<name>.yaml` and log in once by
+   hand — Retake keeps the session." Then run as normal. The manifest still
+   needs `auth.storageState`; `auth.setup` can be empty.
+6. **Firebase-style apps** keep the session in IndexedDB, which a saved
+   session cannot restore: put the login under plain `setup` instead, so it
+   runs every take (still before the camera, still trimmed).
+
+Never ask for a credential in chat. Never write a literal one into a
+manifest. Never invent one. Tell the person to use a demo account — the
+output is a video they may publish.
+
+## Hard-won rules from real sessions
+
+- **Scout again after ANY server restart** — not just the first time. A dev
+  server that restarts can come back serving a different build or mode on
+  the same port, and the take fails 20 seconds in with a selector timeout
+  that looks like your manifest's fault. Five takes were lost to this once.
+  If the run aborts saying "the app at <url> is not what this manifest
+  expects", believe it: look at not-the-app.png, fix the server, re-run.
+- **A failed step leaves failed-step.png next to the take** — a full-page
+  picture of the exact moment. Read it BEFORE re-running or editing
+  anything; it turns a five-round guess loop into one round.
+- **`waitFor` can match a STALE element.** After an action, the previous
+  capture's Undo button (or any leftover) may still satisfy your selector,
+  and the click lands on the wrong thing. Wait for something unique to the
+  NEW state (a count, a heading, a row with the new text), never for a
+  control that also existed before the action.
+- **What `compressIdle` compresses:** the app's own delays (`waitFor`,
+  `navigate`) and long typing. It NEVER touches your `wait` steps — those
+  are your pacing. Do not re-render hoping a `wait` gets shorter; shorten
+  the wait.
+- **Streaming content:** `waitFor` on a container resolves when the shell
+  exists, not when the text has streamed in. Wait on the signal the app
+  itself uses — a button flipping from busy to ready
+  (`button:has-text("Send")`), a count, a class change.
+
+## Waits that do not lie
+
+A bare `waitFor` resolves the instant the element exists. Three times that
+is the wrong moment, and each has cost a take:
+
+- the element is the **previous** action's success banner, still on screen →
+  `{ action: waitFor, selector: ".landed", gone: true }`
+- the element is an empty shell that **streams** its text in →
+  `minChars: 40`
+- the element is there but still **changing** → `stableMs: 500`
+
+Prefer these to a flat `wait`. A timer that happens to work today is the
+thing that breaks when the app gets slower.
+
+## Rules the manifest enforces, so you do not have to remember them
+
+`validate` and `dry` refuse these outright rather than letting a take discover
+them:
+
+- **Scene labels are unique.** `thumbnail`, `--until`, the stills and the proof
+  log all address a scene by its label.
+- **The action has to fit the element.** `type` on a `<select>`, `select` on a
+  `<div>`, `upload` on something that is not a file input, `click` on a button
+  that is disabled at that moment — `dry` names the fix.
+- **A navigate that changes only the `#fragment` is flagged.** It does not
+  reload the document, so an SPA keeps its state and a stub armed just before
+  it never fires. Add a throwaway query param, or click the app's own link.
+- **A stub that never answers a request fails `check`.** Armed but unmatched
+  means that screen showed the app's real data.
+- **Seeds may not leave anything running** — no `&`, `nohup`, `pm2`. Starting
+  the app is `start_app`'s job, which the person authorises.
+
+## Cheap iteration — a demo should not cost five takes
+
+A take is real time (capture is ~2.3× the finished video) and the field
+average is three to five takes per demo. Most of that is avoidable:
+
+1. **Draft everything.** `--preset draft` has the same layout and timing at
+   a quarter of the pixels. Judge the story there; switch to a post preset
+   once, at the end.
+2. **`--until <scene>` for the head, `--from <scene>` for the tail.** These
+   are the two halves of the same idea and `--from` is the one people miss:
+   when the ending changed, everything before it still runs (the app has to
+   reach that state) but at full speed and off camera. Re-recording a 60s
+   demo to change its last 8 seconds is paying for 50 seconds you already
+   have.
+3. **Get a person's eyes on a cheap draft before buying an expensive take.**
+   A draft costs a quarter of the pixels and answers the only question a
+   checker cannot: is this the right video? Spending seven minutes of
+   capture to find out the story was wrong is the most expensive mistake
+   available in this tool.
+4. **A caption in the wrong place is a nudge, not a take.** `nudge: -1500` on
+   a scene moves its marker 1.5s earlier in the finished video; the caption,
+   the still and the thumbnail all follow. Re-render and look — it is seconds.
+5. **Never re-record for a size or a format.** `render outputs/<name>
+   --preset post-vertical` re-frames the take you have. Captions, camera,
+   speed, cards and posters are all render-time too.
+6. **`dry` before every `run`** — including after the app restarts. It is
+   ~10s and it catches the wrong-build-on-the-port failure that otherwise
+   costs a take and a confusing video.
+7. **Fix everything `dry` and the proof log report in ONE pass.** Reading
+   the whole failure list before editing turns three rounds into one.
+
+## Judging the cut
+
+`check: pass` proves the file is sound, not that the demo is good. Before
+`done`, look: `retake contact outputs/<name>` writes one timestamped grid
+of the whole video (launch cuts get it automatically). Read it for the
+things checks cannot see — a caption that is true when its scene starts and
+false by the end, a payoff nobody can find, four seconds where nothing
+changes. `look` at the payoff scene is the other half.
+
 ## When a take fails
 
 The camera stops at the first failed step, so a failed take is short and
@@ -136,8 +400,8 @@ up to the end of that scene.
 
 - Real interactions read as real: type actual text, scroll to what you use,
   hold on the result. No zoom tricks unless asked.
-- Secrets never go in a manifest. `${ENV_VAR}` + `secret: true`, and tell
-  the person which variable to set.
+- Secrets never go in a manifest and never into chat: the `secrets` tool
+  gets them into `.env` by name; you reference `${NAME}` with `secret: true`.
 - Never invent selectors — only what scout/read_project returned.
 - If the backend is down, prefer a `stub:` block over giving up.
 - Starting the person's app needs their explicit say-so, every time.

package/demos/example.yaml

@@ -1,65 +0,0 @@
-# A template. Copy it, point it at your app, replace the selectors.
-#
-#   retake validate demos/example.yaml     schema + warnings, instant
-#   retake dry demos/example.yaml          every selector and wait, no camera
-#   retake run demos/example.yaml          record + render → outputs/example/
-#
-# Or don't write it at all: once `retake install` has run, ask your coding
-# agent for "a demo of my app at localhost:3000 showing …" and it drafts,
-# dry-runs, records and checks this file for you. `retake ui` is the window
-# to watch it in.
-
-name: example
-title: "Example — the shape of a demo"
-url: http://localhost:3000
-
-preset: post-landscape        # 1080p @ 30fps · see `retake presets`
-viewport: { width: 1440, height: 1080 }   # match your app's natural shape
-scale: 1.8                    # page drawn at 1.8× so text stays crisp at 1080p
-reducedMotion: true           # calms infinite spinners and entrance animations
-camera: auto                  # each scene eases toward the last thing touched
-
-# Put the app in a known state before the camera rolls. Pick what fits:
-#   - { kind: file, path: /tmp/app/state.json, from: seeds/empty.json }
-#   - { kind: evaluate, script: "localStorage.clear()" }
-#   - { kind: command, run: "curl -X POST http://localhost:3000/api/test/reset" }
-seed: []
-
-# Runs before recording starts and is trimmed off the front of the video.
-# Sign-ins belong here — see the "Signing in" section of the README.
-setup: []
-
-steps:
-  - action: scene
-    label: start
-    caption: "The problem, before anything happens."
-    camera: static
-  - action: wait
-    ms: 1800
-
-  - action: click
-    selector: "button:has-text('Get started')"
-    pauseAfter: 900
-
-  - action: type
-    selector: "input[name=title]"
-    text: "A realistic thing a person would type"
-    delay: 40
-    pauseAfter: 600
-
-  - action: click
-    selector: "button[type=submit]"
-  - action: waitFor              # wait for the RESULT, never a fixed sleep
-    selector: ".result"
-    timeout: 30000
-
-  - action: scene
-    label: result
-    caption: "And the result, which is the whole point."
-  - action: wait
-    ms: 2600
-
-outputs:
-  mp4: true
-  gif: false                   # opt-in; gifski is used when installed
-  thumbnail: { scene: result }