specmod 0.2.0__tar.gz → 0.2.2__tar.gz

{specmod-0.2.0 → specmod-0.2.2}/.github/workflows/docs.yml

@@ -33,7 +33,12 @@ jobs:
 
       # The package itself, not just the docs extra: autodoc imports every
       # module it documents, so a docs build is also an import check.
-      - run: uv pip install -e ".[docs,io]"
+      #
+      # `tutorial` supplies the Jupyter kernel. `docs/conf.py` executes the
+      # tutorial notebook on every build instead of trusting committed outputs,
+      # so without ipykernel the build fails on a missing kernel. Keep this list
+      # in step with `.readthedocs.yaml`, which installs the same three.
+      - run: uv pip install -e ".[docs,io,tutorial]"
 
       - name: Build
         # No -W. Intersphinx resolves seven inventories over the network and

{specmod-0.2.0 → specmod-0.2.2}/.github/workflows/release.yml

@@ -28,20 +28,44 @@ jobs:
       - uses: googleapis/release-please-action@v4
         id: release
         with:
+          # A pull request opened with the default GITHUB_TOKEN starts no
+          # workflow runs at all — "events triggered by the GITHUB_TOKEN will
+          # not create a new workflow run". The release PR therefore arrived
+          # with *zero* checks, and since `ci`, `docs` and `build` are required
+          # on main, it could never satisfy them: permanently blocked, with no
+          # failure to point at. v0.2.0 shipped only because the PR was closed
+          # and reopened by hand, which re-fires the event from a real account.
+          #
+          # RELEASE_PLEASE_TOKEN_SPECMOD is a fine-grained PAT (contents + pull
+          # requests, write) so the PR is opened by a user and CI runs on it
+          # normally. It is *not* a PyPI credential — the upload below still
+          # authenticates by OIDC, so the number of publishing secrets is
+          # still zero. See docs/releasing.md for how to mint and renew it.
+          #
+          # The fallback keeps the workflow working in a fork or before the
+          # secret exists; it degrades to the blocked-PR behaviour, not to a
+          # broken run.
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN_SPECMOD || secrets.GITHUB_TOKEN }}
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json
 
   # Deliberately in this workflow rather than a separate publish.yml keyed on
-  # `release: published`, which is what §6.5 of the plan used to describe.
-  # release-please creates the release with the default GITHUB_TOKEN, and
-  # per GitHub's docs "events triggered by the GITHUB_TOKEN will not create a
-  # new workflow run" — so that publish workflow would never fire. The
-  # alternative is a personal access token in secrets, which is the one thing
-  # Trusted Publishing exists to avoid. Gating on the action's own output
-  # keeps the token count at zero.
+  # `release: published`, which is what §6.5 of the plan used to describe. That
+  # workflow could not fire at all while release-please ran on GITHUB_TOKEN,
+  # so this job gates on the action's own `release_created` output instead.
   #
-  # Zenodo is unaffected: it listens to the release *webhook*, which is not
-  # subject to that restriction, so the DOI is still minted from the release.
+  # With RELEASE_PLEASE_TOKEN_SPECMOD the release is created by a PAT, which
+  # *does* start workflow runs, so a separate publish.yml would now work. Still
+  # not worth splitting: one workflow is one concurrency group and one place to
+  # read, with no race between two runs when two merges land together. The
+  # `release_created` gate is also exact, where an event key would fire on any
+  # release — including one created by hand.
+  #
+  # Note the PAT is not a publishing credential: the upload below authenticates
+  # by OIDC, so the number of secrets that can push to PyPI is still zero.
+  #
+  # Zenodo is unaffected either way: it listens to the release *webhook*, which
+  # is not subject to the token restriction, so the DOI is minted regardless.
   publish:
     needs: release-please
     if: needs.release-please.outputs.release_created == 'true'

{specmod-0.2.0 → specmod-0.2.2}/.gitignore

@@ -26,6 +26,11 @@ htmlcov/
 
 # Docs
 docs/_build/
+# `docs/conf.py` copies `tutorial/` here so Sphinx can build the notebook from
+# inside its source directory, with the data it reads by relative path. The
+# copy is also what the notebook's own output lands in, which is the point —
+# executing it where it lives would write into the working tree.
+docs/tutorial/
 
 # Editors / OS
 .ftpconfig
