From 6996a0188e26d929233709d7cbff11b44879aee3 Mon Sep 17 00:00:00 2001
From: Constantinos Eleftheriou <constantinos.eleftheriou@ed.ac.uk>
Date: Mon, 12 Oct 2026 11:53:57 +0100
Subject: [PATCH 1/5] add docs for regressions analyiss

---
 .../how-to/imaging-with-behaviour-analysis.md | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/how-to/imaging-with-behaviour-analysis.md b/docs/how-to/imaging-with-behaviour-analysis.md
index e69de29..18b4e55 100644
--- a/docs/how-to/imaging-with-behaviour-analysis.md
+++ b/docs/how-to/imaging-with-behaviour-analysis.md
@@ -0,0 +1,21 @@
+# Imaging with behaviour
+
+## Pixel-wise regression
+
+`mesoscopy process regression` fits a ridge regression of behavioural regressors to every pixel of a ∆F/F
+recording. Run it on a z-scored recording from `process zscore`.
+
+```bash
+mesoscopy process regression /path/to/example-recording_zscored.h5 /path/to/example-recording_regressors.npz
+```
+
+The regressor file is an NPZ or HDF5 file holding the `regressors` matrix, their `labels` and the `trial_idx` of the
+frames they cover.
+
+Pass `-n/--nuisance-regressors` to add regressors recorded on another clock, such as motion energy from a behaviour
+camera. The nuisance file is an NPZ or HDF5 file with a `timestamps` array. Every other array in it becomes one
+regressor, resampled onto the recording's timestamps, z-scored and added to the regressor matrix. Repeat `-n` to add
+regressors from several files.
+
+The command writes `example-recording_zscored_regression.npz` with the coefficients, R² and mean squared error of
+every pixel. Pass `--h5` for an HDF5 file instead.

From 2ee8fc704a0da9f9ab1a18404ca31fe6bee9c52c Mon Sep 17 00:00:00 2001
From: Constantinos Eleftheriou <constantinos.eleftheriou@ed.ac.uk>
Date: Mon, 12 Oct 2026 11:55:10 +0100
Subject: [PATCH 2/5] add docs about custom masks in extracting region activity

---
 docs/typical-workflow.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/typical-workflow.md b/docs/typical-workflow.md
index 462cfa2..46af871 100644
--- a/docs/typical-workflow.md
+++ b/docs/typical-workflow.md
@@ -70,6 +70,13 @@ mesoscopy report /path/to/example-recording_registered.h5
 mesoscopy process regions /path/to/example-recording.nwb
 ```
 
+This writes `example-recording_regions.csv` with the mean ∆F/F of each Allen atlas region in every frame.
+
+Pass `-m/--mask` to extract custom regions instead. A mask is an NPY, NPZ or TIFF file drawn on the registered
+frames. A boolean mask gives one region, named after the file or, in an NPZ file, after its key. An integer mask
+gives one region per label, named `<name>_<label>`. Masks are not mirrored across hemispheres.
+Repeat `-m` to add masks from several files, and add `--include-aba` to keep the atlas regions as well.
+
 ## Extract peri-event window activity
 
 Given a recording aligned with `mesoscopy align` and the `*_trials.csv` from `visiomode-analysis session`, extract

From 193c00375fd9d072561a225d1220b5743572a747 Mon Sep 17 00:00:00 2001
From: Constantinos Eleftheriou <constantinos.eleftheriou@ed.ac.uk>
Date: Mon, 12 Oct 2026 12:05:57 +0100
Subject: [PATCH 3/5] change to a consistent style for cli help strings, add
 link to docs at end

---
 CHANGELOG.md                          |   4 +
 src/mesoscopy/__init__.py             |  50 ++++--
 src/mesoscopy/align/__init__.py       |  16 +-
 src/mesoscopy/convert/__init__.py     |  84 +++++-----
 src/mesoscopy/export/__init__.py      |  26 +--
 src/mesoscopy/inspect/__init__.py     |  13 +-
 src/mesoscopy/postprocess/__init__.py |   4 +
 src/mesoscopy/preprocess/__init__.py  |  39 +++--
 src/mesoscopy/process/__init__.py     | 218 ++++++++++++--------------
 src/mesoscopy/register/__init__.py    |  66 +++-----
 src/mesoscopy/report/__init__.py      |  22 +--
 tests/test_cli.py                     |  41 +++++
 12 files changed, 324 insertions(+), 259 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3cf5515..6ae08be 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,10 @@ Versions follow [Semantic Versioning](https://semver.org) (`<major>.<minor>.<pat
 
 ## Unreleased
 
+### Changed
+
+- Stylistic changes to CLI help strings.
+
 ## [0.17.0] - 2026-10-12
 
 ### Added
diff --git a/src/mesoscopy/__init__.py b/src/mesoscopy/__init__.py
index 14b457a..d19fb0e 100644
--- a/src/mesoscopy/__init__.py
+++ b/src/mesoscopy/__init__.py
@@ -30,18 +30,33 @@
 
 __version__ = version("mesoscopy")
 
+DOCS_URL = "https://docs.mesoscopy.org"
+
+
+def docs_epilog(page: str = "") -> str:
+    """Help epilog pointing at the docs.
+
+    Args:
+        page: Page path under the docs site, such as "how-to/metrics/". Empty for the home page.
+
+    Returns:
+        The epilog, marked so that click does not rewrap the URL.
+    """
+    return f"\b\nDocumentation at {DOCS_URL}/{page}" if page else f"\b\nDocumentation at {DOCS_URL}"
+
+
 # Lazy subcommands are imported only when they are looked up, to avoid importing heavy dependencies unnecessarily.
 LAZY_SUBCOMMANDS = {
-    "align": ("mesoscopy.align:align_cmd", "Write behaviour-aligned frame timestamps to a recording."),
+    "align": ("mesoscopy.align:align_cmd", "Align frame timestamps to a behaviour session."),
     "convert": ("mesoscopy.convert:convert_cmd", "Convert raw recordings to NWB or HDF5."),
-    "export": ("mesoscopy.export:export_cmd", "Export mesoscopy-generated files to other formats."),
-    "inspect": ("mesoscopy.inspect:inspect_cmd", "Inspect a recording session and associated preprocessing output."),
+    "export": ("mesoscopy.export:export_cmd", "Export mesoscopy files to other formats."),
+    "inspect": ("mesoscopy.inspect:inspect_cmd", "Inspect an NWB recording and its processing progress."),
     "postprocess": ("mesoscopy.postprocess:postprocess_cmd", "Postprocess extracted activity."),
-    "preprocess": ("mesoscopy.preprocess:preprocess_cmd", "Extract haemodynamics-corrected deltaF from a recording."),
-    "process": ("mesoscopy.process:process_cmd", "Extract activity from preprocessed or registered recordings."),
+    "preprocess": ("mesoscopy.preprocess:preprocess_cmd", "Extract haemodynamics-corrected ∆F/F from a recording."),
+    "process": ("mesoscopy.process:process_cmd", "Analyse preprocessed or registered recordings."),
     "register": ("mesoscopy.register:register_cmd", "Register recordings to an anatomical template."),
-    "report": ("mesoscopy.report:report_cmd", "Generate an HTML report for a mesoscopy processing step."),
-    "sample": ("mesoscopy:sample", "Sample an image frame from an HDF5 file and export it as a PNG."),
+    "report": ("mesoscopy.report:report_cmd", "Generate an HTML report for a pipeline stage."),
+    "sample": ("mesoscopy:sample", "Save one frame of an HDF5 recording as a PNG."),
     "start-time": ("mesoscopy:start_time", "Print a recording's start time."),
 }
 
@@ -115,7 +130,7 @@ def _load_lazy_command(self, cmd_name: str) -> click.Command:
         return cmd
 
 
-@click.group(cls=LazyGroup, lazy_subcommands=LAZY_SUBCOMMANDS)
+@click.group(cls=LazyGroup, lazy_subcommands=LAZY_SUBCOMMANDS, epilog=docs_epilog())
 @click.version_option(__version__)
 def cli():
     """Widefield calcium imaging analysis pipeline."""
@@ -124,13 +139,17 @@ def cli():
 @click.command()
 @click.argument("path", type=click.Path(exists=True))
 @click.argument("out_dir", type=click.Path(dir_okay=True))
