docs(tutorial): run the whole pipeline at build, fail loudly on an empty mask

docs/site/tutorial.md

@@ -208,10 +208,21 @@ mask = cellsam_pipeline(
 )
 ```
 
+Before moving on, sanity-check the segmentation. The mask must have the same
+`H, W` dimensions as the input image **and** actually contain cells: a
+degenerate, all-background mask has the correct shape but silently produces an
+*empty* cell-type prediction downstream, so check both.
+
 ```{code-cell} ipython3
-# Sanity check: the segmentation mask should have the same H, W dimensions as
-# the input image
-mask.shape == img.shape[1:]
+assert mask.shape == img.shape[1:], "mask shape does not match the image H, W"
+assert mask.max() > 0, (
+    "segmentation produced no cells - try a different `membrane_channel` "
+    "(see the note above) and confirm cellSAM is running as expected"
+)
+
+# Number of cells detected. cellSAM's label IDs are not necessarily
+# contiguous, so count the distinct labels rather than taking the max.
+int((np.unique(mask) > 0).sum())
 ```
 
 Let's perform a bit of post-processing to ensure that the segmentation mask
@@ -247,8 +258,26 @@ mask_lyr = nim.add_labels(mask, name="CellSAM segmentation")
 mask_lyr.contour = 3  # Relatively thick borders for static viz
 ```
 
-The image and segmentation layers appear directly in the interactive Napari
-viewer. Static documentation builds do not execute or embed GUI screenshots.
+```{code-cell} ipython3
+:tags: [hide-cell]
+
+# For static rendering - can safely be ignored if running notebook interactively
+from pathlib import Path
+
+screenshot_path = Path("../_static/_generated")
+screenshot_path.mkdir(parents=True, exist_ok=True)
+nim.screenshot(
+    path=screenshot_path / "napari_img_and_segmentation.png",
+    canvas_only=False,
+);
+```
+
+<center>
+  <img src="../_static/_generated/napari_img_and_segmentation.png"
+       alt="Napari window of multiplexed image and computed segmentation mask"
+       width=100%
+  />
+</center>
 
 
 ### Cell-type inference with `deepcell-types`
@@ -401,9 +430,26 @@ for k, l in labels_by_celltype.items():
     )
 ```
 
-When running interactively, the new label layers appear directly in the Napari
-viewer and can be toggled independently. Static documentation builds do not
-execute or embed GUI screenshots.
+```{code-cell} ipython3
+:tags: [hide-cell]
+
+# For static rendering - can safely be ignored if running notebook interactively
+from pathlib import Path
+
+screenshot_path = Path("../_static/_generated")
+screenshot_path.mkdir(parents=True, exist_ok=True)
+nim.screenshot(
+    path=screenshot_path / "napari_celltype_layers.png",
+    canvas_only=False,
+);
+```
+
+<center>
+  <img src="../_static/_generated/napari_celltype_layers.png"
+       alt="Napari window of multiplexed image with celltype predictions"
+       width=100%
+  />
+</center>
 
 [hubmap-data-portal]: https://portal.hubmapconsortium.org/search/datasets
 [zarr]: https://zarr.readthedocs.io/en/stable/