@@ -39,9 +44,12 @@ docs/_build/
 
 # Tutorial output. Regenerated by running the notebook; committing it means a
 # diff every time anyone executes it, and a stale copy the moment the pipeline
-# changes. The inputs (Tutorial/Data, Tutorial/MetaData) *are* committed.
-Tutorial/Spectra/*.h5
-Tutorial/Spectra/FlatFiles/
+# changes. The inputs — waveforms, stations, picks — *are* committed.
+#
+# These patterns named `Tutorial/Spectra/` until now, the capitalised layout
+# from before the `src/` move, so they had matched nothing for the whole
+# refactor and the three files below were tracked in spite of the rule above.
+tutorial/data/events/*/spectra/
 
 # Created by `uv run` without --no-sync; this project resolves fresh on
 # purpose so the floors job can test the declared minimums.

{specmod-0.2.0 → specmod-0.2.2}/.readthedocs.yaml

@@ -42,6 +42,12 @@ python:
       extra_requirements:
         # `io` alongside `docs` because autodoc imports every module it
         # documents, and `specmod.io` imports h5py and pyarrow. Without it the
-        # API reference loses those pages to import errors.
+        # API reference loses those pages to import errors — and the tutorial
+        # saves an HDF5 file, so it needs them at execution time too.
         - docs
         - io
+        # `tutorial` supplies the Jupyter kernel. `docs/conf.py` executes the
+        # notebook on every build rather than trusting committed outputs, which
+        # needs ipykernel, nbclient and nbformat present. Without it the build
+        # fails on a missing kernel rather than quietly publishing stale cells.
+        - tutorial

specmod-0.2.2/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.2"
+}

{specmod-0.2.0 → specmod-0.2.2}/CHANGELOG.md

@@ -1,6 +1,38 @@
 # Changelog
 
