ENH: Refined installation procedure and documentation

.agents/agents/architecture.md

@@ -17,16 +17,16 @@ tutorials may require a GPU.
 
 ```text
 src/monai_physio/
-  monai_physio_base.py      — base class with shared logger
-  segment_anatomy_base.py     — abstract segmentation interface
-  segment_chest_*.py          — TotalSegmentator, VISTA-3D, NIM, Ensemble
-  register_images_*.py        — ICON, ANTs, Greedy, time-series wrappers
-  register_models_*.py        — ICP, PCA, distance-map registerers
-  contour_tools.py            — surface extraction from ITK masks
-  convert_vtk_to_usd.py       — high-level VTK→USD (in-memory, PyVista)
-  vtk_to_usd/                 — file-based VTK→USD subpackage
-  usd_tools.py / usd_anatomy_tools.py — USD stage utilities
-  workflow_*.py               — top-level orchestration
+  monai_physio_base.py      - base class with shared logger
+  segment_anatomy_base.py     - abstract segmentation interface
+  segment_chest_*.py          - TotalSegmentator, VISTA-3D, NIM, Ensemble
+  register_images_*.py        - ICON, ANTs, Greedy, time-series wrappers
+  register_models_*.py        - ICP, PCA, distance-map registerers
+  contour_tools.py            - surface extraction from ITK masks
+  convert_vtk_to_usd.py       - high-level VTK→USD (in-memory, PyVista)
+  vtk_to_usd/                 - file-based VTK→USD subpackage
+  usd_tools.py / usd_anatomy_tools.py - USD stage utilities
+  workflow_*.py               - top-level orchestration
 ```
 
 Use `graphify query "<question>"` to locate classes and signatures without manual
@@ -47,13 +47,13 @@ searching.
   subpackage is internal; experiments, CLIs, tests, and tutorials must not
   import from it directly.
 
-## Output format — always produce all six sections
+## Output format - always produce all six sections
 
-1. **Current state** — what exists today, 3–5 bullet points.
-2. **Proposed change** — numbered steps with enough detail to implement.
-3. **Affected files** — every file that will change.
-4. **Trade-offs** — what improves, what gets harder, what breaks.
-5. **Open questions** — decisions that need user input before coding starts.
-6. **Recommended next action** — one sentence.
+1. **Current state** - what exists today, 3–5 bullet points.
+2. **Proposed change** - numbered steps with enough detail to implement.
+3. **Affected files** - every file that will change.
+4. **Trade-offs** - what improves, what gets harder, what breaks.
+5. **Open questions** - decisions that need user input before coding starts.
+6. **Recommended next action** - one sentence.
 
 Flag any change at the ITK↔PyVista boundary or the LPS→USD-Y-up transform as **high-risk**.

.agents/agents/docs.md

@@ -11,13 +11,13 @@ and the knowledge graph accurate and concise.
 
 - Docstrings for public classes, methods, and functions.
 - Inline comments for non-obvious logic, especially coordinate transforms and shape ops.
-- `graphify-out/` — refreshed, never hand-edited: `graphify update .`
-- `README.md` — update only for pipeline-level or dependency changes.
+- `graphify-out/` - refreshed, never hand-edited: `graphify update .`
+- `README.md` - update only for pipeline-level or dependency changes.
 
 ## Rules
 
 - Read the changed code before writing any docs.
-- Keep docstrings factual — describe what the code does, not what you wish it did.
+- Keep docstrings factual - describe what the code does, not what you wish it did.
 - Do not restate ITK image shape, axis order, or world space in docstrings.
   Those are fixed project-wide conventions (see `AGENTS.md`); repeating them
   adds noise. Document only genuine deviations, such as a raw NumPy array

.agents/agents/implementation.md

