[cnicholas]

Summary

• What: a new CI-executed tutorial, docs/tutorials/staged-charts.ipynb, plus runnable staged examples in the chart-types guide, the API reference and the README.
• Why: phased Xbar/S and phase_statistics() ship in 0.5.0, but the guide's example used Wheeler's cavity data, which exists only as a test fixture, and no notebook used phased=True. Readers could not run any of it.
• Scope: docs only. The tutorial uses the bundled coffee-shop data, with the stage derived by one .bin() call on week (cut points 8, 12, 14), in the chained style: formulate, print(study.design()), execute(...).plot(title=...).

Contract / Invariants (must remain true)

• Default behavior unchanged: nothing under processbehavior/ changes
• Residuals unaffected: no library change
• Row/index alignment preserved: no library change
• Lane boundaries preserved: no library change
• Output schema compatible: no library change

Behavior Changes (explicit)

• New semantics (docs):
  • Tutorial 8, Staged Charts: one set of limits vs limits per stage on Xbar and S, phase_statistics(), signals, phased X/mR on every reading, a second factor pooled (by=['stage', 'date']) or charted on its own (by=['daypart'])
  • chart-types "Staged Xbar/S": the example runs as written; the pooling example now uses a study with a factor to pool (the cavity study has only one); a stage is a level, not a stretch of time; explicit (staged-xbar-s)= target, fixing the #staged-xbars links that pointed nowhere
  • api.md Phases: phase_by and insufficient_phases are Xbar/S-only metadata
  • README: a staged-chart snippet and a Features bullet

Key Design Decisions

• Data: bundled coffee-shop set, so every reader can run it; no Wheeler or fill-weight data bundled
• Plots: one chart per plot() call; the stacked companion layout collides its rotated subgroup labels with the second panel
• save_image: shown in Markdown only; CI has no kaleido

Risks & Mitigations

• P0 risks: prose numbers drifting from the outputs
• Mitigations: every quoted number checked against the executed outputs; the README and guide snippets executed as written and reproduce them

Tests

Added / Updated

• docs/tutorials/staged-charts.ipynb added to the nbmake allowlist in ci.yml

Regression Focus (must fail if broken)

• nbmake fails if phased Xbar/S, phase_statistics() or the bin-derived stage stop working as the tutorial uses them

Manual Verification

• pytest --nbmake docs/tutorials/staged-charts.ipynb passes
• pytest tests/test_manual_citations.py tests/test_notebook_ergonomics.py passes
• pytest tests/ -m "not slow": 2610 passed, 7 skipped
• README and chart-types snippets run as written: centres 241.26, 200.62, 220.50, 200.03; S-bar 32.11 for the new baristas
• myst build --html with mystmd 1.10.1: the page builds with its 14 plots; no new warnings
• A returning stage level merges into one phase (A, B, A gives phases A and B), as the docs now say

Notes

• Docs: CHANGELOG [Unreleased] Added
• Follow-ups (not in this PR): the design report counts a time-nested stage's impossible cells as empty (288 on this study) and lists levels alphabetically, ignoring an ordered categorical; a companion plot's second panel has no y-axis title; a returning stage level merges silently