repository is now a presentation-ready development prototype

docs/demo_script.md

@@ -0,0 +1,113 @@
+# Utah Vehicle Health dashboard demo script
+
+Target length: **2 minutes 45 seconds**, embedded in the
+[10-minute presentation](presentation_outline.md).
+
+## Before the audience arrives
+
+1. From the repository root, run `node dashboard/server.mjs`.
+2. Open `http://127.0.0.1:4173/#overview`.
+3. Confirm the header says the sample aggregates validated.
+4. Confirm the private-sample development-preview banner is visible.
+5. Visit all four routes: Overview, Sample cohorts, Model & benchmark, and Data
+   & methods.
+6. Reset Sample cohorts and leave its sort on largest support.
+
+Do not open developer tools, private files, model artifacts, database clients,
+or environment variables during the presentation.
+
+## Live talk track
+
+### 0:00-0:25 — Establish the boundary
+
+**Action:** Start on **Overview**. Point to the development-preview banner before
+pointing to a chart.
+
+**Say:**
+
+> The most important element is this banner. Every value in the dashboard comes
+> from the private 10,000-vehicle development sample. These are suppression-
+> reviewed sample aggregates, not population estimates, and they cannot support
+> individual decisions or county rankings.
+
+### 0:25-1:00 — Explain the overview
+
+**Action:** Point to published support and the observed first-attempt non-pass
+trend, then the coverage map and vehicle-age chart. Do not rank counties by
+outcome.
+
+**Say:**
+
+> The overview reports rounded support and sample first-attempt outcomes for
+> returning vehicles. Non-pass combines fail, reject, and abort. The trend is
+> descriptive of sampled records only. This county graphic communicates feed
+> availability: gray means unavailable, not zero and not better. The age pattern
+> is also an observed sample association, not a causal claim or diagnosis.
+
+### 1:00-1:35 — Use Sample cohorts safely
+
+**Action:** Open **Sample cohorts**. Search for `Toyota` or another currently
+supported make. Leave sorting on largest support. Point to rounded support and
+the “observed sample non-pass” label.
+
+**Say:**
+
+> This view contains only prior make-and-model cohorts that cleared the
+> publication thresholds. I can search supported cohorts, but these are observed
+> development-sample associations—not reliability grades, rankings, or
+> recommendations. Unsupported slices are not inferred in the browser, and
+> suppressed rows are absent rather than hidden.
+
+**Action:** Reset the search before leaving the view.
+
+### 1:35-2:15 — Separate the final model from its benchmark
+
+**Action:** Open **Model & benchmark**. Point first to the role badges, then the
+2024 calibration-fit scope strip, then the “No vehicle-level prediction service”
+boundary.
+
+**Say:**
+
+> The governance decision is explicit: calibrated logistic regression is the
+> final prototype model, while the boosted tree is benchmark-only. The numbers
+> shown here are pre-2025 checks on the same 2024 sample partition used to fit
+> calibration. They are not independent final-performance or population
+> estimates, so we do not select between the cards from these values. The
+> one-time 2025 comparison shown earlier favored logistic and stays in the report
+> and presentation, not the browser bundle. This finished dashboard contains no
+> vehicle lookup, personal inputs, or row-level prediction output.
+
+### 2:15-2:40 — Close on method and privacy
+
+**Action:** Open **Data & methods**. Briefly point to Prediction unit, the
+chronological timeline, evidence status, and the privacy flow.
+
+**Say:**
+
+> The method page makes the contract visible: the target is the first attempt of
+> a returning vehicle's next episode, and every feature ends before that episode.
+> Training, tuning, and calibration are chronological. It also records that 2025
+> was opened once after choices were frozen. Finally, the public path ends in
+> suppressed summaries. No private rows or database connection reach this site.
+
+### 2:40-2:45 — Transition
+
+**Say:**
+
+> That is the prototype: useful sample evidence, with model and privacy
+> boundaries kept visible.
+
+Return to the slide deck's privacy architecture.
+
+## If something goes wrong
+
+If the dashboard shows **data unavailable**, do not bypass validation or edit
+JSON. Say:
+
+> The site rejected an aggregate-contract mismatch and is failing closed, so it
+> shows no estimates. That behavior is part of the privacy and integrity design.
+
+Then continue with a backup screenshot or slides. If a cohort search returns no
+rows, explain that unsupported or suppressed cohorts are intentionally absent
+and reset the filter. Never substitute remembered values or improvise a vehicle-
+level example.