Refresh the docs notebooks and fail CI when they drift from the library

.github/workflows/ci.yml

@@ -52,26 +52,12 @@ jobs:
         run: mypy processbehavior
       - name: Tests
         run: pytest tests/ -m "not slow" --cov=processbehavior --cov-report=xml --cov-report=term-missing
-      - name: Execute docs notebooks (ubuntu / 3.13 only)
-        # Allowlist of notebooks known to execute against the current API.
+      - name: Docs notebooks run and match their saved outputs (ubuntu / 3.13 only)
+        # The docs site shows each notebook's saved outputs without running it. This executes
+        # every docs notebook and fails if what a reader sees no longer matches; the fix is
+        # `python scripts/refresh_notebooks.py`.
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
-        run: |
-          pytest --nbmake \
-            docs/getting-started/quickstart.ipynb \
-            docs/tutorials/first-xmr-chart.ipynb \
-            docs/tutorials/coffee-shop.ipynb \
-            docs/tutorials/process-capability.ipynb \
-            docs/tutorials/process-capability-before-after.ipynb \
-            docs/tutorials/derived-variables.ipynb \
-            docs/tutorials/loss-function.ipynb \
-            docs/tutorials/xbar-s-analysis.ipynb \
-            docs/tutorials/staged-charts.ipynb \
-            docs/tutorials/signal-detection.ipynb \
-            docs/tutorials/stratified-analysis.ipynb \
-            docs/tutorials/design-state-tour.ipynb \
-            docs/tutorials/sds-validation.ipynb \
-            docs/tutorials/sds1-complete-analysis.ipynb \
-            --tb=short
+        run: python scripts/refresh_notebooks.py --check
       - name: Validate against Bishop's reference results (ubuntu / 3.13 only)
         # The ground-truth check: PB against every VAS run of Dr. Bishop's on hand
         # (tests/fixtures/bishop_analyses/). It lives outside tests/ because it

CHANGELOG.md

@@ -47,6 +47,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   report. The `detect_signals()` docstring no longer says Rules 1-4 are the default.
 
 ### Fixed
+- **Tutorial outputs match the library again.** The docs site shows each notebook's saved outputs,
+  and eight tutorials had drifted: limits from before 0.4.0 in the Design-State-1 analysis, flat
+  limits where they now vary by subgroup size in the reference validation, older process means and
+  signal counts. All were re-executed. The Derived Variables tutorial, saved without outputs, now
+  shows them. Prose that the new outputs contradicted was corrected; the Bishop reference values in
+  the reference validation now quote his VAS rerun of 13 October 2026.
+- **The factor x time interaction chart draws its lines in factor order on every machine.** It
+  sorted by time with an unstable sort, so the legend order, and the colour each line got, depended
+  on the numpy version.
 - **Three signal rules now match their definitions.** Rule 5 (trend) fired only on 7 rising or
   falling points, not 6; Rule 6 (oscillation) only on 15 alternating points, not 14; and Rule 2
   counted only points in Zone A, leaving out points beyond 3σ, which Western Electric and Wheeler
@@ -89,6 +98,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   still compared with VAS through their limits.
 
 ### CI / Infrastructure
+- **CI checks that docs notebooks match their saved outputs.** `scripts/refresh_notebooks.py`
+  re-executes the docs notebooks; with `--check` (in CI, replacing the nbmake run) it fails when a
+  notebook no longer runs or what a reader would see has changed, comparing printed text, tables
+  and each figure's data and labels. The `[test]` extra now needs nbclient, nbformat and ipykernel
+  instead of nbmake.
 - **Python 3.14 is tested** on Ubuntu and Windows, in CI and in the release gate, and listed in
   the package classifiers.
 - **The truth report runs in CI.** `validation/truth_report.py` runs on every push (Ubuntu,

CONTRIBUTING.md

@@ -91,6 +91,20 @@ summary.
 If a Bishop check fails after your change, the change is wrong — not the
 reference.
 
+## Docs notebooks
+
+The docs site shows each notebook's saved outputs; it does not run them. After a change that
+alters what a notebook prints or plots, refresh the saved outputs:
+
+```bash
+python scripts/refresh_notebooks.py                 # every docs notebook
+python scripts/refresh_notebooks.py docs/tutorials/signal-detection.ipynb
+```
+
+CI runs `python scripts/refresh_notebooks.py --check` and fails when a notebook no longer runs or
+no longer matches its saved outputs. Then read the text around any changed output: the check
+compares outputs, not prose.
+
 ## Citing the methodology
 
 Code and docs cite Bishop's VAS documentation manual by edition and equation number: