docs/DEMO_RUNBOOK.md

Demo runbook

One page. Everything measured, nothing assumed.

Before you leave

cd scribe/frontend && npm run build

Always rebuild after npm run e2e. The e2e build points the bundle at https://carepath-e2e.example and the served app silently breaks. This has cost an hour once already.

Confirm the Vietnamese voice is staged at a short path:

ls models/vi-tts/espeak-ng-data

espeak-ng reads that directory with a native call that fails past the Windows MAX_PATH limit, so the model cannot live in the HuggingFace cache.

Run it

uvicorn carepath.main:app --app-dir scribe --port 8000

.env is already set to PROVIDER_MODE=demo. Open Chrome at http://127.0.0.1:8000/kham-song-ngu/.

Demo mode is scripted and makes zero outbound network calls — verified by running the whole flow with the socket connect path poisoned. The venue wifi cannot break the demo.

The four minutes

Beat	What you do	What the judge sees
Problem	Open / first and wait two seconds before speaking	A Vietnamese prescription at full size, then the English resolving under each line. Scroll once: 29,5% against 49,1%, the three highest-risk moments, the two priced incumbents
Start	Age 34, nam, "nổi mẩn da"	One screen, no login, no settings
Conversation	Type or speak the scripted lines	English in, Vietnamese out, entity chips appearing
Safety	"I take 15 milligrams"	Red gate, 42% confidence, back-translation. The patient pane shows nothing. Click Sửa, correct to 500 mg, confirm
Paper	Photograph the prescription	Four lines read, each with drug / dose / frequency chips, all gated
Finish	Kết thúc và tạo hồ sơ	Vietnamese record, English patient packet, medication list

Scripted lines are in interpreter/app/providers/demo_scenario.json. Anything off-script falls back to a visible [en->vi] … placeholder rather than failing.

The landing page's opening animation is the whole pitch in two seconds — let it finish before you talk over it. It also sets up the Paper beat: the judge has already seen the object you are about to photograph.

What to say when asked

"Isn't this just Google Translate?" The confirm endpoint returns 409 from any state but awaiting_confirm. 91 risk fixtures across 30 named failure modes, including cross-lingual number and negation mismatch. A translator has no state machine and no clinician.

"Did the AI decide that was dangerous?" No. The vision model only transcribes. Every line goes through the same rule engine that guards spoken turns, so a look-alike drug name is caught by tested code, not a model's judgement.

"What are your numbers?" A 50-case set through the live gateway: drug name, numbers, dose units and laterality all 100%. Negation polarity 98%.

If asked about the missing 2%: one case, Ngưng thuốc → Discontinue the medication. The negation is preserved; discontinue simply is not in our cue list. We did not add it, because tuning the lexicon until the eval reads 100% would make the eval measure nothing. That turn was gated for clinician confirmation regardless — which is the actual point.

Report at interpreter/eval/reports/ckey/. Numbers move slightly run to run; re-run before the pitch if you want the page to match exactly.

If something breaks

Symptom	Do this
Microphone denied or mis-hears	Type instead. Every turn has a typed input beside the mic
A turn errors	Say it again. Turns are independent; nothing is lost
Page reloads mid-visit	It resumes. The visit id is in sessionStorage and the server replays the transcript
Document read fails	It adds nothing and says so. Move on to finishing the visit
Everything is slow	You are on ckey. Set PROVIDER_MODE=demo and restart

Showing the real AI path

Set PROVIDER_MODE=ckey and restart. Measured across 50 turns: median 15s, p90 54s, max 206s. Do one turn, not a whole visit, and say the number out loud — it is a gateway limit, not an architectural one.