@tekyzinc/gsd-t 5.14.10 → 5.16.10

package/commands/gsd-t-gap-analysis.md

@@ -7,13 +7,30 @@ You are performing a gap analysis between a provided specification and the exist
 | Invocation | Mode | Output |
 |---|---|---|
 | `/gsd-t-gap-analysis <spec>` | **Report** (default) | `.gsd-t/gap-analysis.md` — Steps 0.5-9 below, unchanged |
-| `/gsd-t-gap-analysis <spec> --sheet <url>` | **Client deliverable** | The estimating sheet's columns A-D and M-P, red-teamed — Steps 4a-6c |
+| `/gsd-t-gap-analysis <spec> --sheet <url>` | **Client deliverable** | The estimating sheet's columns A-D and M-Q, red-teamed — Steps 3a-6c |
+
+### Column map (client-deliverable mode)
+
+| Col | Holds | Written by |
+|---|---|---|
+| A | Domain | this command |
+| B | User Type | this command |
+| C | Functionality — bold name, blank line, italic purpose | this command |
+| D | Low Level Requirements + `OPEN QUESTIONS:` block | this command |
+| E-L | Phase, sizing, days, money | **`/gsd-t-estimate` — never touched here** |
+| M | Build Status (4 colours) | this command |
+| N | What Works / What Doesn't | this command |
+| O | References | this command |
+| P | **Fallbacks in shipped code** | this command |
+| Q | Impacting Open Hardening Tasks | this command |
+
+A sheet from an earlier run may hold hardening tasks in P, or a `Scope` column. Move hardening to Q and let fallbacks take P; never leave two columns claiming the same header.
 
 **Report mode is the default and is unchanged.** Every existing caller — `/gsd-t-scan`'s next-step offer, `gsd-t-phase.workflow.js` routing — invokes it without `--sheet` and behaves exactly as before.
 
 **Client-deliverable mode** is the procedure proven on the HILO AI Scheduling sheet: 141 raw requirements reduced to 33 feature rows carrying 595 checkable claims, judged against the code, then attacked by a red team that found a 70% defect rate in a column a friendly sample had already approved. It writes only the *what and whether* columns; `/gsd-t-estimate` sizes and prices them afterward. Behaviour map: `.gsd-t/pseudocode/PseudoCode-GapAnalysis.md`.
 
-In client-deliverable mode, run Steps 0.5-3 as written (they load context and parse the spec), then branch to Step 4a instead of Step 4.
+In client-deliverable mode, run Step 0.5 and Step 1, then branch to **Step 3a (Harvest)** — do NOT run Step 2 (Parse Requirements). Step 2 assumes a finished specification was handed to you; in this mode **there usually is no such document**, and expecting one is how a run stalls asking for a spec that was never going to exist.
 
 ## Step 0.5: Scan Freshness Auto-Refresh
 
@@ -196,10 +213,40 @@ If agent teams are not available or there are fewer than 3 requirements, run seq
 
 ---
 
-# Client-deliverable mode (Steps 4a-6c) — only when `--sheet <url>` was given
+# Client-deliverable mode (Steps 3a-6c) — only when `--sheet <url>` was given
 
 Report mode skips this whole block and continues at Step 6.
 
