The one rule
Never hand-edit the generated files. The suspect data lives in ONE place:
scripts/build-csi-roster.js. Running it regenerates every data-bearing page so nothing can drift:
node scripts/build-csi-roster.js
It writes suspect-filter.html, guess-who.html, the Suspect Chart answer key inside candidate-activities.html (between the SUSPECT-MATRIX markers), and wires suspect-book portraits to real photos. A build-time validator guarantees the puzzle still works (see below) and refuses to write a broken roster.The cast of pages
| Page | What it is | Edit how? |
|---|---|---|
| guess-who.html | The big-screen reveal board: face tiles, clue tabs, cross-out animations. PreK/K-3 and Grades 4-5 levels. | GENERATED - edit the build script |
| suspect-filter.html | Same data as a detailed list view (clue rows + dossiers). | GENERATED - edit the build script |
| candidate-activities.html | Internal planning page. Its Suspect Chart answer-key rows are stamped in by the build script. | Prose by hand; CHART is generated |
| station-guides.html | Printables: intro story, kid + helper sheet per station, the 5-clue reveal script. | By hand (keep clue words matching the board) |
| take-home.html | Parent-facing "what I learned" sheet. | By hand |
| suspect-book.html | 13-suspect printable book (community-helper roster; portraits auto-wired to photos). | By hand + build script wires photos |
The case (answer key - staff only)
| Clue | Board chip (say it EXACTLY like this) | Found at station |
|---|---|---|
| Hair | Brown (PreK/K-3) / Brown, curly (4-5) - and it is HUMAN hair | Hair + microscope |
| Bite | Normal human bite (not too big, not too small, ALL teeth there - model #5) | Bite marks |
| Fingerprint | Whorl (every whorl on the board is a human) | Fingerprint |
| Marker | Gray Mondo (found at the ink race by its peach + blue split) | Ink race (5A) |
| Footprint | Asics (waves, 2 tabs) - the decider; the Principal's decoy is arches, 1 tab | Footprint |
Culprit: The Cleaning Lady. She moved the cookies to the front office (not allergy-safe) - revealed by the invisible-ink note demo.
Running the big reveal
- Open guess-who.html on the TV. Level: PreK / K-3 for the young crowd.
- Work the tabs in THIS order: Hair color → Bite → Fingerprint → Marker → Footprint. Footprint LAST - it is the grand finale (the Principal survives until then).
- Skip the Category and Gender tabs. Category = Human would shortcut the whole mystery; Gender is parked as the last tab so you don't hit it by accident.
- Tap a chip = pick it. Press-and-hold = add a second value (for when kids disagree).
- Counts you should see (PreK/K-3): 136 → 29 → 22 → 13 → 6 → 1 - "It's The Cleaning Lady!"
- Expect brown-FUR stragglers after the hair tap (Scooby-Doo, Curious George, Yogi) - that's the script's cue: "we know it was human HAIR... the bite will catch them."
- Full word-for-word script: last two pages of station-guides.html.
Rules for kid-facing materials
- No detective sheets, no writing. Kids observe, double check, and REMEMBER; helpers help them recall at the reveal.
- Never print an answer on a kid page - not the real one, not a fake example. Kids remember whatever is printed. Answers live on staff pages only.
- The protocol at every station: double check (look again - make sure it CAN'T be any other match), then WHISPER the finding to a helper. No shouting answers.
- Remember-phrases must match the board chips verbatim (see answer key above) - that's what the kids pick at the reveal.
Making changes
Change a suspect's clue data (hair, feet, bite, prints)
- Edit the override maps in
scripts/build-csi-roster.js:HAIR_OVERRIDE,FOOT_OVERRIDE,BITE_OVERRIDE,FP_OVERRIDE(+HAIR_ALSO/FP_ALSOfor two-color characters). Culprit/twins/decoys are hand-set inCRIME,TWIN_DIFF, andDECOYS. - Run node scripts/build-csi-roster.js
- The validator enforces: exactly ONE full match (the culprit); dropping any single clue still leaves 2+; and by convention only humans get "Normal human bite" or arch/loop/whorl prints. If it fails, it says why and writes nothing.
- Commit the script AND all regenerated files together; push to deploy.
Add or swap a suspect photo
Drop the image at programs/csi/photos/suspects/<slug>.<ext> (slug = name lowercased, dashes: the-cleaning-lady, cookie-monster), add attribution to CREDITS.md (CC-licensed images of the CHARACTER, never the actor), then rerun the build. The photo is ground truth - if it contradicts the suspect's clue data, fix the data via the overrides in the same pass.
Pre-class checklist: pull latest; if any roster data changed, rerun the build and push; print station-guides.html (kid + helper pages); confirm guess-who.html loads on the TV at PreK/K-3 level; cookies staged at the front office.