-@click.option("--index", default=0, show_default=True, help="Index of frame to sample.")
-@click.option("--crop", default=0)
-@click.option("--vmin", type=float, default=0)
-@click.option("--vmax", type=float, default=255)
-@click.option("--key", type=str, default=None, help="Activity column")
+@click.option("--index", default=0, show_default=True, help="Index of the frame to save.")
+@click.option("--crop", default=0, show_default=True, help="Pixels to crop from each edge.")
+@click.option("--vmin", type=float, default=0, show_default=True, help="Lower end of the colour scale.")
+@click.option("--vmax", type=float, default=255, show_default=True, help="Upper end of the colour scale.")
+@click.option("--key", type=str, default=None, help="Dataset holding the frames, such as F or frames.")
 def sample(path, out_dir, index, crop=0, vmin=0, vmax=255, key="frames"):
-    """Sample an image frame from an HDF5 file and export it as a PNG."""
+    """Save one frame of an HDF5 recording as a PNG.
+
+    PATH is an HDF5 recording and OUT_DIR the directory for the image. Pick the frame with --index and its dataset
+    with --key. Writes <name>_sample-<index>.png.
+    """
     import h5py
     from matplotlib import pyplot as plt
 
@@ -154,7 +173,8 @@ def sample(path, out_dir, index, crop=0, vmin=0, vmax=255, key="frames"):
 def start_time(path: str) -> None:
     """Print a recording's start time.
 
-    This is the first /timestamps entry of an HDF5 file, or the session_start_time of an NWB file, as stored.
+    PATH is an HDF5 recording or an NWB file. Prints the first frame timestamp of an HDF5 file, or the session start
+    time of an NWB file.
     """  # noqa: DOC501
     from mesoscopy import io
 
diff --git a/src/mesoscopy/align/__init__.py b/src/mesoscopy/align/__init__.py
index 77bc394..e916ed5 100644
--- a/src/mesoscopy/align/__init__.py
+++ b/src/mesoscopy/align/__init__.py
@@ -43,26 +43,26 @@
     "--session-start",
     type=str,
     default=None,
-    help="Behaviour session start time, ISO 8601. Mutually exclusive with --behaviour-json.",
+    help="Behaviour session start time in ISO format, instead of --behaviour-json.",
 )
 @click.option(
     "--behaviour-json",
     type=click.Path(exists=True, dir_okay=False),
     default=None,
-    help="Visiomode behaviour session JSON file; its 'timestamp' key gives the session start.",
+    help="Visiomode behaviour session JSON file giving the session start.",
 )
 @click.option(
     "--behaviour-id",
     type=str,
     default=None,
-    help="Behaviour session identifier. Required with --session-start, defaults to the JSON file stem otherwise.",
+    help="Behaviour session identifier, required with --session-start. Defaults to the --behaviour-json file name.",
 )
 @click.option(
     "--max-offset",
     type=float,
     default=DEFAULT_MAX_OFFSET_S,
     show_default=True,
-    help="Largest allowed offset, in seconds, between the first frame and the behaviour session start.",
+    help="Largest allowed offset between the first frame and the session start, in seconds.",
 )
 def align_cmd(
     path: str,
@@ -71,7 +71,11 @@ def align_cmd(
     behaviour_id: str | None,
     max_offset: float,
 ) -> None:
-    """Write behaviour-aligned frame timestamps to a preprocessed or registered HDF5 recording."""  # noqa: DOC501
+    """Align frame timestamps to a behaviour session.
+
+    PATH is a preprocessed or registered HDF5 recording. Give the session start with --behaviour-json, or with
+    --session-start and --behaviour-id. Writes /timestamps_aligned, in seconds from the session start, into PATH.
+    """  # noqa: DOC501
     if (session_start is None) == (behaviour_json is None):
         msg = "Exactly one of --session-start or --behaviour-json is required."
         raise click.UsageError(msg)
@@ -103,7 +107,7 @@ def align_recording(
 
     Args:
         h5_path (str): Path to the HDF5 recording holding an ISO 8601 `/timestamps` dataset.
-        session_start (str | datetime): Behaviour session start time, ISO 8601.
+        session_start (str | datetime): Behaviour session start time, ISO format.
         behaviour_session (str): Behaviour session identifier.
         max_offset_s (float, optional): Largest allowed absolute offset of the first frame from the session start,
             in seconds. Defaults to 600.
diff --git a/src/mesoscopy/convert/__init__.py b/src/mesoscopy/convert/__init__.py
index 9ef32d0..ac4b63c 100644
--- a/src/mesoscopy/convert/__init__.py
+++ b/src/mesoscopy/convert/__init__.py
@@ -25,12 +25,15 @@
 
 import click
 
+from mesoscopy import docs_epilog
+
 
 @click.group("convert")
-def convert_cmd(): ...
+def convert_cmd() -> None:
+    """Convert raw recordings to NWB or HDF5."""
 
 
-@convert_cmd.command("h5")
+@convert_cmd.command("h5", epilog=docs_epilog("typical-workflow/"))
 @click.argument(
     "input_path",
     type=click.Path(exists=True),
@@ -40,7 +43,7 @@ def convert_cmd(): ...
     "--out-dir",
     type=click.Path(),
     default="./",
-    help="Output directory for converted file, defaults to current working directory. Will be created if it doesn't exist.",
+    help="Output directory, created if missing.",
 )
 @click.option(
     "-l",
@@ -48,37 +51,42 @@ def convert_cmd(): ...
     is_flag=True,
     show_default=True,
     default=False,
-    help="Create a link to the HDF5 dataset instead of copying it over. If this is enabled, you MUST keep the raw HDF5 file - if you delete it, the data will also be gone.",
+    help="Link the raw frames instead of copying them. The NWB file then needs the raw HDF5 file to stay in place.",
 )
 @click.option(
-    "-f", "--frames-group", type=str, default="frames", help="HDF group path under which frame data is stored."
+    "-f", "--frames-group", type=str, default="frames", show_default=True, help="HDF5 dataset holding the frames."
 )
 @click.option(
     "-t",
     "--timestamps-group",
     type=str,
     default="timestamps",
-    help="HDF group path under which timestamp data is stored.",
+    show_default=True,
+    help="HDF5 dataset holding the timestamps.",
 )
 @click.option(
     "-m",
     "--meta",
     "meta_path",
     type=click.Path(exists=True),
-    help="Path to animal metadata file. Must be YAML or JSON format.",
+    help="Subject and session metadata file in YAML or JSON format.",
 )
-@click.option("--subject-id", type=str, help="Metadata field - subject identifier.")
-@click.option("--sex", type=click.Choice(["M", "F"], case_sensitive=False), help="Metadata field - subject sex.")
-@click.option("--genotype", type=str, help="Metadata field - subject genotype.")
-@click.option("--species", type=str, help="Metadata field - subject species.")
-@click.option("--strain", type=str, help="Metadata field - subject strain.")
-@click.option("--dob", type=str, help="Metadata field - subject date of birth in YYYY-MM-DD format (i.e. 1900-01-31).")
-@click.option("--description", "session_description", type=str, help="Metadata field - session description.")
-@click.option("--experimenter", type=str, help="Metadata field - experimenter name.")
-@click.option("--lab", type=str, help="Metadata field - lab experiment was done in.")
-@click.option("--institution", type=str, help="Metadata field - institution experiment was done in.")
+@click.option("--subject-id", type=str, help="Subject identifier.")
+@click.option("--sex", type=click.Choice(["M", "F"], case_sensitive=False), help="Subject sex.")
+@click.option("--genotype", type=str, help="Subject genotype.")
+@click.option("--species", type=str, help="Subject species.")
+@click.option("--strain", type=str, help="Subject strain.")
+@click.option("--dob", type=str, help="Subject date of birth as YYYY-MM-DD.")
+@click.option("--description", "session_description", type=str, help="Session description.")
+@click.option("--experimenter", type=str, help="Experimenter name.")
+@click.option("--lab", type=str, help="Lab the session was recorded in.")
+@click.option("--institution", type=str, help="Institution the session was recorded in.")
 def convert_h5_cmd(**kwargs: typing.Any) -> None:
-    """Convert a raw mesoscale calcium recording session from HDF5 to an NWB file compatible with mesoscopy."""
+    """Convert a raw HDF5 recording to NWB.
+
+    INPUT_PATH is a raw dual-channel HDF5 recording. Fill in the subject and session metadata with --meta or the
+    metadata options. Writes an NWB file named after INPUT_PATH.
+    """
     import mesoscopy.convert.hdf5 as conv_h5
 
     conv_h5.to_nwb(**kwargs)
@@ -94,33 +102,33 @@ def convert_h5_cmd(**kwargs: typing.Any) -> None:
     "--out-dir",
     type=click.Path(),
     default="./",
-    help="Output directory for converted file, defaults to current working directory. Will be created if it doesn't exist.",
+    help="Output directory, created if missing.",
 )
 @click.option(
     "-t",
     "--ts-path",
     type=click.Path(exists=True),
-    help="Path to timestamps file. Must be plain text or delimited.",
+    help="Frame timestamps file, plain text or delimited.",
 )
 @click.option(
     "-d",
     "--ts-delimiter",
     type=click.Choice([",", "\t", " "], case_sensitive=False),
     default=",",
-    help="Timestamp file delimiter, if file is delimited.",
+    help="Delimiter of the timestamps file.",
 )
 @click.option(
     "-c",
     "--ts-column",
     type=int,
-    help="Column in timestamp file to be used as timestamps. Must be provided if file is delimited and has more than one column.",
+    help="Column of the timestamps file to read, needed when it has more than one.",
 )
 @click.option(
     "--ts-has-header",
     type=bool,
     is_flag=True,
     default=False,
-    help="Flag signifying whether or not the timestamps file has a header row.",
+    help="The timestamps file has a header row.",
 )
 @click.option(
     "-l",
@@ -128,27 +136,31 @@ def convert_h5_cmd(**kwargs: typing.Any) -> None:
     is_flag=True,
     show_default=True,
     default=False,
-    help="Generate an HDF5 linker file only without converting to NWB.",
+    help="Write the HDF5 file only, without converting it to NWB.",
 )
 @click.option(
     "-m",
     "--meta",
     "meta_path",
     type=click.Path(exists=True),
-    help="Path to animal metadata file. Must be YAML or JSON format.",
+    help="Subject and session metadata file in YAML or JSON format.",
 )
-@click.option("--subject-id", type=str, help="Metadata field - subject identifier.")
-@click.option("--sex", type=click.Choice(["M", "F"], case_sensitive=False), help="Metadata field - subject sex.")
-@click.option("--genotype", type=str, help="Metadata field - subject genotype.")
-@click.option("--species", type=str, help="Metadata field - subject species.")
-@click.option("--strain", type=str, help="Metadata field - subject strain.")
-@click.option("--dob", type=str, help="Metadata field - subject date of birth in YYYY-MM-DD format (i.e. 1900-01-31).")
-@click.option("--description", "session_description", type=str, help="Metadata field - session description.")
-@click.option("--experimenter", type=str, help="Metadata field - experimenter name.")
-@click.option("--lab", type=str, help="Metadata field - lab experiment was done in.")
-@click.option("--institution", type=str, help="Metadata field - institution experiment was done in.")
+@click.option("--subject-id", type=str, help="Subject identifier.")
+@click.option("--sex", type=click.Choice(["M", "F"], case_sensitive=False), help="Subject sex.")
+@click.option("--genotype", type=str, help="Subject genotype.")
+@click.option("--species", type=str, help="Subject species.")
+@click.option("--strain", type=str, help="Subject strain.")
+@click.option("--dob", type=str, help="Subject date of birth as YYYY-MM-DD.")
+@click.option("--description", "session_description", type=str, help="Session description.")
+@click.option("--experimenter", type=str, help="Experimenter name.")
+@click.option("--lab", type=str, help="Lab the session was recorded in.")
+@click.option("--institution", type=str, help="Institution the session was recorded in.")
 def convert_video_cmd(**kwargs: typing.Any) -> None:
-    """Convert a raw mesoscale calcium recording session from video to an NWB file compatible with mesoscopy."""
+    """Convert a raw video recording to NWB.
+
+    INPUT_PATH is an AVI or MP4 recording and --ts-path its frame timestamps file. Fill in the subject and session
+    metadata with --meta or the metadata options. Writes an HDF5 file and an NWB file named after INPUT_PATH.
+    """
     import mesoscopy.convert.video as conv_vid
 
     if not kwargs.get("ts_path"):
diff --git a/src/mesoscopy/export/__init__.py b/src/mesoscopy/export/__init__.py
index 94f84d9..1c8c7d5 100644
--- a/src/mesoscopy/export/__init__.py
+++ b/src/mesoscopy/export/__init__.py
@@ -32,7 +32,7 @@
 
 @click.group("export")
 def export_cmd() -> None:
-    """Export mesoscopy-generated files."""
+    """Export mesoscopy files to other formats."""
 
 
 @export_cmd.command("nwb")
@@ -41,11 +41,14 @@ def export_cmd() -> None:
     "--out-path",
     type=click.Path(dir_okay=False, path_type=str),
     default="",
-    help="Path to save the exported NWB file. "
-    "If not provided, the output file will be named as the input file with '_export.nwb' appended.",
+    help="Path of the exported NWB file. Defaults to <name>_export.nwb next to NWB_PATH.",
 )
 def export_nwb_cmd(**kwargs: typing.Any) -> None:
