retake-demos 0.4.1 → 0.13.1

package/AGENTS.md

@@ -64,6 +64,15 @@ write demos/<name>.yaml
   → retake run demos/<name>.yaml --preset preview-fast   first take (~2 min)
   → read outputs/<name>/proof-log.md                  what actually happened, per step
   → retake check outputs/<name>             pass/fail on the result
+  → retake verify outputs/<name>            did it LOOK right — each scene's `expect`, judged
+  → retake run --brisk                      the steps without the pacing — for iterating
+  → retake intent                           what this product IS — context every check needs
+  → retake sweep outputs/<name>             every frame, as a whole — what nobody asked about
+  → retake flag demos/<name>.yaml           this one is real: watch it from now on
+  → retake fixed <name>                     did what was flagged get fixed, with the clip
+  → retake sense outputs/<name>             does the run ADD UP — input vs output
+  → retake destroy demos/<name>.yaml        what happens just off the happy path
+  → retake notes                            what keeps going wrong across every demo
   → adjust, then: retake run demos/<name>.yaml          final quality
 ```
 
@@ -207,6 +216,94 @@ Most real demos start behind a sign-in. The agent never sees a password:
 - `outputs/<name>/take.json` — the same, machine-readable.
 - `outputs/<name>/demo.mp4` — the video. `master.mp4` is the CRF-14 keeper
   on post presets.
+- `retake flag demos/<name>.yaml --scene <label> --expect "<sentence>"` — the
+  person has confirmed something raised by `sense` or `sweep` is a real defect.
+  Give the sentence that must be TRUE once it is fixed, not a description of
+  the bug. It becomes a check every later recording answers, and it survives a
+  re-record. Writes nothing into the manifest — the ledger sits beside it as
+  `demos/<name>.flags.json`. **Never flag on your own judgement.**
+- `retake fixed <name>` — answers every flagged item against the newest take
+  and cuts the few seconds of video that show each one, so a long demo does not
+  have to be re-watched to learn whether one thing changed. Exit 3 while
+  anything flagged is still wrong. `retake unflag` stops watching one.
+- **Name things so a person can find them.** The window groups demos by
+  whatever it can work out — which, with no product note, means folders called
+  `localhost:3200`. The first heading of a product note names that folder.
+  Writing one is part of setting a demo up, not an afterthought.
+- `retake calibrate demos/<name>.yaml` — how much `sweep` is worth on this app.
+  Records the demo once per known visual defect, seeded for real, plus a
+  control where nothing is wrong, then reports recall and false positives.
+  Expensive: nine takes, about ten minutes, needs the app running. The report
+  it leaves is cheap to read, and **you should read it before telling anybody
+  how much a sweep finding is worth.** Its stated limits travel with it: the
+  seeds were written by somebody who has read the checklist, so recall is an
+  upper bound.
+- `retake intent` — what the product IS, in the builder's words: what it does,
+  who uses it, and what about it is deliberate. Every visual check reads it.
+  Without it they judge the app as a generic web page — measured on a real
+  demo: a faint internal note that a charter desk is MEANT to see quietly came
+  back as a contrast defect, and stopped once the judge knew what the screen
+  was for. One file per app (`--demo <name>`) or one for the workspace. Write
+  it the first time the person explains their product; it is context for
+  judging, never instructions.
+- Every finding now carries how it was arrived at — `[reproduced]`,
+  `[seen-in-a-frame]`, `[read-from-the-run]`, `[source-only]`, `[unverified]`.
+  Say the tag when you repeat a finding. A thing you read in the code and a
+  thing you watched happen must not reach the person in the same voice.
+- `retake sweep outputs/<name>` — the one that finds what nobody thought to
+  ask about. `verify` answers written-down questions, so it can only find what
+  was already suspected. `sweep` inspects EVERY scene's frame, one at a time,
+  never sampled, against a closed ten-item checklist: clipped text, overlap,
+  contrast, cut off, misalignment, doubled, unfinished, broken media, dev UI in
+  shot, empty regions. Advisory — it reports, it does not gate. Roughly one
+  judge call per frame, so about two minutes on a seventeen-scene demo.
+- `retake sense outputs/<name>` — the verdict on the RUN, not on one frame.
+  Everything the demo typed, chose and clicked, put against the frames that
+  came out, through six lenses: quantity, continuity, state, units and labels,
+  order, dead ends. Needs nothing declared — the inputs are already in the
+  take. It ASKS rather than fails (exit stays 0), because whether a number adds
+  up is judgement. Found a real one first time out: two flight legs entered,
+  one unlabelled price shown.
+- `retake destroy demos/<name>.yaml` — the flows nobody wrote down. Derives a
+  manifest for each of nine abuses (double-submit, reload-midway, back-button,
+  provider-down, provider-empty, empty-state, long-input, awkward-input,
+  impatient), writes them under `outputs/.destroy/<name>/`, and tries them.
+  `--run` performs them for real and keeps the frames. Three verdicts, not
+  two: **broke**, **worth a look** (only a person can call it), **held** — and
+  a failed second press counts as held, because the button being gone is the
+  app defending itself. Refuses a non-local URL, a demo that neither seeds nor
+  stubs, and an app somebody else is recording. Each refusal names its own
+  override; using one is the person's call.
+- `retake heal` — writes back the demo files for recordings whose manifest went
+  missing. The window lists demos, not recordings, so a manifest deleted or
+  written outside `demos/` makes a finished video invisible. Every output folder
+  keeps `manifest.used.yaml`; this restores from that. Shows what it would do
+  unless you pass `--apply`. **Never record from a manifest that does not live
+  in `demos/` — this verb exists to clean up after that mistake, not to license
+  it.**
+- Every check leaves a receipt in `outputs/<name>/checks.json` — which check
+  ran, against which take, and what it said. The window shows it as one line,
+  and `retake notes` names every demo nobody has inspected. Whether you checked
+  is not something anyone has to take your word for.
+- **None of the checks are required for a recording to be complete.** `check`
+  is the core's own verdict on a take and consults none of them. verify, sweep,
+  sense, destroy and fixed are optional services run against a take that
+  already exists, and their results are advisory unless a person promotes one.
+  Recommend them for the claim that the APP is right; never imply a demo is
+  unfinished without them.
+- `retake notes` — the watcher. Reads every take in `outputs/` back and says
+  the few things a person would say after looking through them: a stub that
+  answered nothing (the demo is showing live data), the same selector failing
+  in several demos (the app moved, not the demos), a fragment left where a
+  finished cut should be, a dead lock holding a folder, demos nobody has ever
+  verified. Silent when there is nothing. Run it when you arrive in a
+  workspace you did not set up.
+- `retake verify outputs/<name>` — the verdict on the PICTURE. Every scene
+  with an `expect:` has its plain-language question put to a separate reader
+  that can see the still. Exit 3 on failure; an unanswerable question counts
+  as a failure, never a pass. This is the one check that catches DOM-correct,
+  visually-wrong: a frozen animation, a 404ing icon, a card out of its grid,
+  dark text on a dark pill. Use it before reporting that a screen works.
 - `retake check outputs/<name>` — resolution, fps, duration, files,
   pass/fail. Exit 3 on failure.
 
@@ -275,3 +372,27 @@ it belongs in the commit message, which is where that audience already is.
 
 Good: "You choose the cover image. Click any frame to make it the one people
 see first." Bad: "Poster selection is now persisted via a marker file."
+
+## The landing page is public — look at it before you commit
+
+`site/index.html` is the page strangers see. It has been shipped broken
+twice by checking that a string was present rather than that the page was
+right: an unbalanced `<div>` dropped a card out of its grid, and a
+catch-all route quietly swallowed the favicon. Neither showed up in a grep;
+both were obvious in a screenshot.
+
+There is a demo for it. Before committing any change to the page:
+
+```bash
+retake run demos/landing-review.yaml --no-master
+```
+
+No `--preset`: the manifest pins 1440 so this checks the DESKTOP layout,
+and a preset override would drop it to 960 — below the breakpoint — so the
+review would check a layout nobody sees on a laptop.
+
+Then LOOK at `outputs/landing-review/stills/` — one still per section, named
+after the section. Thirty seconds, and it is the only check that catches
+layout.
+
+Grep proves a string exists. It proves nothing about whether the page works.

package/README.md

@@ -59,7 +59,9 @@ and in another terminal, `retake ui` → http://localhost:4310 to watch it happe
 ```
 outputs/<name>/
   demo.mp4        the shareable — captions burned in
