Update model card for weights layout and CI bucket (#3)

- Update model card for weights layout and CI bucket (58a0861f11c7729ba658a1ee35dad204696a04c6)

.gitattributes

@@ -42,3 +42,4 @@ manual_0429 filter=lfs diff=lfs merge=lfs -text
 omelette1_0429 filter=lfs diff=lfs merge=lfs -text
 omelette2_0429 filter=lfs diff=lfs merge=lfs -text
 t2s_mod_ep1k2_0728 filter=lfs diff=lfs merge=lfs -text
+weights/** filter=lfs diff=lfs merge=lfs -text

README.md

@@ -2,6 +2,8 @@
 license: mit
 library_name: pytorch
 pipeline_tag: image-segmentation
+buckets:
+  - BrainVascuLab/vesselboost-ci
 tags:
   - medical-imaging
   - mri
@@ -36,22 +38,50 @@ See `config.json` for the machine-readable inference configuration.
 
 ## Checkpoints
 
-Checkpoint names and extensions are preserved from the original release.
+All pretrained checkpoints are stored under `weights/`. Their original filenames and serialization formats are preserved from the original release.
 
 | Checkpoint                            | MRI contrast     | Description                                                                                                                             |
 | ------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `BM_VB2_aug_all_ep2k_bat_10_0903`   | TOF-MRA          | Primary TOF-MRA checkpoint referenced by the VesselBoost documentation and tests; trained with the combined augmentation configuration. |
-| `VB2_aug_intensity_ep2k_bat10_0903` | TOF-MRA          | Augmentation ablation using the intensity augmentation configuration.                                                                   |
-| `VB2_aug_off_ep2k_bat10_0903`       | TOF-MRA          | Augmentation ablation with augmentation disabled.                                                                                       |
-| `VB2_aug_random_ep2k_bat10_0903`    | TOF-MRA          | Augmentation ablation using the random augmentation configuration.                                                                      |
-| `VB2_aug_spatial_ep2k_bat10_0903`   | TOF-MRA          | Augmentation ablation using the spatial augmentation configuration.                                                                     |
-| `manual_0429`                       | TOF-MRA          | Legacy checkpoint associated with the manual-label training run and used in VesselBoost v2.0.2 examples.                                |
-| `omelette1_0429`                    | TOF-MRA          | Legacy TOF-MRA checkpoint identified as Omelette variant 1.                                                                             |
-| `omelette2_0429`                    | TOF-MRA          | Legacy TOF-MRA checkpoint identified as Omelette variant 2.                                                                            |
-| `t2s_mod_ep1k2_0728`                | T2*-weighted MRI | Experimental T2*-weighted vessel-segmentation checkpoint. It has not received the same validation as the primary TOF-MRA model.         |
+| [`BM_VB2_aug_all_ep2k_bat_10_0903`](weights/BM_VB2_aug_all_ep2k_bat_10_0903)   | TOF-MRA          | Primary TOF-MRA checkpoint referenced by the VesselBoost documentation and tests; trained with the combined augmentation configuration. |
+| [`VB2_aug_intensity_ep2k_bat10_0903`](weights/VB2_aug_intensity_ep2k_bat10_0903) | TOF-MRA          | Augmentation ablation using the intensity augmentation configuration.                                                                   |
+| [`VB2_aug_off_ep2k_bat10_0903`](weights/VB2_aug_off_ep2k_bat10_0903)       | TOF-MRA          | Augmentation ablation with augmentation disabled.                                                                                       |
+| [`VB2_aug_random_ep2k_bat10_0903`](weights/VB2_aug_random_ep2k_bat10_0903)    | TOF-MRA          | Augmentation ablation using the random augmentation configuration.                                                                      |
+| [`VB2_aug_spatial_ep2k_bat10_0903`](weights/VB2_aug_spatial_ep2k_bat10_0903)   | TOF-MRA          | Augmentation ablation using the spatial augmentation configuration.                                                                     |
+| [`manual_0429`](weights/manual_0429)                       | TOF-MRA          | Legacy checkpoint associated with the manual-label training run and used in VesselBoost v2.0.2 examples.                                |
+| [`omelette1_0429`](weights/omelette1_0429)                    | TOF-MRA          | Legacy TOF-MRA checkpoint identified as Omelette variant 1.                                                                             |
+| [`omelette2_0429`](weights/omelette2_0429)                    | TOF-MRA          | Legacy TOF-MRA checkpoint identified as Omelette variant 2.                                                                            |
+| [`t2s_mod_ep1k2_0728`](weights/t2s_mod_ep1k2_0728)                | T2*-weighted MRI | Experimental T2*-weighted vessel-segmentation checkpoint. It has not received the same validation as the primary TOF-MRA model.         |
 
 The augmentation-specific checkpoints are included to preserve the original model set and support comparison or reproduction of augmentation experiments. For the standard TOF-MRA prediction workflow, use `manual_0429` or `BM_VB2_aug_all_ep2k_bat_10_0903` unless reproducing a specific legacy experiment.
 
+## Downloading checkpoints
+
+Install the Hugging Face command-line client:
+
+```bash
+python -m pip install huggingface_hub
+```
+
+Download the primary TOF-MRA checkpoint:
+
+```bash
+hf download BrainVascuLab/VesselBoost \
+  weights/BM_VB2_aug_all_ep2k_bat_10_0903 \
+  --local-dir saved_models
+```
+
+The downloaded checkpoint will be available at `saved_models/weights/BM_VB2_aug_all_ep2k_bat_10_0903`.
+
+Download every pretrained checkpoint and the checksum manifest:
+
+```bash
+hf download BrainVascuLab/VesselBoost \
+  --include "weights/*" \
+  --local-dir saved_models
+```
+
+For reproducible automated workflows, pass `--revision` with a specific Hugging Face commit hash rather than relying on the moving `main` branch.
+
 ## Preprocessing and inference
 
 VesselBoost v2.0.2 performs the following inference operations:
@@ -69,12 +99,15 @@ VesselBoost preprocessing modes can optionally perform N4 bias-field correction,
 
 ## Integrity verification
 
-SHA-256 checksums are provided in `MANIFEST.sha256`. From the directory containing the downloaded files, verify them with:
+SHA-256 checksums for every checkpoint are provided in [`weights/MANIFEST.sha256`](weights/MANIFEST.sha256). After downloading all files, verify them with:
 
 ```bash
+cd saved_models/weights
 sha256sum --check MANIFEST.sha256
 ```
 
+All nine checkpoints should report `OK`.
+
 Load the checkpoints with the pinned VesselBoost source and map tensors to the intended device. When supported by the installed PyTorch version, use `weights_only=True` when loading these state dictionaries.
 
 ## Known limitations and expected failure cases
@@ -89,6 +122,22 @@ Load the checkpoints with the pinned VesselBoost source and map tensors to the i
 - Training labels for small vessels can be incomplete or imperfect. Predictions should not be interpreted as a complete representation of the cerebral vasculature.
 - Detailed provenance for `manual_0429`, `omelette1_0429`, and `omelette2_0429` training runs is documented in our ApertureNeuro journal article *VesselBoost: A Python Toolbox for Small Blood Vessel Segmentation in Human Magnetic Resonance Angiography Data*.
 
+## GitHub Actions CI outputs
+
+The latest generated outputs from VesselBoost's GitHub Actions test workflows are stored in the public [VesselBoost CI bucket](https://huggingface.co/buckets/BrainVascuLab/vesselboost-ci).
+
+The bucket uses the following layout:
+
+```text
+github_actions/
+├── boost/predicted_labels/
+├── prediction/predicted_labels/
+├── train/saved_model/
+└── tta/predicted_labels/
+```
+
+These files are automated CI diagnostics, not validated model releases or benchmark results. Each successful push-triggered workflow replaces the previous contents of its corresponding directory.
+
 ## Resources and citation
 
 - Paper DOI: [10.52294/001c.123217](https://doi.org/10.52294/001c.123217)