-    """Create a sharable copy of an NWB file by resolving external data links."""
+    """Make a shareable copy of an NWB file.
+
+    NWB_PATH is an NWB file that links to the HDF5 files mesoscopy writes. Writes a self-contained copy with the
+    linked data copied in.
+    """
     click.echo("Exporting NWB file...")
     export_path = export_nwb(**kwargs)
     click.echo(f"NWB file exported to {export_path}")
@@ -57,11 +60,13 @@ def export_nwb_cmd(**kwargs: typing.Any) -> None:
     "--out-path",
     type=click.Path(dir_okay=True, path_type=str),
     default=".",
-    help="Path to save the exported video file."
-    "If not provided, the output file will be named as the input file with '_deltaf.mp4' appended.",
+    help="Output directory for the video.",
 )
 def export_deltaf_cmd(**kwargs: typing.Any) -> None:
-    """Export delta F frames as a video file."""
+    """Export a ∆F/F recording as a video.
+
+    PATH is an HDF5 or NWB ∆F/F recording. Writes <session>_deltaf.mp4.
+    """
     export_deltaf(**kwargs)
 
 
@@ -71,10 +76,13 @@ def export_deltaf_cmd(**kwargs: typing.Any) -> None:
     "--out-dir",
     type=click.Path(dir_okay=True, path_type=str),
     default=".",
-    help="Directory to save the exported timestamps file.",
+    help="Output directory for the timestamps file.",
 )
 def export_timestamps_cmd(**kwargs: typing.Any) -> None:
-    """Export timestamps as a text file."""
+    """Export a recording's timestamps as text.
+
+    PATH is an HDF5 or NWB recording. Writes <session>_timestamps.txt with one timestamp per line.
+    """
     click.echo("Exporting timestamps...")
     export_timestamps(**kwargs)
     click.echo(f"Timestamps exported to {kwargs['out_dir']}")
diff --git a/src/mesoscopy/inspect/__init__.py b/src/mesoscopy/inspect/__init__.py
index 967274f..347a592 100644
--- a/src/mesoscopy/inspect/__init__.py
+++ b/src/mesoscopy/inspect/__init__.py
@@ -23,10 +23,11 @@
 
 import click
 
+from mesoscopy import docs_epilog
 from mesoscopy import io
 
 
-@click.command("inspect")
+@click.command("inspect", epilog=docs_epilog("typical-workflow/"))
 @click.argument(
     "input_path",
     type=click.Path(exists=True),
@@ -36,24 +37,32 @@
     "info_level",
     flag_value="meta_only",
     default=True,
+    help="Print the metadata only. This is the default.",
 )
 @click.option(
     "--acquisition",
     "info_level",
     flag_value="acquisition",
+    help="Also open the raw acquisition in a viewer.",
 )
 @click.option(
     "--deltaf",
     "info_level",
     flag_value="deltaf",
+    help="Also open the ∆F/F series in a viewer.",
 )
 @click.option(
     "--registered",
     "info_level",
     flag_value="registered",
+    help="Also open the registered ∆F/F series in a viewer.",
 )
 def inspect_cmd(input_path: str, info_level: str) -> None:
-    """Inspect a calcium recording session and associated preprocessing output. Files must be in NWB format."""
+    """Inspect an NWB recording and its processing progress.
+
+    INPUT_PATH is an NWB file. Pass --acquisition, --deltaf or --registered to open that data in a napari viewer.
+    Prints the session metadata and which pipeline stages have run.
+    """
     inspect(input_path=input_path, info_level=info_level)
 
 
