@navipartner/demo-video 0.4.0 → 0.5.0

package/skills/np-demo-video/SKILL.md

@@ -1,348 +1,364 @@
----
-name: np-demo-video
-description: Produce or change a marketing demo video of a NaviPartner React app (retail self-checkout, food-order kiosk, or any app with a demo/ adapter) in the house look, which is calm camera pushes, serif statement cards and customer branding, recorded by the engine @navipartner/demo-video. Use when asked for a product demo video, a showcase of a flow, a marketing or SoMe clip, a customer-branded video (e.g. "two waters, in a customer's branding"), or to re-record a demo after UI changes.
----
-
-# NaviPartner demo video
-
-You direct; the engine (`@navipartner/demo-video`) films. You write a story
-(JSON). Never write Playwright code for a video and never edit the app to
-make a video pass.
-
-**Read [look.md](look.md) first.** It defines how every video must look and
-feel: chapters, statement cards, camera, cursor, branding. This file is the
-workflow.
-
-## 1. Understand the request
-
-From the request, take:
-- **Product:** which app.
-- **Chapters:** the 1–4 ideas to show.
-- **Brand:** default NaviPartner.
-- **Data:** the products, names and amounts the request mentions ("two
-  waters").
-
-Card text defaults to English. Ask only for what you cannot infer.
-
-### The primary story
-
-Every app has one **primary story**: the journey the app exists for, from
-start to the moment of value. It is the app's first story, and the one filmed
-when a request names no feature ("make a video of the QR app", "a video in
-the customer's branding").
-
-| App | Primary story | Ends on |
-|---|---|---|
-| Self-service food order | order and pay | "Thank you", order number |
-| QR food order | order from the table | order received |
-| Retail self-checkout | scan and pay | paid, receipt |
-| NP Passes | create a pass | the pass is created |
-
-To find it in a new app:
-- **The e2e suite's happy path.** There is almost always a spec that walks the
-  whole flow (`complete-order-flow.spec.ts`, `06-order-complete.spec.ts`).
-  Follow it, and end where it asserts success.
-- **The app's purpose.** Its README, routes and package description say what
-  it is for. If they disagree with the happy-path spec, ask.
-
-Name the story for that job (`checkout`, `create-pass`) and mark it
-`"primary": true`. One story per app may be primary; `demo-video list` refuses
-two. In the PR, say which spec the story follows, so the developer can confirm
-it is the right journey.
-
-Run `pnpm --dir <app> exec demo-video list` first. If a primary story exists and the
-request names no feature, render it (`pnpm --dir <app> exec demo-video render` without `--story`,
-with `--brand` if one is asked for) instead of writing a new one. For a
-repo with several apps and no app named, ask which app, or offer each app's
-primary story. A PR never films it by default; only stories a PR adds or
-changes are filmed there.
-
-## 2. Plan the chapters on paper first
-
-Before any JSON, write the plan. For each chapter give, in this order:
-1. **What the viewer sees happen**, as one plain sentence with the chapter's
-   verb: "the shopper scans an item and it lands in the basket".
-2. **The actions** (2–5), and for each one **what it changes and where on
-   screen** that change appears (a new row at the top, the total at the
-   bottom, a new screen).
-3. **The shot:** one push-in on the area that holds a control *and* what it
-   changes, or wide when they're far apart. The camera never chases the
-   cursor.
-4. **The statement card**, written last, from sentence 1 (see "Writing the
-   cards").
-5. **The payoff fact**, if there is one: a value the app shows, checked with
-   `expectText`.
-
-Check it against look.md:
-- Is the story clear on mute?
-- Does every card describe exactly what the chapter after it shows?
-- Does the hook land by second 6?
-
-Example, retail self-checkout for a customer (here the made-up brand Acme):
-
-```
-open    Introducing · Acme logo · sub "Self-checkout"
-ch1     sees: a guest scans two waters and they land in the basket
-        shots: wide for the scans (the rows appear at the top);
-               push in 1.5 on the basket rows to read them
-        card: "Scan *and go*."
-ch2     sees: the guest pays by card and the payment goes through
-        shots: push in 1.6 on "Go to payment" (button + total);
-               pull out when the payment screen opens
-        card: "Pay *by card*."
-payoff  "Paid *in seconds*." · sub "64,50 kr. by card." (expectText on the total)
-end     Acme logo · "Self-checkout by NaviPartner"
-```
-
-## 3. Learn the app
-
-1. **Adapter:** `<app>/demo/demo.config.ts`. It says how the app runs
-   offline (`setup` → the e2e mocks), its `ready` testid and any
-   `actions` (e.g. retail's `scan`). No adapter yet: see "A new app" below.
-2. **Testids:** read the components for every screen in the plan and collect
-   their `data-testid`s.
-3. **Data:** a story is inspired only by what the project's Playwright
-   e2e tests already have: their mocks, logins and data. Read the e2e specs
-   (they already walk the flows) and the mocks `setup` calls. Only data they
-   return can appear (items, barcodes, prices, names).
-   - Never add fixtures or change the mocks or the app for a video.
-   - Skip the test edge cases the mocks contain on purpose, such as a product
-     with an absurdly long name or an error item.
-   - If the request needs data the e2e tests don't have, say so instead of
-     inventing it.
-   - One exception: a customer brand may rename the mock's products in its
-     `config.demoData` (see "A new brand"). It gives them names only, never
-     new barcodes, prices or flows.
-
-### A new app
-
-1. From the repo root: `npx --ignore-scripts @navipartner/demo-video init --app <app>`, then
-   `pnpm install`. (A repo set up for the first time runs
-   `npx --ignore-scripts @navipartner/demo-video init` without `--app` first.)
-   It adds the
-   dependency and writes a `demo.config.ts` skeleton with the dev server
-   from `playwright.config`.
-2. Finish the skeleton from the app's **current** code and e2e tests, not
-   from notes or an older adapter:
-   - `appPath` and `ready`: what the e2e helpers open and wait for.
-   - `setup`: the e2e mocks exactly as the tests call them.
-   - The brand: find the response that carries the app's branding and the
-     code that parses it. Lay the brand over it with `overlayResponse`,
-     using only keys that code accepts (colour formats, asset fields).
-   - `actions` for what a test does through code (a scanner bridge, a test
-     dispatch), and `idleTimeoutSeconds` if the app resets when idle.
-3. Write the primary story (above), then `pnpm --dir <app> exec demo-video check`.
-
-## 4. Write the story
-
-A developer writes stories locally (VS Code, with this skill) and a PR
-confirms them. A `/demo-video` PR comment, and later the Linear agent, only
-pick an existing story and a brand: they never write one. A story is
-`<app>/demo/stories/<name>.json`, named for what it shows (`checkout`,
-`settings`), and holds no brand: the same story renders for any brand with
-`--brand <name>`. A customer's own words go in a variant (below).
-
-    { "app": "<adapter app>",
-      "description": "One sentence: what the story shows. Follows e2e/<spec>.",
-      "primary": true,
-      "title":   { "eyebrow": "Introducing", "logo": true, "sub": "…" },
-      "closing": { "logo": true, "sub": "…" },
-      "steps": [ … ] }
-
-Steps: `click` `type` `press` `zoom` `frame` `zoomOut` `park` `waitFor`
-`expectText` `hold` `card`, plus the adapter's actions (every field in
-[reference.md](reference.md)).
-
-How the look maps onto steps:
-
-- **Cards:** `{ "do": "card", "heading": "Pay *by card*." }` opens a
-  chapter; `"style": "brand"` is the full-bleed payoff. A card stays up at
-  least as long as it takes to read, so `seconds` is only needed to hold one
-  longer.
-- **Push in:** `{ "do": "zoom", "target": "…", "scale": 1.6 }` on the area
-  where the action *and its result* are, then hold steady through the
-  clicks there. Use 1.4–1.8 (the engine accepts 1.3–2). `"zoom"` on a click
-  pushes in on that control first. At most two push-ins a chapter.
-- **Frame the action and its result together:**
-  `{ "do": "frame", "targets": ["pay-button", "order-total"] }` computes one
-  shot that holds them all (2–4 targets, each a testid or
-  `{ "target", "nth" }`), pushed in as far as they fit (at most 1.8, or
-  `maxScale`). Prefer it to guessing one zoom target. Targets too far apart
-  for a push-in fail `check`: frame things that sit together.
-- **A result elsewhere:** when a click changes something outside the shot (a
-  row added at the top, a new screen), pull out right after it
-  (`zoomOut`), or frame both from the start. `check` fails a click whose
-  change the viewer never sees.
-- **Read:** `hold` 1.5–3 s on anything the viewer must read (a total, a
-  confirmation).
-- **Leave the beats to the engine.** It pauses on each target before the
-  press, holds the press, waits for the app to react, settles the camera
-  before acting, lingers on a chapter's result before its card, and opens
-  every chapter wide with the cursor at rest. Don't add holds for those.
-- **Works with every brand:** any story can be filmed with any brand (the
-  label uses the app's default). Never target text a brand's `demoData`
-  sets (renamed products, an order number): pick products by testid and
-  `nth`, the mock's order. Run `check` without `--brand` as well as with the
-  brand you're writing for.
-- **Safety:** after each navigation, `waitFor` the next screen's testid. Put
-  `expectText` on prices and confirmations so the video fails if the copy is
-  wrong, and so a card may quote them.
-
-### Writing the cards
-
-The words are what the viewer remembers; write them with care.
-
-- **A statement names what the chapter shows,** in the chapter's own verb,
-  before it happens: a scan chapter is "Scan *and go*.", not "Shopping made
-  easy." If the viewer couldn't point at it in the next ten seconds, rewrite
-  it.
-- **The italic word is the action or its result** ("*scan*", "*by card*",
-  "*paid*"), never a filler word.
-- **A payoff states the result just shown,** with the app's real values from
-  an `expectText`: "64,50 kr. by card." No durations, counts or claims the
-  video doesn't show; `check` rejects a number no `expectText` proves.
-- **Title sub:** what the product is ("Self-checkout"). **Closing sub:** one
-  short line, the product's promise.
-- **Never on a card:** testids, barcodes, internal names, "demo", "test",
-  exclamation marks, "seamless", "effortless", "revolutionary".
-- Statements ≤ 7 words, subs ≤ 16 (`check` stops at 8 and 16), sentence
-  case, ending with a full stop.
-
-### A new brand
-
-A customer brand is `<app>/demo/brands/<name>.json` with its assets in
-`<app>/demo/brands/<name>/`. Fields: [reference.md](reference.md).
-
-A customer's name, logo and look are their trademarks. A video in them is
-made with their permission, from what they gave us, and stays internal until
-they approve it.
-
-- **Only with permission.** Make a customer brand only when the request says
-  the customer has agreed to a video in their branding (an account manager or
-  the customer asked for it). If that's unclear, ask before you start.
-- **Only their own material, never invented or recreated:** the logo file and
-  brand guide the customer supplied, or that a NaviPartner colleague received
-  from them. Don't download, trace, redraw or recolour a logo from their
-  website, and don't guess a colour or font. If a value is missing, ask the
-  customer contact for it; colours from their public site are a stand-in to
-  confirm with them, never final.
-- **Say where it came from.** The PR that adds the brand names the source of
-  the logo, colours and fonts, and who gave permission. Without that, the
-  brand doesn't merge.
-- **Logo:** an SVG or a PNG with a transparent background, readable on a
-  light background (`logoColor`, a top-level key, recolours a white SVG; use
-  it only when their brand guide allows that colour version).
-- **Fonts:** only a font whose licence covers use in a video. Google Fonts are
-  open-licensed and fine. A customer's own or commercial font is used only if
-  they confirm their licence covers it; otherwise take the closest Google
-  Font and say so in the report. Never copy font files from their website.
-- **No claims for them:** cards state what the video shows. No customer
-  quotes, statistics or "trusted by" lines, and a closing card says what the
-  product is, not that the customer endorses it.
-- **Publishing:** a customer-branded video goes to the customer for approval
-  before it is published anywhere. Say so in the report.
-- **`config`:** only keys the app's branding code accepts. Override every
-  value the e2e mock sets that would show through, such as a mock
-  `backgroundColor`.
-- **`config.demoData`** (when the adapter supports it): the customer's names
-  for the mock's products, keyed by the mock's barcodes. Mock data such as
-  "Toothpaste" or "TEST CARD" reads as a test run in a customer video. Use
-  plain product names ("Lemonade"), or ones the customer gave you, never a
-  third party's brand ("Coca-Cola"). Keep the mock's prices, so pick
-  products that are believable at those prices, and put the totals on the
-  cards from the render, not from your own sums.
-- **App limits:** an app may only offer presets (retail has two font pairs).
-  Pick the closest and say in the report what the kiosk can't show.
-- **`video` fonts** load from Google Fonts: the heading in 400, 700 and
-  italic 400, the body in 400 and 600. If a font lacks one, give `fontsUrl`
-  yourself.
-- Render with `--brand <name>` and check the stills before calling it done.
-
-### A variant: the story in a customer's words
-
-When a customer video needs its own words (their product, their place), write
-a variant beside the story instead of a copy: `checkout.acme.json`.
-
-    { "extends": "checkout",
-      "brand": "acme",
-      "description": "The checkout story, for Acme.",
-      "title":   { "sub": "Self-service at Acme" },
-      "closing": { "sub": "…" },
-      "cards":   [ { "heading": "A burger *and a lemonade*." }, { … }, { … } ] }
-
-- The steps are always the base story's: a variant changes words and brand,
-  never the flow. Fix the flow in the base, once, for every variant.
-- `cards` gives every card step of the base, in order; each entry, like
-  `title` and `closing`, changes only the fields it names. When the base
-  gains or loses a card, the variant stops loading until it is updated.
-- It films with its own brand only. `/demo-video checkout in acme branding`
-  and the form (story `checkout`, brand `acme`) pick the variant.
-- The same rules as any card: numbers proven by the base's `expectText`s,
-  and the customer's permission for their name (see "A new brand").
-- `check --story checkout.acme` before the PR, and re-check the variants
-  when you change their base.
-
-### Not supported yet
-
-There's no music bed. Videos are silent, so they must work on mute.
-
-## 5. Check, then render
-
-    pnpm --dir <app> exec demo-video check [--story <name>] --json
-
-Without `--story`, commands use the primary story. `check` performs every
-step for real and fails on anything that would film badly:
-
-| It says | Fix |
-|---|---|
-| `"x" is outside the shot …` | The zoom frames the wrong area: zoom on what this shot clicks, or `zoomOut` first |
-| `clicking "x" changes y, which is outside the shot …` | Frame what the click changes, or `zoomOut` right after the click |
-| `N camera push-ins in one chapter` | Push in once on the chapter's area and hold steady |
-| `… only fit in the wide shot` | `frame` things that sit together, or stay wide |
-| `… gives N cards; … has M` | Give the variant one entry per card of its story, in order |
-| `a zoom with nothing in its shot` | Remove it, or act or read something in it |
-| `zoom 2.4; use 1.3–2` | Zoom less: context reads better and stays sharp |
-| `"…" looks like a testid-like name / barcode / code` | Cards are for people: say it in words |
-| `"38" isn't shown by an expectText` | Quote only values an `expectText` checks |
-| `the card announces a chapter in which nothing is done` | Follow it with the steps it describes |
-
-Fix what the report names. Its `visible` list shows what is on screen at the
-failing step. Repeat until it passes, at most 3 rounds; a story that still
-fails is reported as "couldn't show this", with the last report. Then:
-
-    pnpm --dir <app> exec demo-video render [--story <name>] [--brand <name>]
-
-Rendering films every frame (60 fps, frame by frame), so it takes about
-five times the video's length. While tuning, `render --draft` films at
-30 fps in about half the time (`…-draft-demo.mp4`); render the final without
-it. Playwright starts the app's dev server from
-the adapter's `webServer`; if it can't on this machine, start it yourself
-with the same command and env, and it is reused.
-
-## 6. Review like a viewer
-
-Open `<app>/demo/out/review/sheet.jpg` first: one frame a second, the whole
-video at a glance. Then the full-size stills beside it. Judge against
-look.md:
-- **Story:** each statement card is followed by exactly what it says, and
-  the payoff by the result it states.
-- **Camera:** every push-in lands where something then happens; no shot is
-  mostly empty space; each click's result is on screen.
-- **Framing:** pushed-in shots fill the frame and read on a phone; nothing
-  important is cut off; the cursor rests out of the way.
-- **Pacing:** each chapter is one idea; nothing rushed, nothing lingering.
-- **Truth:** every word is true of what's on screen.
-
-Adjust the JSON and re-render. Two rounds of tuning is normal; if it takes
-more, the plan from step 2 is the problem.
-
-## Report
-
-Give:
-- the MP4 path and duration
-- the chapter plan
-- the contact sheet and stills
-- which brand it was rendered with, and for a customer brand, that the
-  video needs the customer's approval before it is published
-- anything the video could not show truthfully (it shows demo fixture data,
-  not a real tenant's)
+---
+name: np-demo-video
+description: Produce or change a marketing demo video of a NaviPartner React app (retail self-checkout, food-order kiosk, or any app with a demo/ adapter) in the house look, which is calm camera pushes, serif statement cards and customer branding, recorded by the engine @navipartner/demo-video. Use when asked for a product demo video, a showcase of a flow, a marketing or SoMe clip, a customer-branded video (e.g. "two waters, in a customer's branding"), a pitch draft for a prospective customer (e.g. "pitch draft of checkout for Hotel Royal"; follow pitch.md), or to re-record a demo after UI changes.
+---
+
+# NaviPartner demo video
+
+You direct; the engine (`@navipartner/demo-video`) films. You write a story
+(JSON). Never write Playwright code for a video and never edit the app to
+make a video pass.
+
+**Read [look.md](look.md) first.** It defines how every video must look and
+feel: chapters, statement cards, camera, cursor, branding. This file is the
+workflow.
+
+## 1. Understand the request
+
+From the request, take:
+- **Product:** which app.
+- **Chapters:** the 1–4 ideas to show.
+- **Brand:** default NaviPartner.
+- **Data:** the products, names and amounts the request mentions ("two
+  waters").
+
+Card text defaults to English. Ask only for what you cannot infer.
+
+### The primary story
+
+Every app has one **primary story**: the journey the app exists for, from
+start to the moment of value. It is the app's first story, and the one filmed
+when a request names no feature ("make a video of the QR app", "a video in
+the customer's branding").
+
+| App | Primary story | Ends on |
+|---|---|---|
+| Self-service food order | order and pay | "Thank you", order number |
+| QR food order | order from the table | order received |
+| Retail self-checkout | scan and pay | paid, receipt |
+| NP Passes | create a pass | the pass is created |
+
+To find it in a new app:
+- **The e2e suite's happy path.** There is almost always a spec that walks the
+  whole flow (`complete-order-flow.spec.ts`, `06-order-complete.spec.ts`).
+  Follow it, and end where it asserts success.
+- **The app's purpose.** Its README, routes and package description say what
+  it is for. If they disagree with the happy-path spec, ask.
+
+Name the story for that job (`checkout`, `create-pass`) and mark it
+`"primary": true`. One story per app may be primary; `demo-video list` refuses
+two. In the PR, say which spec the story follows, so the developer can confirm
+it is the right journey.
+
+Run `pnpm --dir <app> exec demo-video list` first. If a primary story exists and the
+request names no feature, render it (`pnpm --dir <app> exec demo-video render` without `--story`,
+with `--brand` if one is asked for) instead of writing a new one. For a
+repo with several apps and no app named, ask which app, or offer each app's
+primary story. A PR never films it by default; only stories a PR adds or
+changes are filmed there.
+
+## 2. Plan the chapters on paper first
+
+Before any JSON, write the plan. For each chapter give, in this order:
+1. **What the viewer sees happen**, as one plain sentence with the chapter's
+   verb: "the shopper scans an item and it lands in the basket".
+2. **The actions** (2–5), and for each one **what it changes and where on
+   screen** that change appears (a new row at the top, the total at the
+   bottom, a new screen).
+3. **The shot:** one push-in on the area that holds a control *and* what it
+   changes, or wide when they're far apart. The camera never chases the
+   cursor.
+4. **The statement card**, written last, from sentence 1 (see "Writing the
+   cards").
+5. **The payoff fact**, if there is one: a value the app shows, checked with
+   `expectText`.
+
+Check it against look.md:
+- Is the story clear on mute?
+- Does every card describe exactly what the chapter after it shows?
+- Does the hook land by second 6?
+
+Example, retail self-checkout for a customer (here the made-up brand Acme):
+
+```
+open    Introducing · Acme logo · sub "Self-checkout"
+ch1     sees: a guest scans two waters and they land in the basket
+        shots: wide for the scans (the rows appear at the top);
+               push in 1.5 on the basket rows to read them
+        card: "Scan *and go*."
+ch2     sees: the guest pays by card and the payment goes through
+        shots: push in 1.6 on "Go to payment" (button + total);
+               pull out when the payment screen opens
+        card: "Pay *by card*."
+payoff  "Paid *in seconds*." · sub "64,50 kr. by card." (expectText on the total)
+end     Acme logo · "Self-checkout by NaviPartner"
+```
+
+## 3. Learn the app
+
+1. **Adapter:** `<app>/demo/demo.config.ts`. It says how the app runs
+   offline (`setup` → the e2e mocks), its `ready` testid and any
+   `actions` (e.g. retail's `scan`). No adapter yet: see "A new app" below.
+2. **Testids:** read the components for every screen in the plan and collect
+   their `data-testid`s.
+3. **Data:** a story is inspired only by what the project's Playwright
+   e2e tests already have: their mocks, logins and data. Read the e2e specs
+   (they already walk the flows) and the mocks `setup` calls. Only data they
+   return can appear (items, barcodes, prices, names).
+   - Never add fixtures or change the mocks or the app for a video.
+   - Skip the test edge cases the mocks contain on purpose, such as a product
+     with an absurdly long name or an error item.
+   - If the request needs data the e2e tests don't have, say so instead of
+     inventing it.
+   - One exception: a customer brand may rename the mock's products in its
+     `config.demoData` (see "A new brand"). It gives them names only, never
+     new barcodes, prices or flows.
+
+### A new app
+
+1. From the repo root: `npx --ignore-scripts @navipartner/demo-video init`,
+   then `pnpm install`. It finds the apps (folders with a
+   `playwright.config`). With one app (at the repo root or in a folder) it
+   sets that app up too; with several it lists them, and you run
+   `init --app <folder>` for this one. Setting an app up adds the dependency
+   and writes a `demo.config.ts` skeleton with the dev server from
+   `playwright.config`.
+2. Finish the skeleton from the app's **current** code and e2e tests, not
+   from notes or an older adapter:
+   - `appPath` and `ready`: what the e2e helpers open and wait for.
+   - `setup`: the e2e mocks exactly as the tests call them.
+   - The brand: find the response that carries the app's branding and the
+     code that parses it. Lay the brand over it with `overlayResponse`,
+     using only keys that code accepts (colour formats, asset fields).
+   - `brandNeeds`: every `config` key and asset slot `setup` uses, each
+     with what it is and where it shows ("full-screen photo behind the
+     menu, landscape"). A brand without one fails `check`, and a pitch
+     draft's research fills exactly these, so be specific. Mark a need the
+     app can do without `optional: true`. `demo-video brand-needs` prints
+     them.
+   - `actions` for what a test does through code (a scanner bridge, a test
+     dispatch), and `idleTimeoutSeconds` if the app resets when idle.
+3. Write the primary story (above), then `pnpm --dir <app> exec demo-video check`.
+
+## 4. Write the story
+
+A developer writes stories locally (VS Code, with this skill) and a PR
+confirms them. A `/demo-video` comment (on a PR, an issue, or from Linear's
+synced thread) and the Run workflow form only
+pick an existing story and a brand: they never write one. A story is
+`<app>/demo/stories/<name>.json`, named for what it shows (`checkout`,
+`settings`), and holds no brand: the same story renders for any brand with
+`--brand <name>`. A customer's own words go in a variant (below).
+
+    { "app": "<adapter app>",
+      "description": "One sentence: what the story shows. Follows e2e/<spec>.",
+      "primary": true,
+      "title":   { "eyebrow": "Introducing", "logo": true, "sub": "…" },
+      "closing": { "logo": true, "sub": "…" },
+      "steps": [ … ] }
+
+Steps: `click` `type` `press` `zoom` `frame` `zoomOut` `park` `waitFor`
+`expectText` `hold` `card`, plus the adapter's actions (every field in
+[reference.md](reference.md)).
+
+How the look maps onto steps:
+
+- **Cards:** `{ "do": "card", "heading": "Pay *by card*." }` opens a
+  chapter; `"style": "brand"` is the full-bleed payoff. A card stays up at
+  least as long as it takes to read, so `seconds` is only needed to hold one
+  longer.
+- **Push in:** `{ "do": "zoom", "target": "…", "scale": 1.6 }` on the area
+  where the action *and its result* are, then hold steady through the
+  clicks there. Use 1.4–1.8 (the engine accepts 1.3–2). `"zoom"` on a click
+  pushes in on that control first. At most two push-ins a chapter.
+- **Frame the action and its result together:**
+  `{ "do": "frame", "targets": ["pay-button", "order-total"] }` computes one
+  shot that holds them all (2–4 targets, each a testid or
+  `{ "target", "nth" }`), pushed in as far as they fit (at most 1.8, or
+  `maxScale`). Prefer it to guessing one zoom target. Targets too far apart
+  for a push-in fail `check`: frame things that sit together.
+- **A result elsewhere:** when a click changes something outside the shot (a
+  row added at the top, a new screen), pull out right after it
+  (`zoomOut`), or frame both from the start. `check` fails a click whose
+  change the viewer never sees.
+- **Read:** `hold` 1.5–3 s on anything the viewer must read (a total, a
+  confirmation).
+- **Leave the beats to the engine.** It pauses on each target before the
+  press, holds the press, waits for the app to react, settles the camera
+  before acting, lingers on a chapter's result before its card, and opens
+  every chapter wide with the cursor at rest. Don't add holds for those.
+- **Works with every brand:** any story can be filmed with any brand (the
+  label uses the app's default). Never target text a brand's `demoData`
+  sets (renamed products, an order number): pick products by testid and
+  `nth`, the mock's order. Run `check` without `--brand` as well as with the
+  brand you're writing for.
+- **Safety:** after each navigation, `waitFor` the next screen's testid. Put
+  `expectText` on prices and confirmations so the video fails if the copy is
+  wrong, and so a card may quote them.
+
+### Writing the cards
+
+The words are what the viewer remembers; write them with care.
+
+- **A statement names what the chapter shows,** in the chapter's own verb,
+  before it happens: a scan chapter is "Scan *and go*.", not "Shopping made
+  easy." If the viewer couldn't point at it in the next ten seconds, rewrite
+  it.
+- **The italic word is the action or its result** ("*scan*", "*by card*",
+  "*paid*"), never a filler word.
+- **A payoff states the result just shown,** with the app's real values from
+  an `expectText`: "64,50 kr. by card." No durations, counts or claims the
+  video doesn't show; `check` rejects a number no `expectText` proves.
+- **Title sub:** what the product is ("Self-checkout"). **Closing sub:** one
+  short line, the product's promise.
+- **Never on a card:** testids, barcodes, internal names, "demo", "test",
+  exclamation marks, "seamless", "effortless", "revolutionary".
+- Statements ≤ 7 words, subs ≤ 16 (`check` stops at 8 and 16), sentence
+  case, ending with a full stop.
+
+### A new brand
+
+A customer brand is `<app>/demo/brands/<name>.json` with its assets in
+`<app>/demo/brands/<name>/`. Fields: [reference.md](reference.md).
+
+A customer's name, logo and look are their trademarks. A video in them is
+made with their permission, from what they gave us, and stays internal until
+they approve it.
+
+- **Only with permission.** Make a customer brand only when the request says
+  the customer has agreed to a video in their branding (an account manager or
+  the customer asked for it). If that's unclear, ask before you start.
+- **Only their own material, never invented or recreated:** the logo file and
+  brand guide the customer supplied, or that a NaviPartner colleague received
+  from them. Don't download, trace, redraw or recolour a logo from their
+  website, and don't guess a colour or font. If a value is missing, ask the
+  customer contact for it; colours from their public site are a stand-in to
+  confirm with them, never final.
+- **Say where it came from.** The PR that adds the brand names the source of
+  the logo, colours and fonts, and who gave permission. Without that, the
+  brand doesn't merge.
+- **Logo:** an SVG or a PNG with a transparent background, readable on a
+  light background (`logoColor`, a top-level key, recolours a white SVG; use
+  it only when their brand guide allows that colour version).
+- **Fonts:** only a font whose licence covers use in a video. Google Fonts are
+  open-licensed and fine. A customer's own or commercial font is used only if
+  they confirm their licence covers it; otherwise take the closest Google
+  Font and say so in the report. Never copy font files from their website.
+- **No claims for them:** cards state what the video shows. No customer
+  quotes, statistics or "trusted by" lines, and a closing card says what the
+  product is, not that the customer endorses it.
+- **Publishing:** a customer-branded video goes to the customer for approval
+  before it is published anywhere. Say so in the report.
+- **`config`:** only keys the app's branding code accepts. Override every
+  value the e2e mock sets that would show through, such as a mock
+  `backgroundColor`.
+- **`config.demoData`** (when the adapter supports it): the customer's names
+  for the mock's products, keyed by the mock's barcodes. Mock data such as
+  "Toothpaste" or "TEST CARD" reads as a test run in a customer video. Use
+  plain product names ("Lemonade"), or ones the customer gave you, never a
+  third party's brand ("Coca-Cola"). Keep the mock's prices, so pick
+  products that are believable at those prices, and put the totals on the
+  cards from the render, not from your own sums.
+- **App limits:** an app may only offer presets (retail has two font pairs).
+  Pick the closest and say in the report what the kiosk can't show.
+- **`video` fonts** load from Google Fonts: the heading in 400, 700 and
+  italic 400, the body in 400 and 600. If a font lacks one, give `fontsUrl`
+  yourself.
+- Render with `--brand <name>` and check the stills before calling it done.
+
+### Pitch drafts
+
+Asked for a **pitch draft** (an existing story in a prospective customer's
+branding, usually in a Linear session): follow [pitch.md](pitch.md) and
+nothing else here. A pitch writes nothing to the repo, and its researched
+brand is not a brand: never commit it or copy its values into one. When the
+customer agrees to more, make a real brand with the rules above.
+
+### A variant: the story in a customer's words
+
+When a customer video needs its own words (their product, their place), write
+a variant beside the story instead of a copy: `checkout.acme.json`.
+
+    { "extends": "checkout",
+      "brand": "acme",
+      "description": "The checkout story, for Acme.",
+      "title":   { "sub": "Self-service at Acme" },
+      "closing": { "sub": "…" },
+      "cards":   [ { "heading": "A burger *and a lemonade*." }, { … }, { … } ] }
+
+- The steps are always the base story's: a variant changes words and brand,
+  never the flow. Fix the flow in the base, once, for every variant.
+- `cards` gives every card step of the base, in order; each entry, like
+  `title` and `closing`, changes only the fields it names. When the base
+  gains or loses a card, the variant stops loading until it is updated.
+- It films with its own brand only. `/demo-video checkout in acme branding`
+  and the form (story `checkout`, brand `acme`) pick the variant.
+- The same rules as any card: numbers proven by the base's `expectText`s,
+  and the customer's permission for their name (see "A new brand").
+- `check --story checkout.acme` before the PR, and re-check the variants
+  when you change their base.
+
+### Not supported yet
+
+There's no music bed. Videos are silent, so they must work on mute.
+
+## 5. Check, then render
+
+    pnpm --dir <app> exec demo-video check [--story <name>] --json
+
+Without `--story`, commands use the primary story. `check` performs every
+step for real and fails on anything that would film badly:
+
+| It says | Fix |
+|---|---|
+| `"x" is outside the shot …` | The zoom frames the wrong area: zoom on what this shot clicks, or `zoomOut` first |
+| `clicking "x" changes y, which is outside the shot …` | Frame what the click changes, or `zoomOut` right after the click |
+| `N camera push-ins in one chapter` | Push in once on the chapter's area and hold steady |
+| `… only fit in the wide shot` | `frame` things that sit together, or stay wide |
+| `… gives N cards; … has M` | Give the variant one entry per card of its story, in order |
+| `a zoom with nothing in its shot` | Remove it, or act or read something in it |
+| `zoom 2.4; use 1.3–2` | Zoom less: context reads better and stays sharp |
+| `"…" looks like a testid-like name / barcode / code` | Cards are for people: say it in words |
+| `"38" isn't shown by an expectText` | Quote only values an `expectText` checks |
+| `the card announces a chapter in which nothing is done` | Follow it with the steps it describes |
+
+Fix what the report names. Its `visible` list shows what is on screen at the
+failing step. Repeat until it passes, at most 3 rounds; a story that still
+fails is reported as "couldn't show this", with the last report. Then:
+
+    pnpm --dir <app> exec demo-video render [--story <name>] [--brand <name>]
+
+Rendering films every frame (60 fps, frame by frame), so it takes about
+five times the video's length. While tuning, `render --draft` films at
+30 fps in about half the time (`…-draft-demo.mp4`); render the final without
+it. Playwright starts the app's dev server from
+the adapter's `webServer`; if it can't on this machine, start it yourself
+with the same command and env, and it is reused.
+
+## 6. Review like a viewer
+
+Open `<app>/demo/out/review/sheet.jpg` first: one frame a second, the whole
+video at a glance. Then the full-size stills beside it. Judge against
+look.md:
+- **Story:** each statement card is followed by exactly what it says, and
+  the payoff by the result it states.
+- **Camera:** every push-in lands where something then happens; no shot is
+  mostly empty space; each click's result is on screen.
+- **Framing:** pushed-in shots fill the frame and read on a phone; nothing
+  important is cut off; the cursor rests out of the way.
+- **Pacing:** each chapter is one idea; nothing rushed, nothing lingering.
+- **Truth:** every word is true of what's on screen.
+
+Adjust the JSON and re-render. Two rounds of tuning is normal; if it takes
+more, the plan from step 2 is the problem.
+
+## Report
+
+Give:
+- the MP4 path and duration
+- the chapter plan
+- the contact sheet and stills
+- which brand it was rendered with, and for a customer brand, that the
+  video needs the customer's approval before it is published
+- anything the video could not show truthfully (it shows demo fixture data,
+  not a real tenant's)