ENH: Improve docs navigation and add demo data CLI

.gitignore

@@ -48,3 +48,6 @@ tests/data/
 tests/results/
 tests/baseline_staging/
 test_output.txt
+
+# docs
+docs_buildhtml

AGENTS.md

@@ -42,43 +42,51 @@ Non-Python tools used by contributor workflows:
 
 ## Common Commands
 
-Use `py` on this Windows system, not `python`.
+Prefer the repository-local virtual environment at `.\venv`. Activate it before
+issuing Python commands so `python`, console scripts, and `uv pip` all use that
+environment. If activation is not possible, invoke
+`.\venv\Scripts\python.exe -m ...` directly. Use `uv run ...` only when the
+local `venv` is unavailable and you need uv to create or sync an environment.
+
+```powershell
+# Create the repo-local environment if it does not already exist
+uv venv venv
+.\venv\Scripts\Activate.ps1
 
-```bash
 # Install in editable mode
 uv pip install -e .
 
 # Lint and format
-ruff check . --fix && ruff format .
+python -m ruff check . --fix && python -m ruff format .
 
 # Type checking
-mypy src/ tests/
+python -m mypy src/ tests/
 
 # All pre-commit hooks
-pre-commit run --all-files
+python -m pre_commit run --all-files
 
 # Fast tests
-py -m pytest tests/ -v
+python -m pytest tests/ -v
 
 # Single test file or test by name
-py -m pytest tests/test_contour_tools.py -v
-py -m pytest tests/test_contour_tools.py::test_extract_surface -v
+python -m pytest tests/test_contour_tools.py -v
+python -m pytest tests/test_contour_tools.py::test_extract_surface -v
 
 # Opt-in test buckets
-py -m pytest tests/ -v --run-slow
-py -m pytest tests/ -v --run-gpu
-py -m pytest tests/ -v --run-simpleware
-py -m pytest tests/ -v --run-experiments
-py -m pytest tests/ -v --run-tutorials
+python -m pytest tests/ -v --run-slow
+python -m pytest tests/ -v --run-gpu
+python -m pytest tests/ -v --run-simpleware
+python -m pytest tests/ -v --run-experiments
+python -m pytest tests/ -v --run-tutorials
 
 # Typical local GPU profile
-py -m pytest tests/ -v --run-gpu --run-slow
+python -m pytest tests/ -v --run-gpu --run-slow
 
 # Coverage
-py -m pytest tests/ --cov=src/physiomotion4d --cov-report=html
+python -m pytest tests/ --cov=src/physiomotion4d --cov-report=html
 
 # Create missing baselines