diff --git a/src/mesoscopy/postprocess/__init__.py b/src/mesoscopy/postprocess/__init__.py
index 349f1cc..a33b8bb 100644
--- a/src/mesoscopy/postprocess/__init__.py
+++ b/src/mesoscopy/postprocess/__init__.py
@@ -26,4 +26,8 @@
 
 @click.command()
 def postprocess_cmd():
+    """Postprocess extracted activity.
+
+    This command is a placeholder and does nothing (yet).
+    """
     click.echo("Postprocessing")
diff --git a/src/mesoscopy/preprocess/__init__.py b/src/mesoscopy/preprocess/__init__.py
index 57a3580..acdebf8 100644
--- a/src/mesoscopy/preprocess/__init__.py
+++ b/src/mesoscopy/preprocess/__init__.py
@@ -28,6 +28,7 @@
 import click
 import numpy as np
 
+from mesoscopy import docs_epilog
 from mesoscopy import io
 from mesoscopy import timer
 
@@ -35,7 +36,7 @@
     from dask import array as da
 
 
-@click.command(name="preprocess")
+@click.command(name="preprocess", epilog=docs_epilog("typical-workflow/"))
 @click.argument(
     "path",
     type=click.Path(exists=True),
@@ -45,60 +46,72 @@
     "--out_dir",
     type=click.Path(dir_okay=True),
     default="./",
-    help="Output directory for preprocessed recording.",
+    help="Output directory for the preprocessed recording.",
 )
-@click.option("--chunks", default=100, help="Number of chunks to load in memory.")
+@click.option("--chunks", default=100, show_default=True, help="Frames loaded into memory at a time.")
 @click.option(
     "--crop",
     default=0,
-    help="Number of pixels to crop from the edges of the recording.",
+    show_default=True,
+    help="Pixels to crop from each edge.",
 )
-@click.option("--bins", default=2, help="Recording pixel binning factor.")
+@click.option("--bins", default=2, show_default=True, help="Pixel binning factor.")
 @click.option(
     "--channel-means-only",
     is_flag=True,
     show_default=True,
     default=False,
-    help="Extract the channel means and exit without extracting a delta F series.",
+    help="Stop after extracting the channel means.",
 )
 @click.option(
     "--use-means",
     is_flag=True,
     show_default=True,
     default=False,
-    help="Separate channels using means histogram instead of standard deviation.",
+    help="Separate the channels by their mean intensity instead of their standard deviation.",
 )
 @click.option(
     "--flip-channels",
     is_flag=True,
     show_default=True,
     default=False,
-    help="Flip channel order.",
+    help="Swap the two channels after separating them.",
+)
+@click.option(
+    "--interim_dir",
+    type=click.Path(dir_okay=True),
+    default="interim/",
+    show_default=True,
+    help="Directory for intermediate files, removed when preprocessing ends.",
 )
-@click.option("--interim_dir", type=click.Path(dir_okay=True), default="interim/")
 @click.option(
     "--skip-start",
     default=None,
     type=int,
-    help="Number of frames to skip at the start of the recording.",
+    help="Frames to drop from the start of the recording.",
 )
 @click.option(
     "--skip-end",
     default=None,
     type=int,
-    help="Number of frames to skip at the end of the recording.",
+    help="Frames to drop from the end of the recording.",
 )
 @click.option(
     "--no-qa",
     is_flag=True,
     show_default=True,
     default=False,
-    help="Skip automatic quality control checks.",
+    help="Skip the automatic quality control checks.",
 )
 def preprocess_cmd(
     **kwargs: typing.Any,
 ) -> None:
-    """This command will preprocess a single session dual-channel mixed recording to extract a deltaF signal corrected for the haemodynamic response."""
+    """Extract haemodynamics-corrected ∆F/F from a recording.
+
+    PATH is a raw dual-channel HDF5 or NWB recording. Use --crop and --bins to shrink the frames, and --skip-start
+    and --skip-end to drop frames at either end. Writes <session>_preprocessed.h5, and links it into PATH when PATH
+    is an NWB file.
+    """
     run_preprocessing(**kwargs)
 
 
diff --git a/src/mesoscopy/process/__init__.py b/src/mesoscopy/process/__init__.py
index 703f6d6..218b505 100644
--- a/src/mesoscopy/process/__init__.py
+++ b/src/mesoscopy/process/__init__.py
@@ -38,6 +38,7 @@
 import mesoscopy.process.decoding as pdc
 import mesoscopy.process.metrics as pm
 import mesoscopy.process.perievent as pev
+from mesoscopy import docs_epilog
 from mesoscopy import io
 from mesoscopy import timer
 
@@ -48,7 +49,8 @@
 
 
 @click.group("process")
-def process_cmd(): ...
+def process_cmd() -> None:
+    """Analyse preprocessed or registered recordings."""
 
 
 @process_cmd.command("smooth")
@@ -61,17 +63,22 @@ def process_cmd(): ...
     "--out_dir",
     type=click.Path(dir_okay=True),
     default="./",
-    help="Output directory for smoothed recording.",
+    help="Output directory for the smoothed recording.",
 )
 @click.option(
     "-s",
     "--sigma",
     type=int,
     default=2,
+    show_default=True,
     help="Standard deviation of the Gaussian kernel, in pixels.",
 )
 def smooth_cmd(path: str, out_dir: str, sigma: int = 2) -> None:
-    """Generate a smoothed DeltaF/F recording using a Laplace of Gaussian filter."""
+    """Smooth a ∆F/F recording.
+
+    PATH is an HDF5 or NWB ∆F/F recording. Set the width of the Laplacian-of-Gaussian filter with --sigma. Writes
+    <session>_smoothed.h5.
+    """
     import mesoscopy.process.smooth as psm
 
     if not Path(out_dir).exists():
@@ -111,10 +118,13 @@ def smooth_cmd(path: str, out_dir: str, sigma: int = 2) -> None:
     "--out_dir",
     type=click.Path(dir_okay=True),
     default="./",
-    help="Output directory for z-scored recording.",
+    help="Output directory for the z-scored recording.",
 )
 def zscore_cmd(path: str, out_dir: str) -> None:
-    """Pixel-wise z-score ∆F/F signal."""
+    """Z-score a ∆F/F recording pixel by pixel.
+
+    PATH is an HDF5 or NWB ∆F/F recording. Writes <session>_zscored.h5, and adds it to PATH when PATH is an NWB file.
+    """
     from pynwb.image import ImageSeries
 
     import mesoscopy.process.zscore as pzs
@@ -170,7 +180,7 @@ def zscore_cmd(path: str, out_dir: str) -> None:
         io.write_nwb(path, nwbfile, io=nwbio)
 
 
-@process_cmd.command("regions")
+@process_cmd.command("regions", epilog=docs_epilog("typical-workflow/"))
 @click.argument(
     "path",
     type=click.Path(exists=True),
@@ -180,7 +190,7 @@ def zscore_cmd(path: str, out_dir: str) -> None:
     "--out_dir",
     type=click.Path(dir_okay=True),
     default="./",
-    help="Output directory for region activity file.",
+    help="Output directory for the region activity file.",
 )
 @click.option(
     "-m",
@@ -188,23 +198,21 @@ def zscore_cmd(path: str, out_dir: str) -> None:
     "mask_paths",
     type=click.Path(exists=True),
     multiple=True,
-    help=(
-        "Path to a custom region mask file (NPY, NPZ or TIFF), drawn in registered frame coordinates. A boolean mask"
-        " is extracted as a single region, named after the file (or, for NPZ files, after each key); an"
-        " integer-labelled mask is extracted as one region per label, named '<name>_<label>'. Masks are used as"
-        " drawn and are not mirrored across hemispheres. May be passed multiple times to combine masks from several"
-        " files. Supplying a mask replaces the ABA region extraction unless --include-aba is given."
-    ),
+    help="Region mask file in NPY, NPZ or TIFF format, drawn on the registered frames. Repeat to add more files.",
 )
 @click.option(
     "--include-aba",
     is_flag=True,
     default=False,
-    help="Extract ABA-defined regions alongside any custom masks. Has no effect if no mask is supplied.",
+    help="Extract the atlas regions alongside the -m masks.",
 )
 # A click command's docstring doubles as its --help text, so it deliberately carries no Raises: section.
 def regions_cmd(path: str, out_dir: str, mask_paths: tuple[str, ...], include_aba: bool) -> None:
-    """Extract ∆F signal averages from ABA-defined regions, custom region masks, or both."""  # noqa: DOC501
+    """Extract the mean ∆F/F of each brain region.
+
+    PATH is a registered HDF5 or NWB recording. Pass -m to use your own region masks instead of the Allen atlas
+    regions, and --include-aba to keep both. Writes <session>_regions.csv with the mean trace of each region.
+    """  # noqa: DOC501
     import pandas as pd
 
     import mesoscopy.process.region as pr
@@ -268,7 +276,7 @@ def regions_cmd(path: str, out_dir: str, mask_paths: tuple[str, ...], include_ab
     click.echo(f"Saved region activity at {outpath}")
 
 
-@process_cmd.command("regression")
+@process_cmd.command("regression", epilog=docs_epilog("how-to/imaging-with-behaviour-analysis/"))
 @click.argument(
     "recording_path",
     type=click.Path(exists=True),
@@ -282,14 +290,15 @@ def regions_cmd(path: str, out_dir: str, mask_paths: tuple[str, ...], include_ab
     "--out_dir",
     type=click.Path(dir_okay=True),
     default="./",
-    help="Output directory for regression results.",
+    help="Output directory for the regression results.",
 )
 @click.option(
     "-a",
     "--alpha",
     type=float,
     default=1.0,
-    help="Ridge regularisation strength. Defaults to 1.0.",
+    show_default=True,
+    help="Ridge regularisation strength.",
 )
 @click.option(
     "-n",
@@ -297,35 +306,27 @@ def regions_cmd(path: str, out_dir: str, mask_paths: tuple[str, ...], include_ab
     "nuisance_regressor_paths",
     type=click.Path(exists=True),
     multiple=True,
-    help=(
-        "Path to an external nuisance regressor file (NPZ or HDF5), e.g. behavioural motion energy. Every"
-        " array/dataset in the file other than 'timestamps' is treated as one nuisance regressor and interpolated"
-        " onto the recording's own timestamps before being z-scored and appended to the regressor matrix. May be"
-        " passed multiple times to add nuisance regressors from several files."
-    ),
+    help="Nuisance regressor file in NPZ or HDF5 format, such as motion energy. Repeat to add more files.",
 )
 @click.option(
     "-f",
     "--fast",
     is_flag=True,
     default=False,
-    help=(
-        "Use fast vectorised implementation of ridge regression. This is an experimental feature and may not work for"
-        " all datasets. Use with caution. Defaults to False."
-    ),
+    help="Use the faster, experimental vectorised solver.",
 )
 @click.option(
     "--npz",
     "file_format",
     flag_value="npz",
     default="npz",
-    help="Save regression results as a compressed NumPy .npz file. Defaults to True.",
+    help="Save the results as a compressed NPZ file. This is the default.",
 )
 @click.option(
     "--h5",
     "file_format",
     flag_value="h5",
-    help="Save regression results as an HDF5 file. Defaults to False.",
+    help="Save the results as an HDF5 file.",
 )
 def regression_cmd(
     recording_path: str,
@@ -336,7 +337,12 @@ def regression_cmd(
     fast: bool,
     file_format: str,
 ) -> None:
-    """Perform pixel-wise ridge regression on a preprocessed ∆F/F recording."""  # noqa: DOC501
+    """Regress behavioural variables onto each ∆F/F pixel.
+
+    RECORDING_PATH is an HDF5 or NWB ∆F/F recording and REGRESSOR_PATH an NPZ or HDF5 file of regressors. Add
+    regressors recorded on another clock with -n. Writes <session>_regression.npz with the coefficients, R² and mean
+    squared error of each pixel.
+    """  # noqa: DOC501
     import mesoscopy.process.regression as regr
 
     if not Path(out_dir).exists():
@@ -443,8 +449,8 @@ def _metrics_options(command: Callable[..., None]) -> Callable[..., None]:
             type=click.Choice(pm.ONSET_METHODS),
             default="sd",
             show_default=True,
-            help="Onset by threshold at a multiple of the baseline SD or a fraction of the amplitude, or by"
-            " extrapolating a line fitted to the rise back to baseline.",
+            help="Onset by a baseline SD threshold, an amplitude fraction threshold, or a line extrapolated from the"
+            " rise.",
         ),
         click.option(
             "--onset-sd",
@@ -480,7 +486,7 @@ def _metrics_options(command: Callable[..., None]) -> Callable[..., None]:
             type=int,
             default=1,
             show_default=True,
-            help="Moving-average window in samples, odd, for peak, onset, decay and offset detection. 1 disables.",
+            help="Odd moving-average window in samples used to find peaks, onsets, decays and offsets. 1 turns it off.",
         ),
         click.option(
             "--decay-fraction",
@@ -494,8 +500,7 @@ def _metrics_options(command: Callable[..., None]) -> Callable[..., None]:
             type=click.IntRange(min=1),
             default=10,
             show_default=True,
-            help="Trial groups with fewer trials get empty session summaries, reliability and mean-trace metrics. The"
-            " all-trials session summaries are always taken.",
+            help="Trial groups with fewer trials get empty session, reliability and mean-trace metrics.",
         ),
     ]
     for option in reversed(options):
@@ -524,8 +529,8 @@ def wrapper(*args: typing.Any, **kwargs: typing.Any) -> None:
             "--mask-response/--no-mask-response",
             default=True,
             show_default=True,
-            help="End cue-aligned reliability epochs at each trial's response; trials without one end at the"
-            " median response time.",
+            help="End cue-aligned reliability epochs at each trial's response, or at the median response time for"
+            " trials without one.",
         ),
         click.option(
             "--min-rt",
@@ -656,7 +661,7 @@ def _write_metrics(tables: pm.MetricsTables, out_dir: str, stem: str) -> None:
         click.echo(f"Saved {description} at {path}")
 
 
-@process_cmd.command("peri-event")
+@process_cmd.command("peri-event", epilog=docs_epilog("typical-workflow/"))
 @click.argument(
     "recording_path",
     type=click.Path(exists=True, dir_okay=False),
@@ -670,7 +675,7 @@ def _write_metrics(tables: pm.MetricsTables, out_dir: str, stem: str) -> None:
     "--out_dir",
     type=click.Path(dir_okay=True),
     default="./",
-    help="Output directory for peri-event windows.",
+    help="Output directory for the peri-event windows.",
 )
 @click.option(
     "--event",
@@ -705,19 +710,19 @@ def _write_metrics(tables: pm.MetricsTables, out_dir: str, stem: str) -> None:
     type=click.Choice(["interp", "nearest"]),
     default="interp",
     show_default=True,
-    help="Linear interpolation, or the nearest recorded sample.",
+    help="Resample by linear interpolation or by taking the nearest recorded sample.",
 )
 @click.option(
     "--baseline",
     type=(float, float),
     default=None,
-    help="Baseline window START END, seconds relative to the event; its mean is subtracted per trial.",
+    help="Baseline window START END in seconds from the event, whose mean is subtracted from each trial.",
 )
 @click.option(
     "--with-metrics",
     is_flag=True,
     default=False,
-    help="Also write the response metrics of `process metrics`, joined with TRIALS_PATH. CSV input only.",
+    help="Also write the `process metrics` tables. CSV input only.",
 )
 @_metrics_options
 @_reliability_options
@@ -745,12 +750,12 @@ def perievent_cmd(
     reliability: pm.ReliabilityOptions,
     bootstrap: pm.BootstrapOptions,
 ) -> None:
-    """Extract per-trial windows around a behavioural event from a behaviour-aligned recording.
+    """Cut per-trial windows around a behavioural event.
 
-    RECORDING_PATH is an HDF5 recording with /F and /timestamps_aligned, or a _regions.csv with a time_aligned
-    column. TRIALS_PATH is the *_trials.csv written by visiomode-analysis session. HDF5 input gives HDF5 output;
-    CSV input gives long-format CSV output with the TRIALS_PATH columns joined onto every row. --with-metrics also
-    writes the tables of `process metrics` from the CSV output, using --baseline as the metrics baseline window.
+    RECORDING_PATH is a behaviour-aligned HDF5 recording or *_regions.csv, and TRIALS_PATH the *_trials.csv from
+    visiomode-analysis. Choose the event with --event and the window with --pre and --post. Writes
+    <stem>_event-<event>_perievent.h5 for HDF5 input, or a long-format <stem>_event-<event>_perievent.csv with the
+    trials columns for CSV input.
     """  # noqa: DOC501
     import pandas as pd
 
@@ -954,7 +959,7 @@ def _perievent_csv(
     return kept, out
 
 
-@process_cmd.command("metrics")
+@process_cmd.command("metrics", epilog=docs_epilog("how-to/metrics/"))
 @click.argument(
     "path",
     type=click.Path(exists=True, dir_okay=False),
@@ -964,7 +969,7 @@ def _perievent_csv(
     "--out_dir",
     type=click.Path(dir_okay=True),
     default="./",
-    help="Output directory for metrics tables.",
+    help="Output directory for the metrics tables.",
 )
 @click.option(
     "--baseline",
@@ -978,7 +983,7 @@ def _perievent_csv(
     "trials_path",
     type=click.Path(exists=True, dir_okay=False),
     default=None,
-    help="Trials CSV to join onto the per-trial table by trial_index, for peri-event files without trials columns.",
+    help="Trials CSV to join by trial_index, for peri-event files without trials columns.",
 )
 @_metrics_options
 @_reliability_options
@@ -1000,18 +1005,11 @@ def metrics_cmd(
     reliability: pm.ReliabilityOptions,
     bootstrap: pm.BootstrapOptions,
 ) -> None:
-    """Extract per-trial response metrics and per-session variability from peri-event traces.
-
-    PATH is the long-format *_perievent.csv written by `process peri-event`. Writes <stem>_metrics.csv with onset
-    time, peak time, amplitude, area under the curve, decay time, offset time and duration per trial per region,
-    and <stem>_metrics-session.csv with the mean, SD and CV of each across trials, plus the mean pairwise
-    trial-trace correlation, per region and trial group. Go/no-go sessions are grouped by sdt_type, go/no-go
-    stimulus and lever push, as well as all trials. For go/no-go sessions aligned to the cue, trial start or lever
-    push, the session table also has trial-to-trial reliability metrics over the cue-to-lever epoch.
-
-    Also writes <stem>_metrics-boot.csv with the same metrics taken from the trial-mean trace of each region and
-    trial group, with bootstrap percentile intervals from resampling the trials, and <stem>_traces-boot.csv with
-    the mean traces and their intervals. --bootstrap 0 skips both.
+    """Measure trial response metrics from peri-event traces.
+
+    PATH is a *_perievent.csv from `process peri-event`. Set the windows with --baseline and --response, and the
+    onset method with --onset. Writes <stem>_metrics.csv per trial, <stem>_metrics-session.csv per trial group, and
+    the bootstrapped mean-trace tables <stem>_metrics-boot.csv and <stem>_traces-boot.csv.
     """  # noqa: DOC501
     import pandas as pd
 
@@ -1058,7 +1056,7 @@ def metrics_cmd(
     _write_metrics(tables, out_dir, Path(path).stem.removesuffix("_perievent"))
 
 
-@process_cmd.command("connectivity")
+@process_cmd.command("connectivity", epilog=docs_epilog("how-to/connectivity/"))
 @click.argument(
     "path",
     type=click.Path(exists=True, dir_okay=False),
@@ -1074,8 +1072,7 @@ def metrics_cmd(
     "--response",
     type=(float, float),
     default=None,
-    help="Response window START END, seconds relative to the event, end inclusive. Defaults to all post-event samples."
-    " Peri-event input only.",
+    help="Response window START END, seconds relative to the event, end inclusive. Defaults to all post-event samples.",
 )
 @click.option(
     "-t",
@@ -1083,37 +1080,34 @@ def metrics_cmd(
     "trials_path",
     type=click.Path(exists=True, dir_okay=False),
     default=None,
-    help="Trials CSV to join by trial_index, for peri-event files without trials columns. Peri-event input only.",
+    help="Trials CSV to join by trial_index, for peri-event files without trials columns.",
 )
 @click.option(
     "--min-trials",
     type=click.IntRange(min=1),
     default=10,
     show_default=True,
-    help="Trial groups with fewer trials get empty metrics. The all-trials metrics are always taken. Peri-event"
-    " input only.",
+    help="Trial groups with fewer trials get empty metrics.",
 )
 @click.option(
     "--mask-response/--no-mask-response",
     default=True,
     show_default=True,
-    help="End cue-aligned epochs at each trial's response; trials without one end at the median response time."
-    " Peri-event input only.",
+    help="End cue-aligned epochs at each trial's response, or at the median response time for trials without one.",
 )
 @click.option(
     "--min-rt",
     type=click.FloatRange(min=0),
     default=0.2,
     show_default=True,
-    help="Drop trials with a response time below this, in seconds. Peri-event input only.",
+    help="Drop trials with a response time below this, in seconds.",
 )
 @click.option(
     "--response-pad",
     type=click.FloatRange(min=0),
     default=0.0,
     show_default=True,
-    help="Extend each epoch past the response by this, in seconds. Cue-aligned epochs still end within the response"
-    " window. Peri-event input only.",
+    help="Extend each epoch past the response by this, in seconds.",
 )
 @click.option(
     "--max-lag",
@@ -1134,7 +1128,7 @@ def metrics_cmd(
     "mutual_info",
     default=True,
     show_default=True,
-    help="Estimate the mutual information of each pair, the slowest part.",
+    help="Estimate the mutual information of each pair, which is the slowest metric.",
 )
 @click.option(
     "--te-history",
@@ -1148,8 +1142,7 @@ def metrics_cmd(
     type=click.IntRange(min=0),
     default=200,
     show_default=True,
-    help="Surrogates for the transfer entropy z-scores: trial shuffles on peri-event input, circular shifts on a"
-    " regions CSV. 0 leaves the z-scores out.",
+    help="Surrogates for the transfer entropy z-scores. 0 leaves the z-scores out.",
 )
 @click.option(
     "--with-te/--no-te",
@@ -1163,22 +1156,21 @@ def metrics_cmd(
     "rolling",
     default=False,
     show_default=True,
-    help="Also take r, r_residual, mi and mi_residual in windows sliding over the whole peri-event window, written"
-    " to <stem>_connectivity-rolling.csv. Peri-event input only.",
+    help="Also write <stem>_connectivity-rolling.csv with connectivity in windows sliding over the peri-event window.",
 )
 @click.option(
     "--rolling-window",
     type=click.FloatRange(min=0, min_open=True),
     default=0.5,
     show_default=True,
-    help="Length of the rolling windows, in seconds, rounded to whole samples.",
+    help="Length of the rolling windows, in seconds.",
 )
 @click.option(
     "--rolling-step",
     type=click.FloatRange(min=0, min_open=True),
     default=0.1,
     show_default=True,
-    help="Time between the starts of consecutive rolling windows, in seconds, rounded to whole samples.",
+    help="Time between the starts of consecutive rolling windows, in seconds.",
 )
 @click.option(
     "--seed",
@@ -1207,22 +1199,12 @@ def connectivity_cmd(
     rolling_step: float,
     seed: int,
 ) -> None:
-    """Measure pairwise connectivity between regions, over the cue-to-response epoch or over whole traces.
-
-    PATH is the long-format *_perievent.csv written by `process peri-event`, or the *_regions.csv written by
-    `process regions`. Writes <stem>_connectivity.csv with one row per region pair and trial group: the Pearson
-    correlation of the pooled epoch samples, the same after removing the group's mean response, the mean of the
-    per-trial correlations, the mutual information of the pooled samples and of the residuals in bits, the
-    partial correlation given every other region, the lag and value of the peak cross-correlation, and with --with-te
-    the transfer entropy of the residuals in each direction with its z-score against surrogates. Epochs run from
-    the cue to each trial's response, as for the reliability metrics of `process metrics`, extended past the
-    response by --response-pad; without the cue_onset and response_time columns the whole response window is used.
-    Go/no-go sessions are grouped by sdt_type, go/no-go stimulus and lever push, as well as all trials. With
-    --with-rolling it also writes <stem>_connectivity-rolling.csv, with the correlations and mutual information in
-    windows sliding over the whole peri-event window, one row per region pair, trial group and window.
-
-    A regions CSV gives the metrics over the whole recording instead, as the all-trials rows only, without the
-    residual and per-trial columns. The trial options and --with-rolling do not apply.
+    """Measure pairwise connectivity between regions.
+
+    PATH is a *_perievent.csv from `process peri-event`, measured over each trial's cue-to-response epoch, or a
+    *_regions.csv from `process regions`, measured over the whole recording. Add --with-te for transfer entropy and
+    --with-rolling for connectivity in sliding windows. Writes <stem>_connectivity.csv with one row per region pair
+    and trial group.
     """  # noqa: DOC501
     import pandas as pd
 
@@ -1305,7 +1287,7 @@ def connectivity_cmd(
     click.echo(f"Saved rolling connectivity metrics at {output}")
 
 
-@process_cmd.command("decode")
+@process_cmd.command("decode", epilog=docs_epilog("how-to/decoding/"))
 @click.argument(
     "path",
     type=click.Path(exists=True, dir_okay=False),
@@ -1323,7 +1305,7 @@ def connectivity_cmd(
     type=click.Choice(list(pdc.LABELS), case_sensitive=False),
     default="stim",
     show_default=True,
-    help="What to decode. stim is the go against the no-go stimulus, response the lever push against no push.",
+    help="Decode the go/no-go stimulus or the lever push.",
 )
 @click.option(
     "--response",
@@ -1344,7 +1326,7 @@ def connectivity_cmd(
     type=click.IntRange(min=1),
     default=10,
     show_default=True,
-    help="Trials each class needs in a trial group. Groups with fewer get empty scores.",
+    help="Trials each class needs for a trial group to be decoded.",
 )
 @click.option(
     "--mask-response/--no-mask-response",
@@ -1370,57 +1352,57 @@ def connectivity_cmd(
     type=click.FloatRange(min=0),
     default=0.0,
     show_default=True,
-    help="Extend the epoch past the response by this, in seconds, within the response window.",
+    help="Extend the epoch past the response by this, in seconds.",
 )
 @click.option(
     "--folds",
     type=click.IntRange(min=2),
     default=5,
     show_default=True,
-    help="Folds of the stratified cross-validation.",
+    help="Cross-validation folds.",
 )
 @click.option(
     "--repeats",
     type=click.IntRange(min=1),
     default=10,
     show_default=True,
-    help="Repeats of the cross-validation, each with a fresh split.",
+    help="Cross-validation repeats, each with a fresh split.",
 )
 @click.option(
     "--shuffles",
     type=click.IntRange(min=0),
     default=200,
     show_default=True,
-    help="Label shuffles for the chance level and p-values. 0 leaves the columns out.",
+    help="Label shuffles for the chance level and p-values. 0 leaves them out.",
 )
 @click.option(
     "--with-rolling/--no-rolling",
     "rolling",
     default=False,
     show_default=True,
-    help="Also decode in windows sliding over the whole peri-event window, written to"
-    " <stem>_label-<label>_decoding-rolling.csv.",
+    help="Also write <stem>_label-<label>_decoding-rolling.csv with scores in windows sliding over the peri-event"
+    " window.",
 )
 @click.option(
     "--rolling-window",
     type=click.FloatRange(min=0, min_open=True),
     default=0.5,
     show_default=True,
-    help="Length of the rolling windows, in seconds, rounded to whole samples.",
+    help="Length of the rolling windows, in seconds.",
 )
 @click.option(
     "--rolling-step",
     type=click.FloatRange(min=0, min_open=True),
     default=0.1,
     show_default=True,
-    help="Time between the starts of consecutive rolling windows, in seconds, rounded to whole samples.",
+    help="Time between the starts of consecutive rolling windows, in seconds.",
 )
 @click.option(
     "--baseline",
     type=(float, float),
     default=None,
-    help="Window START END, seconds relative to the event, end exclusive, whose mean gives the chance level of the"
-    " rolling table. Defaults to every sample before the event.",
+    help="Window START END, seconds relative to the event, end exclusive, whose mean gives the rolling chance level."
+    " Defaults to every sample before the event.",
 )
 @click.option(
     "--seed",
@@ -1449,15 +1431,11 @@ def decode_cmd(
     baseline: tuple[float, float] | None,
     seed: int,
 ) -> None:
-    """Decode the stimulus or the lever push of each trial from region activity.
-
-    PATH is the long-format *_perievent.csv written by `process peri-event` for a go/no-go session. A logistic
-    regression and a linear discriminant decoder are fitted to each region's mean activity between the cue and the
-    median response time, and to all regions together, under repeated stratified cross-validation, over all trials
-    and within the groups that hold the other variable constant. Writes <stem>_label-<label>_decoding.csv with the
-    scores and their chance level per decoder, region and trial group, and <stem>_label-<label>_decoding-weights.csv
-    with the population weights. With --with-rolling the scores are also taken in windows sliding over the
-    peri-event window and written to <stem>_label-<label>_decoding-rolling.csv.
+    """Decode the stimulus or lever push from region activity.
+
+    PATH is a go/no-go *_perievent.csv from `process peri-event`. Pick what to decode with --label, and add
+    --with-rolling to decode in sliding windows. Writes <stem>_label-<label>_decoding.csv with the scores per decoder,
+    region and trial group, and <stem>_label-<label>_decoding-weights.csv with the population weights.
     """  # noqa: DOC501
     import pandas as pd
 
diff --git a/src/mesoscopy/register/__init__.py b/src/mesoscopy/register/__init__.py
index 29b277a..3d67ee5 100644
--- a/src/mesoscopy/register/__init__.py
+++ b/src/mesoscopy/register/__init__.py
@@ -30,6 +30,7 @@
 import numpy as np
 
 import mesoscopy.resources as res
+from mesoscopy import docs_epilog
 from mesoscopy import io
 from mesoscopy import timer as timer
 
@@ -39,10 +40,10 @@
 
 @click.group("register")
 def register_cmd() -> None:
-    """Register recordings to a template."""
+    """Register recordings to an anatomical template."""
 
 
-@register_cmd.command("label")
+@register_cmd.command("label", epilog=docs_epilog("typical-workflow/"))
 @click.argument(
     "path",
     type=click.Path(exists=True),
@@ -52,33 +53,25 @@ def register_cmd() -> None:
     "--out_dir",
     type=click.Path(dir_okay=True),
     default="./",
-    help="Output directory for landmarks file.",
+    help="Output directory for the landmarks file.",
 )
 @click.option(
     "-t",
     "--template-points",
     type=click.Path(dir_okay=False),
-    help="Path to template landmark points in CSV or Fiji XML points format",
+    help="Template landmarks in CSV or Fiji XML points format, instead of the Allen CCF landmarks.",
 )
 @click.option(
     "--session-id",
     type=str,
-    help="Session ID for the recording.",
+    help="Session ID naming the landmarks file. Defaults to the name of PATH.",
 )
 def label_cmd(path, out_dir, template_points, session_id) -> dict:
-    """Mark landmarks on a recording for registration to a template using the landmarks GUI.
+    """Mark anatomical landmarks on a recording.
 
-    Args:
-        path (str): Path to preprocessed HDF5 file or NWB file.
-        out_dir (str): Output directory for registration landmarks file.
-        template_points (str): Path to template landmark points in CSV or Fiji XML points format.
-        session_id (str): Session ID for the recording.
-
-    Returns:
-        dict: Dictionary with the landmarks and their x-y coordinates.
-              Dictionary keys are landmark names, while x-y coordinates are stored as an (x, y)
-              tuple, i.e. (column, row).
-    """
+    PATH is a preprocessed HDF5 or NWB recording. Drag each landmark onto its anatomical location in the napari
+    window that opens, then press Save and Close. Writes <session>_landmarks.csv for `register landmarks`.
+    """  # noqa: DOC201
     from dask import array as da
 
     import mesoscopy.preprocess.compute as preproc_compute
@@ -130,7 +123,7 @@ def label_cmd(path, out_dir, template_points, session_id) -> dict:
     return recording_landmarks
 
 
-@register_cmd.command("landmarks")
+@register_cmd.command("landmarks", epilog=docs_epilog("typical-workflow/"))
 @click.argument(
     "path",
     type=click.Path(exists=True),
@@ -140,19 +133,19 @@ def label_cmd(path, out_dir, template_points, session_id) -> dict:
     "--out_dir",
     type=click.Path(dir_okay=True),
     default="./",
-    help="Output directory for registered recording.",
+    help="Output directory for the registered recording.",
 )
 @click.option(
     "-r",
     "--recording-points",
     type=click.Path(dir_okay=False),
-    help="Path to recording landmark points in Fiji XML points format",
+    help="Recording landmarks in CSV or Fiji XML points format.",
 )
 @click.option(
     "-t",
     "--template-points",
     type=click.Path(dir_okay=False),
-    help="Path to template landmark points in Fiji XML points format",
+    help="Template landmarks in CSV or Fiji XML points format, instead of the Allen CCF landmarks.",
 )
 @click.option(
     "-s",
@@ -160,22 +153,21 @@ def label_cmd(path, out_dir, template_points, session_id) -> dict:
     type=float,
     default=None,
     help=(
-        "Scale of the Allen CCF template the frames are registered to, relative to its native 140x142 pixels. Defaults"
-        " to the scale at which template pixels match the recording's pixel size, so the recording keeps its own"
-        " resolution. Ignored with -t."
+        "Scale of the Allen CCF template relative to its native 140x142 pixels. Defaults to the scale that keeps the"
+        " recording's resolution. Ignored with -t."
     ),
 )
 @click.option(
     "--output-width",
     type=int,
     default=None,
-    help="Deprecated, use --scale. Width of the registered frames.",
+    help="Width of the registered frames. Deprecated in favour of --scale.",
 )
 @click.option(
     "--output-height",
     type=int,
     default=None,
-    help="Deprecated, use --scale. Height of the registered frames.",
+    help="Height of the registered frames. Deprecated in favour of --scale.",
 )
 def landmarks_cmd(
     path: str,
@@ -186,24 +178,12 @@ def landmarks_cmd(
     output_width: int | None = None,
     output_height: int | None = None,
 ) -> str:
-    """Register a recording to a template based on defined landmarks.
+    """Register a recording to the Allen CCF template.
 
-    Args:
-        path (str): Path to preprocessed recording HDF5 or NWB file.
-        out_dir (str): Output directory for registered recording.
-        recording_points (str, optional): Path to recording landmark points in CSV or Fiji XML points format.
-        template_points (str, optional): Path to template landmark points in CSV or Fiji XML points format.
-        scale (float, optional): Scale of the Allen CCF template, relative to its native size. Defaults to the
-            scale matching the recording's pixel size.
-        output_width (int, optional): Deprecated, use ``scale``. Width of the registered frames.
-        output_height (int, optional): Deprecated, use ``scale``. Height of the registered frames.
-
-    Returns:
-        str: Path to the registered recording file.
-
-    Raises:
-        ValueError: If the path to recording landmarks cannot be inferred, or the options conflict.
-    """
+    PATH is a preprocessed HDF5 or NWB recording with landmarks marked by `register label`. The landmarks file is
+    found next to PATH or in --out_dir, or given with -r. Writes <session>_registered.h5, and links it into PATH when
+    PATH is an NWB file.
+    """  # noqa: DOC201, DOC501
     import mesoscopy.register.transform as trf
 
     click.echo(f"Registering recording {path} to template.")
diff --git a/src/mesoscopy/report/__init__.py b/src/mesoscopy/report/__init__.py
index cb510a3..904b591 100644
--- a/src/mesoscopy/report/__init__.py
+++ b/src/mesoscopy/report/__init__.py
@@ -26,6 +26,7 @@
 from jinja2 import PackageLoader
 from jinja2 import select_autoescape
 
+from mesoscopy import docs_epilog
 from mesoscopy import io
 
 PREPROCESSING_REPORT_TEMPLATE = "preprocessing.html"
@@ -35,7 +36,7 @@
 env = Environment(loader=PackageLoader("mesoscopy.report", "templates"), autoescape=select_autoescape())
 
 
-@click.command(name="report")
+@click.command(name="report", epilog=docs_epilog("how-to/reports/"))
 @click.argument("path")
 @click.option(
     "-o",
@@ -49,23 +50,14 @@
     "--trials",
     type=click.Path(exists=True, dir_okay=False),
     default=None,
-    help="Trials CSV giving sdt_type per trial, for peri-event files written without it.",
+    help="Trials CSV giving sdt_type per trial, for peri-event files without it.",
 )
 def report_cmd(path: str, out_dir: str, trials: str | None) -> str:
-    """Generate an HTML report for a mesoscopy processing step.
+    """Generate an HTML report for a pipeline stage.
 
-    PATH is a *_preprocessed.h5, *_registered.h5 or *_perievent.csv file. Peri-event reports pick up the
-    *_metrics.csv and *_metrics-session.csv written by `process metrics` and the *_connectivity.csv written by
-    `process connectivity` next to the input when present.
-
-    Args:
-        path (str): Path to the input file.
-        out_dir (str): Directory where the report will be saved. Defaults to the current directory
-        trials (str, optional): Trials CSV for peri-event files without an sdt_type column.
-
-    Returns:
-        str: Path to the generated report.
-    """  # noqa: DOC501
+    PATH is a *_preprocessed.h5, *_registered.h5 or *_perievent.csv file. A peri-event report also shows the
+    metrics and connectivity tables if found next to PATH. Writes <name>_report.html.
+    """  # noqa: DOC201, DOC501
     if path.endswith("_preprocessed.h5"):
         return generate_preprocessing_report(path, out_dir=out_dir)
     elif path.endswith("_registered.h5"):
diff --git a/tests/test_cli.py b/tests/test_cli.py
index c707aea..5d4ca23 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -23,6 +23,7 @@
 
 import subprocess
 import sys
+from pathlib import Path
 
 import click
 import h5py
@@ -91,6 +92,46 @@ def test_unknown_subcommand_is_none():
     assert mesoscopy.cli.get_command(click.Context(mesoscopy.cli), "nope") is None
 
 
+def _walk(path: str, cmd: click.Command) -> list[tuple[str, click.Command]]:
+    found = [(path, cmd)]
+    if isinstance(cmd, click.Group):
+        ctx = click.Context(cmd)
+        for name in cmd.list_commands(ctx):
+            sub = cmd.get_command(ctx, name)
+            assert sub is not None
+            found += _walk(f"{path} {name}", sub)
+    return found
+
+
+@pytest.mark.parametrize("name", list(mesoscopy.LAZY_SUBCOMMANDS))
+def test_subcommand_summary_matches_help(name):
+    cmd = mesoscopy.cli.get_command(click.Context(mesoscopy.cli), name)
+
+    assert cmd.help.splitlines()[0] == mesoscopy.LAZY_SUBCOMMANDS[name][1]
+
+
+def test_summaries_fit_group_listings():
+    # Click cuts a summary off with "..." when it overruns the 80-column command listing.
+    for path, cmd in _walk("mesoscopy", mesoscopy.cli):
+        if not isinstance(cmd, click.Group):
+            continue
+        ctx = click.Context(cmd)
+        names = cmd.list_commands(ctx)
+        limit = 78 - 6 - max(len(name) for name in names)
+        for name in names:
+            assert not cmd.get_command(ctx, name).get_short_help_str(limit).endswith("..."), f"{path} {name}"
+
+
+def test_docs_epilogs_point_at_docs_pages():
+    docs = Path(__file__).parents[1] / "docs"
+    epilogs = {path: cmd.epilog for path, cmd in _walk("mesoscopy", mesoscopy.cli) if cmd.epilog}
+
+    assert "mesoscopy" in epilogs
+    for path, epilog in epilogs.items():
+        page = epilog.split(mesoscopy.DOCS_URL)[1].strip("/")
+        assert (docs / f"{page or 'index'}.md").exists(), path
+
+
 def test_start_time_prints_first_timestamp(tmp_path):
     path = str(tmp_path / "rec.h5")
     with h5py.File(path, "w") as f:

From a599d71b48b12f4db2e80e5a1a96c5167d42a5c5 Mon Sep 17 00:00:00 2001
From: Constantinos Eleftheriou <constantinos.eleftheriou@ed.ac.uk>
Date: Mon, 12 Oct 2026 12:31:26 +0100
Subject: [PATCH 4/5] update changelog

---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6ae08be..4a549fc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,7 +6,7 @@ Versions follow [Semantic Versioning](https://semver.org) (`<major>.<minor>.<pat
 
 ### Changed
 
-- Stylistic changes to CLI help strings.
+- Stylistic changes to CLI help strings ([#217](https://github.com/DuguidLab/mesoscopy/pull/217)).
 
 ## [0.17.0] - 2026-10-12
 

From bef64cf161c72b171d2182efc173124263628ac9 Mon Sep 17 00:00:00 2001
From: Constantinos Eleftheriou <constantinos.eleftheriou@ed.ac.uk>
Date: Mon, 12 Oct 2026 12:32:28 +0100
Subject: [PATCH 5/5] update changelog

---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4a549fc..6ae08be 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,7 +6,7 @@ Versions follow [Semantic Versioning](https://semver.org) (`<major>.<minor>.<pat
 
 ### Changed
 
-- Stylistic changes to CLI help strings ([#217](https://github.com/DuguidLab/mesoscopy/pull/217)).
+- Stylistic changes to CLI help strings.
 
 ## [0.17.0] - 2026-10-12