Document real-world peak detector validation

README.md

@@ -69,20 +69,34 @@ roll weight, and comparable sawtooth/batch signals. It retains the current
 maximum and emits it only after the value is below
 `drop_ratio * current_peak` continuously for `hold_seconds`. Configuration is
 `min_peak`, `drop_ratio` (strictly between 0 and 1), non-negative
-`hold_seconds`, and positive `max_sample_gap_seconds`. The hold uses elapsed
+`hold_seconds`, and positive `max_sample_gap_seconds`. These are per-signal
+configuration parameters, not globally fixed process constants. The hold uses elapsed
 timestamps, never a sample count; an interval longer than the configured
 maximum sample gap restarts a reset candidate,
 so a timestamp gap alone is not evidence that a signal remained below threshold.
 `max_sample_gap_seconds` is required rather than defaulted, so the source's
 continuity assumption is explicit for each detector configuration.
-Reset values can be negative and need not be zero. Equal timestamps are
-accepted in arrival order but add no elapsed hold time; backwards timestamps
-are rejected.
+Reset values need not approach zero (and can be negative), and peak magnitude
+can vary materially between cycles. Equal timestamps are accepted in arrival
+order but add no elapsed hold time; backwards timestamps are rejected.
 
-The first real-world validation case is K7 roll length (m), variable
-`bf81c547-dccf-4709-aee2-0f78366d1dfc`. When the ignored local capture is
-present, run `python scripts/validate_k7_roll_length.py` to inspect detected
-peaks without adding the raw capture to tests or version control.
+Real-world validations use ignored local captures and are not part of the test
+suite. K7 roll length (m), variable `bf81c547-dccf-4709-aee2-0f78366d1dfc`, is
+the clean reference case: its 10-second capture produced exactly four plausible
+peaks of about 49.98 m with `min_peak=10`, `drop_ratio=0.75`,
+`hold_seconds=60`, and `max_sample_gap_seconds=20`. Run
+`python scripts/validate_k7_roll_length.py` when that capture is available.
+
+Bento 2 roll weight (kg), machine `6201f3de-b940-45d7-930c-1481c5ae9e1d`,
+variable `059c0015-9aff-4270-a4ce-f21b83f99378`, is the more realistic
+robustness case. Its observed 10-second signal has plateaus, reset values of
+roughly 300–470 kg, and materially varying peak heights. With
+`min_peak=800`, `drop_ratio=0.75`, `hold_seconds=60`, and
+`max_sample_gap_seconds=20`, the extended capture produces 13 plausible
+completed peaks, including a legitimate approximately 1195 kg cycle. Run
+`python scripts/validate_bento2_roll_weight.py` when the ignored capture is
+available. Neither capture should be added to version control or automated
+tests.
 
 `docker compose up -d timescaledb` is an optional local database design for a
 future persistence milestone. It is not required for the bootstrap tests.