-## [0.2.0](https://github.com/sgjholt/SpecMod/compare/v0.1.1...v0.2.0) (2026-08-23)
+<!-- The 0.2.0 heading below is edited by hand, and is the only entry that is.
+release-please generated `compare/v0.1.1...v0.2.0`, which 404s: 0.1.1 predates
+this repository's tagging and was never tagged, so there is nothing at that
+ref. It is preserved on the frozen `master` branch instead, and comparing
+against that branch is the same diff under a name that resolves. Only the first
+release could have this problem — every later one has a real predecessor tag —
+so leave subsequent headings as generated. release-please only prepends to this
+file, so this edit survives. -->
+
+## [0.2.2](https://github.com/sgjholt/SpecMod/compare/v0.2.1...v0.2.2) (2026-09-05)
+
+
+### Bug Fixes
+
+* ignore the tutorial output at the path it is actually written to ([ad34cc7](https://github.com/sgjholt/SpecMod/commit/ad34cc7d44208e5bd49a2d1f1277516670848dc7))
+
+
+### Documentation
+
+* publish the tutorial, executed on every build ([ccd1842](https://github.com/sgjholt/SpecMod/commit/ccd18429b9da5db875885d88269fb70686e6eaa3))
+
+## [0.2.1](https://github.com/sgjholt/SpecMod/compare/v0.2.0...v0.2.1) (2026-08-23)
+
+
+### Documentation
+
+* add the Zenodo DOI to the README and the citation metadata ([8a89884](https://github.com/sgjholt/SpecMod/commit/8a89884f654b14bf5eb9ed8a32d10dc22d5e5fb4))
+* PyPI and docs badges, and an install section for people who are not us ([d444397](https://github.com/sgjholt/SpecMod/commit/d44439762214b93fd8eef3f64745570b3b8be2b0))
+* repoint the 0.2.0 changelog link, which 404s ([f1bbe31](https://github.com/sgjholt/SpecMod/commit/f1bbe3143ca3ca6dd58f584546e716d2170a790a))
+* say where the code behind the publication lives ([ae7e906](https://github.com/sgjholt/SpecMod/commit/ae7e906209a87844cf2106a826be5111a6ef2036))
+* turn the roadmap's stages into milestones against versions ([b933e69](https://github.com/sgjholt/SpecMod/commit/b933e69d219a54e4a7db894797a507a3bb24e31c))
+
+## [0.2.0](https://github.com/sgjholt/SpecMod/compare/master...v0.2.0) (2026-08-23)
 
 
 ### ⚠ BREAKING CHANGES

{specmod-0.2.0 → specmod-0.2.2}/CITATION.cff

@@ -7,6 +7,13 @@ authors:
     given-names: James
 repository-code: "https://github.com/sgjholt/SpecMod"
 license: MIT
+identifiers:
+  # The concept DOI, which always resolves to the newest release. Zenodo also
+  # mints a version DOI per release; cite that one instead when reproducibility
+  # matters and you need the reader to land on the exact version you ran.
+  - type: doi
+    value: "10.5281/zenodo.22071455"
+    description: "Concept DOI — resolves to the latest release."
 keywords:
   - seismology
   - spectral modelling

{specmod-0.2.0 → specmod-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: specmod
-Version: 0.2.0
+Version: 0.2.2
 Summary: A Python toolbox for processing and modelling seismic spectra
 Project-URL: Homepage, https://github.com/sgjholt/SpecMod
 Project-URL: Repository, https://github.com/sgjholt/SpecMod
@@ -56,6 +56,10 @@ Description-Content-Type: text/markdown
 
 # SpecMod
 
+[![PyPI](https://img.shields.io/pypi/v/specmod.svg)](https://pypi.org/project/specmod/)
+[![Documentation](https://readthedocs.org/projects/specmod/badge/?version=stable)](https://specmod.readthedocs.io/en/stable/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22071455.svg)](https://doi.org/10.5281/zenodo.22071455)
+
 A Python toolbox for processing and modelling seismic spectra, following the
 method of Edwards *et al.* (2010).
 
@@ -71,26 +75,44 @@ source model to direct-phase spectra.
 > breaking changes at every `0.x` release until the API settles at 1.0 — they
 > land in minor bumps by design, with no deprecation cycle. Pin an exact
 > version for anything you intend to publish.
-> [`docs/roadmap.md`](docs/roadmap.md) says which stages are done and what 1.0
-> will mean; [`docs/REFACTOR_PLAN.md`](docs/REFACTOR_PLAN.md) is the working
-> document behind it.
+> [`docs/roadmap.md`](docs/roadmap.md) says what has shipped, in which version,
+> and what 1.0 will mean; [`docs/REFACTOR_PLAN.md`](docs/REFACTOR_PLAN.md) is
+> the working document behind it.
 
 ## Installation
 
 Requires Python 3.11 or newer.
 
+```sh
+pip install specmod
+```
+
+While this is `0.x`, pin the exact version in anything you intend to publish:
+`pip install specmod==<version>`, taking the current one from the badge above.
+The reason is in the status note — `0.x` releases move names and numbers, and
+the pin plus the configuration stamp each output carries are together what
+make a run reproducible.
+
+To work on SpecMod rather than with it, clone the repository and install it
+editable with the test and lint tooling:
+
 ```sh
 pip install -e ".[dev]"
 ```
 
-Optional extras:
+Optional extras, installable as `pip install "specmod[multitaper]"` or in
+combination — `pip install "specmod[multitaper,wavelet]"`:
 
 | Extra | Adds |
 |---|---|
+| `io` | `h5py` and `pyarrow` — needed to save or load spectra, as HDF5 for arrays and Parquet for tables |
 | `multitaper` | Prieto's `multitaper` package — jackknife confidence intervals, F-test for spectral lines |
 | `wavelet` | PyWavelets, for wavelet families beyond the built-in Morlet |
 | `mcmc` | `emcee`, for Markov-chain Monte Carlo parameter search |
 
+`io` is the one most people want: without it SpecMod computes and plots
+normally, but `specmod.io` raises on the first save telling you to install it.
+
 No Fortran compiler is needed. Multitaper estimation is implemented natively on
 SciPy's DPSS tapers, so the historical `mtspec` dependency — Fortran source with
 no wheels and no release since 2016 — is no longer required.
@@ -202,6 +224,13 @@ Every output records the configuration that produced it, a hash of it, and the
 SpecMod version, so a locally-overridden run is still reproducible from its
 outputs.
 
+The published Magna results were produced with **0.1.1**, which predates this
+refactor. That code is preserved unchanged on the
+[`master`](https://github.com/sgjholt/SpecMod/tree/master) branch, which is
+protected and frozen; `main` is the trunk now. `0.1.1` was never tagged or
+published to PyPI, so the branch is the reference — there is no release to
+install. Read it there when you need to see exactly what the paper ran.
+
 ## Documentation
 
 The full documentation — the pipeline with its equations, the estimator

{specmod-0.2.0 → specmod-0.2.2}/README.md

@@ -1,5 +1,9 @@
 # SpecMod
 
+[![PyPI](https://img.shields.io/pypi/v/specmod.svg)](https://pypi.org/project/specmod/)
+[![Documentation](https://readthedocs.org/projects/specmod/badge/?version=stable)](https://specmod.readthedocs.io/en/stable/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22071455.svg)](https://doi.org/10.5281/zenodo.22071455)
+
 A Python toolbox for processing and modelling seismic spectra, following the
 method of Edwards *et al.* (2010).
 
@@ -15,26 +19,44 @@ source model to direct-phase spectra.
 > breaking changes at every `0.x` release until the API settles at 1.0 — they
 > land in minor bumps by design, with no deprecation cycle. Pin an exact
 > version for anything you intend to publish.
-> [`docs/roadmap.md`](docs/roadmap.md) says which stages are done and what 1.0
-> will mean; [`docs/REFACTOR_PLAN.md`](docs/REFACTOR_PLAN.md) is the working
-> document behind it.
+> [`docs/roadmap.md`](docs/roadmap.md) says what has shipped, in which version,
+> and what 1.0 will mean; [`docs/REFACTOR_PLAN.md`](docs/REFACTOR_PLAN.md) is
+> the working document behind it.
 
 ## Installation
 
 Requires Python 3.11 or newer.
 
+```sh
+pip install specmod
+```
+
+While this is `0.x`, pin the exact version in anything you intend to publish:
+`pip install specmod==<version>`, taking the current one from the badge above.
+The reason is in the status note — `0.x` releases move names and numbers, and
+the pin plus the configuration stamp each output carries are together what
+make a run reproducible.
+
+To work on SpecMod rather than with it, clone the repository and install it
+editable with the test and lint tooling:
+
 ```sh
 pip install -e ".[dev]"
 ```
 
-Optional extras:
+Optional extras, installable as `pip install "specmod[multitaper]"` or in
+combination — `pip install "specmod[multitaper,wavelet]"`:
 
 | Extra | Adds |
 |---|---|
+| `io` | `h5py` and `pyarrow` — needed to save or load spectra, as HDF5 for arrays and Parquet for tables |
 | `multitaper` | Prieto's `multitaper` package — jackknife confidence intervals, F-test for spectral lines |
 | `wavelet` | PyWavelets, for wavelet families beyond the built-in Morlet |
 | `mcmc` | `emcee`, for Markov-chain Monte Carlo parameter search |
 
+`io` is the one most people want: without it SpecMod computes and plots
+normally, but `specmod.io` raises on the first save telling you to install it.
+
 No Fortran compiler is needed. Multitaper estimation is implemented natively on
 SciPy's DPSS tapers, so the historical `mtspec` dependency — Fortran source with
 no wheels and no release since 2016 — is no longer required.
@@ -146,6 +168,13 @@ Every output records the configuration that produced it, a hash of it, and the
 SpecMod version, so a locally-overridden run is still reproducible from its
 outputs.
 
+The published Magna results were produced with **0.1.1**, which predates this
+refactor. That code is preserved unchanged on the
+[`master`](https://github.com/sgjholt/SpecMod/tree/master) branch, which is
+protected and frozen; `main` is the trunk now. `0.1.1` was never tagged or
+published to PyPI, so the branch is the reference — there is no release to
+install. Read it there when you need to see exactly what the paper ran.
+
 ## Documentation
 
 The full documentation — the pipeline with its equations, the estimator

{specmod-0.2.0 → specmod-0.2.2}/docs/conf.py

@@ -14,7 +14,9 @@ gives.
 
 from __future__ import annotations
 
+import shutil
 from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
 
 project = "SpecMod"
 author = "James Holt"
@@ -32,7 +34,9 @@ except PackageNotFoundError:  # pragma: no cover - docs built without an install
 version = ".".join(release.split(".")[:2])
 
 extensions = [
-    "myst_parser",
+    #: `myst_nb` supersedes `myst_parser` — it is a superset, and loading both
+    #: makes Sphinx complain that the `.md` parser is registered twice.
+    "myst_nb",
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
@@ -45,9 +49,10 @@ extensions = [
 
 #: `REFACTOR_PLAN.md` is a working document, not documentation — it is written
 #: for whoever is doing the refactor and records decisions and their evidence.
-#: `notebooks/` is built by Phase 6 with myst-nb; until then the `.ipynb` files
-#: would be copied in without being executed, which is worse than leaving them
-#: out. `notes/` *is* included: `choosing-a-transform.md` links to it for a
+#: `notebooks/` holds the source for the transform comparison, which
+#: `tools/measure_docs.py` renders into `choosing-a-transform.md`; the page is
+#: what is published, so building the notebook too would duplicate it.
+#: `notes/` *is* included: `choosing-a-transform.md` links to it for a
 #: per-trace table, so excluding it broke that link.
 exclude_patterns = [
     "_build",
@@ -57,9 +62,58 @@ exclude_patterns = [
     ".DS_Store",
 ]
 
-#: Markdown only. Every page in `docs/` is already written that way, and
-#: allowing both means two syntaxes for the same job.
-source_suffix = {".md": "markdown"}
+# ------------------------------------------------------- the tutorial notebook
+
+#: The tutorial lives in `tutorial/`, outside this source directory, next to the
+#: 1 MB of PNR waveforms it reads through paths relative to itself. Sphinx only
+#: builds what is under `docs/`, so it is copied in here.
+#:
+#: A copy rather than a move, and rather than executing it where it sits,
+#: because **the notebook writes**: cell 53 saves an HDF5 file under
+#: `data/events/<event>/spectra/` and cell 54 writes flatfiles beside it. Run in
+#: place, a docs build would leave those artefacts in the working tree — which
+#: is why `tests/test_tutorial.py` executes it in a `tmp_path` copy too. This is
+#: the same trick, and the copy is what the artefacts land in.
+#:
+#: Copying the data with it is what keeps the notebook's `Path("data/events")`
+#: working, so the notebook is identical whether opened from `tutorial/`, run by
+#: pytest, or built here. `tutorial/` stays canonical: eight other files name
+#: `tutorial/data/events/`, and the CI job that executes it records that a
+#: renamed data directory has already broken this once.
+_HERE = Path(__file__).parent
+_TUTORIAL_SRC = _HERE.parent / "tutorial"
+_TUTORIAL_DST = _HERE / "tutorial"
+
+if _TUTORIAL_SRC.is_dir():
+    shutil.rmtree(_TUTORIAL_DST, ignore_errors=True)
+    shutil.copytree(_TUTORIAL_SRC, _TUTORIAL_DST)
+
+#: `force`, not `auto`. `auto` executes only notebooks that arrive without
+#: outputs, and the tutorial is committed *with* 28 cells of them — so `auto`
+#: would publish whatever was last saved by hand, which is the silent rot this
+#: is meant to end. Forcing it means the page can only show output the code
+#: actually produced against the code being documented.
+nb_execution_mode = "force"
+#: Matches `tests/test_tutorial.py`. The whole notebook runs in ~40s; the
+#: default 30s is per cell, and the two-stage fit is the one that would trip it.
+nb_execution_timeout = 600
+#: A notebook that raises fails the build. That is the point: an executed
+#: tutorial is only a guarantee if a broken one is loud.
+nb_execution_raise_on_error = True
+#: `False` keeps the kernel's working directory at the notebook's own, which is
+#: what `Path("data/events")` resolves against.
+nb_execution_in_temp = False
+
+#: Markdown for the prose pages — every one in `docs/` is written that way, and
+#: allowing reStructuredText too would mean two syntaxes for the same job — plus
+#: `.ipynb` for the tutorial.
+#:
+#: Both map to `myst-nb`, which is the only parser name `myst_nb` 1.4 registers:
+#: it does not re-register `myst_parser`'s `markdown`, so leaving `.md` pointing
+#: at that fails the build outright with "Source parser for markdown not
+#: registered". The `myst-nb` parser is a superset and reads the prose pages
+#: identically.
+source_suffix = {".md": "myst-nb", ".ipynb": "myst-nb"}
 
 #: `linkify` is deliberately absent: it needs `linkify-it-py` and every link in
 #: these pages is already explicit.

{specmod-0.2.0 → specmod-0.2.2}/docs/documentation.md

@@ -195,8 +195,11 @@ pages can link to each other's sections.
   those work; without it MyST does not read `$` at all.
 - `amsmath` is **not** enabled — nothing here uses a bare `\begin{align}`
   outside `$` delimiters. A `\begin{cases}` inside `$$` renders without it.
-- Markdown only. `source_suffix` maps `.md`; there is no reStructuredText in
-  `docs/`, so there is one syntax rather than two.
+- Markdown and notebooks. `source_suffix` maps `.md` and `.ipynb`, both to
+  `myst-nb` — there is no reStructuredText in `docs/`, so there is one prose
+  syntax rather than two. Both suffixes name `myst-nb` because that is the only
+  parser `myst_nb` registers; pointing `.md` at `myst_parser`'s `markdown`
+  fails the build with "Source parser for markdown not registered".
 - For a Sphinx directive that has no MyST spelling, drop into rST:
 
 ````markdown
@@ -225,6 +228,40 @@ Type hints come from the annotations via `autodoc_typehints = "description"`.
 `sphinx-autodoc-typehints` is deliberately **not** used: measured, it produced
 the same 367 documented objects while calling an API Sphinx 10 removes.
 
+### The tutorial notebook
+
+`tutorial/SpecModTutorial.ipynb` is published as part of the site and
+**executed on every build** (`nb_execution_mode = "force"`). Every figure and
+number on the page came from running that code against the code being
+documented, and a notebook that raises fails the build
+(`nb_execution_raise_on_error = True`). That is the whole point: a tutorial
+nobody runs is the first thing to rot, and this one broke three times before
+anything executed it.
+
+Three things about the arrangement are worth knowing before changing it.
+
+**It is copied into `docs/tutorial/` by `conf.py`, not moved.** Sphinx builds
+only what is under `docs/`, and the notebook reads its 1 MB of waveforms
+through paths relative to itself — so the data has to travel with it. The copy
+is gitignored. `tutorial/` stays canonical because eight other files name
+`tutorial/data/events/`, and a renamed data directory has broken this before.
+
+**The copy is also what the notebook writes into.** It saves an HDF5 file and
+two flatfiles as part of the lesson. Executed where it lives, a docs build
+would leave those in your working tree; `tests/test_tutorial.py` copies to
+`tmp_path` for exactly the same reason.
+
+**Outputs are stripped in git**, by the `nbstripout` pre-commit hook, and
+regenerated at build time. Do not commit them back: `force` ignores them, so a
+committed output is never what a reader sees — only a stale diff.
+
+The kernel comes from the `tutorial` extra. Both `.readthedocs.yaml` and
+`.github/workflows/docs.yml` install `[docs,io,tutorial]`; keep them in step or
+one of the two builds fails on a missing kernel. This does mean the notebook
+executes twice per pull request — once here and once in the `notebook` CI job,
+which also checks imports and that deleted modules stay unmentioned. Roughly
+40 seconds, paid twice, for two genuinely different failures.
+
 ### Numbers in prose
 
 Any table that came from a measurement is generated, not typed. Edit

{specmod-0.2.0 → specmod-0.2.2}/docs/index.md

@@ -24,8 +24,8 @@ treat everything here as provisional until the API settles at 1.0:
 
 What will *not* change silently: the units conventions and the Parseval
 contract are pinned by tests, and the golden references fail loudly rather
-than drifting. The [roadmap](roadmap.md) says which stages are done and what
-1.0 will mean.
+than drifting. The [roadmap](roadmap.md) says what has shipped, in which
+version, and what 1.0 will mean.
 :::
 
 ```python
@@ -45,6 +45,11 @@ print(fits.table[["id", "llpsp", "fc", "ts"]])
 
 ## Where to start
 
+[Tutorial](tutorial/SpecModTutorial.ipynb)
+: One event end to end — waveforms and picks in, source parameters out. Every
+  figure and number on the page is produced by running the notebook at build
+  time, so it cannot describe an API that no longer exists.
+
 [Processing](processing.md)
 : Every step of the pipeline with the equation it implements — what a window
   is, how the noise is compared against it, and what the bandwidth selector
@@ -67,8 +72,8 @@ print(fits.table[["id", "llpsp", "fc", "ts"]])
   settings that have to be turned on once.
 
 [Roadmap](roadmap.md)
-: What is built, what is being worked on, and what 1.0 will mean. Stages, not
-  dates.
+: What has shipped and in which version, what is being worked on, and what 1.0
+  will mean. Milestones, not dates.
 
 ## Working on SpecMod
 
@@ -97,6 +102,7 @@ one either way.
 :maxdepth: 2
 :hidden:
 
+tutorial/SpecModTutorial
 processing
 choosing-a-transform
 pick-formats