Make the packet board and loss recovery easy to follow during the viva

README.md

@@ -1,5 +1,16 @@
 # Reliable UDP file transfer with SDN failover
 
+Transfer a binary file over UDP while an SDN controller routes around a failed
+or degraded network path. The C11 transport implements Selective Repeat, SACK, adaptive RTO and congestion control. The Python OpenFlow 1.3 controller schedules adaptive probes, reroutes around failures and supports weighted multipath DATA.
+
+## Quick start
+
+| Command | Opens or runs |
+| --- | --- |
+| `make demo` | Interactive eight-stage CLI assessment console |
+| `python3 scripts/run.py viz` | Live 32-packet browser telemetry at [localhost:8080](http://localhost:8080) |
+| `make test` | Full automated test suite |
+
 ## One-command assessment menu
 
 Run from the repository root.
@@ -37,9 +48,9 @@ Run the console from the repository root. It builds the C binaries and opens the
 python3 scripts/run.py viz
 ```
 
-Choose one of the six numbered scenarios. The default explain-mode playback supports play, pause and single-event stepping. Advanced manual controls and raw logs are collapsed below the three main panels. The console captures actual
+Choose one of the five numbered scenarios. The default 32-packet guided playback supports play, pause and single-event stepping. Advanced manual controls and raw logs are collapsed below the three main panels. The console captures actual
 24-byte headers through a UDP relay, streams sender/receiver JSONL records, shows
-the sender ring snapshots, and reports independent SHA-256 verification. The relay
+permanent packet cards, and reports independent SHA-256 verification. The relay
 adds 15 ms in each direction to make the transitions visible. **Drop next DATA**
 discards one observed DATA datagram.
 
@@ -50,9 +61,6 @@ supply only the fields they retained. The localhost run supplies transport data,
 while Mininet recordings supply controller events.
 
 
-Transfer a binary file over UDP while an SDN controller routes around a failed
-or degraded network path. The C11 transport implements Selective Repeat, SACK, adaptive RTO and congestion control. The Python OpenFlow 1.3 controller schedules adaptive probes, reroutes around failures and supports weighted multipath DATA.
-
 ## Try a file transfer on localhost
 
 Use a C compiler and Make. Open two terminals in the repository:
@@ -132,6 +140,6 @@ It provides no authentication, encryption, persistent resume or TCP fairness.
 
 ![Lower-branch failure and application recovery](results/presentation/timeline.svg)
 
-The retained Linux trial shows the sequence of controller and application events.
+Read the enlarged recovery interval first. The controller spent 1.227 ms installing the replacement route, then waited 41.038 ms for the first advancing ACK. The full transfer recovered in 42.265 ms from the observed cut. Compare successful configurations in the [goodput plot](results/presentation/goodput_mbps.svg).
 Across the measured evaluation, 132 transfers matched their hashes and 48 static
 failures were expected. [Measurements and scope](docs/REPORT.md).

docs/DEMO.md

@@ -35,19 +35,17 @@ select the stages needed for the assessment.
 python3 scripts/run.py viz
 ```
 
-Choose a numbered preset. Scenarios 1–3 execute real 1 MiB C transfers with the
-displayed transport settings. Scenario 4 runs the no-SACK and SACK variants on
-identical bytes and compares their measured outcomes. Scenarios 5–6 automatically
-load verified upper-path link-cut recordings, preferring live-failover/live-static
-directories when available and falling back to the retained evaluation.
-
-Play, pause and single-event stepping affect visual presentation. The backend
-continues collecting the real run into an SSE journal. Slow Explain Mode samples
-key transitions at one event per second and holds the first occurrence of each major milestone for four seconds.
-The event strip identifies the source and recorded time when available. A white outline identifies the current sequence inside the window.
-The counters follow the displayed event, and measured backend timestamps remain
-independent of presentation delays. Duplicate DATA arrivals are reported separately
-from final file integrity.
+Choose 1 for a clean 32 KiB transfer, 2 or 3 for the same first-attempt losses
+at packets 4, 14 and 23, or 4 to compare both modes on identical bytes.
+The C endpoints run first. Guided playback merges their events and relay frames
+by timestamp. Blue means sent, amber means buffered, and green means the client
+has acknowledged the contiguous prefix. Each card keeps its original ID.
+Scenario 5 replays a measured Mininet failover. For longer files the board
+shows the first 32 packets while the counters cover the entire transfer.
+
+Use Guided playback for a guided walkthrough, Step-by-step to stop at losses and
+retries, or Instant to reach the result. Click a story entry to inspect its
+packet states. Playback speed is independent of the measured transfer duration.
 
 Raw logs, wire bytes, manual transport settings and active-trial tail controls are
 inside the collapsed advanced drawer. Pause a red gap, amber buffered chunk or
@@ -105,7 +103,7 @@ Use this as an ownership and rehearsal plan. Attribute implementation work to it
 | 1 — Sender and reliability | 0:00–2:00 | 1, then 2 | “UDP gives us datagrams. Our sender adds sequence numbers, a bounded 32-slot window and retransmission. A missing ACK holds the contiguous base.” Point to a missing slot and the timer. |
 | 2 — Receiver and integrity | 2:00–4:00 | 3 | “The receiver saves later chunks instead of discarding them. SACK reports which chunks are already buffered. Once the hole is repaired, the contiguous prefix advances. CRC32 checks the file before finalization and independent SHA-256 verifies it.” Point to amber slots, the bitmap and MATCH. |
 | 3 — SDN control | 4:00–7:00 | 5 | “The application cannot repair a broken path. OpenFlow port status detects the hard cut. The controller installs the lower branch and waits for barriers. Separate bidirectional probes detect soft degradation and assess the backup.” Pause on LINK DOWN and ROUTE READY. |
-| 4 — Integration and evidence | 7:00–9:00 | 6, then 4 | “A static route cannot deliver through a permanent cut. The recorded matrix contains 132 hash-matched transfers and 48 expected static failures. This A/B pair is a separate live comparison.” Point to the failure outcome and measured comparison bars. |
+| 4 — Integration and evidence | 7:00–9:00 | CLI stage 6, then web preset 4 | “A static route cannot deliver through a permanent cut. The recorded matrix contains 132 hash-matched transfers and 48 expected static failures. This A/B pair is a separate live comparison.” Point to the failure outcome and measured comparison bars. |
 | All — Questions | 9:00–10:00 | Pause | Each person answers for the module they reviewed. Every member should be able to trace START → DATA/ACK → FIN and link down → route ready → useful ACK. |
 
 Prepare the recorded traces and A/B results before the assessment so selection and

docs/REPORT.md

@@ -81,6 +81,5 @@ from retained digest records and endpoint completion, not a fresh payload rehash
 The [labelled recovery timeline](../results/presentation/timeline.svg) is regenerated
 from the retained lower-recovery trial's progress, controller and outage records.
 The [goodput comparison](../results/presentation/goodput_mbps.svg) is regenerated
-from matrix/metrics.csv. Multi-line configuration labels, units, sample counts and
-mean/range annotations make each group identifiable. These are new renderings of
+from matrix/metrics.csv. Rows identify the configurations being compared. Each dot marks a mean and each line spans the observed range. Shared settings appear above the plot. These are new renderings of
 the recorded measurements.