ENH: Cleaned up infrastructure and documentation

.agents/agents/implementation.md

@@ -5,7 +5,8 @@ tools: Read, Edit, Write, Bash, Glob, Grep
 ---
 
 You are an implementation agent for PhysioTwin4D, an early-alpha scientific Python library
-that converts 4D CT scans into animated USD models for NVIDIA Omniverse.
+that provides methods, workflows, tutorials, and a CLI for creating personalized
+physiological digital twins from 3D medical images.
 
 ## Pipeline
 

.gitattributes

@@ -1,2 +1,3 @@
 *.hdf filter=lfs diff=lfs merge=lfs -text
 *.mha filter=lfs diff=lfs merge=lfs -text
+docs/assets/*.gif filter=lfs diff=lfs merge=lfs -text

.github/workflows/docs.yml

@@ -20,7 +20,9 @@ jobs:
     steps:
     - name: Checkout code
       uses: actions/checkout@v6
-
+      with:
+        lfs: true
+
     - name: Free up disk space
       run: |
         echo "Disk space before cleanup:"

AGENTS.md

@@ -2,10 +2,14 @@
 
 Role-based guidance for AI agents working in this repository.
 
-PhysioTwin4D converts 4D CT scans into animated USD models for NVIDIA
-Omniverse. It is an **early-alpha** scientific Python library. Clarity beats
-premature optimization. Breaking changes are acceptable. Backward compatibility
-is not a goal.
+PhysioTwin4D is a collection of methods, workflows, tutorials, and CLI tools
+for creating personalized physiological digital twins: starting from a 3D
+medical image of a subject, extracting anatomic models, and then using AI
+surrogates to estimate the subject's physiological processes (initially
+cardiac and respiratory motion, expanding to electrophysiology, blood flow,
+and organ perfusion). It is an **early-alpha** scientific Python library.
+Clarity beats premature optimization. Breaking changes are acceptable.
+Backward compatibility is not a goal.
 
 ## Role
 
@@ -42,8 +46,8 @@ Non-Python tools used by contributor workflows:
 
 ## Common Commands
 
-Prefer the repository-local virtual environment at `.\venv`. Activate it before
-issuing Python commands so `python`, console scripts, and `uv pip` all use that
+Prefer the repository-local virtual environment at `.\venv` or `..\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.
@@ -98,13 +102,10 @@ Version bumping: `bumpver update --patch`, `--minor`, or `--major`.
 ## Codex Sandbox
 
 - If a Python command fails with
-  `No Python at '"C:\Users\saylward\AppData\Local\Programs\Python\Python311\python.exe'`,
-  do not assume Python 3.11 is missing. The Codex sandbox can break the
-  launcher or venv path.
-- Use the temporary validation environment instead:
-  `C:\Users\saylward\AppData\Local\Temp\pt4d-uv-env\Scripts\python.exe`.
-  It has been verified as Python 3.11.9 with `ruff` available.
-- Run that temporary venv outside the sandbox when needed. Treat this as an
+  `No Python at ...`
+  do not assume Python is missing. The sandbox can break the launcher or venv path.
+- Use the local virtual environment instead: `.\venv`, `..\venv`, `.\.venv`, `..\.venv`
+- Run that venv outside the sandbox when needed. Treat this as an
   environment/sandbox workaround, not a dependency or installation problem.
 
 ## Universal Rules
@@ -128,12 +129,10 @@ 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 `python -m pytest tests/ -v` from the active `.\venv` to verify changes.
+- Run `python -m pytest tests/ -v` from the active virtual 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
-  download it automatically via the session fixtures.
 - Consult `docs/API_MAP.md` to locate classes, methods, and signatures before
   searching manually.
 - Do not commit changes or make pull requests unless specifically told to do so.
@@ -150,8 +149,9 @@ Version bumping: `bumpver update --patch`, `--minor`, or `--major`.
 - Convert surfaces to USD right-handed Y-up only at USD export by
   `vtk_to_usd.lps_points_to_usd`:
   USD `+X=Left`, `+Y=Superior`, `+Z=Anterior`.
-- Masks are ITK images with integer labels. Keep anatomy group IDs consistent
+- Labelmaps are ITK images with integer labels. Keep anatomy group IDs consistent
   across segmenters.
+- Masks are binary ITK images.
 - Transforms are ITK composite transforms stored in compressed `.hdf` files.
 
 ## Implementation Role

CLAUDE.md

@@ -2,9 +2,6 @@
 
 Project guidance for Claude Code in this repository.
 
-Codex and other AI agents should use `AGENTS.md` as the primary shared
-instructions file. Claude-specific behavior and slash-command usage remain here.
-
 ## Role:
 We are developing open-source code for scientific AI libraries. Leverage GPU-accelerated methods when appropriate.
 
@@ -46,21 +43,6 @@ py -m pytest tests/ -v
 py -m pytest tests/test_contour_tools.py -v
 py -m pytest tests/test_contour_tools.py::test_extract_surface -v
 
-# Opt-in buckets (each flag enables one marker family)
-py -m pytest tests/ -v --run-slow         # tests marked 'slow'
-py -m pytest tests/ -v --run-gpu          # tests marked 'requires_gpu'
-py -m pytest tests/ -v --run-simpleware   # tests marked 'requires_simpleware'
-py -m pytest tests/ -v --run-physicsnemo  # tests marked 'requires_physicsnemo'
-py -m pytest tests/ -v --run-experiments  # tests marked 'experiment'
-py -m pytest tests/ -v --run-tutorials    # tests marked 'tutorial'
-
-# Enable every bucket at once (equivalent to passing all --run-* flags).
-# Self-hosted CI GPU runner uses this after installing [test,cuda13,physicsnemo].
-py -m pytest tests/ -v --run-all
-
-# Typical local GPU profile.
-py -m pytest tests/ -v --run-gpu --run-slow
-
 # With coverage
 py -m pytest tests/ --cov=src/physiotwin4d --cov-report=html
 
@@ -86,8 +68,9 @@ Regenerate it after any public API change: `py utils/generate_api_map.py`
 - Surfaces: `pv.PolyData` in LPS (inherited from the source `itk.Image` via
   `itk.vtk_image_from_image`); converted to USD right-handed Y-up only at USD
   export by `vtk_to_usd.lps_points_to_usd` (USD +X=Left, +Y=Superior, +Z=Anterior)
-- Masks: ITK images with integer labels; consistent anatomy group IDs across all segmenters
-- Transforms: ITK composite transforms stored in `.hdf` files with compression
+- Labelmaps: ITK images with integer labels defined by anatomy segmenter used.
+- Masks: ITK binary images
+- Transforms: ITK transforms stored in `.hdf` files with compression
 
 ## Testing
 

MANIFEST.in

@@ -3,7 +3,6 @@ include README.md
 include LICENSE
 include CLAUDE.md
 include CHANGELOG.md
-include doc/PYPI_RELEASE_GUIDE.md
 
 # Include configuration files
 include pyproject.toml