@@ -23,7 +23,7 @@ Key modules: `monai_physio_base.py`, `segment_chest_*.py`, `register_images_*.py
 `workflow_*.py`. Use `graphify query "<question>"` to locate classes before
 searching manually.
 
-## Process — follow this order every time
+## Process - follow this order every time
 
 1. Read the relevant source file(s) in full.
 2. Summarize current behavior in 2–4 sentences.
@@ -51,11 +51,13 @@ searching manually.
   (`torch.multiprocessing` requires it).
 - Double quotes for strings and docstrings. Never single quotes. 88-char line limit.
 - Full type hints; `Optional[X]` not `X | None` (mypy UP007 is suppressed).
-- `pathlib.Path` for all file paths. `subprocess.run(check=True, text=True)` — no `os.system`.
-- After every Python edit run `python -m ruff check . --fix && python -m ruff format .`
-  from the active `.\venv`.
+- `pathlib.Path` for all file paths. `subprocess.run(check=True, text=True)` - no `os.system`.
+- After every Python edit run `python -m ruff check <file> --fix && python -m ruff format <file>`
+  on the file(s) you touched, from the active `.\venv`. Running ruff against
+  the whole repo (`.`) can rewrite unrelated files - reserve that for an
+  explicit, separate repo-wide pass.
 
-## Data conventions — fixed, do not restate
+## Data conventions - fixed, do not restate
 
 - ITK images: axes X, Y, Z [, T] in LPS world space (ITK's native frame).
 - 4D time series: shape `(X, Y, Z, T)`. Never silently squeeze or permute.
@@ -77,3 +79,7 @@ searching manually.
 - Do not add error handling for impossible internal states.
 - Do not create new files when editing an existing one suffices.
 - Do not add features beyond what was requested.
+- When fixing a bug, fix it. Do not add a comment recording what was wrong,
+  what changed, or how it was diagnosed - that belongs in the commit message,
+  not the code. Only exceptional motivations (a non-obvious constraint a
+  future editor would otherwise reintroduce) earn a comment.

.agents/agents/testing.md

@@ -9,18 +9,18 @@ exercise the library's scientific pipelines using real downloaded data
 wherever practical.
 
 **A GPU is assumed.** Supporting CPU-only machines is not a requirement, so a
-test may require a GPU. Mark it `@pytest.mark.requires_gpu` and move on — do
+test may require a GPU. Mark it `@pytest.mark.requires_gpu` and move on - do
 not shrink a case, weaken an assertion, or add a CPU fallback just to keep a
 test off the GPU bucket.
 
 ## Test architecture
 
-- `tests/conftest.py` — session-scoped fixtures chaining: download → convert → segment → register
-- `tests/baselines/` — stored via Git LFS; fetch with `git lfs pull`
-- `src/monai_physio/test_tools.py` — baseline comparison utilities (`TestTools`)
+- `tests/conftest.py` - session-scoped fixtures chaining: download → convert → segment → register
+- `tests/baselines/` - stored via Git LFS; fetch with `git lfs pull`
+- `src/monai_physio/test_tools.py` - baseline comparison utilities (`TestTools`)
 - Markers (all opt-in via `--run-<bucket>`): `slow`, `requires_gpu`,
   `requires_simpleware`, `tutorial`. The `requires_data` marker
-  no longer exists — tests that need downloadable data pull it through the
+  no longer exists - tests that need downloadable data pull it through the
   session fixtures and run by default.
 
 ## Run commands
@@ -39,7 +39,7 @@ python -m pytest tests/ -v --run-gpu --run-slow
 python -m pytest tests/ --create-baselines                        # create missing baselines
 ```
 
-## Writing tests — rules
+## Writing tests - rules
 
 1. Read the implementation file first; understand the public interface.
 2. Propose a test plan: what behaviors to cover, what inputs each needs.
@@ -55,7 +55,7 @@ python -m pytest tests/ --create-baselines                        # create missi
      that does not fit the test's purpose.
    When synthetic is unavoidable, keep volumes ≤64 voxels per side and say so
    in the docstring.
