project subfolders masks/ and exports/ are now created only when verso tries to populate them. This matches the behavior of the app for the annotation subfolder

Author: valtot

.claude/data-model.md

@@ -12,7 +12,7 @@ The JSON filename defaults to `project-verso.json`
 ```
 my_experiment/
     project-verso.json     # all project state, settings, metadata
-    thumbnails/            # working-resolution OME-TIFFs + filmstrip PNGs
+    thumbnails/            # working-resolution OME-TIFFs
     masks/                 # slice masks as 1-bit PNGs
     annotations/           # point series (points.csv) + area masks, one folder each
     exports/               # export outputs (images with overlays, aligned stacks, etc.)
@@ -21,6 +21,23 @@ my_experiment/
             <image-slug>/  # only when "Separate output per slice" is on: same files per section
 ```
 
+**Subfolders are created lazily.** Project creation makes only the folder and the
+JSON; each subfolder appears when something first writes into it — `thumbnails/`
+via `ensure_working_copy` (`engine/io/image_io.py`), `masks/` via `save_mask`
+(`engine/preprocessing.py`), `annotations/` via `save_annotations`
+(`engine/io/annotation_io.py`), `exports/` via the export writers
+(`engine/io/export_stack.py`, `quant_export.py`, `export_images.py`). A new writer
+must `mkdir(parents=True, exist_ok=True)` its own parent, and every reader must
+tolerate the folder being absent (`.exists()` guard).
+
+In practice `thumbnails/` always exists once a project is successfully created:
+both the New Project and Import QUINT dialogs run `generate_thumbnails`, and the
+`populate_metadata` pass that follows regenerates any thumbnail still missing
+(including when the user hit Skip) because it needs `resolution_thumbnail_wh`.
+Skip therefore only forgoes the progress dialog, not the work. Missing thumbnails
+are never fatal regardless — every consumer goes through `ensure_working_copy`,
+which regenerates from the original on demand.
+
 Quantification CSVs are written by `engine/io/quant_export.py`; each run gets its
 own timestamped folder. Pooled runs write the tables at the top level; per-slice
 runs write one `<slugified-image-stem>/` subfolder per section instead. Aggregated

CLAUDE.md

@@ -121,11 +121,14 @@ User projects are folders, not single files:
 ```
 my_experiment/
     project-verso.json   # all state, settings, metadata (DEFAULT_PROJECT_FILENAME)
-    thumbnails/          # working-resolution OME-TIFFs + filmstrip PNGs
+    thumbnails/          # working-resolution OME-TIFFs
     masks/               # slice masks (1-bit PNG)
+    annotations/         # point series + area masks, one folder each
     exports/             # export outputs (warped images, etc.)
 ```
 
+Only the project folder and its JSON are created up front. **Every subfolder is created on demand by whatever writes the first file into it** — `thumbnails/` by `ensure_working_copy`, `masks/` by `save_mask`, `annotations/` by `save_annotations`, `exports/` by the export writers. Never scaffold them eagerly: a project should not carry an empty folder for a step the user has not reached. Correspondingly, every reader must guard with `.exists()`.
+
 Original images are referenced by path in `section.original_path`, not copied. See [.claude/data-model.md](.claude/data-model.md) for the JSON schema.
 
 ## Save policy

src/verso/gui/controllers/export_controller.py

@@ -535,16 +535,26 @@ def _annotation_titles(project_dir: Path, kind: str) -> list[str]:
         return titles
 
     def _show_export_done(self, out_dir: Path, message: str) -> None:
-        """Completion box with an "Open folder" shortcut to the export dir."""
+        """Completion box with an "Open folder" shortcut to the export dir.
+
+        ``exports/`` is created by whichever writer produces the first file, so a
+        run that wrote nothing (cancelled, or a quantification with no tables)
+        leaves it absent. The button is offered only when the folder really
+        exists, rather than opening a path that is not there.
+        """
         from PyQt6.QtCore import QUrl
         from PyQt6.QtGui import QDesktopServices
 
         box = QMessageBox(self._window)
         box.setIcon(QMessageBox.Icon.Information)
         box.setWindowTitle("Export complete")
         box.setText(message)
-        open_btn = box.addButton("Open folder", QMessageBox.ButtonRole.ActionRole)
+        open_btn = (
+            box.addButton("Open folder", QMessageBox.ButtonRole.ActionRole)
+            if out_dir.exists()
+            else None
+        )
         box.addButton(QMessageBox.StandardButton.Ok)
         box.exec()
-        if box.clickedButton() is open_btn:
+        if open_btn is not None and box.clickedButton() is open_btn:
             QDesktopServices.openUrl(QUrl.fromLocalFile(str(out_dir)))

src/verso/gui/dialogs/import_quint.py

@@ -611,10 +611,10 @@ def _on_accept(self) -> None:
         if not self._confirm_aspect_ratios(original_paths):
             return
 
+        # Only the project folder itself is created here; thumbnails/, masks/ and
+        # exports/ are each made by whatever first writes into them (thumbnails/ by
+        # the generate_thumbnails call below), so no empty folders are left behind.
         folder_path.mkdir(parents=True, exist_ok=True)
-        (folder_path / "thumbnails").mkdir(exist_ok=True)
-        (folder_path / "masks").mkdir(exist_ok=True)
-        (folder_path / "exports").mkdir(exist_ok=True)
         project_path = folder_path / f"{slug}_verso.json"
 
         orientation = self._orientation_combo.currentData() or "coronal"

src/verso/gui/dialogs/new_project.py

@@ -546,8 +546,11 @@ def _on_accept(self) -> None:
             return
 
         # A project is a self-contained folder named after the project, created
-        # inside the location the user picked. The JSON and every subfolder live
-        # inside it; the user never names the file directly.
+        # inside the location the user picked. The JSON lives inside it and the
+        # user never names the file directly. Subfolders (thumbnails/, masks/,
+        # exports/, annotations/) are not scaffolded here: each is created by
+        # whatever writes the first file into it, so a project never carries an
+        # empty folder for a step the user has not reached.
         slug = _slugify_project_name(name)
         folder_path = Path(location) / slug
         if folder_path.exists() and any(folder_path.iterdir()):
@@ -560,9 +563,6 @@ def _on_accept(self) -> None:
             )
             return
         folder_path.mkdir(parents=True, exist_ok=True)
-        (folder_path / "thumbnails").mkdir(exist_ok=True)
-        (folder_path / "masks").mkdir(exist_ok=True)
-        (folder_path / "exports").mkdir(exist_ok=True)
 
         project_path = folder_path / f"{slug}_verso.json"