docs: document SEALS model selection and scientific rationale

- Explain why we use `--fast True` (runs SEALS, the ISLES'22 winner)
- Document that SEALS only needs DWI+ADC (perfect match for MR-Lite)
- Add model comparison table (SEALS vs NVAUTO vs SWAN)
- Clarify that FLAIR is only needed for full ensemble mode
- Document external validation rationale (ISLES22 training → ISLES24 testing)
- Update all specs with consistent SEALS/fast mode comments

Files updated:
- 00-context.md: Full SEALS explanation and scientific validity
- 01-phase-0-repo-bootstrap.md: Config comment
- 03-phase-2-deepisles-docker.md: CLI reference section
- 04-phase-3-pipeline.md: Function docstring
- 05-phase-4-gradio-ui.md: UI checkbox label/info
- 06-phase-5-polish.md: Config comment

docs/specs/00-context.md

@@ -95,9 +95,37 @@ data/scratch/isles24_extracted/
 - **Paper**: Nature Communications 2025 - "DeepISLES: A clinically validated ischemic stroke segmentation model"
 - **GitHub**: [ezequieldlrosa/DeepIsles](https://github.com/ezequieldlrosa/DeepIsles)
 - **Docker**: `isleschallenge/deepisles`
-- **Inputs**: DWI + ADC (required), FLAIR (optional)
+- **Inputs**: DWI + ADC (required), FLAIR (required for ensemble, optional for fast mode)
 - **Output**: 3D binary lesion mask (NIfTI)
-- **Mode**: We use `fast=True` (single model) not the full 3-model ensemble
+- **Mode**: `fast=True` runs **SEALS only** (the ISLES'22 challenge winner)
+
+#### Why we use `fast=True` (SEALS-only mode)
+
+DeepISLES is an ensemble of 3 models from the ISLES'22 challenge:
+
+| Model | Based On | Inputs Required | Notes |
+|-------|----------|-----------------|-------|
+| **SEALS** | nnUNet | DWI + ADC | 🏆 **ISLES'22 Winner** - runs in `--fast` mode |
+| NVAUTO | MONAI Auto3dseg | DWI + ADC + FLAIR | Requires FLAIR |
+| SWAN | FACTORIZER | DWI + ADC + FLAIR | Requires FLAIR |
+
+**Key insight**: ISLES24-MR-Lite contains only DWI + ADC (no FLAIR). Therefore:
+- `--fast True` → Runs SEALS only → **Perfect match** for our dataset
+- `--fast False` → Would try to run all 3 models → NVAUTO/SWAN would fail without FLAIR
+
+This is **not a downgrade**. SEALS won the ISLES'22 challenge and is state-of-the-art for stroke lesion segmentation using DWI+ADC alone.
+
+#### Scientific validity: External validation with zero data leakage
+
+| Dataset | Year | Used For |
+|---------|------|----------|
+| **ISLES 2022** | 2022 | SEALS training data (250 cases) |
+| **ISLES 2024** | 2024 | Our test data (149 cases from MR-Lite) |
+
+- Different patient cohorts (2 years apart, different hospitals)
+- SEALS has **never seen** ISLES24 patients
+- We have ground truth masks → can validate predictions
+- This constitutes a legitimate **external validation study**
 
 ### 3. visualization: NiiVue
 

docs/specs/01-phase-0-repo-bootstrap.md

@@ -233,7 +233,7 @@ class Settings(BaseSettings):
 
     # DeepISLES
     deepisles_docker_image: str = "isleschallenge/deepisles"
-    deepisles_fast_mode: bool = True
+    deepisles_fast_mode: bool = True  # SEALS-only (ISLES'22 winner, no FLAIR needed)
 
     # Paths
     temp_dir: str | None = None

docs/specs/03-phase-2-deepisles-docker.md

@@ -55,11 +55,28 @@ docker run --rm \
 **Expected input files:**
 - `dwi.nii.gz` (required) - Diffusion-weighted imaging
 - `adc.nii.gz` (required) - Apparent diffusion coefficient
-- `flair.nii.gz` (optional) - FLAIR sequence
+- `flair.nii.gz` (optional) - Required for full ensemble, not needed for fast mode
 
 **Output:**
 - `results/` directory containing the lesion mask
 
+### Why `--fast True` (SEALS-only mode)
+
+DeepISLES contains 3 models from the ISLES'22 challenge:
+
+| Model | Inputs | Notes |
+|-------|--------|-------|
+| **SEALS** (nnUNet) | DWI + ADC | 🏆 ISLES'22 Winner - runs with `--fast True` |
+| NVAUTO (MONAI) | DWI + ADC + FLAIR | Requires FLAIR |
+| SWAN (FACTORIZER) | DWI + ADC + FLAIR | Requires FLAIR |
+
+**We default to `fast=True` because:**
+1. ISLES24-MR-Lite only has DWI + ADC (no FLAIR)
+2. SEALS alone is the challenge-winning algorithm
+3. Running the full ensemble without FLAIR would fail for 2/3 models
+
+This is not a compromise—SEALS is state-of-the-art for DWI+ADC stroke segmentation.
+
 ## interfaces and types
 
 ### `inference/docker.py`

docs/specs/04-phase-3-pipeline.md

@@ -103,7 +103,7 @@ def run_pipeline_on_case(
         case_id: Case identifier (string) or index (int)
         dataset_id: HF dataset ID (default from settings)
         output_dir: Directory for results (default: temp dir)
-        fast: Use single-model mode (faster)
+        fast: Use SEALS-only mode (ISLES'22 winner, DWI+ADC only, no FLAIR needed)
         gpu: Use GPU acceleration
         compute_dice: Compute Dice score if ground truth available
         cleanup_staging: Remove staging directory after inference

docs/specs/05-phase-4-gradio-ui.md

@@ -423,8 +423,8 @@ def create_settings_accordion() -> dict[str, gr.components.Component]:
     with gr.Accordion("Advanced Settings", open=False):
         fast_mode = gr.Checkbox(
             value=True,
-            label="Fast Mode",
-            info="Use single model (faster, slightly less accurate)",
+            label="Fast Mode (SEALS)",
+            info="Run SEALS only (ISLES'22 winner, requires DWI+ADC). Disable for full ensemble (requires FLAIR).",
         )
         show_ground_truth = gr.Checkbox(
             value=True,

docs/specs/06-phase-5-polish.md

@@ -145,7 +145,7 @@ class Settings(BaseSettings):
 
     # DeepISLES
     deepisles_docker_image: str = "isleschallenge/deepisles"
-    deepisles_fast_mode: bool = True
+    deepisles_fast_mode: bool = True  # SEALS-only (ISLES'22 winner, no FLAIR needed)
     deepisles_timeout_seconds: int = 1800  # 30 minutes
     deepisles_use_gpu: bool = True