-5. Do not restate ITK shape, axis order, or world frame in test docstrings —
+5. Do not restate ITK shape, axis order, or world frame in test docstrings -
    those are fixed conventions. State only what is specific to the test, such
    as the size of a synthetic volume.
 6. When a test produces an image or surface, compare against a baseline using
@@ -68,7 +68,7 @@ python -m pytest tests/ --create-baselines                        # create missi
    `@pytest.mark.requires_simpleware`. Mark tutorial tests with
    `@pytest.mark.tutorial`. Tests that just
    need downloadable data need no marker.
-10. Do not mock segmentation or registration models — test real outputs.
+10. Do not mock segmentation or registration models - test real outputs.
 11. No emojis in test files (Windows cp1252 encoding has bitten this project).
 
 ## Naming

.agents/skills/check-conventions/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: Audit changed files (or a given path) against MONAI Physio's hard project rules — base-class inheritance, logging, coordinate conventions, USD entry point, Windows multiprocessing guard, quoting, type-hint style, line length, and emoji ban. Reports violations without auto-fixing.
+description: Audit changed files (or a given path) against MONAI Physio's hard project rules - base-class inheritance, logging, coordinate conventions, USD entry point, Windows multiprocessing guard, quoting, type-hint style, line length, and emoji ban. Reports violations without auto-fixing.
 ---
 
 Audit MONAI Physio source for hard-rule violations.
@@ -36,7 +36,7 @@ context such as class inheritance), then flag every occurrence of:
       from a file that is **not** `src/monai_physio/convert_vtk_to_usd.py`
       and is **not** itself inside `src/monai_physio/vtk_to_usd/`.
       Experiments, CLIs, tests, and tutorials must use `ConvertVTKToUSD`.
-- [ ] A docstring or comment claiming PyVista surfaces are in **RAS** — they
+- [ ] A docstring or comment claiming PyVista surfaces are in **RAS** - they
       are in **LPS** internally; convert to USD Y-up only at export.
 
 ### Windows multiprocessing
@@ -58,9 +58,13 @@ context such as class inheritance), then flag every occurrence of:
 ### Public API hygiene
 - [ ] A public method (no leading underscore) without a NumPy-style docstring.
 - [ ] A docstring or comment that restates the fixed ITK shape, axis order, or
-      LPS world space — flag it even when it also documents what the parameter
+      LPS world space - flag it even when it also documents what the parameter
       or return value means. Only genuine deviations from the conventions in
       `CLAUDE.md` may be documented.
+- [ ] A comment that narrates a bug fix's history instead of the code itself -
+      what was wrong, what changed, or how it was diagnosed. That belongs in
+      the commit message. Flag it unless the motivation is truly exceptional
+      (a non-obvious constraint a future editor would otherwise reintroduce).
 
 ### Migration guide
 - [ ] A deprecation shim, removed-symbol re-export, or removed-symbol stub
@@ -85,4 +89,4 @@ End with a one-line summary: total findings per rule category.
 Do **not** auto-fix. The point is to surface violations the user can decide
 how to address. If `$ARGUMENTS` includes `--fix`, ask before mutating anything
 and limit fixes to the trivially mechanical rules (line length is not one of
-them — `ruff format` covers that).
+them - `ruff format` covers that).

.agents/skills/commit/SKILL.md

@@ -20,7 +20,7 @@ Instructions:
      that should not be committed, display an error, stop processing, and abort
    - Do NOT add any untracked files to the commit.
 
-2. Scan the diff for breaking changes to the public API — renamed or removed
+2. Scan the diff for breaking changes to the public API - renamed or removed
    classes, methods, or CLI flags, changed signatures or defaults, changed
    output file layouts.
    - If there are none, continue.
@@ -56,7 +56,7 @@ Instructions:
         `ruff check --fix` and `ruff format`. Do not run ruff project-wide.
       - For `mypy` errors: fix the type annotations in the flagged files.
       - For other hook failures: diagnose and fix the root cause; do NOT use `--no-verify`.
