@tekyzinc/gsd-t 5.16.10 → 5.16.11

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.16.11] - 2026-08-27
+
+### Fixed — the voice fix was the wrong fix, and the gate was measuring the wrong thing
+
+Both corrections came from running the shipped pipeline against real work, and
+both invalidate advice published hours earlier in 5.16.10.
+
+**Pick a text-to-speech service whose voice is a fixed trained speaker.** The
+source run had fought drift with batching — 8 sentences per request so one
+request meant one performance, audio split back apart on silences, splits
+verified, whole takes re-rendered when they measured as drifted. All of that was
+mitigation for a property of the wrong kind of service. A language model's audio
+output treats a voice name as a style hint it re-interprets on every request, so
+the narrator genuinely changes part-way through a video; batching reduces how
+often that happens and cannot stop it, because a batch boundary is still a
+boundary between two readings. Moving to a dedicated speech service, where a
+voice id is a fixed trained speaker, ended it in one change — and took batch
+boundaries, silence splitting, miscut clips and per-model daily quotas with it.
+One sentence per request became both the simple thing and the correct thing. The
+batching guidance is kept, demoted to what to do when you cannot switch.
+
+**Gate on mean pitch, not within-video pitch spread.** The published gate failed
+**nine of the twelve videos its own project had already shipped** — every one
+confirmed by ear as a single steady narrator. A ±35 Hz spread threshold is right
+for a language-model TTS, where a wide spread means a different reading, and
+wrong for a fixed speaker, where it measures ordinary sentence intonation: a
+question rising, a list falling, a short line sitting higher. Flattening that
+would make the narration robotic. The speaker-identity signal is the mean, which
+across those twelve videos sat inside a 7 Hz band. So the gate now checks the
+mean against a calibrated band and reports the spread without gating it — ten of
+twelve pass, and the two that still fail do so on volume, which is real.
+
+The rule this produces, now in the command: **calibrate a gate against output a
+human has already approved before trusting it.** A gate that fails most of your
+known-good work is measuring the wrong thing, and believing it costs you
+re-rendering audio that was already correct.
+
+**Narration lines must be full sentences of 8 words or more.** Integrated
+loudness needs enough audio to measure against; a two-word clip ("Create
+Curriculum.") lands off target, blows the video's volume spread and trips the
+miscut check. This cost two full render cycles before it was diagnosed. When a
+step needs an action the narration does not describe, run it untimed rather than
+inventing a stub line.
+
+**Templates:** `choose()` opens a dropdown, holds it open long enough to read,
+and picks — the choice is the most informative moment in a create-flow, and a
+highlighted select shows the viewer nothing. `enter()` types a value visibly
+rather than filling it instantly. `act()` performs either outside a narrated
+beat, because both only build an action and a bare `await` on one silently does
+nothing. New `cast.mjs` carries every name said aloud in one place.
+
+**Narration guidance rewritten around two woven stories** — the operator's, told
+in their own voice and shown on screen, and the customer's, which is why every
+value typed is that value. The test: a sentence that survives with the names
+removed is explaining the software, not telling the story.
+
+- `commands/gsd-t-demo-videos.md`: Stage 1 rewritten; cast step gains the
+  two-story weave, the products/pricing rule and the dropdown mandate
+- `templates/demo-videos/e2e/cast.mjs`: new
+- `templates/demo-videos/e2e/runtime.ts`: `enter()`, `choose()`, `act()`
+- `templates/demo-videos/e2e/example.{lines.mjs,spec.ts}`: rewritten as a story
+
 ## [5.16.10] - 2026-08-27
 
 ### Added — `/gsd-t-demo-videos`, narrated walkthrough videos of a running app

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.16.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.16.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.

package/commands/gsd-t-demo-videos.md

@@ -39,8 +39,8 @@ transition, and a slideshow does not read as software being used.
 | A **running app with real data** — deployed/preview URL, not a local build with an empty database | An empty tenant on video is indistinguishable from a feature that was never built | Yes — ask for the URL, a login, and the name of a tenant that actually has data |
 | **Playwright** installed | The recorder | Yes — `gsd-t setup-playwright` |
 | **ffmpeg** | Every audio operation | Yes |
-| **auto-editor** (Python venv, bundled into the project, not PATH) | Silence removal, Stage 5 | Yes |
-| A **TTS key** with quota | The narrator | Yes — see § Quota |
+| **auto-editor** (Python venv, bundled into the project, not PATH) | Silence removal, Stage 4 | Yes |
+| A **text-to-speech service with FIXED voices** (e.g. Google Cloud TTS) | The narrator. A language-model TTS re-reads a style hint per request and the voice drifts | Yes — see Stage 1 |
 
 **Ask for the tenant by name.** In the source run, two videos were filmed
 against the wrong location before the right ID was pinned down; the numbering
@@ -118,12 +118,121 @@ Two silent-failure traps seen in practice, worth checking for in any form:
 Also: several elements can carry `role=dialog` (a sidebar, an assistant panel).
 Match a dialog by its title, never `.first()`.
 
-State plainly in the handoff whether seeded data survives (a shared demo site
-often resets nightly).
+**Every cast member must have a script that recreates it.** A shared demo site
+usually resets (nightly is common), so anything the walkthrough names aloud is
+gone by morning — and a walkthrough that references a course which no longer
+exists fails at its first selector. Treat the reset as normal and make the data
+reproducible: one seeder per cast member, re-runnable, and idempotent where the
+app allows it (check whether the record is already there and say so, rather than
+creating a duplicate).
+
+`--seed` re-runs the whole cast, so the day's first recording starts from a known
+state. State plainly in the handoff which parts of the cast are seeded ahead and
+which are created live on camera.
 
 ---
 
-## Step 4 — WRITE the narration as beats
+## Step 4 — CAST the demo (do this BEFORE writing a word)
+
+**A demo that describes what a form is for, while the form sits empty, teaches
+nothing.** The viewer learns that a button exists — not what the software does.
+That is the clinical failure, and it is what this step removes.
+
+**Two stories, woven.** The operator's story is what happens on screen, told in
+their own voice — *"I'm setting fifty-five hours."* The customer's story is why
+every value they type is that value. Neither works alone: the customer alone is a
+bio, the operator alone is a person explaining a form.
+
+| The reason | The decision | On screen |
+|---|---|---|
+| Maya works night shifts | Tyler picks Part 61, not Part 141 | dropdown → **Part 61** |
+| Maya has never flown | Tyler sets 55 hours, not the FAA's 40 | types **55** |
+| Maya can only fly mornings | Tyler assigns James, who flies mornings | dropdown → **James Rivera** |
+
+**The reason comes BEFORE the value, in the same breath** — *"She's on nights,
+so — Part 61."* Value-then-justification is the teacher voice creeping back.
+
+**The tell that you have slipped back into explaining:** a "because" clause
+pointing at the software. *"so it's required rather than optional"*, *"which is
+what the invoice uses later"*, *"the schedule refuses it otherwise"*. Every
+reason must point at the customer, never at the mechanism. Read the finished
+narration aloud: **a sentence that would survive with the names removed is
+explaining the software, and it is wrong.**
+
+Pick real, named specifics and write them down as a cast list before any
+narration is drafted. Not "a course" — a course with a name someone could say out
+loud. Not "a student" — a person with a name.
+
+Put the cast in ONE constants block that both the seeder and the spec import, so
+a name can be changed in a single edit and can never drift between the narration
+and the screen:
+
+```js
+// e2e/walkthrough/cast.mjs — the demo's cast. One edit changes it everywhere.
+export const CAST = {
+  course:  'Private Pilot Certificate — Part 61',
+  student: { first: 'Maya', last: 'Ellison', email: 'maya.ellison@example.com' },
+  // …aircraft, instructor, dates — everything the walkthrough names aloud
+};
+```
+
+**Three rules, and the third is the one a spec silently loses:**
+
+1. **Every named thing is real and specific.** A syllabus with actual stage
+   names, a certificate someone actually earns, a rate someone actually pays.
+   Generic placeholders (`Test Course 1`, `Student A`) read as fake and make the
+   whole demo read as fake with them.
+
+2. **The data is ENTERED on camera, not described — and EVERY DROPDOWN IS
+   OPENED AND PICKED.** The walkthrough types the values and saves. A sentence
+   explaining what a field is for, over an empty field, is the defect.
+
+   A dropdown that is merely highlighted shows nothing: the viewer cannot see
+   what the alternatives were, or that a choice happened at all. **The choice is
+   the most informative moment in a create-flow** — it is where the customer's
+   situation becomes the operator's decision. Use `choose()`, never
+   `highlight()`, on a select.
+
+   If the flow creates something, the demo creates it — that also proves the
+   create-flow works, which describing it never does.
+
+3. **The names CARRY FORWARD.** Once the course is created, every later sentence
+   says that course BY NAME. Once the student is enrolled, they are referred to
+   by name for the rest of the video — "Maya's next lesson", not "the student's
+   next lesson". This is what makes the walkthrough one story instead of a tour
+   of screens. It is easy to lose because each step is written independently, so
+   check it as a pass over the finished narration: **a sentence that says "the
+   student" or "the course" after the cast has been introduced is a bug.**
+
+**Give any value with a symbol or abbreviation a spoken twin.** The narrator
+reads text literally, so `$185/hr` comes out as "dollar one eight five slash h
+r" and `9:00 AM` as "nine colon zero zero A M". Keep the typed value for the
+form field and a said-aloud version for the sentence, both in the cast block.
+
+**Price it with the real billable parts.** A course, a plan or a subscription is
+the SUM of the things a charge attaches to, so build those things on camera and
+attach them — not one summary price. In the flight-school example that is four
+products: the airplane per hour, the instructor per hour, ground instruction per
+hour, and the materials kit once. The payoff line is the one that makes the whole
+section land: *"an hour of dual bills Maya two-sixty — a hundred and eighty-five
+for the airplane, seventy-five for James"* is arithmetic the viewer just watched
+being set up.
+
+**Order the walkthrough as the real-life sequence**, so each screen is visited
+because the previous one made it necessary: build the course → enrol the named
+student → schedule their first lesson → fly it → bill it. That ordering is what
+makes the dependency context land ("before you can schedule a student for a
+course, a program must exist and be linked to a course") instead of being
+asserted.
+
+**When creation hits a guardrail**, that is information, not a blocker — the app
+refusing an incomplete enrolment is worth showing. But do not fight it on camera:
+fall back to an existing named record, and say in the handoff which parts of the
+cast are created live and which are pre-seeded.
+
+---
+
+## Step 5 — WRITE the narration as beats
 
 Two files per walkthrough, and the separation is load-bearing:
 
@@ -146,12 +255,19 @@ Narration rules, each from a user correction:
   reads from it.
 - **Count what is on screen before writing about it.** "Eight-step wizard" shipped
   in a video where the UI says *Step 1 of 9*.
+- **Say the cast's names, every time.** After Step 4's cast is introduced, "the
+  student" and "the course" are bugs — it is *Maya Ellison* and the *Private
+  Pilot Certificate — Part 61*. Read the finished narration once looking only
+  for this.
+- **Narrate the value being typed, not the field's purpose.** "Her first lesson
+  is Tuesday at nine, with James in the Cessna 172" — not "you would select a
+  date, an instructor and an aircraft here".
 - **Naming a whole strip highlights the strip; making a point about one control
   highlights that control; navigating by it moves the mouse and clicks it.**
 
 ---
 
-## Step 5 — the five-stage build
+## Step 6 — the five-stage build
 
 Run in this order, every time. Nothing here is optional.
 
@@ -171,68 +287,72 @@ recordings to find. Preflight walks the same screens without recording and
 reports **every** missing target in one pass. It never asserts; it prints a
 report. The real gate is still the recording itself.
 
-### Stage 1 — Voice (the hardest-won stage)
-
-**Cause of tone drift, confirmed: one API request per sentence.** The model
-re-decides its delivery on every request, so the narrator audibly changed within
-a single video. Describing the speaker in the prompt does not fix it — it is
-being asked to act, fresh, dozens of times.
-
-Two deterministic fixes, neither of which rests on listening and deciding it
-sounds fine:
-
-**Volume — forced.** Every clip goes through a two-pass ffmpeg `loudnorm` to the
-same target (EBU R128, −18 LUFS). Measured effect: within-video drift went from
-as much as **7.5 dB to ~0.5 dB**, and every video sits at exactly −18.0 so they
-match each other too. A normalise-only script fixes existing clips with no API
-calls.
-
-**Tone — batched, then verified.** Sentences go **8 per request**, numbered, with
-an instruction to leave two seconds of silence between them; the returned audio is
-cut back apart on those silences. One request means one performance.
-
-> **BATCH SIZE IS 8 AND THAT WAS MEASURED.** Bigger is not better: an 18-line
-> script as a single take gave a pitch spread of **46 Hz**; the same script in
-> 8-line batches gave **16 Hz**. Line-by-line pitch tracing showed why — the
-> narrator holds ~100–115 Hz for a dozen lines then slips (140 Hz at line 15),
-> losing the persona the further it gets from the instruction. Re-measure before
-> changing it.
-
-**The split is verified, never assumed.** If a batch does not come back with the
-expected number of gaps, retry it; if it still disagrees, render those lines one
-at a time. Each piece must also be about as long as its sentence takes to say
-(~2.8 words/sec, accepted band 0.6×–1.7×). A wrong split puts half a sentence on
-the wrong step — worse than the drift it was meant to cure.
-
-**The gate.** Measure three numbers per clip and report the **spread** across the
-video: loudness (LUFS), pitch (median fundamental, Hz), speaking rate (energy
-peaks/sec), plus **miscut** clips. Thresholds: volume 1.5 dB, pitch 35 Hz, rate
-5/s, zero miscuts.
-
-**Ensure, don't check.** Render → measure → **throw the take away and re-render
-if it drifts** (3 attempts, then halt rather than ship). This is not theoretical:
-one video's first take came back at 46 Hz and was discarded for a 15 Hz one;
-another needed all three attempts (44 → 41 → 31 Hz).
-
-> **Do not trust a single A/B run.** A "persona anchor" prompt looked like a large
-> win (7 Hz vs plain) and reversed on the next run (21 Hz vs 9 Hz). It was
-> run-to-run variance. Two renders of the same prompt genuinely differ — which is
-> exactly why the gate exists instead of a one-time tuning pass.
-
-**Keep the voice identical across the whole set**, not just within a video. Voice
-name, speed, model, target loudness and persona text all belong in the cache key:
-change any one and the video re-renders rather than mixing two deliveries.
-
-**Retry every one of these** — each returned something other than usable audio and
-was fatal until handled:
-
-| Symptom | Handling |
-|---|---|
-| transient `400 INVALID_ARGUMENT` | retry — the identical request succeeds moments later |
-| `200` carrying no audio | retry — the model answered without speech |
-| a call with no deadline | time it out; a hung render looks exactly like a working one |
-| a crashed attempt | the ensure loop catches it and retries, rather than losing the video |
-| `429` per-day quota | switch model or key — see § Quota |
+### Stage 1 — Voice
+
+**Pick a text-to-speech service whose voice is a FIXED TRAINED SPEAKER, not a
+language model reading a style hint.** This one choice decides whether the
+narrator can drift at all, and everything else in this stage follows from it.
+
+The source run learned it the expensive way. It started on a language model's
+audio output (Gemini `generateContent`), where a voice name is a *style hint the
+model re-interprets on every request* — so the narrator audibly changed
+part-way through a video. Enormous effort went into mitigation: batching 8
+sentences per request so one request meant one performance, splitting the
+returned audio back apart on silences, verifying every split, and re-rendering
+whole takes that measured as drifted. It reduced how OFTEN the voice changed and
+could never stop it, because **a batch boundary is still a boundary between two
+different readings**.
+
+Moving to a dedicated speech service (Google Cloud Text-to-Speech) ended it in
+one change. A voice id there is a fixed trained speaker: the same id returns the
+same speaker every time, forever. That removed batch boundaries, silence
+splitting, miscut clips, per-model daily quotas, and drift — all at once — and
+made **one sentence per request** both the simple thing and the correct thing.
+
+> **If you are on a language-model TTS and cannot switch**, the mitigation is
+> batching: 8 sentences per request (measured — an 18-line single take spread
+> 46 Hz of pitch, 8-line batches 16 Hz), a verified split that retries rather
+> than guessing where a sentence ended, and a re-render loop. Treat it as a
+> workaround, not a design.
+
+**Volume is forced, on every service.** Two-pass ffmpeg `loudnorm` to a fixed
+target (EBU R128, −18 LUFS). Measured on the shipped set: ±0.3–0.7 dB within a
+video, every video landing on the same target so they match each other too. This
+is worth doing even with a fixed speaker — it is the one number a service will
+not hold steady for you.
+
+**Every narration line must be a full sentence — 8 words or more.** Integrated
+loudness needs enough audio to measure against; a two- or three-word clip
+("Create Curriculum.") lands off target and blows the video's volume spread,
+and also trips miscut and speaking-rate checks. If a step needs an action the
+narration does not describe, run it untimed rather than inventing a stub line.
+
+### The gate — measure IDENTITY, not expressiveness
+
+Measure per clip and report across the video: loudness (LUFS), pitch (median
+fundamental, Hz), speaking rate (energy peaks/sec), and **miscut clips** — a
+clip whose length is far from what its sentence should take to say.
+
+**Gate on the MEAN pitch, not the within-video spread.** This is the correction
+that matters, and it was found by running the gate against twelve videos a human
+had already confirmed sounded perfect: **a ±35 Hz spread threshold failed nine
+of them.** Within-video pitch spread is ordinary sentence intonation — a
+question rising, a list falling, a short line sitting higher — and flattening it
+would make the narration robotic. The speaker-identity signal is the mean: across
+those same twelve videos it sat in a 7 Hz band (102–109 Hz), which is what a
+fixed speaker looks like.
+
+Working thresholds: volume ±1.5 dB, mean pitch inside a band calibrated from
+known-good output, rate ±5.5/s, zero miscuts.
+
+> **Calibrate a gate against output a human has approved, before trusting it.**
+> A gate that fails most of your known-good work is measuring the wrong thing,
+> and the cost of believing it is re-rendering audio that was already correct.
+
+**Ensure, don't just check.** Render → measure → re-render if it fails (3
+attempts, then halt rather than ship). Even with a fixed speaker this catches a
+bad take: `build-a-course` failed its first attempt on volume and passed the
+second.
 
 ### Stage 2 — Record
 
@@ -302,7 +422,7 @@ The user's verdict on this stage was "It's perfect. Run this after every video."
 
 ---
 
-## Step 6 — VERIFY before showing the user
+## Step 7 — VERIFY before showing the user
 
 The user should never be the one who finds these. Check, per video:
 
@@ -319,12 +439,28 @@ The user should never be the one who finds these. Check, per video:
    `highlight` → `goto` adjacency. (Audited at 22 instances across 6 videos in
    the source run.)
 6. **Counts in the narration match the UI** — tabs, wizard steps, row counts.
+7. **The cast is named throughout** — grep the finished narration for "the
+   student", "the course", "a user", "the aircraft". After the cast is
+   introduced, each of those is a line that should say a name instead.
+8. **Data was entered, not described** — any step whose sentence explains what a
+   field is for should be typing into that field. A form that stays empty while
+   the narration explains it is the clinical failure this exists to prevent.
+9. **Every dropdown was opened and picked** — grep the spec for `highlight(`
+   on a select; each one should be `choose()`. The step log records `choose`
+   as its own action, so count them against the number of selects in the flow.
 
 Then show the user each video as it finishes, not in a batch at the end.
 
 ---
 
-## Quota — it is per PROJECT and per MODEL
+## Quota and auth — only if you are on a language-model TTS
+
+A dedicated speech service typically bills per character with no per-model daily
+cap, and authenticates with a cloud login rather than an API key (Google Cloud
+TTS is OAuth-only — it refuses an API key, and needs a quota project). If that is
+what you are on, this section does not apply.
+
+On a language-model TTS the quota rules bite hard:
 
 - A free tier can be as low as **10 requests per day per model**, and the error
   names it (`…PerDayPerProjectPerModel-FreeTier`). It dies almost immediately.
@@ -351,12 +487,14 @@ docs/demo-videos/HANDOFF.md              hard-won facts, bugs found, what is ope
 docs/demo-videos/walkthrough-<name>.mp4  output (gitignore it)
 e2e/walkthrough/<name>.lines.mjs         narration, one sentence per entry
 e2e/walkthrough/<name>.spec.ts           what happens on screen per sentence
-e2e/walkthrough/runtime.ts               step(), highlight(), click(), goTo()
+e2e/walkthrough/runtime.ts               step(), highlight(), click(), enter(), choose(), act(), goTo()
+e2e/walkthrough/cast.mjs                 the demo's cast — every name said aloud
 e2e/walkthrough/signin.ts                shared sign-in + the tenant constant
 e2e/walkthrough/manifest.ts              loads narration; skips if audio is missing
 e2e/walkthrough/preflight.spec.ts        checks every target without recording
-scripts/walkthrough-voice.mjs            batched TTS, loudness-normalised
-scripts/walkthrough-voice-check.mjs      measures spread + miscuts; exit 4 on drift
+scripts/walkthrough-voice-gcloud.mjs     the narrator — fixed-voice TTS, one sentence/request
+scripts/walkthrough-voice.mjs            SUPERSEDED — batched language-model TTS
+scripts/walkthrough-voice-check.mjs      volume spread + MEAN-pitch identity + miscuts; exit 4
 scripts/walkthrough-voice-ensure.mjs     render → measure → re-render → halt
 scripts/walkthrough-normalise.mjs        force existing clips to one loudness
 scripts/walkthrough-mux.mjs              lay audio on the recording

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.16.10",
+  "version": "5.16.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/demo-videos/README.md

@@ -71,11 +71,12 @@ videos in the source run.
 
 | File | Role |
 |---|---|
-| `e2e/runtime.ts` | `step()`, `highlight()`, `click()`, `goTo()`; narration is the clock; throws when a sentence has no visible target |
+| `e2e/runtime.ts` | `step()`, `highlight()`, `click()`, `enter()`, `choose()`, `act()`, `goTo()`; narration is the clock; throws when a sentence has no visible target |
 | `e2e/manifest.ts` | loads narration; a spec **skips** when its audio is missing rather than failing the run |
 | `e2e/signin.ts` | shared sign-in + the tenant constant — **ask for this, don't derive it** |
 | `e2e/preflight.spec.ts` | walks every target without recording, reports all misses in one pass |
-| `e2e/example.lines.mjs` | narration shape, with the writing rules |
+| `e2e/cast.mjs` | **the demo's cast** — Tyler (the voice), Maya (the reason), the syllabus and the priced products; spoken twins for anything with a symbol |
+| `e2e/example.lines.mjs` | narration shape, with the writing rules — follows one named student through one named course |
 | `e2e/example.spec.ts` | spec shape, with the overlay/settle rules |
 | `scripts/walkthrough-voice.mjs` | batched TTS (8/request), verified split, two-pass loudnorm |
 | `scripts/walkthrough-voice-check.mjs` | measures LUFS/pitch/rate spread + miscuts; **exit 4** on drift |

package/templates/demo-videos/e2e/cast.mjs

@@ -0,0 +1,104 @@
+/**
+ * The demo's CAST — every name and value the walkthrough says out loud or types.
+ *
+ * TWO STORIES, WOVEN
+ * ------------------
+ * Tyler owns the flight school; his is the story on screen, in his own voice.
+ * Maya is why every value he types is THAT value. Neither works alone — Maya
+ * by herself is a bio, Tyler by himself is a man explaining a form.
+ *
+ *   Maya works night shifts   ->  Tyler picks Part 61, not Part 141
+ *   Maya has never flown      ->  Tyler sets 55 hours, not the FAA's 40
+ *   Maya can only fly mornings->  Tyler assigns James, who flies mornings
+ *
+ * The reason comes BEFORE the value, in the same breath: "She's on nights, so —
+ * Part 61." Value-then-justification is the teacher voice creeping back.
+ *
+ * THREE RULES:
+ *   1. Real and specific. "Private Pilot Certificate — Part 61", not
+ *      "Test Course 1". A generic placeholder makes the whole demo read as fake.
+ *   2. ENTERED on camera, not described — including EVERY DROPDOWN. A select
+ *      that is merely highlighted shows nothing: the viewer cannot see what the
+ *      alternatives were or that a choice was made. Open it, pick the value.
+ *   3. The names CARRY FORWARD. After the cast is introduced, every later
+ *      sentence uses the name — "Maya's first lesson", never "the student's".
+ *
+ * The example is a flight school; replace it with your own domain. The SHAPE is
+ * what matters: a person with a reason, an operator with a decision, and the
+ * exact values that get typed and picked.
+ */
+
+/** The narrator. He speaks in the first person — his school, his decisions. */
+export const TYLER = { name: 'Tyler', role: 'flight school owner' };
+
+/** The reason every value below is the value it is. */
+export const MAYA = {
+  first: 'Maya',
+  last: 'Ellison',
+  short: 'Maya',
+  email: 'maya.ellison@example.com',
+  phone: '(480) 555-0142',
+  /** The facts Tyler's choices answer to. Each one drives a field. */
+  age: 24,
+  ageSpoken: 'twenty-four',
+  job: 'works nights at the hospital',
+  experience: 'has never flown anything',
+  goal: 'her private pilot license by spring',
+  availability: 'Weekday mornings',
+};
+
+export const STUDENT_NAME = `${MAYA.first} ${MAYA.last}`;
+
+/** The course Tyler builds for her. */
+export const COURSE = {
+  name: 'Private Pilot Certificate — Part 61',
+  /** Dropdown selections — each is OPENED and PICKED on camera. */
+  certificate: 'Private Pilot',
+  regulation: 'Part 61',
+  category: 'Airplane, Single-Engine Land',
+  /** Typed. 55 not 40, because nobody finishes in the FAA minimum. */
+  hours: '55',
+  hoursSpoken: 'fifty-five',
+};
+
+/** The syllabus, in the order Maya flies it. Each stage is typed + typed-picked. */
+export const STAGES = [
+  { name: 'Ground School',            type: 'Ground',        hours: '15', spoken: 'fifteen' },
+  { name: 'Pre-Solo Flight Training', type: 'Dual',          hours: '20', spoken: 'twenty' },
+  { name: 'Solo Flight',              type: 'Solo',          hours: '10', spoken: 'ten', endorsement: true },
+  { name: 'Cross-Country',            type: 'Dual and Solo', hours: '5',  spoken: 'five' },
+  { name: 'Checkride Preparation',    type: 'Dual',          hours: '5',  spoken: 'five' },
+];
+
+/**
+ * PRODUCTS — everything a charge can be applied to.
+ *
+ * The sum of a course's products is what an invoice is built from, so these are
+ * created first and then attached to the course. This is the spine of the
+ * story: build the chargeable things, attach them, and the invoice falls out.
+ */
+export const PRODUCTS = [
+  { name: 'Cessna 172 — N172SA',   type: 'Aircraft Rental', price: '185', unit: 'per hour', wet: true },
+  { name: 'Flight Instruction — CFI', type: 'Instructor Time', price: '75',  unit: 'per hour' },
+  { name: 'Ground Instruction',    type: 'Instructor Time', price: '65',  unit: 'per hour' },
+  { name: 'Private Pilot Kit',     type: 'Materials',       price: '289', unit: 'One-time' },
+];
+
+/** Everything else Tyler names aloud. */
+export const INSTRUCTOR = { name: 'James Rivera', short: 'James', why: 'flies mornings, good with first-timers' };
+export const AIRCRAFT = { tail: 'N172SA', tailSpoken: 'November one seven two Sierra Alpha', type: 'Cessna 172' };
+export const FIRST_LESSON = { day: 'Tuesday', time: '9:00 AM', timeSpoken: 'nine in the morning' };
+
+/**
+ * SPOKEN forms. The narrator reads text literally, so "$185/hr" comes out as
+ * "dollar one eight five slash h r" and "9:00 AM" as "nine colon zero zero A M".
+ * The typed value goes in the form; these go in the sentence.
+ */
+export const SPOKEN = {
+  aircraftRate:   'a hundred and eighty-five',
+  cfiRate:        'seventy-five',
+  groundRate:     'sixty-five',
+  kitPrice:       'two hundred and eighty-nine',
+  dualHourTotal:  'two-sixty',
+  courseTotal:    'about thirteen thousand, four hundred',
+};

package/templates/demo-videos/e2e/example.lines.mjs

@@ -1,28 +1,79 @@
 /**
  * TEMPLATE — the narration for one walkthrough. Nothing but sentences.
  *
- * A BEAT IS ONE IDEA BEING EXPLAINED, NOT ONE SCREEN. A beat may dwell on three
- * things within a screen, or carry across a navigation. Building around screens
- * is what produced fixed-length steps and the drift that followed.
+ * THIS IS A STORY, NOT A TOUR. Tyler owns the school and speaks in his own
+ * voice; Maya is why every value he types is that value. Read it aloud: if a
+ * sentence would survive with the names removed, it is explaining the software
+ * instead of telling the story, and it is wrong.
+ *
+ * The failure this replaces: "Her contact details are what the school will use
+ * to reach her, so they're required rather than optional" — a sentence about a
+ * form. What it should say: "Maya's asleep by eight most nights, so mornings
+ * are all she has" — a fact about Maya that lands in a field.
+ *
+ * THE TELL: a "because" clause pointing at the software. "so it's required",
+ * "which is what the invoice uses later", "the schedule refuses it otherwise".
+ * Every reason must point at Maya, never at the mechanism.
  *
  * Rules, each from a user correction in the source run:
- *   - Never name something the viewer cannot see. If the sentence names a
- *     thing, the matching step must point at that thing.
- *   - Don't invent jargon. Not "groups" — "the left sidebar's top-level menus,
- *     which expand to show…".
+ *   - EVERY DROPDOWN IS OPENED AND PICKED, and the sentence says the chosen
+ *     value. A highlighted select shows nothing — the viewer cannot see what
+ *     the alternatives were, or that a choice happened at all.
+ *   - The reason comes BEFORE the value, in the same breath. "She's on nights,
+ *     so — Part 61." Not the value followed by a justification.
+ *   - Narrate the VALUE, not the field's purpose. "Fifty-five hours, because
+ *     nobody finishes in forty" — not "you would enter the hours here".
+ *   - Use the SPOKEN form of any value with a symbol or abbreviation. The
+ *     narrator reads literally: "$185/hr" becomes "dollar one eight five slash
+ *     h r". cast.mjs carries a said-aloud twin for those.
+ *   - Don't invent jargon. Not "groups" — "the left sidebar's top-level menus".
  *   - Explain, don't sell. No "exciting", no "powerful", no enthusiasm.
- *   - Give the dependency context: why this screen exists, and what downstream
- *     reads from it.
  *   - COUNT WHAT IS ON SCREEN before writing about it. "Eight-step wizard"
  *     shipped in a video where the UI said "Step 1 of 9".
  *
  * The order here is the order in the spec. Index N of LINES is L[N] there.
  */
+import {
+  AIRCRAFT, COURSE, FIRST_LESSON, INSTRUCTOR, MAYA, PRODUCTS, SPOKEN, STAGES, STUDENT_NAME,
+} from './cast.mjs';
+
+const [PLANE, CFI, GROUND, KIT] = PRODUCTS;
+
 export const LINES = [
-  "Before anyone can book a flight, the aircraft has to exist here, at the location it lives at.",
-  "The four cards across the top are the fleet's condition right now: how many are available, how many are grounded, how many open squawks there are, and how much maintenance is coming due.",
-  "Below that is the fleet itself. Seven aircraft at this location, each with its hourly rate.",
-  "That rate is what turns a flight into money later, so it belongs to the aircraft, not to the booking.",
-  "Opening an aircraft gives you its full record, and the record has seven tabs — each one a different kind of history for the same airframe.",
-  "So: register the aircraft, set its rate, keep its maintenance and its logbook current. Everything downstream reads from this record.",
+  // ── Why this course exists ──────────────────────────────────────────────
+  `${STUDENT_NAME} walked into my school on Monday. She's ${MAYA.ageSpoken}, ${MAYA.job}, ${MAYA.experience}. She wants ${MAYA.goal}.`,
+  `I don't have a course she can join, so I'm building the one she'll fly.`,
+
+  // ── The course ──────────────────────────────────────────────────────────
+  `The ${COURSE.name}. That's the license itself — fly a small plane, day or night, carry passengers, just not for money.`,
+  `Certificate type, ${COURSE.certificate}. That's what she walks out with.`,
+  `${MAYA.short}'s on night shifts and can't hold to a fixed school timetable, so — ${COURSE.regulation}. It lets her fly when she's free. Part 141 would have locked her into my schedule.`,
+  `I'm setting ${COURSE.hoursSpoken} hours. The FAA minimum is forty and nobody finishes in forty — fifty-five is what my students actually take, and I'd rather quote ${MAYA.short} a number she'll hit.`,
+  `${COURSE.category}. She'll train in the one-seventy-twos.`,
+
+  // ── The syllabus, in the order she flies it ─────────────────────────────
+  `Now the syllabus. Five stages, in the order ${MAYA.short} flies them.`,
+  `${STAGES[0].name} — weather, regulations, navigation, radio work. All on the ground, ${STAGES[0].spoken} hours of it, before she touches an airplane.`,
+  `${STAGES[1].name}. Takeoffs, landings, stalls, emergencies — ${STAGES[1].spoken} hours of dual, meaning ${INSTRUCTOR.short} is beside her the whole time.`,
+  `${STAGES[2].name}. ${STAGES[2].spoken} hours, and the first of them is the day ${MAYA.short} takes off by herself. It needs my endorsement — I sign that off, nobody else.`,
+  `${STAGES[3].name}. ${STAGES[3].spoken} hours of long flights to airports she has never seen, navigating there and back.`,
+  `${STAGES[4].name}. The last ${STAGES[4].spoken} hours, flying to the standard an examiner will hold her to.`,
+
+  // ── The products — everything a charge attaches to ──────────────────────
+  `Now what ${MAYA.short} actually pays for. Every chargeable thing is its own product, and a course is the sum of the products on it.`,
+  `The airplane. ${PLANE.name}, ${SPOKEN.aircraftRate} an hour, wet — fuel included, so ${MAYA.short} isn't doing arithmetic after every lesson.`,
+  `${CFI.name}, ${SPOKEN.cfiRate} an hour. That's ${INSTRUCTOR.short} in the right seat, and it bills whether they fly or sit out a weather delay.`,
+  `${GROUND.name}, ${SPOKEN.groundRate}. Cheaper, because there's no airplane on the clock.`,
+  `And the ${KIT.name} — ${SPOKEN.kitPrice}, one time. Her books, charts, plotter and headset, bought on day one.`,
+  `All four go onto the course.`,
+  `So an hour of dual bills ${MAYA.short} ${SPOKEN.dualHourTotal} — ${SPOKEN.aircraftRate} for the airplane, ${SPOKEN.cfiRate} for ${INSTRUCTOR.short}. Her ${COURSE.hoursSpoken} hours come to ${SPOKEN.courseTotal}, and that's the number I quote her.`,
+  `The ${COURSE.name} is open for enrollment.`,
+
+  // ── Maya ────────────────────────────────────────────────────────────────
+  `Now ${MAYA.short} herself.`,
+  `She's asleep by eight most nights, so — ${MAYA.availability}. That's all she has.`,
+  `Into the ${COURSE.name}. She's the first one in it.`,
+  `${INSTRUCTOR.name} takes her. He ${INSTRUCTOR.why}.`,
+  `Her first lesson: ${FIRST_LESSON.day}, ${FIRST_LESSON.timeSpoken}, in ${AIRCRAFT.tailSpoken}. Ground School, hour one.`,
+  `That's ${MAYA.short}'s ${COURSE.hoursSpoken} hours laid out in front of her. ${FIRST_LESSON.day} morning she starts the first one.`,
 ];

package/templates/demo-videos/e2e/example.spec.ts

@@ -1,52 +1,143 @@
 /**
- * TEMPLATE — one continuous recorded walkthrough.
+ * TEMPLATE — one continuous recorded walkthrough, following a named cast.
  *
  * One sentence, one thing on screen, in the same order as the .lines.mjs file.
  * The step's LENGTH comes from the measured audio; nothing here sets a duration
  * except the settle waits after a navigation.
  *
- *   highlight(x)  outline it, mouse stays put     (naming something)
- *   click(x)      mouse glides to it and clicks   (operating something)
- *   goTo(url)     navigate                        (jumping elsewhere)
- *   none()        no target — ONLY for a genuinely abstract line
+ *   highlight(x)      outline it, mouse stays put     (naming something)
+ *   click(x)          mouse glides to it and clicks   (operating something)
+ *   enter(x, value)   type a REAL value into a field  (entering data)
+ *   choose(x, option) OPEN a dropdown and pick        (making a decision)
+ *   goTo(url)         navigate                        (jumping elsewhere)
+ *   none()            no target — ONLY for a genuinely abstract line
+ *
+ * EVERY DROPDOWN USES choose(), NEVER highlight(). A select that is merely
+ * outlined shows nothing: the viewer cannot see what the alternatives were, or
+ * that a choice was made at all. The choice IS the story — it is where Maya's
+ * situation becomes Tyler's decision.
+ *
+ * VALUES COME FROM cast.mjs, never retyped as literals here. A name in two
+ * places will eventually disagree with itself, and then the narration says one
+ * thing while the screen shows another.
  *
  * AVOID highlight() IMMEDIATELY FOLLOWED BY goTo(). On camera that reads as
- * "they clicked that thing and it took us here" — and they did not. Click the
- * real navigation, or park the cursor somewhere neutral first.
+ * "they clicked that thing and it took us here" — and they did not.
  */
 import { test } from '@playwright/test';
 import { loadNarration } from './manifest';
 import { LOC, signInAsAdmin } from './signin';
-import { click, highlight, installOverlay, none, startRun, step, writeRunLog } from './runtime';
+import { AIRCRAFT, COURSE, INSTRUCTOR, MAYA, PRODUCTS, STAGES, STUDENT_NAME } from './cast.mjs';
+import {
+  act, choose, click, enter, highlight, installOverlay, none, startRun, step, writeRunLog,
+} from './runtime';
 
 const NAME = 'example';
 const { ready, audio: AUDIO, L } = loadNarration(NAME);
+const [PLANE, CFI, GROUND, KIT] = PRODUCTS;
+
+/** Settle after a navigation. 6-8s, not 5 — a 5s read shows a populated page as empty. */
+const SETTLE = 7000;
 
 test(`walkthrough — ${NAME}`, async ({ page }) => {
   // A spec whose audio is not rendered SKIPS. Playwright imports every spec
   // before applying --grep, so throwing here takes down the whole run.
   test.skip(!ready, 'narration not rendered yet');
-  test.setTimeout(20 * 60_000);
+  test.setTimeout(25 * 60_000);
 
   startRun(AUDIO as never);
   await signInAsAdmin(page);
 
-  await page.goto(`/location/${LOC}/{route}`, { waitUntil: 'domcontentloaded' });
-  await page.waitForTimeout(6000);        // 6-8s, not 5 — see the settle note
-  await installOverlay(page);
+  const settle = async (ms = SETTLE) => {
+    await page.waitForTimeout(ms);
+    await installOverlay(page);   // the overlay does not survive a navigation
+  };
+  const field = (label: string) => page.getByLabel(new RegExp(label, 'i'));
+  const button = (name: string) => page.getByRole('button', { name: new RegExp(name, 'i') });
 
-  await step(page, L[0], none());
-  await step(page, L[1], highlight(page.getByText(/{Card Title}/i)));
-  await step(page, L[2], highlight(page.getByText(/{List Heading}/i)));
-  await step(page, L[3], highlight(page.getByText(/{Rate}/i).first()));
+  // ── Why this course exists ──────────────────────────────────────────────
+  await page.goto(`/location/${LOC}/{programs-route}`, { waitUntil: 'domcontentloaded' });
+  await settle();
 
-  await step(page, L[4], click(page.getByRole('button', { name: /{Open Record}/i })));
-  // Re-install the overlay after every navigation — the cursor and highlight
-  // layers are injected into the page and do not survive one.
-  await page.waitForTimeout(6000);
+  await step(page, L[0], none());                                  // Maya walked in
+  await step(page, L[1], click(button('{New Program}')));          // so I'm building it
+  await settle(2500);
+
+  // ── The course ──────────────────────────────────────────────────────────
+  await step(page, L[2], enter(field('{Program Name}'), COURSE.name));
+  await step(page, L[3], choose(field('{Certificate}'), COURSE.certificate));
+  await step(page, L[4], choose(field('{Regulation}'), COURSE.regulation));
+  await step(page, L[5], enter(field('{Total Hours}'), COURSE.hours));
+  await step(page, L[6], choose(field('{Category}'), COURSE.category));
+
+  // ── The syllabus — one stage per line, each named, typed and picked ─────
+  await step(page, L[7], click(button('{Add Stage}')));
+  await settle(2000);
+
+  for (const [i, stage] of STAGES.entries()) {
+    // Each stage is one narrated beat: name it, and the type is what the
+    // sentence is actually about (Ground vs Dual vs Solo).
+    await step(page, L[8 + i], enter(field('{Stage Name}'), stage.name));
+    // act(), not a bare await — choose() only BUILDS an action; awaiting one
+    // does nothing and leaves the field empty.
+    await act(page, choose(field('{Stage Type}'), stage.type));
+    await act(page, enter(field('{Stage Hours}'), stage.hours));
+    if (stage.endorsement) await page.getByLabel(/{endorsement}/i).check().catch(() => {});
+    await button('{Add Stage}').click().catch(() => {});
+    await page.waitForTimeout(800);
+  }
   await installOverlay(page);
 
-  await step(page, L[5], none());
+  // ── The products — everything a charge attaches to ──────────────────────
+  await page.goto(`/location/${LOC}/{products-route}`, { waitUntil: 'domcontentloaded' });
+  await settle();
+
+  await step(page, L[13], none());                                 // what Maya pays for
+
+  // Four products, created on camera. L[14..17] each narrate one.
+  for (const [i, product] of PRODUCTS.entries()) {
+    await step(page, L[14 + i], click(button('{New Product}')));
+    await settle(2000);
+    await act(page, enter(field('{Product Name}'), product.name));
+    await act(page, choose(field('{Product Type}'), product.type));
+    await act(page, enter(field('{Price}'), product.price));
+    await act(page, choose(field('{Billing}'), product.unit));
+    await button('^Save').click().catch(() => {});
+    await settle(3000);
+  }
+
+  // Attach all four to the course — the sum of these IS the invoice.
+  await page.goto(`/location/${LOC}/{programs-route}`, { waitUntil: 'domcontentloaded' });
+  await settle();
+  await step(page, L[18], choose(field('{Products}'), PLANE.name));
+  for (const p of [CFI, GROUND, KIT]) await act(page, choose(field('{Products}'), p.name));
+
+  await step(page, L[19], highlight(page.getByText(/{Total}|{Estimated}/i).first()));
+  await step(page, L[20], click(button('{Publish}')));
+  await settle();
+
+  // ── Maya ────────────────────────────────────────────────────────────────
+  await page.goto(`/location/${LOC}/{students-route}`, { waitUntil: 'domcontentloaded' });
+  await settle();
+
+  await step(page, L[21], click(button('{Add Student}')));
+  await settle(2500);
+  await act(page, enter(field('{Full Name}'), STUDENT_NAME));
+  await act(page, enter(field('{Email}'), MAYA.email));
+  await act(page, enter(field('{Phone}'), MAYA.phone));
+
+  await step(page, L[22], choose(field('{Availability}'), MAYA.availability));
+  await step(page, L[23], choose(field('{Enroll}'), COURSE.name));
+  await step(page, L[24], choose(field('{Instructor}'), INSTRUCTOR.name));
+  await button('^Save').click().catch(() => {});
+  await settle();
+
+  // ── Her first lesson ────────────────────────────────────────────────────
+  await page.goto(`/location/${LOC}/{schedule-route}`, { waitUntil: 'domcontentloaded' });
+  await settle();
+
+  await step(page, L[25], highlight(page.getByText(new RegExp(AIRCRAFT.tail, 'i')).first()));
+  await step(page, L[26], highlight(page.getByText(new RegExp(STUDENT_NAME, 'i')).first()));
 
   // The step log is the proof of what was on screen when. The mux reads it.
   writeRunLog(NAME);

package/templates/demo-videos/e2e/runtime.ts

@@ -29,7 +29,7 @@ export interface StepLog {
   audioMs: number;
   route: string;
   focus: string;
-  action: 'highlight' | 'click' | 'goto' | 'none';
+  action: 'highlight' | 'click' | 'type' | 'choose' | 'goto' | 'none';
 }
 
 const log: StepLog[] = [];
@@ -134,11 +134,34 @@ async function reveal(page: Page, loc: Locator): Promise<Locator | null> {
 export type Action =
   | { kind: 'highlight'; loc: Locator }
   | { kind: 'click'; loc: Locator }
+  | { kind: 'type'; loc: Locator; value: string }
+  | { kind: 'choose'; loc: Locator; option: string }
   | { kind: 'goto'; url: string }
   | { kind: 'none' };
 
 export const highlight = (loc: Locator): Action => ({ kind: 'highlight', loc });
 export const click = (loc: Locator): Action => ({ kind: 'click', loc });
+/**
+ * Type a REAL value into a field, visibly, while the sentence says it.
+ *
+ * This is the action that makes a demo concrete instead of clinical. A sentence
+ * explaining what a field is for, over an empty field, teaches nothing — so the
+ * narration says the value and this puts it on screen, character by character
+ * so the viewer can read it going in.
+ */
+// Named `enter`, not `type` — `import { type X }` is TypeScript's type-only
+// import syntax, so an exported `type` is a trap for whoever imports it.
+export const enter = (loc: Locator, value: string): Action => ({ kind: 'type', loc, value });
+/**
+ * Open a dropdown, let the options be READ, then pick one.
+ *
+ * The most informative moment in a create-flow is the choice: it is where the
+ * specific decision becomes visible. A highlighted select with a value already
+ * in it shows nothing — the viewer cannot tell what the alternatives were, or
+ * that a choice was made at all. So this opens the list, holds it open long
+ * enough to read, and then clicks the option.
+ */
+export const choose = (loc: Locator, option: string): Action => ({ kind: 'choose', loc, option });
 export const goTo = (url: string): Action => ({ kind: 'goto', url });
 export const none = (): Action => ({ kind: 'none' });
 
@@ -151,6 +174,85 @@ export const none = (): Action => ({ kind: 'none' });
  * eats the whole step the rest is zero and the timeline simply shifts; the
  * audio track is assembled afterward from these logged timings, never guessed.
  */
+/**
+ * Carry out one action and report what it landed on.
+ *
+ * Shared by step() (a narrated beat) and act() (a field the narration does not
+ * mention individually). `context` is only used to make an error legible.
+ */
+async function perform(page: Page, action: Action, context: string): Promise<string> {
+  if (action.kind === 'none') return '';
+
+  if (action.kind === 'goto') {
+    await page.goto(action.url, { waitUntil: 'domcontentloaded' }).catch(() => {});
+    await installOverlay(page);
+    return action.url;
+  }
+
+  const target = await reveal(page, action.loc);
+  if (!target) {
+    throw new Error(
+      `[walkthrough] target not visible for: "${context.slice(0, 70)}"\n` +
+        '  Every sentence must point at something that is actually on screen.',
+    );
+  }
+
+  let focus = (await target.innerText().catch(() => ''))?.slice(0, 40) ?? '';
+  const box = await target.boundingBox();
+  if (!box) return focus;
+
+  const cx = box.x + box.width / 2;
+  const cy = box.y + box.height / 2;
+  await ring(page, box);
+  await glide(page, cx, cy, 700);
+
+  if (action.kind === 'click') {
+    await page.waitForTimeout(420);
+    await target.click({ timeout: 15_000 }).catch(() => {});
+    await clearRing(page);
+    await installOverlay(page);
+  } else if (action.kind === 'choose') {
+    // Open it, HOLD so the options are readable, then pick. A native <select>
+    // cannot be opened visibly, so fall back to selectOption for one.
+    await page.waitForTimeout(300);
+    await target.click({ timeout: 15_000 }).catch(() => {});
+    await page.waitForTimeout(900);
+    const tag = await target.evaluate((el) => el.tagName.toLowerCase()).catch(() => '');
+    if (tag === 'select') {
+      await target.selectOption({ label: action.option }).catch(() => {});
+    } else {
+      const opt = page
+        .getByRole('option', { name: action.option, exact: false })
+        .or(page.getByRole('menuitem', { name: action.option, exact: false }))
+        .first();
+      await opt.click({ timeout: 10_000 }).catch(() => {});
+    }
+    focus = action.option.slice(0, 40);
+    await clearRing(page);
+  } else if (action.kind === 'type') {
+    // Click in, clear, then type at a readable pace — fill() makes the value
+    // appear instantly, which reads as a screenshot rather than data entry.
+    await page.waitForTimeout(300);
+    await target.click({ timeout: 15_000 }).catch(() => {});
+    await target.fill('').catch(() => {});
+    await target.pressSequentially(action.value, { delay: 45 }).catch(() => {});
+    focus = action.value.slice(0, 40);
+  }
+  return focus;
+}
+
+/**
+ * Perform an action OUTSIDE a narrated step — for fields a sentence does not
+ * mention individually but which still have to be filled.
+ *
+ * choose() and enter() only BUILD an action; they do nothing on their own, and
+ * `await choose(...)` is a no-op that silently leaves the field empty. step()
+ * performs one action; use act() for the rest.
+ */
+export async function act(page: Page, action: Action): Promise<void> {
+  await perform(page, action, '(unnarrated field)');
+}
+
 export async function step(
   page: Page,
   narration: string,
@@ -160,35 +262,7 @@ export async function step(
   if (!clip) throw new Error(`[walkthrough] no audio for: "${narration.slice(0, 70)}"`);
 
   const startMs = now();
-  let focus = '';
-
-  if (action.kind === 'goto') {
-    await page.goto(action.url, { waitUntil: 'domcontentloaded' }).catch(() => {});
-    await installOverlay(page);
-    focus = action.url;
-  } else if (action.kind !== 'none') {
-    const target = await reveal(page, action.loc);
-    if (!target) {
-      throw new Error(
-        `[walkthrough] target not visible for: "${narration.slice(0, 70)}"\n` +
-          '  Every sentence must point at something that is actually on screen.',
-      );
-    }
-    focus = (await target.innerText().catch(() => ''))?.slice(0, 40) ?? '';
-    const box = await target.boundingBox();
-    if (box) {
-      const cx = box.x + box.width / 2;
-      const cy = box.y + box.height / 2;
-      await ring(page, box);
-      await glide(page, cx, cy, 700);
-      if (action.kind === 'click') {
-        await page.waitForTimeout(420);
-        await target.click({ timeout: 15_000 }).catch(() => {});
-        await clearRing(page);
-        await installOverlay(page);
-      }
-    }
-  }
+  const focus = await perform(page, action, narration);
 
   // Hold for whatever is left of the spoken sentence.
   const spent = now() - startMs;