-py -m pytest tests/ --create-baselines
+python -m pytest tests/ --create-baselines
 ```
 
 Version bumping: `bumpver update --patch`, `--minor`, or `--major`.
@@ -95,7 +103,8 @@ Version bumping: `bumpver update --patch`, `--minor`, or `--major`.
   below 88 characters.
 - Full type hints are required under strict mypy. Use `Optional[X]`, not
   `X | None`.
-- Run `py -m pytest tests/ -v` to verify changes. Slow, GPU, Simpleware,
+- Run `python -m pytest tests/ -v` from the active `.\venv` to verify changes.
+  Slow, GPU, Simpleware,
   experiment, and tutorial tests are auto-skipped unless their opt-in flag is
   passed.
 - The `requires_data` marker no longer exists. Tests that need external data
@@ -172,8 +181,8 @@ Version bumping: `bumpver update --patch`, `--minor`, or `--major`.
 - Update docstrings for every changed public method. Keep claims factual.
 - Document with docstrings and inline comments.
 - Do not create new `.md` files unless explicitly requested.
-- Regenerate `docs/API_MAP.md` after any public API change:
-  `py utils/generate_api_map.py`.
+- Regenerate `docs/API_MAP.md` after any public API change from the active
+  `.\venv`: `python utils/generate_api_map.py`.
 
 ## Architecture Role
 

docs/API_MAP.md

@@ -5,9 +5,9 @@ _Re-run `py utils/generate_api_map.py` whenever public APIs change._
 
 ## docs/conf.py
 
-- **class Mock** (line 20)
-- `def autodoc_skip_member(app, what, name, obj, skip, options)` (line 222): Custom function to skip certain members during autodoc processing.
-- `def setup(app)` (line 230): Custom setup function for Sphinx.
+- **class Mock** (line 22)
+- `def autodoc_skip_member(app, what, name, obj, skip, options)` (line 227): Custom function to skip certain members during autodoc processing.
+- `def setup(app)` (line 239): Custom setup function for Sphinx.
 
 ## experiments/Colormap-VTK_To_USD/colormap_vtk_to_usd.py
 
@@ -428,6 +428,10 @@ _Re-run `py utils/generate_api_map.py` whenever public APIs change._
 
 - `def main()` (line 19): Command-line interface for create statistical model workflow.
 
+## src/physiomotion4d/cli/download_data.py
+
+- `def main(argv=None)` (line 16): Download a supported PhysioMotion4D example dataset.
+
 ## src/physiomotion4d/cli/fit_statistical_model_to_patient.py
 
 - `def main()` (line 17): Command-line interface for heart model to patient registration.
@@ -870,7 +874,7 @@ _Re-run `py utils/generate_api_map.py` whenever public APIs change._
 
 ## tests/test_cli_smoke.py
 
-- `def test_cli_help(module_name, monkeypatch, capsys)` (line 24): Each CLI module exits successfully for --help.
+- `def test_cli_help(module_name, monkeypatch, capsys)` (line 25): Each CLI module exits successfully for --help.
 
 ## tests/test_contour_tools.py
 
@@ -916,6 +920,11 @@ _Re-run `py utils/generate_api_map.py` whenever public APIs change._
   - `def test_mask_ids_missing_boundary_labels_falls_back(self, tmp_path)` (line 562): Mesh without boundary_labels array falls back to a 'default' prim.
   - `def test_mask_ids_groups_by_segmenter_type(self, tmp_path)` (line 577): When a segmenter is supplied, labels are grouped under their
 
+## tests/test_download_data_cli.py
+
+- `def test_download_data_cli_uses_default_dataset_and_directory(monkeypatch, capsys)` (line 14): Default CLI arguments route Slicer-Heart-CT to data/Slicer-Heart-CT.
+- `def test_download_data_cli_uses_requested_directory(monkeypatch, tmp_path)` (line 34): The --directory option controls where Slicer-Heart-CT is stored.
+
 ## tests/test_download_heart_data.py
 
 - **class TestDataDownloadTools** (line 16): Synthetic tests for dataset verification helpers.

docs/_static/custom.css

@@ -268,13 +268,21 @@ dt.sig {
     line-height: 1.08;
 }
 
-.pm4d-hero p:not(.pm4d-kicker) {
+.pm4d-hero p:not(.pm4d-kicker):not(.pm4d-hero__version) {
     max-width: 760px;
     margin: 0;
     color: #d8dde6;
     font-size: 1.1rem;
 }
 
+.pm4d-hero p.pm4d-hero__version {
+    max-width: 760px;
+    margin: 1.9rem 0 0;
+    color: #ffffff;
+    font-size: 0.78rem;
+    font-weight: 700;
+}
+
 .pm4d-card-grid {
     display: grid;
     grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));

docs/api/cli/download_data.rst

@@ -0,0 +1,10 @@
+===================
+download_data (CLI)
+===================
+
+.. automodule:: physiomotion4d.cli.download_data
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+See :doc:`../../cli_scripts/download_data` for usage examples.

docs/api/cli/index.rst

@@ -22,6 +22,7 @@ Module Index.
    convert_image_to_vtk
    convert_vtk_to_usd
    create_statistical_model
+   download_data
    fit_statistical_model_to_patient
    reconstruct_highres_4d_ct
    visualize_pca_modes

docs/architecture.rst

@@ -9,8 +9,8 @@ configuration.
 
 .. warning::
 
-   PhysioMotion4D 2026.05.07 beta is not validated for clinical use. It is a
-   research and visualization toolkit, not a medical device.
+   PhysioMotion4D {{ pm4d_project_version }} beta is not validated for clinical
+   use. It is a research and visualization toolkit, not a medical device.
 
 Data Flow
 =========

docs/cli_scripts/best_practices.rst

@@ -242,7 +242,7 @@ Ensuring Reproducible Results
 
    # processing_metadata.yaml
    patient_id: patient_001
-   physiomotion4d_version: 2026.05.07
+   physiomotion4d_version: {{ pm4d_project_version }}
    script: heart-gated-ct
    date: 2026-01-08