Visualization gallery notebook (not executed in CI)

.github/scripts/run_notebooks.py

@@ -1,4 +1,11 @@
-"""Execute every example notebook; fail CI on any cell error."""
+"""Execute every example notebook; fail CI on any cell error.
+
+A notebook opts out by setting ``metadata.compileml.ci_execute = false`` in
+its own notebook metadata — the declaration travels with the file, so it
+survives renames and is visible to anyone reading the notebook. Opted-out
+notebooks still ship committed outputs; the APIs they demonstrate are
+covered by the unit tests.
+"""
 
 import sys
 from pathlib import Path
@@ -10,8 +17,11 @@
 
 failed = False
 for path in sorted(EXAMPLES.glob("*.ipynb")):
-    print(f"executing {path.name} …", flush=True)
     nb = nbformat.read(path, as_version=4)
+    if nb.metadata.get("compileml", {}).get("ci_execute") is False:
+        print(f"skipping {path.name} (ci_execute: false)")
+        continue
+    print(f"executing {path.name} …", flush=True)
     try:
         NotebookClient(
             nb, timeout=900, kernel_name="python3", resources={"metadata": {"path": str(EXAMPLES)}}

CHANGELOG.md

@@ -34,6 +34,11 @@ inside each artifact (`schema_version`).
 - Runtime self-check: on artifacts recording `exact_attribution`, `decide()`
   refuses to emit an explanation whose residual is nonzero — every explained
   production decision now re-proves attribution integrity in place.
+- `examples/04_visualization.ipynb`: rendered reference gallery for the viz
+  suite — arrow geometry, exact remainder truncation, the depth>2 residual
+  bar, dependency-free SVG, every colour/sort encoding, per-band facets, and
+  restyling. Notebooks can now opt out of CI execution via
+  `metadata.compileml.ci_execute = false`.
 
 ### Changed
 - Documentation doctrine: explain everything by default. Complete attribution

CONTRIBUTING.md

@@ -29,6 +29,14 @@ The suite is deterministic and offline; `pytest` should pass everywhere.
 The GnuCOBOL parity test runs automatically where `cobc` is installed and
 skips elsewhere.
 
+### Notebooks
+
+CI executes the example notebooks on every push. A notebook may opt out by
+setting `metadata.compileml.ci_execute = false` — reserved for rendered
+galleries whose APIs are already covered by unit tests. If you change
+`compileml.viz`, re-run `examples/04_visualization.ipynb` and commit the
+regenerated figures.
+
 ## Style
 
 - `ruff check` and `black --check` (line length 100) must pass.

docs/howto/visualize.md

@@ -75,3 +75,11 @@ Every renderer accepts `labels={feature: display_name}` and a `colors={…}`
 override (keys: `up`, `down`, `base`, `remainder`, `residual`, `good`, `bad`,
 `neutral`), and the matplotlib functions take an `ax=` to compose into your
 own figures.
+
+## See it rendered
+
+[`examples/04_visualization.ipynb`](https://github.com/orgoca/CompileML/blob/main/examples/04_visualization.ipynb)
+is the visual reference for everything on this page: arrow geometry, exact
+remainder truncation, the depth>2 residual bar, inline SVG, every `color_by`
+and `value_color` encoding, `sort_metric` variants, per-band facets, and
+restyling with an institutional palette.

examples/README.md

@@ -1,14 +1,20 @@
 # CompileML examples
 
-Three executable notebooks, all offline and deterministic (synthetic
+Four executable notebooks, all offline and deterministic (synthetic
 credit-style data with a fixed seed) — they run top-to-bottom anywhere the
-package is installed, and CI executes them.
+package is installed.
+
+CI executes 01–03 on every push. Notebook 04 is a rendered gallery: it opts
+out of CI execution (`metadata.compileml.ci_execute = false`) and ships
+committed figures instead, since every API it demonstrates is already covered
+by `tests/test_viz.py`. Re-run it after changing anything in `compileml.viz`.
 
 | Notebook | What it shows |
 |---|---|
 | [`01_quickstart.ipynb`](01_quickstart.ipynb) | The full pipeline: teacher → whitebox → bands → reason codes → hashed artifact → stdlib-runtime decision → eight-check validation. Includes the reconciliation identity re-added by hand. |
 | [`02_deploy_sql_cobol.ipynb`](02_deploy_sql_cobol.ipynb) | The same artifact as a generated SQL query — **executed in SQLite and diffed against the Python runtime, integer for integer** — and as a generated COBOL program. |
 | [`03_governance.ipynb`](03_governance.ipynb) | Tamper refusal (edit one integer, loading fails), zero-churn recalibration with the predecessor-hash chain, and certified bands that find five real risk plateaus but refuse to segment noise. |
+| [`04_visualization.ipynb`](04_visualization.ipynb) | Reference gallery for `compileml[viz]`: waterfall arrow geometry, exact remainder truncation, the depth>2 residual bar, dependency-free SVG, every `color_by` / `value_color` / `sort_metric` option, per-band facets, and restyling with your own palette. |
 
 Notebooks 01 and 03 render their figures with
 [`compileml.viz`](../docs/howto/visualize.md) (`pip install compileml[viz]`) —