+## Step 3a: HARVEST the sources — the requirements do not exist yet, you are deriving them
+
+**Do not ask the user for a requirements document. In this mode there usually isn't one.** The job is to harvest everything a tracker project holds and synthesize requirements from it. A run that stops to request a spec has misread the task — this exact stall happened on the FRC Predictive run.
+
+Harvest, in this order, and report a count for each:
+
+1. **The project's attachments** — NOT its description. On the proven run the description was empty and all three requirement documents were attached files. Pull `attachments?parent=<project_gid>`, then each attachment's `download_url`, and read them. A Statement of Work PDF was the single richest source: **1,431 lines, whose Exhibit B (~1,000 lines) was the real specification.**
+2. **Every task** — name, notes, and status.
+3. **Every subtask.** Parent tasks are usually coarse rollups; the real detail and the file citations live one level down. The proven run pulled **192 subtasks** because *"the rollups are too coarse."* One rollup alone carried 46 findings.
+4. **Task comments.** One Bugs section — a ticket plus three pull-request comments — drove several rows by itself.
+5. **Any spec documents in the repo**, if the user named one.
+
+**An empty section list or a zero-task view is not an empty project.** Check attachments before concluding anything is missing.
+
+**If a genuinely required source cannot be reached** — no credentials, a 403, an attachment that will not download — say exactly which one and stop. That is a blocked run. "The project has no tasks" is not, until attachments have been checked too.
+
+**Tracker status is unreliable — never carry it through as truth.** On the proven run *"3 of the 6 tasks still show open, but their comments say implemented in PR #4386 with named commits."* Every status is re-decided against the code in Step 5a; a tracker status only ever becomes a flag that the tracker disagrees with reality.
+
+## Step 3b: REPAIR the graph before you rely on it
+
+The judgment in Step 5a is only as good as the index it queries.
+
+1. `gsd-t graph status`.
+2. **Missing → build it**: `gsd-t graph index` (allow up to 900s on a large repo). An absent index is repairable, never a reason to stop.
+3. **Stale → re-index** the touched set.
+4. **Broken → repair, then re-verify anything already judged against it.** The proven run found its own index producing *"unresolved call edges"* and had to re-check the Partial/Implemented calls that hinge on whether code is actually wired in.
+5. **Cannot build it → HALT.** Do not answer structural questions by grep; grep matches text, and the question is about relationships.
+
+Report which of these happened. A silent "the graph was fine" claim is not acceptable — say whether it was built, re-indexed, repaired, or already current.
+
 ## Step 4a: Strip everything that isn't buildable — HUMAN-CONFIRMED
 
 **This step removes most of the input, and getting it wrong poisons every step after it.**
@@ -232,27 +279,127 @@ Group the survivors into features a person would name (`Availability, Operating
 
 ## Step 4c: Describe each feature
 
-- **Column C** — the feature name in bold, then ONE sentence of purpose beneath it.
+**Columns A, B, C — the reading columns.** A client scans these three and stops; everything right of them is detail. Format them exactly:
+
+- **Column A — Domain.** Plain text, one or two words: `Training Pace`, `Configuration`, `Curriculum`.
+- **Column B — User Type.** The roles this serves, comma-separated: `Student, Instructor, Scheduling admin`. Wraps onto two lines; that is fine.
+- **Column C — Functionality.** THREE parts in one cell:
+  1. The feature name, **bold**: `Training Pace (EPW) Service and Exceptions`
+  2. A **blank line**
+  3. One sentence of purpose, in *italic*, saying what it is FOR — not what it does mechanically.
+
+```
+Training Pace (EPW) Service and Exceptions        ← bold
+
+Would give the whole platform one trustworthy     ← italic
+answer to whether a student is keeping up, what
+a proposed change would do to that, and how the
+requirement bends for a part week or an
+approved break.
+```
+
+**Match the verb to the build status.** A purpose sentence in present tense on an unbuilt row asserts the feature exists — the same defect as present-tense requirement bullets:
+
+| Status | Voice | Example |
+|---|---|---|
+| Not Implemented | **conditional** | *"**Would give** the whole platform one trustworthy answer to whether a student is keeping up"* |
+| Implemented / Partial | present | *"**Keeps** every scheduling setting a school has chosen in one checked, version-tracked place"* |
+
+Purpose, not mechanics. *"Would give the platform one trustworthy answer to whether a student is keeping up"* — not *"computes events-per-week from enrollment data."*
+
 - **Column D** — the requirements as bullets, written as **instructions**: "Work out each student's required events-per-week." **Never** as statements of current fact: "Resolves each student's required events-per-week."
 
 Present tense reads as a description of working code. On a row that turns out to be unbuilt, the row contradicts itself — this exact defect appeared in the proven run and had to be rewritten across all 32 rows.
 
 Plain words in column D. No jargon a client would have to decode.
 
+**Every row ends with its OPEN QUESTIONS — the unknowns you could not settle from the sources.** Append to the same cell, after a blank line:
+
+```
+OPEN QUESTIONS:
+? Which specific settings count as safety settings and therefore cannot be overridden by a lower layer
+? Whether enrollment-level exceptions are set per student or per cohort
+```
+
+One question per line, prefixed `?`, phrased so a client can answer it without reading code. These are the decisions someone must make before the work can be built or priced — a version-migration policy, which values are non-overridable, whether a school may define its own types.
+
+**A row with no `OPEN QUESTIONS` block is asserting there are no unknowns.** That is occasionally true and usually not. On the proven sheet, six of eight sampled rows carried them. Before omitting the block, ask: *could two reasonable people build this differently from what column D says?* If yes, the difference is an open question.
+
+**Do not invent questions to fill the block, and do not answer them yourself.** An unknown you resolved by assumption is not an open question — it is an assumption, and it belongs in column D as a stated bullet.
+
 ## Step 5a: Judge each feature against the code
 
-Query the code graph for each feature's surface (`gsd-t graph`), read what it names, and decide:
+Query the code graph for each feature's surface (`gsd-t graph`), read what it names, and decide. **Four statuses, four colours — every one of them coloured, none left plain:**
+
+| Status | Colour | Means | What it needs |
+|---|---|---|---|
+| **Implemented** | 🟢 green | Every bullet is built | Verification only |
+| **Partial** | 🟡 yellow | Some bullets are built | **Finishing** |
+| **Incorrect** | 🔵 light blue | Code exists and **contradicts** the requirement | **Fixing** — different work from finishing |
+| **Not Implemented** | 🔴 red | No code exists for it | Building |
+
+**Incorrect is not a shade of Partial.** Partial means work is missing; Incorrect means work is present and wrong, and someone must first undo what is there. Pricing the two identically understates the second. If you never assign Incorrect across a whole sheet, check whether you have been folding contradictions into Partial.
 
-- **Implemented** — every bullet is built.
-- **Not Implemented** — none of it is.
-- **Partial** — some is. **MUST be followed by `Not implemented:` and the specific bullets that are missing.** A bare "Partial" is not an answer anyone can act on.
+**Partial and Incorrect MUST name specifics.** Partial is followed by `Not implemented:` and the exact bullets missing. Incorrect is followed by `Contradicts:` and what the code does instead. A bare "Partial" or "Incorrect" is not an answer anyone can act on.
 
-Write the verdict to **column M**, and to **column N** what works today versus what does not.
+Write the verdict to **column M** with its background colour, and to **column N** what works today versus what does not.
 
 ## Step 5b: References and impacting debt
 
 - **Column O** — where each claim came from: `Requirements doc (6 reqs) · Asana task · PR #4386`. Short clickable names, each token its own link. Never a wall of file paths.
-- **Column P** — open Extreme/Critical findings from `.gsd-t/techdebt.md` that would hit this feature. **Judge by the code each finding cites, not by keyword match.**
+- **Column Q** — open Extreme/Critical findings that would hit this feature. **Judge by the code each finding cites, not by keyword match.** (This sat in P before fallbacks took that slot; a sheet built by an earlier run may still have it in P — move it rather than leaving two columns claiming the same thing.)
+
+**Where the findings come from, and why the tracker alone is not enough:** pull the hardening project's open items at **subtask level** — the parent tasks are rollups. Then **match each subtask back to `.gsd-t/techdebt.md`** for its real file citations. On the proven run the tracker notes were too thin to judge from, and 152 of 154 subtasks had to be resolved against the local register to get the file paths that make the mapping decidable. Of 154 open subtasks, 28 genuinely touched the feature set.
+
+A feature with no findings is a real answer, not a miss — usually an unbuilt feature with no shipped code for a defect to land on. Say so rather than leaving the cell ambiguous.
+
+## Step 5c: Fallbacks in the shipped code — a second pass over the built features
+
+**Only for rows marked Implemented, Partial, or Incorrect.** A Not Implemented row has no shipped code, so it has no fallbacks — leave its cell empty rather than writing "none", which reads as a clean result.
+
+A **fallback** is any branch that continues after a failure: a `catch` that carries on, a `|| default`, a silent degrade, a secondary path that hides the first one failing. Each one is a place a real failure can hide, and a place the client's system will do something quietly wrong instead of stopping.
+
+Run the detector over the project once:
+
+```bash
+# Project-local copy first, else the global package's copy.
+node bin/gsd-t-fallback-detect.cjs --scan --project . --json
+```
+
+It returns `{ok, filesScanned, found, preExisting, approved, unapproved, findings}`. There is no `gsd-t fallback-detect` subcommand — invoke the file directly.
+
+Then attribute each finding to the feature whose code it sits in — **judged by the file the finding cites**, the same rule as the debt mapping in Step 5b, never by keyword.
+
+Write to **column P** — the slot right after References, so the reader meets a feature's own defects before the wider hardening list in Q:
+
+```
+⚠ UNAPPROVED — solver.ts:214
+   catch → returns an empty slot list
+⚠ UNAPPROVED — pace.ts:88
+   missing required-lessons-per-week → defaults to 3
+◆ pre-existing — legacy-import.ts:31
+   predates the rule; never justified
+✓ approved — cache.ts:40
+   "stale read beats a hard failure on a cold cache" — DH
+```
+
+**Three states, and they mean different things — do not collapse them into two:**
+
+| State | Where it comes from | What to tell the client |
+|---|---|---|
+| **approved** | listed in `.gsd-t/fallbacks.json`, with a written reason | Someone justified this deliberately |
+| **pre-existing** | listed in `.gsd-t/fallbacks-baseline.json` | Predates the rule. **Not approved — merely grandfathered.** Nobody has ever justified it |
+| **unapproved** | in neither file | The finding |
+
+An approval carries six required fields — `id`, `location`, `whatFails`, `whyNotHalt`, `whatItDoesInstead`, `approvedBy` — so "approved" means someone wrote down what fails, why stopping was worse, and what happens instead. Quote the `whyNotHalt` reason in the cell; an approval nobody can read is indistinguishable from an unapproved one.
+
+**Pre-existing is a finding for a client, even though the gate lets it through.** The gate blocks NEW fallbacks; a grandfathered one is still unexamined code that continues after a failure. Show it.
+
+**List all three.** The unapproved and pre-existing ones are the findings. The approved ones prove the pass ran and judged rather than skipped — a column showing only warnings cannot be told apart from one that found nothing.
+
+**A malformed `fallbacks.json` is a HALT, never "no approvals."** The detector already refuses to read unreadable as approved; do not paper over that by writing an empty cell.
+
+**Where a fallback contradicts the row's own column D, say so.** The requirements already ban several by name — *"never silently add the whole instructor roster as fallbacks when the policy turns fallback off"*, *"refuse to fall back to an out-of-date old field once the move has run."* A fallback in the code that the spec explicitly forbids is the strongest finding on the sheet: mark it `⚠ CONTRADICTS COLUMN D` and quote the bullet it breaks.
 
 ## Step 6a: RED TEAM the sheet — NOT a review
 
@@ -272,10 +419,13 @@ Verdict per checker: `FAIL` (defects listed) or `GRUDGING-PASS` (searched, found
 | O — references | 76 | **Every one** | A link resolves or it doesn't. |
 | Dropped list (Step 4a) | all | **Every one** | A wrongly-dropped requirement is invisible downstream — nothing else can catch it. |
 | M — gap bullets | 108 | **Batch of 20** | Each asserts code is absent; disproving it costs a search. |
-| P — debt mappings | 104 | **Batch of 20** | Each needs the finding read AND the feature's code read. |
+| P — fallbacks | varies | **Batch of 20** | Each needs the cited code read to confirm it really continues after a failure. |
+| Q — debt mappings | 104 | **Batch of 20** | Each needs the finding read AND the feature's code read. |
 
 **Widening rule:** if **3 or more** of a batch of 20 are wrong, that column goes to every-claim. The batch proved the column is unreliable; sampling further only hides the rest.
 
+**A red-team finding can overturn the analysis, not just its wording.** On the proven run a checker reversed a substantive verdict: *"My reconciliation claimed aircraft ranking didn't exist. The code does build a real ordered list."* When a checker contradicts a status call, the checker's evidence wins unless you can cite code that refutes it — the checker read the code fresh, the original judgment did not.
+
 **One checker does nothing but hunt cross-column contradictions** — a row whose column C asserts a capability in present tense while column M lists that same capability as the row's defining gap. No single-column checker can see this; it is the defect class that reached the client sheet in the proven run.
 
 **All checkers returning clean is a FAILED check, not a clean sheet.** The proven run had one clean column out of six. An all-clean result means the framing was too gentle: re-run with sharper prompts. Do NOT report a clean sheet on the first all-pass.
@@ -289,7 +439,7 @@ Verdict per checker: `FAIL` (defects listed) or `GRUDGING-PASS` (searched, found
 
 ## Step 6c: Write the sheet — leave the money alone
 
-Write columns **A-D and M-P** using the service-account path documented in `commands/gsd-t-estimate.md` Step 5 (permanent SA `gsd-t-sheets-writer@ai-estimator-415612.iam.gserviceaccount.com`, self-signed JWT, Sheets v4 REST). A `403` on the read-probe means the sheet isn't shared — prompt the user to share it as Editor and re-probe.
+Write columns **A-D and M-Q** using the service-account path documented in `commands/gsd-t-estimate.md` Step 5 (permanent SA `gsd-t-sheets-writer@ai-estimator-415612.iam.gserviceaccount.com`, self-signed JWT, Sheets v4 REST). A `403` on the read-probe means the sheet isn't shared — prompt the user to share it as Editor and re-probe.
 
 **NEVER write columns E-L** (Phase, Web Portal, Backend/API, Days, MFactor Days, Total Days, LOW $, HIGH $). Those are `/gsd-t-estimate`'s to fill, and the sheet's own formulas compute the money from them.
 

package/commands/gsd-t-help.md

@@ -380,6 +380,12 @@ Use these when user asks for help on a specific command:
 - **Updates**: new deliverable `share/<Repo>-user-stories.md` (+ optional `.docx` via pandoc) + `share/media/*.png` (rendered diagrams) + `.gsd-t/user-stories/diagrams/*.mmd`
 - **Use when**: You need to hand a development team discrete, testable user stories in the Tekyz handoff style. Distinct from `/gsd-t-prd` (which writes the INTERNAL `docs/prd.md`) — this is an EXTERNAL client/dev deliverable. Diagrams are authored as Mermaid but embedded as rendered images (needs `@mermaid-js/mermaid-cli`). Format reference: `~/.claude/playbooks/tekyz-user-stories-format.md`
 
+### demo-videos
+- **Summary**: Produce narrated screen-recording walkthrough videos of a running application — coverage plan from the live app, Playwright seeding through the real UI, batched text-to-speech with a measured one-voice gate, one continuous recording per walkthrough, audio muxed at recorded timestamps, then silence trimmed
+- **Auto-invoked**: No
+- **Updates**: `docs/demo-videos/PLAN.md`, `docs/demo-videos/HANDOFF.md`, `docs/demo-videos/walkthrough-<name>.mp4`, `e2e/walkthrough/*`, `scripts/walkthrough-*.mjs`, `scripts/demo-data/*`
+- **Use when**: You need shareable demo or training videos of an app that already runs with real data. Narration is the master clock — each step lasts exactly as long as its measured spoken sentence. Needs Playwright, ffmpeg, auto-editor and a TTS key with quota. Templates: `templates/demo-videos/`
+
 ### populate
 - **Summary**: Auto-populate all living docs from existing codebase analysis
 - **Auto-invoked**: No

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.14.10",
+  "version": "5.16.10",
   "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

@@ -0,0 +1,89 @@
+# Demo-video pipeline templates
+
+Working scripts behind `/gsd-t-demo-videos`. These are the real thing from a
+completed 12-walkthrough production run, not sketches. Copy them into a project
+and fill the `{tokens}`; do not re-derive the pipeline.
+
+## Install into a project
+
+```bash
+mkdir -p e2e/walkthrough scripts scripts/demo-data docs/demo-videos
+cp <gsd-t>/templates/demo-videos/e2e/*      e2e/walkthrough/
+cp <gsd-t>/templates/demo-videos/scripts/walkthrough-*.mjs  scripts/
+cp <gsd-t>/templates/demo-videos/scripts/seed-lib.mjs       scripts/demo-data/
+
+# auto-editor, bundled so it does not depend on PATH
+python3 -m venv .venv-tools/auto-editor
+.venv-tools/auto-editor/bin/pip install auto-editor
+
+printf '\n.demo-build/\n.tts-cache-v2/\ndocs/demo-videos/*.mp4\n' >> .gitignore
+```
+
+Add a Playwright project:
+
+```ts
+{
+  name: 'walkthrough',
+  testDir: './e2e/walkthrough',
+  testMatch: /\.spec\.ts$/,
+  timeout: 15 * 60_000,
+  use: {
+    ...devices['Desktop Chrome'],
+    baseURL: process.env.DEMO_URL || 'https://demo.example.com',
+    viewport: { width: 1440, height: 900 },
+    // PIN THE SIZE. Unpinned, Playwright downscales and the result is
+    // upscaled back to a blurry finish.
+    video: { mode: 'on', size: { width: 1440, height: 900 } },
+    trace: 'off',
+  },
+}
+```
+
+Then fill: `signin.ts` (persona + tenant id), `preflight.spec.ts` (targets), and
+one `<name>.lines.mjs` + `<name>.spec.ts` pair per walkthrough.
+
+## Run
+
+```bash
+DEMO_RUN=1 npx playwright test --project=walkthrough --grep preflight   # 0 check targets
+node scripts/walkthrough-voice-ensure.mjs <name>                        # 1 narration + gate
+DEMO_RUN=1 npx playwright test --project=walkthrough --grep "<name>"    # 2 record
+node scripts/walkthrough-mux.mjs  <name>                                # 3 lay audio on video
+node scripts/walkthrough-trim.mjs <name>                                # 4 cut the silence
+```
+
+Stage 4 is not optional — it removed 7.4 minutes of dead air across twelve
+videos in the source run.
+
+## Environment
+
+| Variable | Purpose |
+|---|---|
+| `DEMO_URL` | the running app to film |
+| `DEMO_GATE_PW` | password gate in front of a demo site, if any |
+| `GEMINI_API_KEY_3` / `_2` / `GEMINI_API_KEY` | TTS, tried in that order |
+| `VOICE_NAME`, `VOICE_SPEED`, `VOICE_BATCH`, `VOICE_LUFS` | narrator settings — all in the cache key |
+| `TTS_MODEL` | pin one model instead of the fallback list |
+| `TRIM_MARGIN` | silence kept either side of speech (default `0.2s`) |
+| `HEADED=1` | watch a seeder run |
+
+## What each file is for
+
+| File | Role |
+|---|---|
+| `e2e/runtime.ts` | `step()`, `highlight()`, `click()`, `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/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 |
+| `scripts/walkthrough-voice-ensure.mjs` | render → measure → re-render → halt at 3 |
+| `scripts/walkthrough-normalise.mjs` | force existing clips to one loudness, no API calls |
+| `scripts/walkthrough-mux.mjs` | places clips at recorded timestamps; no overlaps; warns on overrun |
+| `scripts/walkthrough-trim.mjs` | auto-editor silence removal, in place, re-runnable |
+| `scripts/demo-data/seed-lib.mjs` | seeder sign-in, settle, and the refusal-reporting rule |
+
+The reasoning behind every threshold and retry is in the file headers — they are
+the record of what failed, so read them before changing a constant.

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

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ *
+ * 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…".
+ *   - 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.
+ */
+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.",
+];

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

@@ -0,0 +1,53 @@
+/**
+ * TEMPLATE — one continuous recorded walkthrough.
+ *
+ * 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
+ *
+ * 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.
+ */
+import { test } from '@playwright/test';
+import { loadNarration } from './manifest';
+import { LOC, signInAsAdmin } from './signin';
+import { click, highlight, installOverlay, none, startRun, step, writeRunLog } from './runtime';
+
+const NAME = 'example';
+const { ready, audio: AUDIO, L } = loadNarration(NAME);
+
+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);
+
+  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);
+
+  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()));
+
+  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 installOverlay(page);
+
+  await step(page, L[5], none());
+
+  // The step log is the proof of what was on screen when. The mux reads it.
+  writeRunLog(NAME);
+});

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

@@ -0,0 +1,30 @@
+/**
+ * Load a walkthrough's narration manifest.
+ *
+ * Playwright imports EVERY spec in the project before it applies --grep, so a
+ * spec whose audio has not been rendered yet used to throw at import time and
+ * take the whole run down with it — including the walkthroughs that were ready.
+ * Missing audio is a reason to skip that one walkthrough, not to fail the run.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+export interface Narration {
+  ready: boolean;
+  audio: Map<string, { file: string; ms: number }>;
+  L: string[];
+}
+
+export function loadNarration(name: string): Narration {
+  const file = path.join(process.cwd(), '.demo-build', `audio-${name}.json`);
+  if (!existsSync(file)) return { ready: false, audio: new Map(), L: [] };
+
+  const manifest = JSON.parse(readFileSync(file, 'utf8'));
+  return {
+    ready: true,
+    audio: new Map(
+      manifest.lines.map((l: any) => [l.text, { file: l.file, ms: l.ms }]),
+    ),
+    L: manifest.lines.map((l: any) => l.text as string),
+  };
+}

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

@@ -0,0 +1,109 @@
+/**
+ * Stage 0 — check every walkthrough's targets WITHOUT recording.
+ * TEMPLATE: fill SCREENS and DRILLDOWNS with what your specs point at.
+ *
+ * Recording is the slow way to discover a bad selector: the run stops at the
+ * first sentence whose target is not on screen, so a spec with three bad
+ * selectors costs three full recordings to find them all. This walks the same
+ * screens and reports EVERY missing target in one pass.
+ *
+ *   DEMO_RUN=1 npx playwright test --project=walkthrough --grep preflight
+ *
+ * It never asserts, so it cannot fail the suite — it prints a report. The real
+ * gate is still the recording itself, which refuses to narrate what is not
+ * visible; this just makes getting there quick.
+ */
+import { test } from '@playwright/test';
+import { LOC, signInAsAdmin } from './signin';
+
+interface Target {
+  where: string;
+  what: string;
+  find: (page: any) => any;
+}
+
+/** Everything the specs point at, grouped by the screen it must appear on. */
+const SCREENS: Array<{ route: string; settle: number; targets: Target[] }> = [
+  {
+    route: `/location/${LOC}/dashboard`,
+    // 6-8 SECONDS, NOT 5 — a 5s read reports a populated page as empty.
+    settle: 8_000,
+    targets: [
+      { where: 'dashboard', what: '{a heading}', find: (p) => p.getByText(/{Heading}/i) },
+      { where: 'dashboard', what: '{a card}', find: (p) => p.getByText(/{Card Title}/i) },
+    ],
+  },
+];
+
+/**
+ * Screens reached by opening a record and clicking its tabs, rather than by URL.
+ * COUNT THE TABS ON SCREEN — a record with 7 tabs narrated as 3 ships an error.
+ */
+const DRILLDOWNS: Array<{
+  name: string;
+  open: (page: any) => Promise<void>;
+  tabs: Array<{ tab: string; targets: Target[] }>;
+}> = [
+  // {
+  //   name: 'aircraft',
+  //   open: async (p) => {
+  //     await p.goto(`/location/${LOC}/{route}`, { waitUntil: 'domcontentloaded' });
+  //     await p.waitForTimeout(8_000);
+  //     await p.getByRole('button', { name: /{Open Record}/i }).first().click();
+  //     await p.waitForTimeout(6_000);
+  //   },
+  //   tabs: [{ tab: '{Tab Name}', targets: [...] }],
+  // },
+];
+
+async function firstVisible(loc: any): Promise<{ visible: boolean; n: number }> {
+  const n = await loc.count().catch(() => 0);
+  for (let i = 0; i < n; i += 1) {
+    if (await loc.nth(i).isVisible().catch(() => false)) return { visible: true, n };
+  }
+  return { visible: false, n };
+}
+
+test('walkthrough — preflight target check', async ({ page }) => {
+  test.setTimeout(25 * 60_000);
+  await signInAsAdmin(page);
+
+  const missing: string[] = [];
+  let checked = 0;
+
+  for (const screen of SCREENS) {
+    await page.goto(screen.route, { waitUntil: 'domcontentloaded' }).catch(() => {});
+    await page.waitForTimeout(screen.settle);
+
+    for (const t of screen.targets) {
+      checked += 1;
+      const { visible, n } = await firstVisible(t.find(page));
+      if (!visible) missing.push(`${t.where.padEnd(14)} ${t.what}  (${n} matched, none visible)`);
+    }
+  }
+
+  for (const d of DRILLDOWNS) {
+    await d.open(page).catch(() => {});
+    for (const group of d.tabs) {
+      const tab = page
+        .getByRole('button', { name: new RegExp(`^${group.tab}$`, 'i') })
+        .first();
+      if (await tab.isVisible().catch(() => false)) {
+        await tab.click().catch(() => {});
+        await page.waitForTimeout(5_000);
+      } else {
+        missing.push(`${d.name.padEnd(14)} tab "${group.tab}" not reachable`);
+        continue;
+      }
+      for (const t of group.targets) {
+        checked += 1;
+        const { visible, n } = await firstVisible(t.find(page));
+        if (!visible) missing.push(`${t.where.padEnd(14)} ${t.what}  (${n} matched, none visible)`);
+      }
+    }
+  }
+
+  console.log(`\n── preflight: ${checked} targets checked, ${missing.length} missing`);
+  for (const m of missing) console.log(`   MISSING  ${m}`);
+  if (!missing.length) console.log('   all targets visible');
+});