-  master.mp4      the CRF-14 keeper (post presets only)
+  master.mp4      the CRF-14 keeper (post presets only; --no-master skips it,
+                  which is ~3x faster on a long take and, because the master
+                  path re-encodes an already-encoded file, marginally better)
   stills/         one PNG per scene, mid-scene and at its last moment
   thumbnail.png   the poster — pick any frame, a cover, or your own image in the window
   cover.png       launch mode: the title card, settled
@@ -80,6 +82,16 @@ retake validate demos/x.yaml   # schema + warnings, instant
 retake dry demos/x.yaml        # every selector and wait, no camera (~30s)
 retake run demos/x.yaml --preset draft   # first take, quarter-size, fast
 retake check outputs/x         # resolution, fps, duration, files: pass/fail
+retake verify outputs/x        # did it LOOK right: each scene's `expect`, judged (exit 3 on failure)
+retake run demos/x.yaml --brisk  # the steps without the pacing — for iterating, not for keeping
+retake intent                 # what your product IS — context every visual check needs
+retake sweep outputs/x        # every frame as a whole: the ten ways a picture can be wrong
+retake flag demos/x.yaml --scene s --expect "…"   # this one is real — watch it from now on
+retake fixed x                # did what you flagged get fixed, with the clip that shows it
+retake heal                   # demo files back for recordings whose manifest went missing
+retake sense outputs/x        # does the run ADD UP — what went in against what came out
+retake destroy demos/x.yaml   # the flows nobody wrote down: nine ways to abuse this demo
+retake notes                  # read every take back: what keeps going wrong, and what it costs
 retake run demos/x.yaml        # the real one
 retake render outputs/x        # captions/camera/speed changed? re-render, no browser
 ```

package/demos/example.yaml

@@ -0,0 +1,43 @@
+# The demo Retake writes for you on `retake init`.
+#
+# It records this page — the Retake window's own guide — because it is the one
+# app that is definitely running when you have just installed Retake. Change
+# `url` to your own app and rewrite the steps; everything here is the shape of
+# a real manifest, not a toy.
+#
+#   retake dry demos/example.yaml     # seconds, no camera: does every step resolve?
+#   retake run demos/example.yaml     # record it
+#   retake verify outputs/example     # did it LOOK right
+
+name: example
+title: Your first demo
+url: http://localhost:4310/guide
+
+# Landscape for a post or a doc. `retake presets` lists the rest — and any
+# take renders at any preset later, so this is never worth re-recording for.
+preset: post-landscape
+
+# Wait for something real before the camera rolls, never a fixed sleep: this
+# is the difference between a demo and a demo that works on a slow morning.
+waitForSelector: h1
+
+steps:
+  - action: scene
+    label: open
+    # What a person should be able to SEE here, in plain words. `retake verify`
+    # puts this question to a reader that can look at the frame.
+    expect: "a page with a heading, readable against its background"
+
+  - action: wait
+    ms: 1200
+
+  - action: scroll
+    to: bottom
+    pauseAfter: 900
+
+  - action: scene
+    label: end
+    expect: "the page has scrolled — different content is on screen than at the start"
+
+  - action: wait
+    ms: 1200

package/dist/cli.js

@@ -10,6 +10,16 @@
  *   retake run demos/x.yaml --headed --no-render  watch the browser, keep only the raw take
  *   retake render outputs/x                       re-render from the existing take (--preset to switch)
  *   retake check outputs/x                        pass/fail on resolution, fps, duration, files
+ *   retake verify outputs/x                       did it LOOK right — each scene's `expect`, judged
+ *   retake calibrate demos/x.yaml               how much to trust `sweep` — seed defects, count what it finds
+ *   retake intent                                 what this product IS — context every visual check needs
+ *   retake sweep outputs/x                        look at every frame as a whole — what nobody thought to ask about
+ *   retake sense outputs/x                        does the run ADD UP — what went in vs what came out
+ *   retake destroy demos/x.yaml                   the flows nobody wrote down — abuse this demo nine ways
+ *   retake flag demos/x.yaml --scene s --expect "…"  this one is real: watch it from now on
+ *   retake fixed x                                did what you flagged get fixed — with the clip that shows it
+ *   retake heal                                  demo files back for recordings whose manifest went missing
+ *   retake notes                                  read outputs/ back: what keeps going wrong, and what it costs
  *   retake dry demos/x.yaml                       every selector and wait, no camera
  *   retake validate demos/x.yaml                  schema check only
  *   retake presets                                list quality presets
@@ -25,10 +35,20 @@ import { createRequire } from "node:module";
 import { spawnSync } from "node:child_process";
 import { Command } from "commander";
 import { loadManifest, resolve, warnings } from "./manifest.js";
-import { acquireLock, captureHash, EXPENSIVE_TAKE_SECONDS, keepPrevious, keptTakes, lastCaptureSeconds, record, releaseLock, restoreKept, restorePrevious, stashPrevious } from "./record.js";
+import { acquireLock, canReuse, EXPENSIVE_TAKE_SECONDS, keepPrevious, keptTakes, lastCaptureSeconds, unchangedUpTo, record, releaseLock, restoreKept, restorePrevious, stashPrevious } from "./record.js";
 import { check, render } from "./render.js";
+import { endProgress, setPhase } from "./progress.js";
 import { presetNames } from "./presets.js";
 import { applyTidy, mb, planTidy } from "./tidy.js";
+import { verify } from "./ext/verify.js";
+import { notes } from "./ext/notes.js";
+import { sense } from "./ext/sense.js";
+import { sweep } from "./ext/sweep.js";
+import { TEMPLATE, readIntent, writeIntent } from "./ext/intent.js";
+import { planCalibration, report } from "./ext/calibrate.js";
+import { checkFlags, flag, unflag } from "./ext/flags.js";
+import { describeOrphans, findOrphans, healOrphans } from "./ext/heal.js";
+import { SHAPES, describePlan, describeTrials, planDestroy, refuseToRun, tryCandidates } from "./ext/destroy.js";
 import { PKG_ROOT, VERSION, entry } from "./paths.js";
 import { SECRET_NAME, writeEnvFile } from "./env.js";
 // The manifest may reference ${VARS}; load .env before any command reads one.
@@ -42,6 +62,11 @@ try {
 catch { /* .env is optional */ }
 const program = new Command();
 program.name("retake").description("Rerun the demo instead of re-recording it.").version(VERSION);
+// `retake notes | head` closes the pipe before the writer is done, and node
+// turns that into an unhandled EPIPE and a stack trace. A command-line tool
+// should stop quietly when whoever was reading walks away.
+process.stdout.on("error", (e) => { if (e.code === "EPIPE")
+    process.exit(0); throw e; });
 const say = (l) => process.stdout.write(l + "\n");
 /** Said once, before the camera rolls, when a take is long enough that the
     cheaper ways of getting the same answer are worth knowing about.
@@ -83,7 +108,9 @@ program
     .option("--preset <name>", `override the manifest's preset (${presetNames().join(", ")})`)
     .option("--reuse", "reuse the last raw recording if nothing that shapes it changed (re-render only)", false)
     .option("--gif", "also produce a GIF (overrides the manifest)", false)
