docs: add the Open Source Friday demo project and run of show

examples/open-source-friday-demo/README.md

@@ -0,0 +1,101 @@
+# Open Source Friday demo
+
+Demo material for the GitHub Open Source Friday stream (Twitch, LinkedIn and YouTube via StreamYard).
+
+`shipping-api/` is a small Express service whose five direct dependencies are deliberately pinned to old versions. It is here rather than in a scratch directory so the demo is versioned, reproducible, and identical on every rehearsal.
+
+## Why a purpose-built project
+
+Scanning a real maintainer's repository live on GitHub's own channel puts their vulnerabilities on a broadcast they did not agree to. This project uses real, recognisable packages and real CVEs without doing that to anyone. It also behaves the same every rehearsal, which a live repository does not.
+
+## The four beats, about 8 minutes
+
+Run everything from this directory.
+
+**1. The scan, around 90 seconds**
+
+```bash
+cve-lite ./shipping-api
+```
+
+Expect roughly `11 packages · 1 critical · 6 high · 5 direct · 6 transitive`. Two things to narrate: the direct versus transitive split, and the `⚡ Fix Now` badge, which is CVSS severity crossed with EPSS exploitation likelihood rather than severity alone.
+
+**2. The proof, around 2 minutes**
+
+```bash
+cve-lite ./shipping-api --verbose --all
+```
+
+`--all` matters: plain `--verbose` hides low-severity findings, which drops three of the six transitive packages and breaks the Root story.
+
+The fix table is the strongest argument for the tool. Point at **Versions scanned** and **Still known vulnerable**: for axios it scans over twenty published versions and finds most of them still vulnerable before recommending one. Most scanners hand you the advisory's suggested version without checking it.
+
+**3. The artifact, around 2 minutes**
+
+```bash
+cve-lite ./shipping-api --report
+```
+
+The HTML dashboard, with every finding, its dependency path, and a copy button per fix command. `--sbom spdx` is worth a mention if there is time, since emitting both CycloneDX and SPDX with findings attached is something no other free JS tool does.
+
+**Run this before the fix.** After the fix the project is clean and the report is empty, which is an anticlimax rather than a finale.
+
+**4. The payoff, around 2 minutes**
+
+Copy the commands the scan printed, run them, rescan. It goes fully green:
+
+```
+Scan complete. No known vulnerabilities found.
+```
+
+**Use the commands from the run you just did, not the ones written here.** They change as advisories are published. See the warning below.
+
+Ending on green is deliberate. It is a stronger close than a document.
+
+The transitive story is the one to weave through: six of the findings are packages nobody installed directly, and they all resolve through a single `npm install express@...`. That is the part npm audit and Dependabot do not do.
+
+## Resetting between rehearsals
+
+Beat 4 rewrites `package.json` and the lockfile, so the project is clean afterwards and the demo cannot be repeated. Reset with:
+
+```bash
+git checkout -- examples/open-source-friday-demo
+```
+
+## The one real risk: results move
+
+Findings and fix versions come from live OSV and npm data, so **two runs hours apart can differ**. This happened during preparation: axios was recommended as `0.21.2` in one run and `0.33.0` in the next. Running beat 4 with a stale command leaves the project still showing findings, which turns the payoff beat into a shrug.
+
+**The fix is timing, not offline mode.** You are in the StreamYard room at 12:45 for tech checks and live at 1:00. Rehearse the scan in that window and use the commands from that run. Advisories are not published in a 15 minute gap, so the drift effectively disappears.
+
+Do not prepare the fix commands the day before and paste them on air.
+
+## Do not demo offline mode
+
+`--offline` is tempting for determinism. Do not use it for this demo. Two of the four beats are weaker or absent offline, and they are the two that differentiate the tool. See [Offline vs Online Results](https://owasp.org/cve-lite-cli/docs/offline-vs-online-results).
+
+**Registry-validated fix versions only work online.** Offline falls back to the advisory's raw `firstFixedVersion` hint. That removes beat 2 entirely: the "scanned 23 versions, 22 still vulnerable" columns and the "hint is not published on npm, using nearest published version" note both come from live registry calls.
+
+**Parent-version upgrades only run online.** Offline handles in-range parent updates but skips the case that needs a newer parent, showing "no safe version was identified automatically" instead. That is half the transitive story.
+
+Offline is also not what viewers get if they follow along, and `advisories sync` is setup narration that buys nothing on air.
+
+**Keep it as the fallback, not the plan.** If the network fails mid-stream, having a synced database means you can keep going rather than staring at a spinner on three broadcast channels. Sync it beforehand so it is there:
+
+```bash
+cve-lite advisories sync    # before the stream, as insurance only
+```
+
+If you do fall back to it live, say so, and say what changes: fix targets come from the advisory rather than the registry.
+
+## Their setup checklist
+
+From the Open Source Friday guest guide, the parts that need doing before 12:45:
+
+- Hardwired ethernet rather than wifi, and headphones
+- Browser zoomed to at least 125 percent, screen at 1920x1080
+- Clean browser profile with bookmarks bar and history hidden
+- Do-not-disturb on, browser extensions disabled
+- macOS menu bar and Dock set to auto-hide
+
+Stream starts at 1:00 PM ET; guests join at 12:45 for prep and tech checks.