-   c. Return to step 4 and retry — repeat until the commit succeeds or you have exhausted reasonable fixes.
+   c. Return to step 4 and retry - repeat until the commit succeeds or you have exhausted reasonable fixes.
    d. If an issue cannot be fixed automatically (e.g. a failing test unrelated to the current changes), report it to the user and stop.
 
 6. After a successful commit, print the one-line commit summary (`git log --oneline -1`)

.agents/skills/doc-feature/SKILL.md

@@ -10,10 +10,10 @@ Instructions:
 1. Read the changed source file(s) in full.
 2. Read existing docstrings for every public method or class that changed.
 3. Update docstrings to reflect current behavior using NumPy docstring style.
-   Do not restate ITK shape, axis order, or world space — those are fixed
+   Do not restate ITK shape, axis order, or world space - those are fixed
    project conventions. Document only real deviations from them.
 4. Add inline comments only for non-obvious logic (coordinate transforms, shape permutations).
 5. Do not create new `.md` files unless explicitly asked.
-6. After any public API change — a signature, public behavior, or a public
-   attribute — refresh the knowledge graph: `graphify update .`
-7. Do not paraphrase the method name as the docstring — explain what it does and why.
+6. After any public API change - a signature, public behavior, or a public
+   attribute - refresh the knowledge graph: `graphify update .`
+7. Do not paraphrase the method name as the docstring - explain what it does and why.

.agents/skills/impl/SKILL.md

@@ -15,9 +15,12 @@ Instructions:
 6. Run `ruff check . --fix && ruff format .` after editing Python files.
 7. Prefer compatibility. Break a public API only when the change is generally
    beneficial to future users, and never via a deprecation shim, removed-symbol
-   re-export, or removed-symbol stub — provide a conversion script when the
+   re-export, or removed-symbol stub - provide a conversion script when the
    change is substantial.
 8. Explicitly note any breaking changes introduced, and append an entry for
    each to `docs/developer/migration_next.md` using the template at the bottom
    of that file.
 9. Do not add features beyond what was requested.
+10. When fixing a bug, fix it. Do not add a comment recording what was wrong,
+    what changed, or how it was diagnosed - that belongs in the commit
+    message, not the code. Only truly exceptional motivations earn a comment.

.agents/skills/plan/SKILL.md

@@ -11,7 +11,7 @@ Instructions:
 2. Summarize current behavior in 3–5 bullet points.
 3. Produce a numbered implementation plan with enough detail to act on.
 4. List every file that will change.
-5. Call out any change that breaks the fixed data conventions — an axis
+5. Call out any change that breaks the fixed data conventions - an axis
    permutation, an ITK-to-NumPy handoff, or an LPS-to-USD conversion. Do not
    restate the conventions themselves.
 6. List open questions that need user input before coding starts.

.agents/skills/review-pr/SKILL.md

@@ -28,7 +28,7 @@ If `$ARGUMENTS` is empty, ask the user for the PR number before doing anything.
    If not authenticated, stop and tell the user to run `gh auth login`.
 
 2. Confirm the current branch is **not** `main` and not detached. If it is,
-   warn the user — applied edits will land on whichever branch is checked
+   warn the user - applied edits will land on whichever branch is checked
    out. Ask before proceeding.
 
 3. Confirm the working tree has no unstaged Python edits the user would not
@@ -73,7 +73,7 @@ Defaults worth knowing:
    working-tree changes only; the user controls staging
    (`git add -p`) and commit.
 
-4. Delete `pr_<NUMBER>_review_summary.md` after reporting — the working-tree
+4. Delete `pr_<NUMBER>_review_summary.md` after reporting - the working-tree
    diff is the durable record; the summary is intermediate state.
 
 5. If the run failed:

.agents/skills/simplify-staged/SKILL.md

@@ -11,22 +11,22 @@ $ARGUMENTS
 This is an open-source project that welcomes contributors with a range of backgrounds
 and skill levels. Every change should meet the following bar before it is committed:
 