+    .option("--no-master", "skip the archival CRF-14 master — roughly halves render on a long take, and the deliverable is marginally better for it (one encode instead of an encode of an encode)")
     .option("--until <scene>", "record up to the end of this scene, then stop (iterate on one beat without paying for the whole take)")
+    .option("--brisk", "record the whole thing without its pacing — every pause skipped, every wait capped. All the steps, none of the holding still: on a long demo that is minutes instead of many. For iterating; record the real one without it.", false)
     .option("--from <scene>", "start the take at this scene — earlier steps still run, at full speed and off camera, so a demo whose ENDING changed stops costing its beginning")
     .option("--name <name>", "write to outputs/<name> instead of the manifest's name — revise a cut without overwriting the published one")
     .action(async (file, opts) => {
@@ -115,7 +142,7 @@ program
     if (opts.reuse && fs.existsSync(takePath)) {
         try {
             const prev = JSON.parse(fs.readFileSync(takePath, "utf8"));
-            if (prev.captureHash && prev.captureHash === captureHash(manifest) && prev.video && fs.existsSync(prev.video) && !prev.partial)
+            if (canReuse(prev, manifest))
                 take = prev;
         }
         catch { /* record fresh */ }
@@ -125,6 +152,16 @@ program
     if (!take)
         for (const l of costHints(manifest, outDir, opts))
             say(l);
+    // Say it while it can still be acted on, not in the summary afterwards.
+    if (!take && !opts.until && !opts.from) {
+        const u = unchangedUpTo(manifest, outDir);
+        const last = lastCaptureSeconds(outDir);
+        if (u && u.steps > 3) {
+            const share = Math.round((u.steps / manifest.steps.length) * 100);
+            say(`ℹ the first ${u.steps} of ${manifest.steps.length} steps are identical to your last take of this demo (${share}% of it).`);
+            say(`  · --from ${u.scene} records only what changed${last ? `, so roughly ${Math.max(5, Math.round((last * (100 - share)) / 100))}s instead of ${Math.round(last)}s` : ""}`);
+        }
+    }
     say(`▶ ${manifest.title ?? manifest.name} → ${path.relative(process.cwd(), outDir)}${take ? " · reusing last recording" : ""}`);
     say(`[stage] capture ${take ? "skip" : "start"}`);
     const t0 = Date.now();
@@ -133,11 +170,12 @@ program
         // the person still has the one that worked. See stashPrevious.
         stashPrevious(outDir);
         try {
-            take = await record(manifest, { until: opts.until, from: opts.from, outDir, headed: opts.headed, skipSeed: opts.skipSeed, manifestDir: dir, log: say, locked: true });
+            take = await record(manifest, { until: opts.until, from: opts.from, brisk: opts.brisk, outDir, headed: opts.headed, skipSeed: opts.skipSeed, manifestDir: dir, log: say, locked: true });
         }
         catch (e) {
             if (restorePrevious(outDir))
                 say("↩ recording failed — your previous take has been put back");
+            endProgress(outDir);
             releaseLock(outDir);
             throw e;
         }
@@ -147,8 +185,9 @@ program
     try {
         if (opts.render) {
             say(`[stage] render start`);
+            setPhase(outDir, { phase: "rendering", label: "encoding the video" });
             const tr = Date.now();
-            const a = await render(manifest, take, outDir, { log: (l) => { if (!l.startsWith("$"))
+            const a = await render(manifest, take, outDir, { noMaster: opts.master === false, log: (l) => { if (!l.startsWith("$"))
                     say(l); } });
             if (!opts.keepRaw)
                 cleanRaw(outDir, take, a.mp4);
@@ -160,9 +199,11 @@ program
             const c = check(outDir, manifest);
             say(c.ok ? "check: pass" : "check: FAIL\n  " + c.lines.filter((l) => l.startsWith("FAIL")).join("\n  "));
         }
+        setPhase(outDir, { phase: "checking", label: "checking the result" });
         say(`[stage] done`);
     }
     finally {
+        endProgress(outDir);
         releaseLock(outDir);
     }
     if (take.partial)
@@ -213,6 +254,7 @@ program
                 say(`✓ ${path.relative(process.cwd(), f)}`);
     }
     finally {
+        endProgress(outDir);
         releaseLock(outDir);
     }
 });
@@ -223,9 +265,10 @@ program
     .option("--apply", "actually remove them", false)
     .option("--deep", "also remove demo.mp4 (still re-renderable, but it is the deliverable)", false)
     .option("--orphans", "also remove whole folders whose manifest is gone", false)
+    .option("--failed", "also remove the whole folder of any take whose steps failed — raw recording included, and there is no getting it back", false)
     .action((opts) => {
     const root = path.resolve(opts.out);
-    const plan = planTidy(root, { deep: opts.deep, orphans: opts.orphans, demosDir: path.resolve("demos") });
+    const plan = planTidy(root, { deep: opts.deep, orphans: opts.orphans, failed: opts.failed, demosDir: path.resolve("demos") });
     if (!plan.bytes) {
         say(`nothing to reclaim in ${path.relative(process.cwd(), root)} — ${mb(plan.keptBytes)} of recordings and deliverables, all of it worth keeping.`);
         return;
@@ -247,6 +290,227 @@ program
     const freed = applyTidy(plan);
     say(`\nfreed ${mb(freed)}. Every demo can still be rebuilt with \`retake render outputs/<name>\`.`);
 });
+program
+    .command("flag")
+    .description("mark something as really wrong — it becomes an `expect:` on that scene, and every later recording answers it")
+    .argument("<manifest>", "the demo it is wrong in")
+    .requiredOption("--scene <label>", "which scene shows it")
+    .requiredOption("--expect <sentence>", "what has to be true once it is fixed, in plain words")
+    .option("--question <sentence>", "what was originally raised, if it came from `sense`")
+    .action((file, opts) => {
+    const r = flag(path.resolve(file), { scene: opts.scene, expect: opts.expect, question: opts.question ?? opts.expect, source: opts.question ? "sense" : "you" });
+    if ("error" in r) {
+        say(`✗ ${r.error}`);
+        process.exitCode = 2;
+        return;
+    }
+    say(`flagged on ${opts.scene}: "${r.flag.expect}"`);
+    say(`Every recording from here on answers it — \`verify\` and \`fixed\` both.`);
+    say(`\`retake fixed ${path.basename(file).replace(/\.[^.]+$/, "")}\` after the next take.`);
+});
+program
+    .command("unflag")
+    .description("stop watching something you flagged")
+    .argument("<manifest>", "the demo it was flagged on")
+    .argument("<what>", "the flag's id, or the expectation itself")
+    .action((file, what) => {
+    const r = unflag(path.resolve(file), what);
+    if ("error" in r) {
+        say(`✗ ${r.error}`);
+        process.exitCode = 2;
+        return;
+    }
+    say(`no longer watching: "${r.removed.expect}"`);
+});
+program
+    .command("fixed")
+    .description("did the things you flagged get fixed — answers each one against the newest take, with the few seconds that show it")
+    .argument("<demo>", "demo name, or a path to its manifest")
+    .option("-o, --out <dir>", "output root", "outputs")
+    .option("--no-clips", "skip cutting the clips")
+    .action(async (demo, opts) => {
+    const file = fs.existsSync(demo) ? path.resolve(demo) : path.resolve("demos", `${demo}.yaml`);
+    if (!fs.existsSync(file))
+        throw new Error(`no ${path.relative(process.cwd(), file)}`);
+    const { manifest } = loadManifest(file);
+    const outDir = path.resolve(opts.out, manifest.name);
+    const r = await checkFlags(file, manifest, outDir, { clips: opts.clips, log: say });
+    // Something flagged and still wrong is a failure; nothing flagged is not.
+    if (r.checked.some((c) => c.ok !== true))
+        process.exitCode = 3;
+});
+program
+    .command("destroy")
+    .description("the flows nobody wrote down — writes a manifest for each way this demo could be abused, and tries them")
+    .argument("<manifest>", "the demo to derive candidates from")
+    .option("-o, --out <dir>", "output root", "outputs")
+    .option("--only <shapes>", "just these, comma-separated (see --shapes)")
+    .option("--shapes", "list the ways it knows how to break something, and stop", false)
+    .option("--run", "actually perform the steps instead of only resolving them — slower, and the only way to catch what happens when an app is really used", false)
+    .option("--no-try", "write the candidates and stop")
+    .action(async (file, opts) => {
+    if (opts.shapes) {
+        for (const s of SHAPES) {
+            say(`${s.name}`);
+            say(`  ${s.asks}`);
+            say(`  ${s.because}`);
+            say("");
+        }
+        return;
+    }
+    const loaded = loadManifest(file);
+    const plan = planDestroy(loaded.manifest, path.resolve(opts.out), { only: opts.only?.split(",").map((x) => x.trim()).filter(Boolean) });
+    for (const l of describePlan(plan, loaded.manifest))
+        say(l);
+    if (plan.refused) {
+        process.exitCode = 2;
+        return;
+    }
+    if (!opts.try || !plan.candidates.length)
+        return;
+    // Generating is safe — it makes files. Running clicks things, and that is
+    // where the two refusals bite.
+    const no = refuseToRun(loaded.manifest, process.env, path.resolve(opts.out));
+    if (no) {
+        say("");
+        say(`✗ not running these: ${no}`);
+        process.exitCode = 2;
+        return;
+    }
+    say("");
+    const trials = await tryCandidates(plan, { mode: opts.run ? "run" : "dry", manifestDir: loaded.dir, outRoot: path.resolve(opts.out), log: say });
+    for (const l of describeTrials(trials, opts.run ? "run" : "dry"))
+        say(l);
+    if (trials.some((t) => t.verdict === "broke"))
+        process.exitCode = 3;
+});
+program
+    .command("calibrate")
+    .description("how much to trust `sweep` — seeds a known defect into a working demo, records each one, and counts what it finds")
+    .argument("<manifest>", "a demo whose app is running")
+    .option("-o, --out <dir>", "output root", "outputs")
+    .option("--only <names>", "just these defects, comma-separated")
+    .option("--plan", "write the variants and stop", false)
+    .action(async (file, opts) => {
+    const loaded = loadManifest(file);
+    const outRoot = path.resolve(opts.out);
+    const plan = planCalibration(loaded.manifest, outRoot, { only: opts.only?.split(",").map((x) => x.trim()).filter(Boolean) });
+    say(`${plan.variants.length} variants in ${path.relative(process.cwd(), plan.root)}/ — one control, ${plan.variants.length - 1} seeded`);
+    if (opts.plan)
+        return;
+    const results = [];
+    for (const v of plan.variants) {
+        const dir = path.join(plan.root, v.name);
+        say(`\n${v.name}${v.defect ? ` — ${v.defect.looks}` : ""}`);
+        try {
+            const take = await record(v.manifest, { outDir: dir, manifestDir: loaded.dir, headed: false, log: () => { } });
+            await render(v.manifest, take, dir, { log: () => { }, noMaster: true });
+            const s = await sweep(v.manifest, dir, () => { }, { demosDir: path.resolve("demos") });
+            const took = true; // the seed proved itself in the page, or the take threw
+            const kinds = s.frames.flatMap((f) => f.issues.map((i) => i.kind));
+            const found = !v.defect ? false : kinds.some((k) => k.toUpperCase().startsWith(v.defect.expect.split(" ")[0]));
+            results.push({ variant: v.name, defect: v.defect, kinds, found: found && took, seeded: took, other: v.defect ? kinds.filter((k) => !k.toUpperCase().startsWith(v.defect.expect.split(" ")[0])).length : 0 });
+            say(`  → ${kinds.join(", ") || "nothing"}${v.defect && !took ? "   (the seed did not land — nothing was asked of the check)" : ""}`);
+        }
+        catch (e) {
+            results.push({ variant: v.name, defect: v.defect, kinds: [], found: false, seeded: !/seed did not take/.test(String(e.message)), other: 0, error: String(e.message).split("\n")[0].slice(0, 90) });
+            say(`  → could not run: ${String(e.message).split("\n")[0].slice(0, 90)}`);
+        }
+    }
+    for (const l of report(results))
+        say(l);
+    fs.writeFileSync(path.join(plan.root, "report.json"), JSON.stringify({ at: new Date().toISOString(), demo: loaded.manifest.name, results }, null, 2) + "\n");
+});
+program
+    .command("intent")
+    .description("what this product IS — the context every visual check is missing without it")
+    .argument("[text]", "the note to save; omit to read what is there")
+    .option("--demo <name>", "a note for one demo's app, rather than the whole workspace")
+    .option("--starter", "write a starter file to fill in", false)
+    .action((text, opts) => {
+    const demos = path.resolve("demos");
+    if (opts.starter || (!text && !readIntent(demos, opts.demo))) {
+        if (readIntent(demos, opts.demo) && !text) {
+            say(readIntent(demos, opts.demo));
+            return;
+        }
+        say(`wrote ${path.relative(process.cwd(), writeIntent(demos, TEMPLATE, opts.demo))} — fill it in.`);
+        say("Without it, every check judges your app as a generic web page: anything deliberate about it can come back as a defect.");
+        return;
+    }
+    if (!text) {
+        say(readIntent(demos, opts.demo) ?? "");
+        return;
+    }
+    say(`saved to ${path.relative(process.cwd(), writeIntent(demos, text, opts.demo))}`);
+});
+program
+    .command("sweep")
+    .description("look at every frame as a whole — the ten ways a picture can be wrong, checked on each one, whether or not anybody asked")
+    .argument("<dir>", "an outputs/<name> dir")
+    .argument("[manifest]", "manifest (default demos/<name>.yaml)")
+    .option("--all", "the middle of each scene too, not just its last moment", false)
+    .option("--concurrency <n>", "how many frames to look at at once", "4")
+    .option("--fresh", "ask about every frame again, even the ones that have not changed", false)
+    .action(async (dir, manifestFile, opts) => {
+    const outDir = path.resolve(dir);
+    const file = manifestFile ?? path.join("demos", `${path.basename(outDir)}.yaml`);
+    if (!fs.existsSync(file))
+        throw new Error(`no ${file} — pass the manifest path`);
+    // No exit code, deliberately. Some of these are judgement; `verify` gates.
+    await sweep(loadManifest(file).manifest, outDir, say, { all: opts.all, concurrency: Number(opts.concurrency) || 4, fresh: opts.fresh });
+});
+program
+    .command("sense")
+    .description("does the run ADD UP — what went in against what came out, across the whole demo")
+    .argument("<dir>", "an outputs/<name> dir")
+    .argument("[manifest]", "manifest (default demos/<name>.yaml)")
+    .action((dir, manifestFile) => {
+    const outDir = path.resolve(dir);
+    const file = manifestFile ?? path.join("demos", `${path.basename(outDir)}.yaml`);
+    if (!fs.existsSync(file))
+        throw new Error(`no ${file} — pass the manifest path`);
+    // Deliberately no exit code. sense asks questions; `verify` is the gate.
+    sense(loadManifest(file).manifest, outDir, say);
+});
+program
+    .command("heal")
+    .description("write back the demo files for recordings whose manifest went missing — the window only lists demos, so those recordings are invisible until it does")
+    .option("-o, --out <dir>", "output root", "outputs")
+    .option("--apply", "actually write them (without this it only says what it would do)", false)
+    .action((opts) => {
+    const orphans = findOrphans(path.resolve(opts.out), path.resolve("demos"));
+    const written = opts.apply ? healOrphans(orphans, path.resolve("demos")) : null;
+    for (const l of describeOrphans(orphans, written))
+        say(l);
+});
+program
+    .command("notes")
+    .description("what everyone has actually been doing — reads outputs/ back and says the few things worth saying")
+    .option("-o, --out <dir>", "output root", "outputs")
+    .option("--all", "every note, not just the five that matter", false)
+    .option("--days <n>", "how far back to look", "14")
+    .action((opts) => {
+    const { lines } = notes(path.resolve(opts.out), { all: opts.all, days: Number(opts.days) || 14 });
+    for (const l of lines)
+        say(l);
+});
+program
+    .command("verify")
+    .description("did it LOOK right — puts each scene's `expect` question to a vision model against that scene's still")
+    .argument("<dir>", "an outputs/<name> dir containing take.json and stills/")
+    .argument("[manifest]", "manifest to read the expectations from (default demos/<name>.yaml)")
+    .action(async (dir, manifestFile) => {
+    const outDir = path.resolve(dir);
+    const file = manifestFile ?? path.join("demos", `${path.basename(outDir)}.yaml`);
+    if (!fs.existsSync(file))
+        throw new Error(`no ${file} — pass the manifest path`);
+    const { manifest } = loadManifest(file);
+    const v = await verify(manifest, outDir, say, file);
+    // 3, the same code dry and check already use for "this did not pass".
+    if (!v.ok)
+        process.exitCode = 3;
+});
 program
     .command("render")
     .argument("<dir>", "an outputs/<name> dir containing take.json")
@@ -255,6 +519,7 @@ program
     .option("--scene <label>", "render just one scene to scene-<label>.mp4 (fast, hardware encode)")
     .option("--gif", "also produce a GIF", false)
     .option("--force", "ignore the render cache", false)
+    .option("--no-master", "skip the archival CRF-14 master — halves render on a long take")
     .option("--out <dir>", "write the render into a NEW directory, leaving the original untouched")
     .action(async (dir, manifestFile, opts) => {
     const takePath = path.join(dir, "take.json");
@@ -296,7 +561,7 @@ program
         manifest = { ...manifest, outputs: { ...manifest.outputs, gif: true } };
     acquireLock(path.resolve(dir));
     try {
-        const a = await render(manifest, take, path.resolve(dir), { log: say, force: opts.force, scene: opts.scene });
+        const a = await render(manifest, take, path.resolve(dir), { log: say, force: opts.force, scene: opts.scene, noMaster: opts.master === false });
         for (const f of [a.master, a.mp4, a.gif, a.thumbnail])
             if (f)
                 say(`✓ ${path.relative(process.cwd(), f)}`);

package/dist/describe.js

@@ -313,7 +313,7 @@ const SCHEMA_DOC = `
 Manifest YAML fields:
   name (kebab-case), title, url, mode: demo, preset: post-landscape, waitForSelector (selector present when page is ready),
   camera: static, setup: [steps run before recording], steps: [...], outputs: {mp4: true, gif: true, thumbnail: {scene: <label>}}
-  NEVER set viewport. The preset decides the size and every take at a preset comes out identical; setting viewport makes this demo a different shape from every other one and players letterbox it. Same for cursor, chrome, background, fps, crf and captions — the preset handles all of it.
+  NEVER set captions: true unless the person asked for captions — they are off by default because a caption makes a viewer read instead of watch. Write a caption on each scene anyway: it names the beat in the proof log and the stills. NEVER set viewport. The preset decides the size and every take at a preset comes out identical; setting viewport makes this demo a different shape from every other one and players letterbox it. Same for cursor, chrome, background, fps, crf and captions — the preset handles all of it.
   Always set mode: demo — this is a demo, so nothing goes in the frame but the product. Never emit intro or outro cards, music, callouts or voiceover: those belong to mode: launch, which only a person can ask for.
 Steps (each may have pauseAfter ms, waitFor selector, timeout ms):
   {action: scene, label, caption, camera?: static | {focus: selector, zoom: 1.25}}   a named beat; caption is burned in until the next scene (under 60 chars). Set camera: static on every scene unless the thing being shown is genuinely too small to read at full frame — a calm, still demo reads as more real than a zooming one. If the person asked for zooms (or stillness), that wins.