-- **Readable** — logic is immediately clear to a developer unfamiliar with the file.
-- **Focused** — each function or method does one thing; no hidden side effects.
-- **Consistent** — style, naming, and patterns match the surrounding codebase.
-- **Well-typed** — full type hints; no `Any` unless unavoidable and documented.
-- **Documented** — every public method has a docstring that states what it does,
+- **Readable** - logic is immediately clear to a developer unfamiliar with the file.
+- **Focused** - each function or method does one thing; no hidden side effects.
+- **Consistent** - style, naming, and patterns match the surrounding codebase.
+- **Well-typed** - full type hints; no `Any` unless unavoidable and documented.
+- **Documented** - every public method has a docstring that states what it does,
   its arguments, and return value.
 
 ## Instructions
 
 1. Run `git diff HEAD` to get the full diff of tracked modified files.
    Also run `git diff HEAD --name-only` to list just the changed files.
 
-2. For each modified Python file, read the **entire file** — not just the diff.
+2. For each modified Python file, read the **entire file** - not just the diff.
    Understanding the unchanged context is necessary to judge whether the new code
    fits naturally. If a path from `git diff HEAD --name-only` no longer exists on
-   disk (deleted or renamed), skip it — do not attempt to read or edit it.
+   disk (deleted or renamed), skip it - do not attempt to read or edit it.
 
 3. For each changed section, apply the checks below. Fix every issue found directly
    in the file using small, targeted edits. Do not refactor code that was not changed.
@@ -60,7 +60,7 @@ and skill levels. Every change should meet the following bar before it is commit
 4. After editing, run ruff only on Python files that are modified and still exist
    on disk. Use `git diff --diff-filter=d --name-only HEAD -- '*.py'` to list
    changed, non-deleted `.py` files, then pass only that list to
-   `ruff check --fix` and `ruff format`. Do not run ruff project-wide — it
+   `ruff check --fix` and `ruff format`. Do not run ruff project-wide - it
    may reformat files outside the current change set.
 
 5. Report a concise summary of every change made, grouped by file. If a file needed

.agents/skills/test-feature/SKILL.md

@@ -14,8 +14,8 @@ Instructions:
 4. **Strongly prefer real (downloaded) test data over synthetic data.** Request
    the session fixtures (`test_directories`, `download_test_data`,
    `test_images`) so the standard test datasets are pulled automatically on
-   first use. Real data exercises the production code paths — preprocessing,
-   resampling, dtype handling, world-frame metadata — that synthetic toy
+   first use. Real data exercises the production code paths - preprocessing,
+   resampling, dtype handling, world-frame metadata - that synthetic toy
    volumes silently bypass. Only fall back to synthetic `itk.Image` or
    `pv.PolyData` inputs when:
      - the behavior under test is a pure unit (e.g. axis arithmetic, dict
@@ -30,14 +30,14 @@ Instructions:
    (Git LFS-tracked). Run with `--create-baselines` to materialize missing
    baselines on first use; afterward, regression compares to the stored
    baseline. This catches drift that hand-written numeric thresholds miss.
-6. Do not restate ITK shape, axis order, or world frame in test docstrings —
+6. Do not restate ITK shape, axis order, or world frame in test docstrings -
    those are fixed conventions. State only what is specific to the test, such
    as the size of a synthetic volume.
 7. Mark tests that need a GPU, a slow runtime, or a licensed Simpleware
    install with `@pytest.mark.requires_gpu`, `@pytest.mark.slow`, or
    `@pytest.mark.requires_simpleware` so they fall into the right opt-in
    bucket (`--run-gpu`, `--run-slow`, `--run-simpleware`). Tests that just
-   need downloadable data need **no** marker — the fixture chain handles it.
+   need downloadable data need **no** marker - the fixture chain handles it.
 8. Show the exact command to run the new tests, including any opt-in flags
    the markers require. Examples:
    - `py -m pytest tests/test_<module>.py -v`