Fix critical model implementations and add sample scenarios

Model Fixes (verified against official Qwen3-VL-Embedding repo):
- Embedding: Use last-token pooling instead of mean pooling
- Embedding: Fix dimension from 768/384 to 4096
- Reranker: Use yes/no LM head weights + sigmoid instead of CLS norm
- Apply fixes in both models/real.py and rag/vectorstore.py

Additional Changes:
- Add sample scenarios with real fire damage images
- Add E2E tests with Playwright
- Fix Gradio 6.x tab navigation tests
- Add logging configuration
- Improve UI form handling

All 179 unit tests pass.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.gitattributes

@@ -0,0 +1 @@
+sample_images/*.jpg filter=lfs diff=lfs merge=lfs -text

CLAUDE.md

@@ -22,7 +22,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 | Component | Technology |
 |-----------|------------|
-| UI Framework | Gradio 4.x |
+| UI Framework | Gradio 6.x |
 | Vision/Generation | Qwen3-VL-30B-A3B-Instruct |
 | Embeddings | Qwen3-VL-Embedding-8B |
 | Reranker | Qwen3-VL-Reranker-8B |
@@ -31,6 +31,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 | PDF Generation | Pandoc 3.x |
 | Package Manager | pip + requirements.txt |
 
+## UI Components (Gradio 6.x)
+
+The frontend uses optimized input components:
+
+| Field | Component | Notes |
+|-------|-----------|-------|
+| State | `gr.Dropdown` | 50 US states + DC + territories |
+| Dates | `gr.DateTime` | Calendar picker, no time selection |
+| ZIP Code | `gr.Textbox` + blur validation | Real-time format validation |
+| Credentials | `gr.Dropdown(multiselect=True)` | CIH, CSP, PE, etc. |
+| Floor | `gr.Dropdown` | Basement through Roof |
+| Ceiling Height | `gr.Dropdown` + custom option | 8-20 ft presets |
+| Image Upload | `gr.Files(file_count="multiple")` | Batch upload support |
+
+**Keyboard Shortcuts:**
+- `Ctrl+1` through `Ctrl+5`: Navigate between tabs
+
 ## Development Commands
 
 ```sh

app.py

@@ -5,11 +5,51 @@ Main Gradio application entry point with session state and tab validation.
 
 import gradio as gr
 
+from config.logging import setup_logging
 from config.settings import settings
+
+# Initialize logging before any other imports that might log
+setup_logging(settings.log_level)
+
+import logging
+logger = logging.getLogger(__name__)
+
 from models.loader import get_models
 from ui.state import SessionState, create_new_session, session_to_json, session_from_json
 from ui.storage import get_head_html
 from ui.tabs import project, rooms, images, observations, results
+from ui import samples
+
+
+# Keyboard shortcuts JavaScript (Ctrl+1-5 for tab navigation)
+KEYBOARD_JS = """
+<script>
+document.addEventListener('keydown', (e) => {
+    if (e.ctrlKey && e.key >= '1' && e.key <= '5') {
+        e.preventDefault();
+        const tabIds = [
+            'tab-project-button', 'tab-rooms-button', 'tab-images-button',
+            'tab-observations-button', 'tab-results-button'
+        ];
+        const tabIndex = parseInt(e.key) - 1;
+        const tabButton = document.getElementById(tabIds[tabIndex]);
+        if (tabButton) {
+            tabButton.click();
+        }
+    }
+});
+</script>
+"""
+
+# Validation CSS classes
+VALIDATION_CSS = """
+.valid-field input, .valid-field textarea {
+    border-color: #66bb6a !important;
+}
+.invalid-field input, .invalid-field textarea {
+    border-color: #ef5350 !important;
+}
+"""
 
 
 def create_app() -> gr.Blocks:
@@ -22,6 +62,7 @@ def create_app() -> gr.Blocks:
     # localStorage JS will be injected there
     with gr.Blocks(
         title="FDAM AI Pipeline - Fire Damage Assessment",
+        css=VALIDATION_CSS,
     ) as app:
         # Session state (stored in Gradio State component)
         session_state = gr.State(value=create_new_session())
@@ -46,30 +87,113 @@ def create_app() -> gr.Blocks:
                 """
             )
 
-        # Tab navigation
+        # Sample loader dropdown
+        with gr.Row():
+            sample_dropdown = gr.Dropdown(
+                label="Load Sample",
+                choices=samples.get_sample_choices(),
+                value="",
+                elem_id="sample_dropdown",
+                scale=2,
+            )
+            sample_status = gr.HTML(
+                value="",
+                elem_id="sample_status",
+                scale=3,
+            )
+
+        # Tab navigation (elem_id for stable JS selectors - Gradio appends "-button" for tab buttons)
+        # Store Tab references for individual select event handlers
         with gr.Tabs() as tabs:
             # Tab 1: Project Information
-            with gr.Tab("1. Project Info", id=0):
+            tab_project = gr.Tab("1. Project Info", id=0, elem_id="tab-project")
+            with tab_project:
                 tab1 = project.create_tab()
 
             # Tab 2: Building/Rooms
-            with gr.Tab("2. Building/Rooms", id=1):
+            tab_rooms = gr.Tab("2. Building/Rooms", id=1, elem_id="tab-rooms")
+            with tab_rooms:
                 tab2 = rooms.create_tab()
 
             # Tab 3: Images
-            with gr.Tab("3. Images", id=2):
+            tab_images = gr.Tab("3. Images", id=2, elem_id="tab-images")
+            with tab_images:
                 tab3 = images.create_tab()
 
             # Tab 4: Observations
-            with gr.Tab("4. Observations", id=3):
+            tab_observations = gr.Tab("4. Observations", id=3, elem_id="tab-observations")
+            with tab_observations:
                 tab4 = observations.create_tab()
 
             # Tab 5: Generate Results
-            with gr.Tab("5. Generate Results", id=4):
+            tab_results = gr.Tab("5. Generate Results", id=4, elem_id="tab-results")
+            with tab_results:
                 tab5 = results.create_tab()
 
         # --- Event Handlers ---
 
+        # Sample Loader
+        def handle_sample_load(scenario_id: str, current_session: SessionState):
+            """Handle sample dropdown selection."""
+            if not scenario_id:
+                # Empty selection, do nothing
+                return (
+                    current_session,  # session_state unchanged
+                    *project.load_form_from_session(current_session),  # 12 form values
+                    gr.update(),  # tabs unchanged
+                    "",  # clear status
+                    "",  # reset dropdown
+                )
+
+            # Load the sample
+            new_session = samples.load_sample(scenario_id)
+            if not new_session:
+                return (
+                    current_session,
+                    *project.load_form_from_session(current_session),
+                    gr.update(),
+                    '<span style="color: #c62828;">Error: Sample not found</span>',
+                    "",
+                )
+
+            # Get scenario name for status message
+            scenario = samples.get_scenario_by_id(scenario_id)
+            name = scenario.name if scenario else scenario_id
+
+            # Load form values from new session
+            form_values = project.load_form_from_session(new_session)
+
+            return (
+                new_session,  # updated session_state
+                *form_values,  # 12 form values for Tab 1
+                gr.update(selected=0),  # switch to Tab 1 (Gradio 6.x syntax)
+                f'<span style="color: #2e7d32;">Loaded sample: {name}</span>',
+                "",  # reset dropdown to empty
+            )
+
+        sample_dropdown.change(
+            fn=handle_sample_load,
+            inputs=[sample_dropdown, session_state],
+            outputs=[
+                session_state,
+                tab1["project_name"],
+                tab1["address"],
+                tab1["city"],
+                tab1["state"],
+                tab1["zip_code"],
+                tab1["client_name"],
+                tab1["fire_date"],
+                tab1["assessment_date"],
+                tab1["facility_classification"],
+                tab1["construction_era"],
+                tab1["assessor_name"],
+                tab1["assessor_credentials"],
+                tabs,
+                sample_status,
+                sample_dropdown,
+            ],
+        )
+
         # Tab 1: Project Info
         tab1["validate_btn"].click(
             fn=project.validate_and_continue,
@@ -95,6 +219,13 @@ def create_app() -> gr.Blocks:
             ],
         )
 
+        # ZIP code validation on blur
+        tab1["zip_code"].blur(
+            fn=project.validate_zip_format,
+            inputs=[tab1["zip_code"]],
+            outputs=[tab1["zip_validation"]],
+        )
+
         # Tab 2: Building/Rooms
         tab2["add_room_btn"].click(
             fn=rooms.add_room,
@@ -104,7 +235,8 @@ def create_app() -> gr.Blocks:
                 tab2["room_floor"],
                 tab2["room_length"],
                 tab2["room_width"],
-                tab2["room_height"],
+                tab2["room_height_preset"],
+                tab2["room_height_custom"],
             ],
             outputs=[
                 session_state,
@@ -117,18 +249,27 @@ def create_app() -> gr.Blocks:
                 tab2["room_floor"],
                 tab2["room_length"],
                 tab2["room_width"],
-                tab2["room_height"],
+                tab2["room_height_preset"],
+                tab2["room_height_custom"],
             ],
         )
 
+        # Show/hide custom height input based on preset selection
+        tab2["room_height_preset"].change(
+            fn=rooms.on_height_preset_change,
+            inputs=[tab2["room_height_preset"]],
+            outputs=[tab2["room_height_custom"]],
+        )
+
         tab2["clear_form_btn"].click(
-            fn=lambda: ("", "", None, None, None),
+            fn=lambda: ("", None, None, None, None, None),
             outputs=[
                 tab2["room_name"],
                 tab2["room_floor"],
                 tab2["room_length"],
                 tab2["room_width"],
-                tab2["room_height"],
+                tab2["room_height_preset"],
+                tab2["room_height_custom"],
             ],
         )
 
@@ -169,20 +310,11 @@ def create_app() -> gr.Blocks:
         )
 
         tab2["back_btn"].click(
-            fn=lambda: 0,
+            fn=lambda: gr.update(selected=0),
             outputs=[tabs],
         )
 
         # Tab 3: Images
-        # Update room dropdown when entering tab
-        tabs.select(
-            fn=lambda session, selected: (
-                images.update_room_choices(session) if selected == 2 else gr.update()
-            ),
-            inputs=[session_state, tabs],
-            outputs=[tab3["room_select"]],
-        )
-
         tab3["add_image_btn"].click(
             fn=images.add_image,
             inputs=[
@@ -243,7 +375,7 @@ def create_app() -> gr.Blocks:
         )
 
         tab3["back_btn"].click(
-            fn=lambda: 1,
+            fn=lambda: gr.update(selected=1),
             outputs=[tabs],
         )
 
@@ -276,20 +408,11 @@ def create_app() -> gr.Blocks:
         )
 
         tab4["back_btn"].click(
-            fn=lambda: 2,
+            fn=lambda: gr.update(selected=2),
             outputs=[tabs],
         )
 
         # Tab 5: Generate Results
-        # Update preflight check when entering tab
-        tabs.select(
-            fn=lambda session, selected: (
-                results.check_preflight(session) if selected == 4 else ""
-            ),
-            inputs=[session_state, tabs],
-            outputs=[tab5["preflight_status"]],
-        )
-
         tab5["generate_btn"].click(
             fn=results.generate_assessment,
             inputs=[session_state],
@@ -321,20 +444,18 @@ def create_app() -> gr.Blocks:
         )
 
         tab5["back_btn"].click(
-            fn=lambda: 3,
+            fn=lambda: gr.update(selected=3),
             outputs=[tabs],
         )
 
-        # --- Session Resume Handlers ---
-        # Load form data when navigating to tabs
+        # --- Individual Tab Select Handlers ---
+        # Using Tab.select instead of Tabs.select because Tabs.select doesn't fire in Gradio 6.x
+        # See: https://github.com/gradio-app/gradio/issues/7189
 
-        # Tab 1 (Project): Load project form fields
-        tabs.select(
-            fn=lambda session, selected: (
-                project.load_form_from_session(session) if selected == 0
-                else tuple([gr.update()] * 12)
-            ),
-            inputs=[session_state, tabs],
+        # Tab 1 (Project): Load project form fields when selected
+        tab_project.select(
+            fn=project.load_form_from_session,
+            inputs=[session_state],
             outputs=[
                 tab1["project_name"],
                 tab1["address"],
@@ -351,13 +472,10 @@ def create_app() -> gr.Blocks:
             ],
         )
 
-        # Tab 2 (Rooms): Load room table and stats
-        tabs.select(
-            fn=lambda session, selected: (
-                rooms.load_from_session(session) if selected == 1
-                else (gr.update(), gr.update(), gr.update(), gr.update())
-            ),
-            inputs=[session_state, tabs],
+        # Tab 2 (Rooms): Load room table and stats when selected
+        tab_rooms.select(
+            fn=rooms.load_from_session,
+            inputs=[session_state],
             outputs=[
                 tab2["rooms_table"],
                 tab2["room_count"],
@@ -366,27 +484,28 @@ def create_app() -> gr.Blocks:
             ],
         )
 
-        # Tab 3 (Images): Load gallery and count (room dropdown already handled above)
-        tabs.select(
-            fn=lambda session, selected: (
-                images.load_from_session(session) if selected == 2
-                else (gr.update(), gr.update(), gr.update())
-            ),
-            inputs=[session_state, tabs],
+        # Tab 3 (Images): Load gallery, count, and room dropdown when selected
+        def load_images_tab(session: SessionState):
+            """Load all images tab data."""
+            room_choices = images.update_room_choices(session)
+            gallery, count, warning = images.load_from_session(session)
+            return room_choices, gallery, count, warning
+
+        tab_images.select(
+            fn=load_images_tab,
+            inputs=[session_state],
             outputs=[
+                tab3["room_select"],
                 tab3["images_gallery"],
                 tab3["image_count"],
                 tab3["resume_warning"],
             ],
         )
 
-        # Tab 4 (Observations): Load observation form fields
-        tabs.select(
-            fn=lambda session, selected: (
-                observations.load_form_from_session(session) if selected == 3
-                else tuple([gr.update()] * 15)
-            ),
-            inputs=[session_state, tabs],
+        # Tab 4 (Observations): Load observation form fields when selected
+        tab_observations.select(
+            fn=observations.load_form_from_session,
+            inputs=[session_state],
             outputs=[
                 tab4["smoke_odor"],
                 tab4["odor_intensity"],
@@ -406,21 +525,29 @@ def create_app() -> gr.Blocks:
             ],
         )
 
+        # Tab 5 (Results): Check preflight status when selected
+        tab_results.select(
+            fn=results.check_preflight,
+            inputs=[session_state],
+            outputs=[tab5["preflight_status"]],
+        )
+
     return app
 
 
 def main():
     """Entry point for the application."""
-    print(f"Starting FDAM AI Pipeline...")
-    print(f"Mock models: {settings.mock_models}")
-    print(f"Server: {settings.server_host}:{settings.server_port}")
+    logger.info("Starting FDAM AI Pipeline v4.0.1")
+    logger.info(f"Mock models: {settings.mock_models}")
+    logger.info(f"Log level: {settings.log_level}")
+    logger.info(f"Server: {settings.server_host}:{settings.server_port}")
 
     app = create_app()
     app.launch(
         server_name=settings.server_host,
         server_port=settings.server_port,
         share=False,
-        head=get_head_html(),  # Inject localStorage JavaScript
+        head=get_head_html(KEYBOARD_JS),  # Inject localStorage + keyboard shortcuts
     )
 
 

config/inference.py

@@ -1,24 +1,49 @@
-"""Model inference configuration parameters."""
+"""Model inference configuration parameters.
+
+Configuration values aligned with official Qwen3-VL model recommendations
+and FDAM Technical Spec requirements.
+"""
 
 from dataclasses import dataclass
 
 
 @dataclass
 class VisionInferenceConfig:
-    """Configuration for vision model inference."""
+    """Configuration for vision model inference.
+
+    Per FDAM Technical Spec Section 3 and Qwen3-VL-30B-A3B-Instruct model card.
+    """
 
     max_new_tokens: int = 4096
-    temperature: float = 0.1
+    temperature: float = 0.1  # Low temperature for deterministic output
     top_p: float = 0.9
     do_sample: bool = True
+    repetition_penalty: float = 1.1  # Reduce repetition in generated text
+
+
+@dataclass
+class GenerationInferenceConfig:
+    """Configuration for document generation (SOW, sampling plans).
+
+    Per FDAM Technical Spec Section 3 - separate config for longer generation.
+    """
+
+    max_new_tokens: int = 8192
+    temperature: float = 0.2  # Slightly higher for more varied text
+    top_p: float = 0.95
+    do_sample: bool = True
+    repetition_penalty: float = 1.05
 
 
 @dataclass
 class EmbeddingConfig:
-    """Configuration for embedding model."""
+    """Configuration for embedding model.
+
+    Per Qwen3-VL-Embedding-8B config.json: text_config.hidden_size = 4096
+    """
 
-    embedding_dimension: int = 768
-    normalize: bool = True
+    embedding_dimension: int = 4096  # Per Qwen3-VL-Embedding-8B hidden_size
+    normalize: bool = True  # L2 normalization (per official implementation)
 
 
 @dataclass
@@ -28,7 +53,21 @@ class RerankerConfig:
     top_k: int = 5
 
 
+@dataclass
+class RAGConfig:
+    """Configuration for RAG retrieval pipeline.
+
+    Per FDAM Technical Spec Section 3.
+    """
+
+    top_k_retrieval: int = 10  # Initial retrieval count
+    top_k_rerank: int = 5  # Final results after reranking
+    similarity_threshold: float = 0.7  # Minimum similarity to include
+
+
 # Default configurations
 vision_config = VisionInferenceConfig()
+generation_config = GenerationInferenceConfig()
 embedding_config = EmbeddingConfig()
 reranker_config = RerankerConfig()
+rag_config = RAGConfig()

config/logging.py

@@ -0,0 +1,61 @@
+"""Centralized logging configuration for FDAM AI Pipeline.
+
+Provides structured logging for HuggingFace Spaces troubleshooting.
+Set LOG_LEVEL=DEBUG for detailed output.
+"""
+
+import logging
+import sys
+from typing import Literal
+
+
+LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+
+def setup_logging(level: LogLevel = "INFO") -> None:
+    """Configure structured logging for FDAM Pipeline.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+               DEBUG provides detailed inference timing and RAG scores.
+               INFO provides pipeline stage progress.
+               WARNING and above for production.
+    """
+    log_format = "[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s"
+    date_format = "%Y-%m-%d %H:%M:%S"
+
+    # Configure root logger
+    logging.basicConfig(
+        level=getattr(logging, level.upper(), logging.INFO),
+        format=log_format,
+        datefmt=date_format,
+        handlers=[logging.StreamHandler(sys.stdout)],
+        force=True,  # Override any existing config
+    )
+
+    # Reduce noise from third-party libraries
+    logging.getLogger("chromadb").setLevel(logging.WARNING)
+    logging.getLogger("transformers").setLevel(logging.WARNING)
+    logging.getLogger("gradio").setLevel(logging.WARNING)
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("httpcore").setLevel(logging.WARNING)
+    logging.getLogger("urllib3").setLevel(logging.WARNING)
+    logging.getLogger("PIL").setLevel(logging.WARNING)
+
+    # Log the logging configuration itself
+    logger = logging.getLogger(__name__)
+    logger.info(f"Logging initialized at {level} level")
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger with the given name.
+
+    Convenience function for consistent logger creation.
+
+    Args:
+        name: Logger name (typically __name__ of the calling module).
+
+    Returns:
+        Configured logger instance.
+    """
+    return logging.getLogger(name)

config/settings.py

@@ -10,6 +10,9 @@ class Settings(BaseSettings):
     # Environment
     environment: Literal["development", "production"] = "development"
 
+    # Logging - set LOG_LEVEL=DEBUG for detailed troubleshooting on HF Spaces
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "INFO"
+
     # Model loading - set MOCK_MODELS=true for local dev on RTX 4090
     mock_models: bool = True
 

models/loader.py

@@ -1,9 +1,13 @@
 """Model loading with mock/real switching based on environment."""
 
+import logging
+import time
 from typing import Union
 
 from config.settings import settings
 
+logger = logging.getLogger(__name__)
+
 # Type alias for model stack
 ModelStack = Union["MockModelStack", "RealModelStack"]  # noqa: F821
 
@@ -13,21 +17,37 @@ _model_stack: ModelStack | None = None
 
 def get_model_stack() -> ModelStack:
     """Get model stack based on environment configuration."""
+    start_time = time.time()
+
     if settings.mock_models:
+        logger.info("Loading MOCK model stack (development mode)")
         from models.mock import MockModelStack
 
-        return MockModelStack().load_all()
+        stack = MockModelStack().load_all()
+        elapsed = time.time() - start_time
+        logger.info(f"Mock model stack loaded in {elapsed:.2f}s")
+        return stack
     else:
+        logger.info("Loading REAL model stack (production mode)")
+        logger.info(f"Vision model: {settings.vision_model}")
+        logger.info(f"Embedding model: {settings.embedding_model}")
+        logger.info(f"Reranker model: {settings.reranker_model}")
         from models.real import RealModelStack
 
-        return RealModelStack().load_all()
+        stack = RealModelStack().load_all()
+        elapsed = time.time() - start_time
+        logger.info(f"Real model stack loaded in {elapsed:.2f}s")
+        return stack
 
 
 def get_models() -> ModelStack:
     """Get or create the singleton model stack."""
     global _model_stack
     if _model_stack is None:
+        logger.debug("Model stack not initialized, creating new stack")
         _model_stack = get_model_stack()
+    else:
+        logger.debug("Returning cached model stack")
     return _model_stack
 
 

models/mock.py

@@ -1,9 +1,12 @@
 """Mock model implementations for local development on RTX 4090."""
 
+import logging
 import random
 from typing import Any
 from PIL import Image
 
+logger = logging.getLogger(__name__)
+
 
 class MockVisionModel:
     """Mock vision model that returns realistic JSON responses."""
@@ -27,8 +30,10 @@ class MockVisionModel:
 
     def analyze_image(self, image: Image.Image, context: str = "") -> dict[str, Any]:
         """Return mock vision analysis matching the spec schema."""
+        logger.debug(f"Mock vision analysis (context: {len(context)} chars)")
         selected_zone = random.choice(self.ZONES)
         selected_condition = random.choice(self.CONDITIONS)
+        logger.info(f"Mock vision result: zone={selected_zone}, condition={selected_condition}")
 
         # Generate 2-4 random materials
         num_materials = random.randint(2, 4)
@@ -98,17 +103,33 @@ class MockVisionModel:
 
 
 class MockEmbeddingModel:
-    """Mock embedding model that returns random vectors."""
+    """Mock embedding model that returns deterministic vectors.
+
+    Dimension matches Qwen3-VL-Embedding-8B (4096-dim).
+    Uses last-token pooling concept with L2 normalization.
+    """
 
-    def __init__(self, dimension: int = 768):
+    def __init__(self, dimension: int = 4096):
+        """Initialize with dimension matching real Qwen3-VL-Embedding-8B model."""
         self.dimension = dimension
 
     def embed(self, text: str) -> list[float]:
-        """Return mock embedding vector."""
+        """Return mock embedding vector (4096-dim, L2 normalized).
+
+        Uses hash of text for reproducibility, simulating last-token pooling.
+        """
+        import math
+
         # Use hash of text for reproducibility
         random.seed(hash(text) % (2**32))
         embedding = [random.uniform(-1, 1) for _ in range(self.dimension)]
         random.seed()  # Reset seed
+
+        # L2 normalize (matching real model behavior)
+        norm = math.sqrt(sum(x * x for x in embedding))
+        if norm > 0:
+            embedding = [x / norm for x in embedding]
+
         return embedding
 
     def embed_batch(self, texts: list[str]) -> list[list[float]]:
@@ -117,21 +138,52 @@ class MockEmbeddingModel:
 
 
 class MockRerankerModel:
-    """Mock reranker that returns random scores."""
+    """Mock reranker that returns realistic relevance scores.
+
+    Simulates Qwen3-VL-Reranker behavior with 0-1 sigmoid-like scores.
+    """
 
     def rerank(self, query: str, documents: list[str]) -> list[float]:
-        """Return mock reranking scores."""
-        # Higher scores for documents that share more words with query
+        """Return mock reranking scores (0-1 range, higher = more relevant).
+
+        Uses word overlap + sigmoid-like transformation to mimic real behavior.
+        """
+        import math
+
         scores = []
         query_words = set(query.lower().split())
+
         for doc in documents:
             doc_words = set(doc.lower().split())
-            overlap = len(query_words & doc_words)
-            base_score = overlap / max(len(query_words), 1)
-            noise = random.uniform(-0.1, 0.1)
-            scores.append(min(1.0, max(0.0, base_score + noise)))
+            # Calculate Jaccard-like overlap
+            if len(query_words) > 0:
+                overlap = len(query_words & doc_words)
+                # Scale to get a raw score
+                raw_score = overlap / max(len(query_words), 1) * 3 - 1.5
+            else:
+                raw_score = 0
+
+            # Add small random noise
+            noise = random.uniform(-0.3, 0.3)
+            raw_score += noise
+
+            # Apply sigmoid to get 0-1 range (mimics real model behavior)
+            score = 1 / (1 + math.exp(-raw_score))
+            scores.append(score)
+
         return scores
 
+    def rerank_with_indices(
+        self, query: str, documents: list[str], top_k: int = None
+    ) -> list[tuple[int, float]]:
+        """Rerank and return sorted (index, score) tuples."""
+        scores = self.rerank(query, documents)
+        indexed_scores = list(enumerate(scores))
+        indexed_scores.sort(key=lambda x: x[1], reverse=True)
+        if top_k is not None:
+            indexed_scores = indexed_scores[:top_k]
+        return indexed_scores
+
 
 class MockModelStack:
     """Mock model stack for local development."""
@@ -144,12 +196,12 @@ class MockModelStack:
 
     def load_all(self) -> "MockModelStack":
         """Simulate model loading."""
-        print("[MOCK] Loading mock models for local development...")
-        print("[MOCK] Vision model: MockVisionModel")
-        print("[MOCK] Embedding model: MockEmbeddingModel")
-        print("[MOCK] Reranker model: MockRerankerModel")
+        logger.info("Loading mock models for local development")
+        logger.debug("  Vision model: MockVisionModel")
+        logger.debug("  Embedding model: MockEmbeddingModel")
+        logger.debug("  Reranker model: MockRerankerModel")
         self.loaded = True
-        print("[MOCK] All mock models loaded successfully.")
+        logger.info("All mock models loaded successfully")
         return self
 
     def is_loaded(self) -> bool:

models/real.py

@@ -7,10 +7,12 @@ Requires ~90GB VRAM (4xL4 with 96GB total).
 import json
 import logging
 import re
+import time
 import torch
 from typing import Any
 from PIL import Image
 
+from config.inference import vision_config
 from config.settings import settings
 
 logger = logging.getLogger(__name__)
@@ -28,10 +30,18 @@ class RealModelStack:
         """Load all models with device_map='auto' for multi-GPU distribution."""
         from transformers import AutoModel, AutoProcessor
 
-        print(f"Loading models on {'cuda' if torch.cuda.is_available() else 'cpu'}...")
+        device_type = 'cuda' if torch.cuda.is_available() else 'cpu'
+        logger.info(f"Loading models on {device_type}")
+        if torch.cuda.is_available():
+            gpu_count = torch.cuda.device_count()
+            logger.info(f"CUDA devices available: {gpu_count}")
+            for i in range(gpu_count):
+                mem_gb = torch.cuda.get_device_properties(i).total_memory / (1024**3)
+                logger.info(f"  GPU {i}: {torch.cuda.get_device_name(i)} ({mem_gb:.1f} GB)")
 
         # Vision model (~58GB in BF16)
-        print(f"Loading vision model: {settings.vision_model}...")
+        logger.info(f"Loading vision model: {settings.vision_model}")
+        vision_start = time.time()
         try:
             from transformers import Qwen3VLMoeForConditionalGeneration
 
@@ -45,9 +55,10 @@ class RealModelStack:
                 settings.vision_model,
                 trust_remote_code=True,
             )
+            logger.info(f"Vision model loaded in {time.time() - vision_start:.2f}s")
         except Exception as e:
-            print(f"Failed to load 30B vision model: {e}")
-            print(f"Falling back to {settings.vision_model_fallback}...")
+            logger.warning(f"Failed to load 30B vision model: {e}")
+            logger.info(f"Falling back to {settings.vision_model_fallback}")
             self.models["vision"] = Qwen3VLMoeForConditionalGeneration.from_pretrained(
                 settings.vision_model_fallback,
                 torch_dtype=torch.bfloat16,
@@ -58,9 +69,11 @@ class RealModelStack:
                 settings.vision_model_fallback,
                 trust_remote_code=True,
             )
+            logger.info(f"Fallback vision model loaded in {time.time() - vision_start:.2f}s")
 
         # Embedding model (~16GB in BF16)
-        print(f"Loading embedding model: {settings.embedding_model}...")
+        logger.info(f"Loading embedding model: {settings.embedding_model}")
+        embed_start = time.time()
         self.models["embedding"] = AutoModel.from_pretrained(
             settings.embedding_model,
             torch_dtype=torch.bfloat16,
@@ -71,9 +84,11 @@ class RealModelStack:
             settings.embedding_model,
             trust_remote_code=True,
         )
+        logger.info(f"Embedding model loaded in {time.time() - embed_start:.2f}s")
 
         # Reranker model (~16GB in BF16)
-        print(f"Loading reranker model: {settings.reranker_model}...")
+        logger.info(f"Loading reranker model: {settings.reranker_model}")
+        reranker_start = time.time()
         self.models["reranker"] = AutoModel.from_pretrained(
             settings.reranker_model,
             torch_dtype=torch.bfloat16,
@@ -84,9 +99,10 @@ class RealModelStack:
             settings.reranker_model,
             trust_remote_code=True,
         )
+        logger.info(f"Reranker model loaded in {time.time() - reranker_start:.2f}s")
 
         self.loaded = True
-        print("All models loaded successfully.")
+        logger.info("All models loaded successfully")
         return self
 
     def is_loaded(self) -> bool:
@@ -97,7 +113,43 @@ class RealModelStack:
 class RealVisionModel:
     """Wrapper for real vision model inference."""
 
-    # Analysis prompt template for FDAM fire damage assessment
+    # System prompt for FDAM fire damage assessment (per Technical Spec Section 7)
+    VISION_SYSTEM_PROMPT = """You are an expert industrial hygienist analyzing fire damage images for the FDAM (Fire Damage Assessment Methodology) framework.
+
+## Your Task
+Analyze the provided image and extract structured information about fire damage, materials, and conditions.
+
+## Zone Classification Criteria
+- **Burn Zone**: Direct fire involvement. Look for structural char, complete combustion, exposed/damaged structural elements.
+- **Near-Field**: Adjacent to burn zone with heavy smoke/heat exposure. Look for heavy soot deposits, heat damage (warping, discoloration), strong visible contamination.
+- **Far-Field**: Smoke migration without direct heat exposure. Look for light to moderate deposits, discoloration, no structural damage.
+
+## Condition Assessment Criteria
+- **Background**: No visible contamination; surfaces appear normal/clean.
+- **Light**: Faint discoloration; minimal visible deposits; would show faint marks on white wipe test.
+- **Moderate**: Visible film or deposits; clear contamination; surface color noticeably altered.
+- **Heavy**: Thick deposits; surface texture obscured; heavy coating visible.
+- **Structural Damage**: Physical damage requiring repair before cleaning (charring, warping, holes, collapse).
+
+## Material Identification
+Identify visible materials and categorize as:
+- **Non-porous**: steel, concrete, glass, metal, CMU (concrete masonry unit)
+- **Semi-porous**: painted drywall, sealed wood
+- **Porous**: unpainted drywall, carpet, insulation, acoustic tile, upholstery
+- **HVAC**: rigid ductwork, flexible ductwork
+
+## Combustion Particle Visual Indicators
+- **Soot**: Black/dark gray coating with oily/sticky appearance; fine uniform texture; often creates "shadow" patterns
+- **Char**: Black angular fragments; visible wood grain or fibrous structure; larger particles
+- **Ash**: Gray/white powdery residue; crystalline appearance; often found with char
+
+## Important Notes
+- This is VISUAL assessment only - definitive particle identification requires laboratory analysis
+- When uncertain between two classifications, note both with relative confidence
+- Flag any areas that require professional on-site verification
+- Note any potential access issues visible in the image"""
+
+    # Analysis prompt template with JSON schema
     ANALYSIS_PROMPT = """Analyze this fire damage image and return a JSON response with the following structure:
 
 {
@@ -140,18 +192,6 @@ class RealVisionModel:
     "flags_for_review": ["any items requiring human review"]
 }
 
-Zone definitions:
-- burn: Direct fire involvement, visible charring, structural damage
-- near-field: Adjacent to burn zone, heavy smoke/heat exposure, discoloration
-- far-field: Smoke migration only, light deposits, no structural damage
-
-Condition definitions:
-- background: No visible contamination
-- light: Faint discoloration, minimal deposits
-- moderate: Visible film/deposits, surface color altered
-- heavy: Thick deposits, surface texture obscured
-- structural-damage: Physical damage requiring repair before cleaning
-
 IMPORTANT: Return ONLY valid JSON, no additional text."""
 
     def __init__(self, model, processor):
@@ -160,19 +200,26 @@ IMPORTANT: Return ONLY valid JSON, no additional text."""
 
     def analyze_image(self, image: Image.Image, context: str = "") -> dict[str, Any]:
         """Analyze an image and return structured results."""
+        start_time = time.time()
+        logger.debug(f"Starting vision analysis (context: {len(context)} chars)")
+
         try:
             from qwen_vl_utils import process_vision_info
         except ImportError:
             logger.warning("qwen_vl_utils not available, using basic processing")
             process_vision_info = None
 
-        # Build the analysis prompt
+        # Build the analysis prompt with context
         prompt = self.ANALYSIS_PROMPT
         if context:
             prompt = f"Context: {context}\n\n{prompt}"
 
-        # Prepare messages in Qwen-VL format
+        # Prepare messages in Qwen-VL format with system prompt
         messages = [
+            {
+                "role": "system",
+                "content": self.VISION_SYSTEM_PROMPT,
+            },
             {
                 "role": "user",
                 "content": [
@@ -210,23 +257,57 @@ IMPORTANT: Return ONLY valid JSON, no additional text."""
             # Move inputs to model device
             inputs = {k: v.to(self.model.device) for k, v in inputs.items()}
 
-            # Generate response
+            # Log inference config being used
+            logger.debug(f"Vision inference config: max_new_tokens={vision_config.max_new_tokens}, "
+                        f"do_sample={vision_config.do_sample}, temp={vision_config.temperature}")
+
+            # Generate response using config values
+            inference_start = time.time()
             with torch.no_grad():
-                outputs = self.model.generate(
-                    **inputs,
-                    max_new_tokens=2048,
-                    do_sample=False,
-                    temperature=None,
-                    top_p=None,
-                )
+                if vision_config.do_sample:
+                    outputs = self.model.generate(
+                        **inputs,
+                        max_new_tokens=vision_config.max_new_tokens,
+                        do_sample=True,
+                        temperature=vision_config.temperature,
+                        top_p=vision_config.top_p,
+                        repetition_penalty=vision_config.repetition_penalty,
+                    )
+                else:
+                    # Deterministic mode (no sampling)
+                    outputs = self.model.generate(
+                        **inputs,
+                        max_new_tokens=vision_config.max_new_tokens,
+                        do_sample=False,
+                        temperature=None,
+                        top_p=None,
+                        repetition_penalty=vision_config.repetition_penalty,
+                    )
+
+            inference_time = time.time() - inference_start
+            logger.debug(f"Vision inference completed in {inference_time:.2f}s")
 
             # Decode response
             response_text = self.processor.decode(
                 outputs[0], skip_special_tokens=True
             )
+            logger.debug(f"Response length: {len(response_text)} chars")
 
             # Parse JSON from response
-            return self._parse_vision_response(response_text)
+            result = self._parse_vision_response(response_text)
+
+            # Log result summary
+            total_time = time.time() - start_time
+            zone = result.get("zone", {}).get("classification", "unknown")
+            zone_conf = result.get("zone", {}).get("confidence", 0)
+            condition = result.get("condition", {}).get("level", "unknown")
+            condition_conf = result.get("condition", {}).get("confidence", 0)
+            num_materials = len(result.get("materials", []))
+            logger.info(f"Vision analysis complete in {total_time:.2f}s: "
+                       f"zone={zone} ({zone_conf:.2f}), condition={condition} ({condition_conf:.2f}), "
+                       f"materials={num_materials}")
+
+            return result
 
         except Exception as e:
             logger.error(f"Vision analysis failed: {e}")
@@ -287,14 +368,36 @@ IMPORTANT: Return ONLY valid JSON, no additional text."""
 
 
 class RealEmbeddingModel:
-    """Wrapper for real embedding model inference."""
+    """Wrapper for real embedding model inference.
+
+    Uses last-token pooling per official Qwen3-VL-Embedding implementation:
+    https://github.com/QwenLM/Qwen3-VL-Embedding
+    """
 
     def __init__(self, model, processor):
         self.model = model
         self.processor = processor
 
+    @staticmethod
+    def _pooling_last(hidden_state: torch.Tensor, attention_mask: torch.Tensor) -> torch.Tensor:
+        """Extract the last valid token's hidden state based on attention mask.
+
+        This is the official pooling method from Qwen3-VL-Embedding.
+        It finds the last position where attention_mask == 1 and extracts that token.
+        """
+        # Flip attention mask to find last 1 position
+        flipped_tensor = attention_mask.flip(dims=[1])
+        last_one_positions = flipped_tensor.argmax(dim=1)
+        col = attention_mask.shape[1] - last_one_positions - 1
+        row = torch.arange(hidden_state.shape[0], device=hidden_state.device)
+        return hidden_state[row, col]
+
     def embed(self, text: str) -> list[float]:
-        """Generate embedding for text using mean pooling."""
+        """Generate embedding for text using last-token pooling.
+
+        Per Qwen3-VL-Embedding: extracts the hidden state of the last valid token,
+        then applies L2 normalization.
+        """
         try:
             # Tokenize input
             inputs = self.processor(
@@ -312,31 +415,23 @@ class RealEmbeddingModel:
             with torch.no_grad():
                 outputs = self.model(**inputs)
 
-                # Use mean pooling over sequence dimension
+                # Use last-token pooling (official Qwen3-VL-Embedding method)
                 # outputs.last_hidden_state shape: (batch, seq_len, hidden_dim)
                 attention_mask = inputs.get("attention_mask")
                 if attention_mask is not None:
-                    # Mask-weighted mean pooling
-                    mask_expanded = attention_mask.unsqueeze(-1).expand(
-                        outputs.last_hidden_state.size()
-                    ).float()
-                    sum_embeddings = torch.sum(
-                        outputs.last_hidden_state * mask_expanded, dim=1
-                    )
-                    sum_mask = torch.clamp(mask_expanded.sum(dim=1), min=1e-9)
-                    embeddings = sum_embeddings / sum_mask
+                    embeddings = self._pooling_last(outputs.last_hidden_state, attention_mask)
                 else:
-                    # Simple mean if no attention mask
-                    embeddings = outputs.last_hidden_state.mean(dim=1)
+                    # Fallback: use last token if no attention mask
+                    embeddings = outputs.last_hidden_state[:, -1, :]
 
-                # Normalize
-                embeddings = torch.nn.functional.normalize(embeddings, p=2, dim=1)
+                # L2 normalize (per official implementation)
+                embeddings = torch.nn.functional.normalize(embeddings, p=2, dim=-1)
 
             return embeddings[0].cpu().tolist()
 
         except Exception as e:
             logger.error(f"Embedding generation failed: {e}")
-            # Return zero vector as fallback
+            # Return zero vector as fallback (4096-dim per Qwen3-VL-Embedding-8B)
             hidden_size = getattr(self.model.config, "hidden_size", 4096)
             return [0.0] * hidden_size
 
@@ -346,16 +441,69 @@ class RealEmbeddingModel:
 
 
 class RealRerankerModel:
-    """Wrapper for real reranker model inference."""
+    """Wrapper for real reranker model inference.
+
+    Uses the official Qwen3-VL-Reranker scoring method:
+    - Extracts "yes" and "no" token weights from the LM head
+    - Creates a binary linear layer: weight = yes_weight - no_weight
+    - Scores = sigmoid(linear(last_token_hidden_state))
+
+    Reference: https://github.com/QwenLM/Qwen3-VL-Embedding
+    """
 
     def __init__(self, model, processor):
         self.model = model
         self.processor = processor
+        self.score_linear = None
+        self._initialize_score_linear()
+
+    def _initialize_score_linear(self):
+        """Initialize the binary scoring linear layer from LM head weights.
+
+        Per Qwen3-VL-Reranker: the scoring layer uses the difference between
+        "yes" and "no" token embeddings from the language model head.
+        """
+        try:
+            # Get tokenizer vocab to find yes/no token IDs
+            tokenizer = self.processor.tokenizer if hasattr(self.processor, 'tokenizer') else self.processor
+            vocab = tokenizer.get_vocab()
+
+            # Find yes/no token IDs
+            token_yes_id = vocab.get("yes")
+            token_no_id = vocab.get("no")
+
+            if token_yes_id is None or token_no_id is None:
+                logger.warning("Could not find 'yes'/'no' tokens in vocab, using fallback scoring")
+                return
+
+            # Get LM head weights
+            if not hasattr(self.model, 'lm_head'):
+                logger.warning("Model does not have lm_head, using fallback scoring")
+                return
+
+            lm_head_weights = self.model.lm_head.weight.data
+
+            # Extract yes/no weights
+            weight_yes = lm_head_weights[token_yes_id]
+            weight_no = lm_head_weights[token_no_id]
+
+            # Create binary linear layer: weight = yes - no
+            hidden_size = weight_yes.shape[0]
+            self.score_linear = torch.nn.Linear(hidden_size, 1, bias=False)
+            self.score_linear.weight.data[0] = weight_yes - weight_no
+            self.score_linear = self.score_linear.to(self.model.device)
+            self.score_linear.eval()
+
+            logger.info(f"Initialized reranker score linear from yes/no LM head weights (hidden_size={hidden_size})")
+
+        except Exception as e:
+            logger.warning(f"Failed to initialize score linear from LM head: {e}, using fallback scoring")
+            self.score_linear = None
 
     def rerank(self, query: str, documents: list[str]) -> list[float]:
         """Rerank documents by relevance to query.
 
-        Returns a list of relevance scores for each document.
+        Returns a list of relevance scores (0-1) for each document.
         Higher scores indicate more relevant documents.
         """
         if not documents:
@@ -373,13 +521,13 @@ class RealRerankerModel:
         return scores
 
     def _score_pair(self, query: str, document: str) -> float:
-        """Score a single query-document pair."""
-        # Format as query-document pair for cross-encoder
+        """Score a single query-document pair using official Qwen3-VL-Reranker method."""
         # Truncate document if too long
         max_doc_len = 400
         if len(document) > max_doc_len:
             document = document[:max_doc_len] + "..."
 
+        # Format as query-document pair
         pair_text = f"Query: {query}\n\nDocument: {document}"
 
         try:
@@ -397,16 +545,19 @@ class RealRerankerModel:
             with torch.no_grad():
                 outputs = self.model(**inputs)
 
-                # Use CLS token representation for scoring
-                # Take mean of last hidden state as a simple relevance score
-                cls_embedding = outputs.last_hidden_state[:, 0, :]
+                # Use LAST token hidden state (not CLS/first token)
+                # Per official implementation: last_hidden_state[:, -1]
+                last_token_hidden = outputs.last_hidden_state[:, -1, :]
 
-                # Normalize and take mean as score
-                score = cls_embedding.norm(dim=-1).mean().item()
-
-                # Normalize score to 0-1 range (approximate)
-                # This is heuristic; actual reranker models have specific score heads
-                score = min(1.0, max(0.0, score / 100.0))
+                if self.score_linear is not None:
+                    # Official scoring: linear(last_token) -> sigmoid
+                    raw_score = self.score_linear(last_token_hidden)
+                    score = torch.sigmoid(raw_score).squeeze(-1).item()
+                else:
+                    # Fallback: use L2 norm with better scaling
+                    # This is less accurate but provides reasonable ordering
+                    norm = last_token_hidden.norm(dim=-1).item()
+                    score = min(1.0, max(0.0, norm / 50.0))  # Heuristic scaling
 
             return score
 

pipeline/calculations.py

@@ -7,12 +7,15 @@ Implements deterministic calculations from FDAM v4.0.1:
 - Metals thresholds lookup
 """
 
+import logging
 import math
 from dataclasses import dataclass, field
 from typing import Literal, Optional
 
 from ui.state import SessionState
 
+logger = logging.getLogger(__name__)
+
 
 @dataclass
 class AirFiltrationResult:
@@ -279,6 +282,8 @@ class FDAMCalculator:
         Returns:
             Dictionary with all calculation results
         """
+        logger.debug(f"Running calculations for {len(session.rooms)} rooms")
+
         # Calculate totals from rooms
         total_area = sum(r.length_ft * r.width_ft for r in session.rooms)
         total_volume = sum(
@@ -288,12 +293,14 @@ class FDAMCalculator:
         avg_ceiling = (
             total_volume / total_area if total_area > 0 else 10.0
         )
+        logger.debug(f"Totals: {total_area:.0f} SF, {total_volume:.0f} CF, avg ceiling {avg_ceiling:.1f} ft")
 
         # Air filtration
         air_filtration = self.calculate_air_filtration(
             total_area_sf=total_area,
             avg_ceiling_height_ft=avg_ceiling,
         )
+        logger.debug(f"Air filtration: {air_filtration.units_required} units required")
 
         # Sample density
         sample_density = self.calculate_sample_density(
@@ -301,17 +308,25 @@ class FDAMCalculator:
             has_ceiling_deck=True,  # Assume present
             surface_types_count=3,  # Default assumption
         )
+        logger.debug(f"Sample density: tape={sample_density.tape_lifts_min}-{sample_density.tape_lifts_max}, "
+                    f"wipes={sample_density.surface_wipes_min}-{sample_density.surface_wipes_max}")
 
         # Regulatory flags
         regulatory = self.get_regulatory_flags(
             construction_era=session.project.construction_era or "post-2000",
             facility_classification=session.project.facility_classification or "non-operational",
         )
+        if regulatory.notes:
+            for note in regulatory.notes:
+                logger.debug(f"Regulatory: {note}")
 
         # Metals thresholds
         thresholds = self.get_metals_thresholds(
             facility_classification=session.project.facility_classification or "non-operational",
         )
+        logger.debug(f"Metals thresholds ({thresholds.facility_type}): Pb={thresholds.lead_ug_100cm2} µg/100cm²")
+
+        logger.info(f"Calculations complete: {total_area:.0f} SF, {air_filtration.units_required} air units")
 
         return {
             "total_area_sf": total_area,

pipeline/dispositions.py

@@ -295,6 +295,7 @@ class DispositionEngine:
         Returns:
             List of SurfaceDisposition for each analyzed surface
         """
+        logger.debug(f"Processing {len(vision_results)} vision results")
         dispositions = []
 
         for image_id, result in vision_results.items():
@@ -360,5 +361,12 @@ class DispositionEngine:
                         notes=disp_result.notes,
                     )
                 )
+                logger.debug(f"  {room_name}/{material_type}: {zone}/{condition} -> {disp_result.disposition}")
+
+        # Log disposition summary
+        disp_counts = {}
+        for d in dispositions:
+            disp_counts[d.disposition] = disp_counts.get(d.disposition, 0) + 1
+        logger.info(f"Dispositions generated: {dict(disp_counts)}")
 
         return dispositions

pipeline/generator.py

@@ -4,11 +4,14 @@ Generates Cleaning Specification / Scope of Work documents
 with RAG-enhanced content from the FDAM knowledge base.
 """
 
+import logging
 from dataclasses import dataclass
 from datetime import datetime
 from typing import Optional
 
 from ui.state import SessionState
+
+logger = logging.getLogger(__name__)
 from rag import FDAMRetriever, ChromaVectorStore
 from .calculations import FDAMCalculator, AirFiltrationResult, SampleDensityResult, RegulatoryFlags
 from .dispositions import DispositionEngine, SurfaceDisposition
@@ -74,9 +77,11 @@ class DocumentGenerator:
         Returns:
             GeneratedDocument with markdown content
         """
+        logger.debug("Starting SOW document generation")
         sections = []
 
         # Header
+        logger.debug("Generating section: Header")
         header = self._generate_header(session)
         sections.append(header)
 
@@ -130,12 +135,15 @@ class DocumentGenerator:
 
         # Combine all sections
         markdown = "\n\n---\n\n".join(sections)
+        word_count = len(markdown.split())
+
+        logger.info(f"Document generated: {word_count} words, {len(sections)} sections")
 
         return GeneratedDocument(
             markdown=markdown,
             title=f"SOW - {session.project.project_name}",
             generated_at=datetime.now().isoformat(),
-            word_count=len(markdown.split()),
+            word_count=word_count,
             sections=[
                 "Header", "Project Info", "Scope Summary", "Room Inventory",
                 "Vision Analysis", "Observations", "Dispositions",

pipeline/main.py

@@ -10,6 +10,7 @@ Coordinates the 6-stage processing pipeline:
 """
 
 import logging
+import time
 from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Callable, Optional
@@ -136,10 +137,18 @@ class FDAMPipeline:
         Returns:
             PipelineResult with all outputs
         """
+        pipeline_start = time.time()
         start_time = datetime.now()
         errors = []
         warnings = []
 
+        logger.info("=" * 60)
+        logger.info("FDAM PIPELINE EXECUTION STARTED")
+        logger.info("=" * 60)
+        logger.info(f"Project: {session.project.project_name}")
+        logger.info(f"Facility: {session.project.facility_classification}")
+        logger.info(f"Rooms: {len(session.rooms)}, Images: {len(session.images)}")
+
         def report_progress(stage: int, message: str = ""):
             if progress_callback:
                 progress_callback(
@@ -153,6 +162,8 @@ class FDAMPipeline:
                 )
 
         # Stage 1: Input Validation
+        stage_start = time.time()
+        logger.info("Stage 1/6: Input Validation")
         report_progress(1, "Validating inputs...")
         can_generate, validation_errors = session.can_generate()
 
@@ -165,6 +176,10 @@ class FDAMPipeline:
             if missing_ids:
                 errors.append(f"{len(missing_ids)} image(s) need to be re-uploaded")
 
+            logger.error(f"Validation failed with {len(errors)} error(s)")
+            for err in errors:
+                logger.error(f"  - {err}")
+
             return PipelineResult(
                 success=False,
                 session=session,
@@ -177,7 +192,11 @@ class FDAMPipeline:
                 execution_time_seconds=(datetime.now() - start_time).total_seconds(),
             )
 
+        logger.debug(f"Stage 1 completed in {time.time() - stage_start:.2f}s")
+
         # Stage 2: Vision Analysis
+        stage_start = time.time()
+        logger.info(f"Stage 2/6: Vision Analysis ({len(session.images)} images)")
         report_progress(2, "Analyzing images with AI...")
         model_stack = get_models()
         vision_results = {}
@@ -185,6 +204,7 @@ class FDAMPipeline:
         room_mapping = {}
 
         for i, img_meta in enumerate(session.images):
+            logger.debug(f"Analyzing image {i+1}/{len(session.images)}: {img_meta.filename}")
             img_bytes = image_store.get(img_meta.id)
             if not img_bytes:
                 warnings.append(f"Image {img_meta.filename} not found in store")
@@ -233,17 +253,29 @@ class FDAMPipeline:
                 )
 
             except Exception as e:
+                logger.warning(f"Error analyzing {img_meta.filename}: {e}")
                 warnings.append(f"Error analyzing {img_meta.filename}: {e}")
 
+        logger.info(f"Stage 2 completed in {time.time() - stage_start:.2f}s: "
+                   f"{len(vision_results)} images analyzed")
+
         # Stage 3: RAG Retrieval
+        stage_start = time.time()
+        logger.info("Stage 3/6: RAG Retrieval")
         report_progress(3, "Retrieving FDAM methodology context...")
         # RAG is integrated into disposition engine, just verify connection
         try:
-            _ = self.retriever.retrieve("test connection", top_k=1)
+            test_results = self.retriever.retrieve("test connection", top_k=1)
+            logger.debug(f"RAG connection verified: {len(test_results)} results")
         except Exception as e:
+            logger.warning(f"RAG retrieval unavailable: {e}")
             warnings.append(f"RAG retrieval unavailable: {e}")
 
+        logger.debug(f"Stage 3 completed in {time.time() - stage_start:.2f}s")
+
         # Stage 4: FDAM Logic (Dispositions)
+        stage_start = time.time()
+        logger.info("Stage 4/6: FDAM Logic (Dispositions)")
         report_progress(4, "Applying disposition logic...")
 
         # Convert vision results to dict format for disposition engine
@@ -260,12 +292,21 @@ class FDAMPipeline:
             vision_results=vision_dict,
             room_mapping=room_mapping,
         )
+        logger.info(f"Stage 4 completed in {time.time() - stage_start:.2f}s: "
+                   f"{len(dispositions)} dispositions generated")
 
         # Stage 5: Calculations
+        stage_start = time.time()
+        logger.info("Stage 5/6: Calculations")
         report_progress(5, "Running FDAM calculations...")
         calculations = self.calculator.calculate_from_session(session)
+        logger.debug(f"Calculations: area={calculations.get('total_area_sf', 0):.0f} SF, "
+                    f"volume={calculations.get('total_volume_cf', 0):.0f} CF")
+        logger.debug(f"Stage 5 completed in {time.time() - stage_start:.2f}s")
 
         # Stage 6: Document Generation
+        stage_start = time.time()
+        logger.info("Stage 6/6: Document Generation")
         report_progress(6, "Generating documents...")
         document = self.generator.generate_sow(
             session=session,
@@ -273,6 +314,8 @@ class FDAMPipeline:
             surface_dispositions=dispositions,
             calculations=calculations,
         )
+        logger.info(f"Stage 6 completed in {time.time() - stage_start:.2f}s: "
+                   f"{len(document.sections)} sections generated")
 
         # Update session
         session.has_results = True
@@ -280,6 +323,22 @@ class FDAMPipeline:
         session.update_timestamp()
 
         execution_time = (datetime.now() - start_time).total_seconds()
+        total_time = time.time() - pipeline_start
+
+        # Log final summary
+        logger.info("=" * 60)
+        logger.info("PIPELINE EXECUTION SUMMARY")
+        logger.info("=" * 60)
+        logger.info(f"Success: True")
+        logger.info(f"Total execution time: {total_time:.2f}s")
+        logger.info(f"Images analyzed: {len(vision_results)}")
+        logger.info(f"Dispositions generated: {len(dispositions)}")
+        logger.info(f"Document sections: {len(document.sections)}")
+        logger.info(f"Warnings: {len(warnings)}")
+        if warnings:
+            for w in warnings:
+                logger.warning(f"  - {w}")
+        logger.info("=" * 60)
 
         return PipelineResult(
             success=True,

rag/retriever.py

@@ -6,12 +6,16 @@ Implements tiered retrieval:
 3. Optional reranking for production
 """
 
+import logging
+import time
 from typing import Optional
 from dataclasses import dataclass
 
 from config.settings import settings
 from .vectorstore import ChromaVectorStore
 
+logger = logging.getLogger(__name__)
+
 
 @dataclass
 class RetrievalResult:
@@ -99,7 +103,7 @@ class RealReranker:
         from transformers import AutoModelForSequenceClassification, AutoTokenizer
 
         model_name = "Qwen/Qwen3-VL-Reranker-8B"
-        print(f"Loading reranker model: {model_name}")
+        logger.info(f"Loading reranker model: {model_name}")
 
         self.tokenizer = AutoTokenizer.from_pretrained(
             model_name,
@@ -212,6 +216,9 @@ class FDAMRetriever:
         Returns:
             List of RetrievalResult objects, sorted by final_score descending
         """
+        start_time = time.time()
+        logger.debug(f"RAG retrieve: query='{query[:50]}...' top_k={top_k}")
+
         # Build metadata filter
         where_filter = None
         if category_filter or priority_filter:
@@ -232,6 +239,7 @@ class FDAMRetriever:
         )
 
         if not raw_results:
+            logger.debug("RAG retrieve: no results found")
             return []
 
         # Convert to RetrievalResult objects with priority weighting
@@ -267,6 +275,7 @@ class FDAMRetriever:
 
         # Apply reranking if enabled
         if self.use_reranking and results:
+            logger.debug(f"Applying reranking to {len(results)} results")
             documents = [r.text for r in results]
             rerank_scores = self.reranker.rerank(query, documents)
 
@@ -278,7 +287,19 @@ class FDAMRetriever:
 
         # Sort by final score (descending) and take top_k
         results.sort(key=lambda x: x.final_score, reverse=True)
-        return results[:top_k]
+        final_results = results[:top_k]
+
+        # Log retrieval summary
+        elapsed = time.time() - start_time
+        if final_results:
+            top_score = final_results[0].final_score
+            top_source = final_results[0].source
+            logger.debug(f"RAG retrieve: {len(final_results)} results in {elapsed:.3f}s, "
+                        f"top_score={top_score:.3f}, top_source={top_source}")
+        else:
+            logger.debug(f"RAG retrieve: 0 results in {elapsed:.3f}s")
+
+        return final_results
 
     def retrieve_for_context(
         self,

rag/vectorstore.py

@@ -5,6 +5,7 @@ Uses mock embeddings when MOCK_MODELS=true for local development.
 """
 
 import hashlib
+import logging
 from typing import Optional
 from pathlib import Path
 
@@ -14,15 +15,17 @@ from chromadb.config import Settings
 from config.settings import settings
 from .chunker import Chunk
 
+logger = logging.getLogger(__name__)
+
 
 class MockEmbeddingFunction:
     """Mock embedding function for local development.
 
     Generates deterministic pseudo-embeddings based on text hash.
-    Produces 384-dimensional vectors (matches common embedding models).
+    Produces 4096-dimensional vectors (matches Qwen3-VL-Embedding-8B).
     """
 
-    EMBEDDING_DIM = 384
+    EMBEDDING_DIM = 4096  # Per Qwen3-VL-Embedding-8B hidden_size
 
     def __call__(self, input: list[str]) -> list[list[float]]:
         """Generate mock embeddings for a list of texts."""
@@ -32,8 +35,10 @@ class MockEmbeddingFunction:
         """Generate a deterministic pseudo-embedding from text.
 
         Uses SHA-256 hash expanded to fill embedding dimensions.
-        Not semantically meaningful but provides consistent behavior.
+        L2 normalized to match real model output.
         """
+        import math
+
         # Hash the text
         text_hash = hashlib.sha256(text.encode("utf-8")).digest()
 
@@ -45,16 +50,24 @@ class MockEmbeddingFunction:
             normalized = (byte_val / 127.5) - 1.0
             embedding.append(normalized)
 
+        # L2 normalize (matching real model behavior)
+        norm = math.sqrt(sum(x * x for x in embedding))
+        if norm > 0:
+            embedding = [x / norm for x in embedding]
+
         return embedding
 
 
 class RealEmbeddingFunction:
     """Real embedding function using Qwen3-VL-Embedding-8B.
 
+    Uses last-token pooling per official Qwen3-VL-Embedding implementation.
     Loaded on-demand when MOCK_MODELS=false.
+
+    Reference: https://github.com/QwenLM/Qwen3-VL-Embedding
     """
 
-    EMBEDDING_DIM = 4096  # Qwen embedding dimension
+    EMBEDDING_DIM = 4096  # Per Qwen3-VL-Embedding-8B hidden_size
 
     def __init__(self):
         self.model = None
@@ -69,7 +82,7 @@ class RealEmbeddingFunction:
         from transformers import AutoModel, AutoTokenizer
 
         model_name = "Qwen/Qwen3-VL-Embedding-8B"
-        print(f"Loading embedding model: {model_name}")
+        logger.info(f"Loading embedding model: {model_name}")
 
         self.tokenizer = AutoTokenizer.from_pretrained(
             model_name,
@@ -83,8 +96,23 @@ class RealEmbeddingFunction:
         )
         self.model.eval()
 
+    @staticmethod
+    def _pooling_last(hidden_state, attention_mask):
+        """Extract the last valid token's hidden state.
+
+        Official pooling method from Qwen3-VL-Embedding.
+        Finds the last position where attention_mask == 1 and extracts that token.
+        """
+        import torch
+
+        flipped_tensor = attention_mask.flip(dims=[1])
+        last_one_positions = flipped_tensor.argmax(dim=1)
+        col = attention_mask.shape[1] - last_one_positions - 1
+        row = torch.arange(hidden_state.shape[0], device=hidden_state.device)
+        return hidden_state[row, col]
+
     def __call__(self, input: list[str]) -> list[list[float]]:
-        """Generate embeddings for a list of texts."""
+        """Generate embeddings for a list of texts using last-token pooling."""
         self._load_model()
 
         import torch
@@ -102,9 +130,18 @@ class RealEmbeddingFunction:
                 inputs = {k: v.to(self.model.device) for k, v in inputs.items()}
 
                 outputs = self.model(**inputs)
-                # Use mean pooling over sequence
-                embedding = outputs.last_hidden_state.mean(dim=1).squeeze()
-                embeddings.append(embedding.cpu().float().tolist())
+
+                # Use last-token pooling (official Qwen3-VL-Embedding method)
+                attention_mask = inputs.get("attention_mask")
+                if attention_mask is not None:
+                    embedding = self._pooling_last(outputs.last_hidden_state, attention_mask)
+                else:
+                    # Fallback: use last token if no attention mask
+                    embedding = outputs.last_hidden_state[:, -1, :]
+
+                # L2 normalize (per official implementation)
+                embedding = torch.nn.functional.normalize(embedding, p=2, dim=-1)
+                embeddings.append(embedding.squeeze().cpu().float().tolist())
 
         return embeddings
 
@@ -140,23 +177,28 @@ class ChromaVectorStore:
         if persist_directory:
             persist_path = Path(persist_directory)
             persist_path.mkdir(parents=True, exist_ok=True)
+            logger.debug(f"ChromaDB: using persistent storage at {persist_path}")
             self.client = chromadb.PersistentClient(
                 path=str(persist_path),
                 settings=Settings(anonymized_telemetry=False),
             )
         else:
+            logger.debug("ChromaDB: using in-memory storage")
             self.client = chromadb.Client(
                 settings=Settings(anonymized_telemetry=False),
             )
 
         # Set up embedding function
         self.embedding_function = embedding_function or get_embedding_function()
+        embed_type = "mock" if settings.mock_models else "real"
+        logger.debug(f"ChromaDB: using {embed_type} embeddings")
 
         # Get or create collection
         self.collection = self.client.get_or_create_collection(
             name=self.COLLECTION_NAME,
             metadata={"hnsw:space": "cosine"},
         )
+        logger.info(f"ChromaDB collection '{self.COLLECTION_NAME}' ready: {self.collection.count()} chunks")
 
     def add_chunks(self, chunks: list[Chunk]) -> int:
         """Add chunks to the vector store.

requirements-dev.txt

@@ -0,0 +1,11 @@
+# Development dependencies for FDAM AI Pipeline
+
+# Testing
+pytest
+pytest-asyncio
+pytest-playwright
+playwright
+
+# Code quality
+ruff
+mypy

requirements.txt

@@ -6,7 +6,7 @@ qwen-vl-utils>=0.0.14
 torchvision
 
 # UI
-gradio
+gradio>=6.0.0,<7.0.0
 
 # RAG/Vector Store
 chromadb

tests/conftest.py

@@ -0,0 +1,68 @@
+"""Pytest fixtures for Playwright E2E tests."""
+
+import pytest
+import subprocess
+import time
+import os
+import urllib.request
+import urllib.error
+from playwright.sync_api import sync_playwright, Browser, Page
+
+GRADIO_PORT = 7860
+GRADIO_URL = f"http://localhost:{GRADIO_PORT}"
+
+
+@pytest.fixture(scope="session")
+def gradio_server():
+    """Start Gradio server for E2E tests."""
+    env = os.environ.copy()
+    env["MOCK_MODELS"] = "true"
+
+    # Use venv python for consistent environment
+    python_cmd = ".venv/bin/python" if os.path.exists(".venv/bin/python") else "python3"
+
+    # Don't capture output - let it go to console for debugging
+    process = subprocess.Popen(
+        [python_cmd, "app.py"],
+        env=env,
+    )
+
+    # Wait for server to start with health check
+    max_retries = 30
+    for i in range(max_retries):
+        try:
+            urllib.request.urlopen(GRADIO_URL, timeout=1)
+            break
+        except (urllib.error.URLError, ConnectionRefusedError):
+            time.sleep(1)
+    else:
+        process.terminate()
+        raise RuntimeError("Gradio server failed to start")
+
+    yield GRADIO_URL
+
+    process.terminate()
+    process.wait()
+
+
+@pytest.fixture(scope="session")
+def browser_instance():
+    """Create browser instance for the session."""
+    # Use headless mode for WSL/CI environments, headed for local debugging
+    headless = os.environ.get("PLAYWRIGHT_HEADLESS", "true").lower() == "true"
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=headless)
+        yield browser
+        browser.close()
+
+
+@pytest.fixture
+def page(browser_instance, gradio_server):
+    """Create new page for each test."""
+    context = browser_instance.new_context()
+    page = context.new_page()
+    page.goto(gradio_server)
+    page.wait_for_selector("#sample_dropdown", timeout=10000)
+    yield page
+    context.close()

tests/test_e2e_forms.py

@@ -0,0 +1,307 @@
+"""E2E tests for form interactions."""
+
+import pytest
+from playwright.sync_api import Page, expect
+
+
+def select_sample(page: Page, sample_text: str):
+    """Helper to select a sample from the dropdown."""
+    page.locator("#sample_dropdown input[role='listbox']").click()
+    page.wait_for_timeout(300)
+    page.locator(f"[role='option']:has-text('{sample_text}')").click()
+    # Wait for form to be populated - check that project_name has a value
+    # (status gets cleared when dropdown resets, so we can't rely on it)
+    page.wait_for_function(
+        """() => {
+            const textarea = document.querySelector('#project_name textarea');
+            return textarea && textarea.value && textarea.value.includes('Sample:');
+        }""",
+        timeout=30000
+    )
+
+
+class TestProjectForm:
+    """Test Tab 1 project form."""
+
+    def test_zip_validation_invalid(self, page: Page):
+        """Test ZIP code format validation with invalid input."""
+        # zip_code uses input (max_lines=1), not textarea
+        zip_input = page.locator("#zip_code input")
+
+        # Invalid ZIP (too short)
+        zip_input.fill("123")
+        zip_input.blur()
+        page.wait_for_timeout(300)
+
+        # Should show invalid message (✗ indicates error)
+        expect(page.locator("#zip_validation")).to_contain_text("✗")
+
+    def test_zip_validation_valid(self, page: Page):
+        """Test ZIP code format validation with valid input."""
+        # zip_code uses input (max_lines=1), not textarea
+        zip_input = page.locator("#zip_code input")
+
+        # Valid 5-digit ZIP
+        zip_input.fill("12345")
+        zip_input.blur()
+        page.wait_for_timeout(300)
+
+        # Should show valid checkmark
+        expect(page.locator("#zip_validation")).to_contain_text("Valid")
+
+    def test_zip_validation_valid_plus4(self, page: Page):
+        """Test ZIP+4 format validation."""
+        # zip_code uses input (max_lines=1), not textarea
+        zip_input = page.locator("#zip_code input")
+
+        # Valid ZIP+4
+        zip_input.fill("12345-6789")
+        zip_input.blur()
+        page.wait_for_timeout(300)
+
+        expect(page.locator("#zip_validation")).to_contain_text("Valid")
+
+    def test_facility_classification_radio(self, page: Page):
+        """Test facility classification radio buttons."""
+        # Use specific selector by value attribute to avoid substring matching
+        facility_group = page.locator("#facility_classification")
+
+        # Click Operational radio (use value attribute for exact match)
+        facility_group.locator("input[value='Operational']").click()
+        page.wait_for_timeout(200)
+
+        # Verify it's selected
+        expect(facility_group.locator("input[value='Operational']")).to_be_checked()
+
+        # Click Non-Operational
+        facility_group.locator("input[value='Non-Operational']").click()
+        page.wait_for_timeout(200)
+
+        expect(facility_group.locator("input[value='Non-Operational']")).to_be_checked()
+        expect(facility_group.locator("input[value='Operational']")).not_to_be_checked()
+
+    def test_construction_era_radio(self, page: Page):
+        """Test construction era radio buttons."""
+        page.get_by_label("Pre-1980").click()
+        expect(page.get_by_label("Pre-1980")).to_be_checked()
+
+        page.get_by_label("Post-2000").click()
+        expect(page.get_by_label("Post-2000")).to_be_checked()
+
+
+class TestRoomsForm:
+    """Test Tab 2 rooms form."""
+
+    def test_room_exists_after_sample_load(self, page: Page):
+        """Test room is created when sample is loaded."""
+        select_sample(page, "Bar & Dining Area")
+
+        # Go to Rooms tab
+        page.locator("#tab-rooms-button").click()
+        page.wait_for_timeout(500)
+
+        # Room should exist in table
+        expect(page.locator("#rooms_table")).to_contain_text("Bar & Dining Area")
+
+    def test_custom_height_visibility_toggle(self, page: Page):
+        """Test custom height field appears when 'Custom' selected."""
+        page.locator("#tab-rooms-button").click()
+        page.wait_for_timeout(300)
+
+        # Select a standard height first - click dropdown input to open
+        dropdown_input = page.locator("#room_height_preset input[role='listbox']")
+        dropdown_input.click()
+        page.wait_for_timeout(300)
+        page.locator("[role='option']:has-text('10 ft')").click()
+        page.wait_for_timeout(300)
+
+        # Custom height should be hidden
+        expect(page.locator("#room_height_custom")).not_to_be_visible()
+
+        # Select Custom - click dropdown input to open
+        dropdown_input.click()
+        page.wait_for_timeout(300)
+        page.locator("[role='option']:has-text('Custom')").click()
+        page.wait_for_timeout(300)
+
+        # Custom height should appear
+        expect(page.locator("#room_height_custom")).to_be_visible()
+
+    def test_room_validation_requires_name(self, page: Page):
+        """Test that room name is required."""
+        page.locator("#tab-rooms-button").click()
+        page.wait_for_timeout(300)
+
+        # Try to add room with empty name
+        page.locator("#room_length input").fill("20")
+        page.locator("#room_width input").fill("15")
+
+        # Select height from dropdown - click the input to open
+        page.locator("#room_height_preset input[role='listbox']").click()
+        page.wait_for_timeout(300)
+        page.locator("[role='option']:has-text('10 ft')").click()
+        page.wait_for_timeout(300)
+
+        page.get_by_role("button", name="Add Room").click()
+        page.wait_for_timeout(300)
+
+        # Should show validation error about room name
+        expect(page.locator("#tab2_validation")).to_contain_text("Room name")
+
+
+class TestImagesForm:
+    """Test Tab 3 images form."""
+
+    def test_images_gallery_shows_sample_images(self, page: Page):
+        """Test gallery displays images after sample load."""
+        select_sample(page, "Bar & Dining Area")
+
+        # Go to Images tab
+        page.locator("#tab-images-button").click()
+        page.wait_for_timeout(500)
+
+        # Gallery should have images
+        gallery = page.locator("#images_gallery")
+        expect(gallery).to_be_visible()
+
+        # Should have 3 images
+        images = gallery.locator("img")
+        expect(images).to_have_count(3)
+
+    def test_room_dropdown_populated(self, page: Page):
+        """Test room dropdown is populated after sample load."""
+        select_sample(page, "Bar & Dining Area")
+
+        # Go to Images tab
+        page.locator("#tab-images-button").click()
+        page.wait_for_timeout(500)
+
+        # Click dropdown input to open it and verify room is in options
+        page.locator("#room_select input[role='listbox']").click()
+        page.wait_for_timeout(300)
+
+        # Room should appear in dropdown options
+        expect(page.locator("[role='option']:has-text('Bar & Dining Area')")).to_be_visible()
+
+
+class TestObservationsForm:
+    """Test Tab 4 observations form."""
+
+    def test_checkbox_interactions(self, page: Page):
+        """Test observation checkboxes can be toggled."""
+        page.locator("#tab-observations-button").click()
+        page.wait_for_timeout(300)
+
+        # Check smoke odor
+        smoke_checkbox = page.locator("#smoke_odor input[type='checkbox']")
+        smoke_checkbox.check()
+        expect(smoke_checkbox).to_be_checked()
+
+        # Uncheck
+        smoke_checkbox.uncheck()
+        expect(smoke_checkbox).not_to_be_checked()
+
+    def test_odor_intensity_radio(self, page: Page):
+        """Test odor intensity radio buttons."""
+        page.locator("#tab-observations-button").click()
+        page.wait_for_timeout(300)
+
+        # Use specific selector within odor_intensity group to avoid matching char_density
+        odor_group = page.locator("#odor_intensity")
+
+        odor_group.get_by_label("Strong").click()
+        expect(odor_group.get_by_label("Strong")).to_be_checked()
+
+        odor_group.get_by_label("Moderate").click()
+        expect(odor_group.get_by_label("Moderate")).to_be_checked()
+        expect(odor_group.get_by_label("Strong")).not_to_be_checked()
+
+    def test_observations_persist_after_sample_load(self, page: Page):
+        """Test observations are populated from sample."""
+        select_sample(page, "Factory Area")
+
+        # Go to Observations tab
+        page.locator("#tab-observations-button").click()
+        page.wait_for_timeout(500)
+
+        # Factory sample has smoke odor = True
+        smoke_checkbox = page.locator("#smoke_odor input[type='checkbox']")
+        expect(smoke_checkbox).to_be_checked()
+
+
+class TestDebugSelectors:
+    """Debug tests to verify Gradio HTML structure."""
+
+    def test_capture_dropdown_and_sample_load(self, page: Page):
+        """Capture dropdown HTML and test full sample load.
+
+        Run with: pytest tests/test_e2e_forms.py::TestDebugSelectors::test_capture_dropdown_and_sample_load -v -s
+        """
+        page.wait_for_timeout(2000)
+
+        # Click dropdown to open
+        print("\n--- Opening dropdown ---")
+        dropdown_input = page.locator("#sample_dropdown input[role='listbox']")
+        dropdown_input.click()
+        page.wait_for_timeout(500)
+
+        # Click the Bar & Dining option
+        print("Clicking Bar & Dining option...")
+        page.locator("[role='option']:has-text('Bar & Dining Area')").click()
+        page.wait_for_timeout(2000)  # Wait for sample to load
+
+        # Check sample_status HTML
+        print("\n--- DEBUG: Status HTML ---")
+        try:
+            status_html = page.locator("#sample_status").evaluate("el => el.outerHTML")
+            print("Sample status HTML:", status_html[:500])
+        except Exception as e:
+            print(f"Error getting status: {e}")
+
+        # Check if project name was populated
+        print("\n--- DEBUG: Project Name ---")
+        try:
+            # Get the full HTML of project_name element
+            pn_html = page.locator("#project_name").evaluate("el => el.outerHTML")
+            print(f"Project name HTML:\n{pn_html[:800]}")
+
+            # Try different selectors
+            print("\nTrying different selectors:")
+            print(f"  #project_name input count: {page.locator('#project_name input').count()}")
+            print(f"  #project_name textarea count: {page.locator('#project_name textarea').count()}")
+            print(f"  #project_name [data-testid] count: {page.locator('#project_name [data-testid]').count()}")
+
+            # Check if there's any input/textarea in the document
+            all_inputs = page.locator("input[type='text']").count()
+            print(f"  Total text inputs on page: {all_inputs}")
+
+        except Exception as e:
+            print(f"Error: {e}")
+
+        print("--- END DEBUG ---\n")
+
+    def test_capture_full_page_structure(self, page: Page):
+        """Capture key element structures.
+
+        Run with: pytest tests/test_e2e_forms.py::TestDebugSelectors::test_capture_full_page_structure -v -s
+        """
+        page.wait_for_timeout(2000)
+
+        print("\n--- DEBUG: Page Structure ---")
+
+        # Capture project name structure
+        project_name = page.locator("#project_name")
+        print("Project name HTML:", project_name.evaluate("el => el.outerHTML")[:500])
+
+        # Capture tab button structure
+        try:
+            tab_btn = page.locator("#tab-project-button")
+            print("Tab button exists:", tab_btn.count() > 0)
+        except Exception as e:
+            print(f"Tab button error: {e}")
+
+        # Try to find tab by different selectors
+        tabs = page.locator('[role="tab"]').all()
+        print(f"Found {len(tabs)} tabs with role=tab")
+
+        print("--- END DEBUG ---\n")

tests/test_e2e_samples.py

@@ -0,0 +1,148 @@
+"""E2E tests for sample scenario loading."""
+
+import pytest
+from playwright.sync_api import Page, expect
+
+
+def select_sample(page: Page, sample_text: str):
+    """Helper to select a sample from the dropdown.
+
+    Args:
+        page: Playwright page
+        sample_text: Text of the sample option to select (e.g., "Bar & Dining Area")
+    """
+    # Gradio dropdowns use input[role='listbox'] - click to open
+    page.locator("#sample_dropdown input[role='listbox']").click()
+    page.wait_for_timeout(300)  # Wait for dropdown to open
+
+    # Click the option with matching text
+    page.locator(f"[role='option']:has-text('{sample_text}')").click()
+
+    # Wait for form to be populated - check that project_name has a value
+    # Gradio 6.x uses textarea for textboxes
+    page.wait_for_function(
+        """() => {
+            const textarea = document.querySelector('#project_name textarea');
+            return textarea && textarea.value && textarea.value.includes('Sample:');
+        }""",
+        timeout=30000
+    )
+
+
+class TestSampleLoading:
+    """Test loading sample scenarios via dropdown."""
+
+    def test_bar_dining_loads_correctly(self, page: Page):
+        """Verify Bar & Dining sample loads all data."""
+        select_sample(page, "Bar & Dining Area")
+
+        # Verify Tab 1 populated
+        expect(page.locator("#project_name textarea")).to_have_value(
+            "Sample: Bar & Dining Fire Assessment"
+        )
+        expect(page.locator("#city textarea")).to_have_value("Springfield")
+
+    def test_bar_area_loads_correctly(self, page: Page):
+        """Verify Bar Area sample loads all data."""
+        select_sample(page, "Bar Area")
+
+        expect(page.locator("#project_name textarea")).to_have_value(
+            "Sample: Bar Area Fire Assessment"
+        )
+
+    def test_kitchen_loads_6_images(self, page: Page):
+        """Verify Kitchen sample loads 6 images."""
+        select_sample(page, "Kitchen")
+
+        # Navigate to Images tab
+        page.locator("#tab-images-button").click()
+
+        # Wait for gallery to populate - may take time for images to render
+        page.wait_for_function(
+            """() => {
+                const gallery = document.querySelector('#images_gallery');
+                const images = gallery ? gallery.querySelectorAll('img') : [];
+                return images.length > 0;
+            }""",
+            timeout=10000
+        )
+
+        # Verify image count in gallery
+        gallery = page.locator("#images_gallery")
+        images = gallery.locator("img")
+        expect(images).to_have_count(6)
+
+    def test_factory_loads_1_image(self, page: Page):
+        """Verify Factory sample loads 1 image."""
+        select_sample(page, "Factory Area")
+
+        # Navigate to Images tab
+        page.locator("#tab-images-button").click()
+        page.wait_for_timeout(500)
+
+        # Verify image count
+        gallery = page.locator("#images_gallery")
+        images = gallery.locator("img")
+        expect(images).to_have_count(1)
+
+    def test_factory_operational_facility(self, page: Page):
+        """Verify Factory sample has operational classification."""
+        select_sample(page, "Factory Area")
+
+        # Check facility classification shows Operational
+        expect(page.locator("#facility_classification")).to_contain_text("Operational")
+
+    def test_sample_dropdown_resets_after_selection(self, page: Page):
+        """Verify dropdown resets to placeholder after loading sample."""
+        select_sample(page, "Bar & Dining Area")
+
+        # Dropdown should reset to placeholder text
+        dropdown_input = page.locator("#sample_dropdown input[role='listbox']")
+        expect(dropdown_input).to_have_value("Select a sample scenario...")
+
+
+class TestSampleRoomData:
+    """Test that sample rooms load correct data."""
+
+    def test_bar_dining_room_dimensions(self, page: Page):
+        """Verify Bar & Dining room has correct dimensions."""
+        select_sample(page, "Bar & Dining Area")
+
+        # Navigate to Rooms tab
+        page.locator("#tab-rooms-button").click()
+        page.wait_for_timeout(500)
+
+        # Verify room table shows the room
+        expect(page.locator("#rooms_table")).to_contain_text("Bar & Dining Area")
+        expect(page.locator("#rooms_table")).to_contain_text("40")  # Length
+        expect(page.locator("#rooms_table")).to_contain_text("30")  # Width
+
+    def test_kitchen_room_dimensions(self, page: Page):
+        """Verify Kitchen room has correct dimensions."""
+        select_sample(page, "Kitchen")
+
+        # Navigate to Rooms tab
+        page.locator("#tab-rooms-button").click()
+        page.wait_for_timeout(500)
+
+        # Verify room name
+        expect(page.locator("#rooms_table")).to_contain_text("Commercial Kitchen")
+
+
+class TestSampleObservations:
+    """Test that sample observations load correctly."""
+
+    def test_bar_dining_observations(self, page: Page):
+        """Verify Bar & Dining sample loads observations."""
+        select_sample(page, "Bar & Dining Area")
+
+        # Navigate to Observations tab
+        page.locator("#tab-observations-button").click()
+        page.wait_for_timeout(500)
+
+        # Verify smoke odor checkbox is checked
+        smoke_checkbox = page.locator("#smoke_odor input[type='checkbox']")
+        expect(smoke_checkbox).to_be_checked()
+
+        # Verify odor intensity shows Strong
+        expect(page.locator("#odor_intensity")).to_contain_text("Strong")

tests/test_e2e_workflow.py

@@ -0,0 +1,150 @@
+"""E2E tests for complete assessment workflow."""
+
+import pytest
+from playwright.sync_api import Page, expect
+
+
+def select_sample(page: Page, sample_text: str):
+    """Helper to select a sample from the dropdown."""
+    page.locator("#sample_dropdown input[role='listbox']").click()
+    page.wait_for_timeout(300)
+    page.locator(f"[role='option']:has-text('{sample_text}')").click()
+    # Wait for form to be populated - check that project_name has a value
+    # (status gets cleared when dropdown resets, so we can't rely on it)
+    page.wait_for_function(
+        """() => {
+            const textarea = document.querySelector('#project_name textarea');
+            return textarea && textarea.value && textarea.value.includes('Sample:');
+        }""",
+        timeout=30000
+    )
+
+
+class TestFullWorkflow:
+    """Test complete assessment generation workflow."""
+
+    def test_generate_with_sample(self, page: Page):
+        """Test full generation workflow with sample data."""
+        select_sample(page, "Bar & Dining Area")
+
+        # Navigate to Results tab
+        page.locator("#tab-results-button").click()
+        page.wait_for_timeout(500)
+
+        # Check preflight shows ready
+        expect(page.locator("#preflight_status")).to_contain_text("Ready to Generate")
+
+        # Click generate
+        page.locator("#generate_btn").click()
+
+        # Wait for generation - check for "Complete" in the status textbox input
+        # The processing_status is a Textbox, so we need to check the input value
+        page.wait_for_function(
+            """() => {
+                const input = document.querySelector('#processing_status input, #processing_status textarea');
+                return input && input.value && input.value.includes('Complete');
+            }""",
+            timeout=120000
+        )
+
+        # Verify outputs are visible
+        expect(page.locator("#sow_output")).to_be_visible()
+        expect(page.locator("#download_md")).to_be_visible()
+
+    def test_preflight_check_incomplete_session(self, page: Page):
+        """Test preflight shows errors for incomplete session."""
+        # Don't load sample - go directly to Results
+        page.locator("#tab-results-button").click()
+        page.wait_for_timeout(500)
+
+        # Should show cannot generate message
+        expect(page.locator("#preflight_status")).to_contain_text("Cannot Generate")
+
+
+class TestTabNavigation:
+    """Test tab navigation and validation."""
+
+    def test_click_tab_navigation(self, page: Page):
+        """Test clicking tab buttons navigates correctly."""
+        # Start on Tab 1 (Project)
+        expect(page.locator("#project_name")).to_be_visible()
+
+        # Click Tab 2 (Rooms)
+        page.locator("#tab-rooms-button").click()
+        page.wait_for_timeout(300)
+        expect(page.locator("#room_name")).to_be_visible()
+
+        # Click Tab 3 (Images)
+        page.locator("#tab-images-button").click()
+        page.wait_for_timeout(300)
+        expect(page.locator("#image_upload")).to_be_visible()
+
+        # Click Tab 4 (Observations)
+        page.locator("#tab-observations-button").click()
+        page.wait_for_timeout(300)
+        expect(page.locator("#smoke_odor")).to_be_visible()
+
+        # Click Tab 5 (Results)
+        page.locator("#tab-results-button").click()
+        page.wait_for_timeout(300)
+        expect(page.locator("#generate_btn")).to_be_visible()
+
+    def test_keyboard_shortcuts(self, page: Page):
+        """Test Ctrl+1-5 keyboard shortcuts."""
+        # Start on Tab 1
+        expect(page.locator("#project_name")).to_be_visible()
+
+        # Ctrl+3 -> Images tab
+        page.keyboard.press("Control+3")
+        page.wait_for_timeout(300)
+        expect(page.locator("#image_upload")).to_be_visible()
+
+        # Ctrl+5 -> Results tab
+        page.keyboard.press("Control+5")
+        page.wait_for_timeout(300)
+        expect(page.locator("#generate_btn")).to_be_visible()
+
+        # Ctrl+1 -> Back to Project
+        page.keyboard.press("Control+1")
+        page.wait_for_timeout(300)
+        expect(page.locator("#project_name")).to_be_visible()
+
+    def test_tab1_validation_prevents_navigation(self, page: Page):
+        """Test that incomplete Tab 1 shows validation errors."""
+        # Try to validate empty Tab 1
+        page.get_by_role("button", name="Validate & Continue to Rooms").click()
+        page.wait_for_timeout(500)
+
+        # Should show validation error message with required field errors
+        validation = page.locator("#tab1_validation")
+        expect(validation).to_contain_text("Please fix the following")
+
+
+class TestBackNavigation:
+    """Test back button navigation."""
+
+    def test_back_from_rooms_to_project(self, page: Page):
+        """Test back button from Rooms tab."""
+        # Go to Rooms tab
+        page.locator("#tab-rooms-button").click()
+        page.wait_for_timeout(300)
+
+        # Click back
+        page.get_by_role("button", name="Back to Project").click()
+        page.wait_for_timeout(300)
+
+        # Should be on Project tab
+        expect(page.locator("#project_name")).to_be_visible()
+
+    def test_back_from_images_to_rooms(self, page: Page):
+        """Test back button from Images tab."""
+        # Go to Images tab
+        page.locator("#tab-images-button").click()
+        page.wait_for_timeout(300)
+
+        # Click back
+        page.get_by_role("button", name="Back to Rooms").click()
+        page.wait_for_timeout(300)
+
+        # Should be on Rooms tab
+        expect(page.locator("#room_name")).to_be_visible()

tests/test_samples.py

@@ -0,0 +1,296 @@
+"""Tests for sample room data module."""
+
+import pytest
+from pathlib import Path
+
+from ui.samples import (
+    SAMPLE_SCENARIOS,
+    SAMPLE_SCENARIOS_BY_ID,
+    SAMPLE_IMAGES_DIR,
+    get_sample_choices,
+    load_sample,
+    load_sample_images,
+    get_scenario_by_id,
+)
+from ui.state import SessionState
+from ui.components import image_store
+
+
+class TestSampleScenarios:
+    """Test sample scenario definitions."""
+
+    def test_four_scenarios_defined(self):
+        """Verify exactly 4 sample scenarios are defined."""
+        assert len(SAMPLE_SCENARIOS) == 4
+
+    def test_scenario_ids_unique(self):
+        """Verify all scenario IDs are unique."""
+        ids = [s.id for s in SAMPLE_SCENARIOS]
+        assert len(ids) == len(set(ids))
+
+    def test_scenario_ids_expected(self):
+        """Verify expected scenario IDs exist."""
+        expected_ids = {"bar_dining", "bar_area", "kitchen", "factory"}
+        actual_ids = set(SAMPLE_SCENARIOS_BY_ID.keys())
+        assert actual_ids == expected_ids
+
+    def test_all_scenarios_have_required_fields(self):
+        """Verify all scenarios have required data fields."""
+        for scenario in SAMPLE_SCENARIOS:
+            # Basic fields
+            assert scenario.id
+            assert scenario.name
+            assert scenario.description
+            assert scenario.image_files
+
+            # Project data required fields
+            assert "project_name" in scenario.project_data
+            assert "address" in scenario.project_data
+            assert "city" in scenario.project_data
+            assert "state" in scenario.project_data
+            assert "zip_code" in scenario.project_data
+            assert "client_name" in scenario.project_data
+            assert "fire_date" in scenario.project_data
+            assert "assessment_date" in scenario.project_data
+            assert "facility_classification" in scenario.project_data
+            assert "construction_era" in scenario.project_data
+            assert "assessor_name" in scenario.project_data
+
+            # Room data required fields
+            assert "name" in scenario.room_data
+            assert "length_ft" in scenario.room_data
+            assert "width_ft" in scenario.room_data
+            assert "ceiling_height_ft" in scenario.room_data
+
+            # Observations should have smoke/fire odor at minimum
+            assert "smoke_fire_odor" in scenario.observations_data
+
+
+class TestSampleImages:
+    """Test sample image file existence."""
+
+    def test_sample_images_dir_exists(self):
+        """Verify sample images directory exists."""
+        assert SAMPLE_IMAGES_DIR.exists()
+        assert SAMPLE_IMAGES_DIR.is_dir()
+
+    def test_all_referenced_images_exist(self):
+        """Verify all images referenced in scenarios exist on disk."""
+        missing_files = []
+        for scenario in SAMPLE_SCENARIOS:
+            for filename in scenario.image_files:
+                filepath = SAMPLE_IMAGES_DIR / filename
+                if not filepath.exists():
+                    missing_files.append(f"{scenario.id}: {filename}")
+
+        assert not missing_files, f"Missing image files: {missing_files}"
+
+    def test_bar_dining_has_3_images(self):
+        """Verify Bar & Dining scenario has 3 images."""
+        scenario = SAMPLE_SCENARIOS_BY_ID["bar_dining"]
+        assert len(scenario.image_files) == 3
+
+    def test_bar_area_has_3_images(self):
+        """Verify Bar Area scenario has 3 images."""
+        scenario = SAMPLE_SCENARIOS_BY_ID["bar_area"]
+        assert len(scenario.image_files) == 3
+
+    def test_kitchen_has_6_images(self):
+        """Verify Kitchen scenario has 6 images."""
+        scenario = SAMPLE_SCENARIOS_BY_ID["kitchen"]
+        assert len(scenario.image_files) == 6
+
+    def test_factory_has_1_image(self):
+        """Verify Factory scenario has 1 image."""
+        scenario = SAMPLE_SCENARIOS_BY_ID["factory"]
+        assert len(scenario.image_files) == 1
+
+
+class TestGetSampleChoices:
+    """Test get_sample_choices function."""
+
+    def test_returns_list_of_tuples(self):
+        """Verify function returns list of (label, value) tuples."""
+        choices = get_sample_choices()
+        assert isinstance(choices, list)
+        for choice in choices:
+            assert isinstance(choice, tuple)
+            assert len(choice) == 2
+
+    def test_first_choice_is_placeholder(self):
+        """Verify first choice is the placeholder."""
+        choices = get_sample_choices()
+        label, value = choices[0]
+        assert "Select" in label
+        assert value == ""
+
+    def test_returns_5_choices(self):
+        """Verify returns 5 choices (1 placeholder + 4 scenarios)."""
+        choices = get_sample_choices()
+        assert len(choices) == 5
+
+    def test_all_scenario_ids_in_choices(self):
+        """Verify all scenario IDs appear in choices."""
+        choices = get_sample_choices()
+        values = [v for _, v in choices]
+        assert "bar_dining" in values
+        assert "bar_area" in values
+        assert "kitchen" in values
+        assert "factory" in values
+
+
+class TestLoadSample:
+    """Test load_sample function."""
+
+    def test_load_valid_scenario_returns_session(self):
+        """Verify loading valid scenario returns SessionState."""
+        session = load_sample("bar_dining")
+        assert session is not None
+        assert isinstance(session, SessionState)
+
+        # Cleanup
+        image_store.clear()
+
+    def test_load_invalid_scenario_returns_none(self):
+        """Verify loading invalid scenario returns None."""
+        session = load_sample("nonexistent_scenario")
+        assert session is None
+
+    def test_loaded_session_has_project_data(self):
+        """Verify loaded session has correct project data."""
+        session = load_sample("bar_dining")
+        assert session.project.project_name == "Sample: Bar & Dining Fire Assessment"
+        assert session.project.city == "Springfield"
+        assert session.project.state == "IL"
+
+        # Cleanup
+        image_store.clear()
+
+    def test_loaded_session_has_room(self):
+        """Verify loaded session has room data."""
+        session = load_sample("kitchen")
+        assert len(session.rooms) == 1
+        assert session.rooms[0].name == "Commercial Kitchen"
+        assert session.rooms[0].length_ft == 30.0
+        assert session.rooms[0].width_ft == 25.0
+
+        # Cleanup
+        image_store.clear()
+
+    def test_loaded_session_has_images(self):
+        """Verify loaded session has images loaded into store."""
+        session = load_sample("bar_area")
+        assert len(session.images) == 3
+
+        # Verify images are in store
+        for img in session.images:
+            assert image_store.get(img.id) is not None
+
+        # Cleanup
+        image_store.clear()
+
+    def test_loaded_session_has_observations(self):
+        """Verify loaded session has observations data."""
+        session = load_sample("factory")
+        assert session.observations.smoke_fire_odor is True
+        assert session.observations.odor_intensity == "strong"
+        assert session.observations.large_char_particles is True
+
+        # Cleanup
+        image_store.clear()
+
+    def test_loaded_session_tabs_marked_complete(self):
+        """Verify loaded session has tabs marked as complete."""
+        session = load_sample("bar_dining")
+        assert session.tab1_complete is True
+        assert session.tab2_complete is True
+        assert session.tab3_complete is True
+        assert session.tab4_complete is True
+
+        # Cleanup
+        image_store.clear()
+
+    def test_facility_classification_correct(self):
+        """Verify facility classifications are set correctly."""
+        # Restaurant scenarios should be non-operational
+        session = load_sample("bar_dining")
+        assert session.project.facility_classification == "non-operational"
+        image_store.clear()
+
+        # Factory should be operational
+        session = load_sample("factory")
+        assert session.project.facility_classification == "operational"
+        image_store.clear()
+
+    def test_construction_era_correct(self):
+        """Verify construction eras are set correctly."""
+        # Bar scenarios should be pre-1980
+        session = load_sample("bar_area")
+        assert session.project.construction_era == "pre-1980"
+        image_store.clear()
+
+        # Kitchen should be 1980-2000
+        session = load_sample("kitchen")
+        assert session.project.construction_era == "1980-2000"
+        image_store.clear()
+
+
+class TestGetScenarioById:
+    """Test get_scenario_by_id function."""
+
+    def test_returns_scenario_for_valid_id(self):
+        """Verify returns scenario for valid ID."""
+        scenario = get_scenario_by_id("kitchen")
+        assert scenario is not None
+        assert scenario.id == "kitchen"
+        assert scenario.name == "Kitchen"
+
+    def test_returns_none_for_invalid_id(self):
+        """Verify returns None for invalid ID."""
+        scenario = get_scenario_by_id("invalid_id")
+        assert scenario is None
+
+
+class TestLoadSampleImages:
+    """Test load_sample_images function."""
+
+    def test_loads_images_into_store(self):
+        """Verify images are loaded into image_store."""
+        scenario = SAMPLE_SCENARIOS_BY_ID["bar_dining"]
+        room_id = "test-room-123"
+
+        image_metas = load_sample_images(scenario, room_id)
+
+        assert len(image_metas) == 3
+        for meta in image_metas:
+            assert meta.room_id == room_id
+            assert image_store.get(meta.id) is not None
+
+        # Cleanup
+        image_store.clear()
+
+    def test_image_metadata_has_correct_room_id(self):
+        """Verify image metadata has correct room ID."""
+        scenario = SAMPLE_SCENARIOS_BY_ID["factory"]
+        room_id = "factory-room-456"
+
+        image_metas = load_sample_images(scenario, room_id)
+
+        assert len(image_metas) == 1
+        assert image_metas[0].room_id == room_id
+
+        # Cleanup
+        image_store.clear()
+
+    def test_image_ids_are_unique(self):
+        """Verify each loaded image gets a unique ID."""
+        scenario = SAMPLE_SCENARIOS_BY_ID["kitchen"]
+        room_id = "kitchen-room"
+
+        image_metas = load_sample_images(scenario, room_id)
+
+        ids = [meta.id for meta in image_metas]
+        assert len(ids) == len(set(ids))  # All unique
+
+        # Cleanup
+        image_store.clear()

tests/test_tabs.py

@@ -27,7 +27,7 @@ class TestProjectTab:
             facility_classification="Operational",
             construction_era="Pre-1980",
             assessor_name="John Smith",
-            assessor_credentials="CIH",
+            assessor_credentials=["CIH"],
         )
 
         assert session.project.project_name == "Test Project"
@@ -49,10 +49,10 @@ class TestProjectTab:
             facility_classification="Non-Operational",
             construction_era="Post-2000",
             assessor_name="Name",
-            assessor_credentials="",
+            assessor_credentials=[],
         )
 
-        assert tab_index == 0  # Stay on tab
+        assert tab_index["selected"] == 0  # Stay on tab (Gradio update dict)
         assert "Project name is required" in html
         assert session.tab1_complete is False
 
@@ -71,10 +71,10 @@ class TestProjectTab:
             facility_classification="Non-Operational",
             construction_era="Post-2000",
             assessor_name="Name",
-            assessor_credentials="",
+            assessor_credentials=[],
         )
 
-        assert tab_index == 1  # Go to next tab
+        assert tab_index["selected"] == 1  # Go to next tab (Gradio update dict)
         assert "✓" in html
         assert session.tab1_complete is True
 
@@ -100,10 +100,11 @@ class TestRoomsTab:
         result = rooms.add_room(
             session,
             name="Room 1",
-            floor="Ground",
+            floor="Ground Floor",
             length=100.0,
             width=50.0,
-            height=20.0,
+            height_preset=20,  # Using preset value
+            height_custom=None,
         )
 
         session = result[0]
@@ -121,10 +122,11 @@ class TestRoomsTab:
         result = rooms.add_room(
             session,
             name="",  # Missing
-            floor="",
+            floor=None,
             length=0,  # Invalid
             width=50.0,
-            height=20.0,
+            height_preset=None,  # No height selected
+            height_custom=None,
         )
 
         session = result[0]
@@ -151,23 +153,35 @@ class TestRoomsTab:
 
         session, html, tab_index = rooms.validate_and_continue(session)
 
-        assert tab_index == 2  # Go to Images tab
+        assert tab_index["selected"] == 2  # Go to Images tab (Gradio update dict)
         assert session.tab2_complete is True
 
 
+class MockFile:
+    """Mock file object for testing gr.Files uploads."""
+
+    def __init__(self, path: str):
+        self.name = path
+
+
 class TestImagesTab:
     """Test Tab 3: Images."""
 
-    def test_add_image_valid(self):
+    def test_add_image_valid(self, tmp_path):
         session = SessionState()
         session.rooms.append(RoomFormData(id="room-001", name="Room 1", length_ft=100, width_ft=50, ceiling_height_ft=20))
 
-        # Create a test image
+        # Create a test image file
         test_image = Image.new("RGB", (100, 100), color="red")
+        img_path = tmp_path / "test_image.png"
+        test_image.save(img_path)
+
+        # Create mock file object
+        mock_file = MockFile(str(img_path))
 
         result = images.add_image(
             session,
-            image=test_image,
+            files=[mock_file],
             room_id="room-001",
             description="Test image",
         )
@@ -185,13 +199,19 @@ class TestImagesTab:
         # Cleanup
         image_store.clear()
 
-    def test_add_image_no_room(self):
+    def test_add_image_no_room(self, tmp_path):
         session = SessionState()
+
+        # Create a test image file
         test_image = Image.new("RGB", (100, 100), color="red")
+        img_path = tmp_path / "test_image.png"
+        test_image.save(img_path)
+
+        mock_file = MockFile(str(img_path))
 
         result = images.add_image(
             session,
-            image=test_image,
+            files=[mock_file],
             room_id="",  # No room selected
             description="",
         )
@@ -210,7 +230,7 @@ class TestImagesTab:
 
         session, html, tab_index = images.validate_and_continue(session)
 
-        assert tab_index == 2  # Stay on Images tab
+        assert tab_index["selected"] == 2  # Stay on Images tab (Gradio update dict)
         assert "re-uploaded" in html
 
     def test_update_room_choices(self):
@@ -275,7 +295,7 @@ class TestObservationsTab:
             additional_notes="",
         )
 
-        assert tab_index == 4  # Go to Results tab
+        assert tab_index["selected"] == 4  # Go to Results tab (Gradio update dict)
         assert session.tab4_complete is True
 
     def test_load_form_from_session(self):

ui/constants.py

@@ -0,0 +1,127 @@
+"""UI constants for dropdowns and validation.
+
+Centralized dropdown options for the FDAM AI Pipeline frontend.
+"""
+
+# US States and Territories (display name, abbreviation)
+US_STATES: list[tuple[str, str]] = [
+    ("Alabama", "AL"),
+    ("Alaska", "AK"),
+    ("Arizona", "AZ"),
+    ("Arkansas", "AR"),
+    ("California", "CA"),
+    ("Colorado", "CO"),
+    ("Connecticut", "CT"),
+    ("Delaware", "DE"),
+    ("District of Columbia", "DC"),
+    ("Florida", "FL"),
+    ("Georgia", "GA"),
+    ("Hawaii", "HI"),
+    ("Idaho", "ID"),
+    ("Illinois", "IL"),
+    ("Indiana", "IN"),
+    ("Iowa", "IA"),
+    ("Kansas", "KS"),
+    ("Kentucky", "KY"),
+    ("Louisiana", "LA"),
+    ("Maine", "ME"),
+    ("Maryland", "MD"),
+    ("Massachusetts", "MA"),
+    ("Michigan", "MI"),
+    ("Minnesota", "MN"),
+    ("Mississippi", "MS"),
+    ("Missouri", "MO"),
+    ("Montana", "MT"),
+    ("Nebraska", "NE"),
+    ("Nevada", "NV"),
+    ("New Hampshire", "NH"),
+    ("New Jersey", "NJ"),
+    ("New Mexico", "NM"),
+    ("New York", "NY"),
+    ("North Carolina", "NC"),
+    ("North Dakota", "ND"),
+    ("Ohio", "OH"),
+    ("Oklahoma", "OK"),
+    ("Oregon", "OR"),
+    ("Pennsylvania", "PA"),
+    ("Rhode Island", "RI"),
+    ("South Carolina", "SC"),
+    ("South Dakota", "SD"),
+    ("Tennessee", "TN"),
+    ("Texas", "TX"),
+    ("Utah", "UT"),
+    ("Vermont", "VT"),
+    ("Virginia", "VA"),
+    ("Washington", "WA"),
+    ("West Virginia", "WV"),
+    ("Wisconsin", "WI"),
+    ("Wyoming", "WY"),
+    # Territories
+    ("American Samoa", "AS"),
+    ("Guam", "GU"),
+    ("Northern Mariana Islands", "MP"),
+    ("Puerto Rico", "PR"),
+    ("U.S. Virgin Islands", "VI"),
+]
+
+# State abbreviation to display name mapping
+STATE_ABBR_TO_NAME: dict[str, str] = {abbr: name for name, abbr in US_STATES}
+STATE_NAME_TO_ABBR: dict[str, str] = {name: abbr for name, abbr in US_STATES}
+
+# Floor options for room entry
+FLOOR_OPTIONS: list[str] = [
+    "Basement",
+    "Ground Floor",
+    "1st Floor",
+    "2nd Floor",
+    "3rd Floor",
+    "4th Floor",
+    "5th Floor",
+    "6th Floor",
+    "7th Floor",
+    "8th Floor",
+    "9th Floor",
+    "10th Floor",
+    "Mezzanine",
+    "Roof",
+    "Other",
+]
+
+# Ceiling height presets (display label, value in feet)
+# None value indicates "Custom" option requiring manual input
+CEILING_HEIGHT_PRESETS: list[tuple[str, int | None]] = [
+    ("8 ft", 8),
+    ("9 ft", 9),
+    ("10 ft", 10),
+    ("12 ft", 12),
+    ("14 ft", 14),
+    ("16 ft", 16),
+    ("18 ft", 18),
+    ("20 ft", 20),
+    ("24 ft", 24),
+    ("Custom", None),
+]
+
+# Common IH/safety professional credentials
+ASSESSOR_CREDENTIALS: list[str] = [
+    "CIH",    # Certified Industrial Hygienist
+    "CSP",    # Certified Safety Professional
+    "PE",     # Professional Engineer
+    "QEP",    # Qualified Environmental Professional
+    "CHMM",   # Certified Hazardous Materials Manager
+    "OHST",   # Occupational Health and Safety Technologist
+    "ASP",    # Associate Safety Professional
+    "Other",
+]
+
+# Credential display names (for UI tooltips or help text)
+CREDENTIAL_DESCRIPTIONS: dict[str, str] = {
+    "CIH": "Certified Industrial Hygienist",
+    "CSP": "Certified Safety Professional",
+    "PE": "Professional Engineer",
+    "QEP": "Qualified Environmental Professional",
+    "CHMM": "Certified Hazardous Materials Manager",
+    "OHST": "Occupational Health and Safety Technologist",
+    "ASP": "Associate Safety Professional",
+    "Other": "Other certification",
+}

ui/samples.py

@@ -0,0 +1,357 @@
+"""Sample room data for testing the FDAM AI Pipeline.
+
+Provides 4 pre-configured sample scenarios with complete project data,
+room information, images, and qualitative observations.
+"""
+
+import uuid
+import io
+from pathlib import Path
+from dataclasses import dataclass, field
+
+from PIL import Image
+
+from ui.state import (
+    SessionState,
+    ProjectFormData,
+    RoomFormData,
+    ImageFormData,
+    ObservationsFormData,
+)
+from ui.components import image_store
+
+
+# Path to sample images directory
+SAMPLE_IMAGES_DIR = Path(__file__).parent.parent / "sample_images"
+
+
+@dataclass
+class SampleScenario:
+    """Definition of a sample fire damage scenario."""
+
+    id: str
+    name: str
+    description: str
+    project_data: dict
+    room_data: dict
+    observations_data: dict
+    image_files: list[str] = field(default_factory=list)
+
+
+# --- Sample Scenario Definitions ---
+
+SAMPLE_SCENARIOS = [
+    # 1. Bar & Dining Area
+    SampleScenario(
+        id="bar_dining",
+        name="Bar & Dining Area",
+        description="3 images",
+        project_data={
+            "project_name": "Sample: Bar & Dining Fire Assessment",
+            "address": "1234 Main Street",
+            "city": "Springfield",
+            "state": "IL",
+            "zip_code": "62701",
+            "client_name": "Sample Test Client",
+            "fire_date": "2024-11-15",
+            "assessment_date": "2024-12-01",
+            "facility_classification": "non-operational",
+            "construction_era": "pre-1980",
+            "assessor_name": "Test Assessor",
+            "assessor_credentials": ["CIH"],
+        },
+        room_data={
+            "name": "Bar & Dining Area",
+            "floor": "Ground Floor",
+            "length_ft": 40.0,
+            "width_ft": 30.0,
+            "ceiling_height_ft": 12.0,
+        },
+        observations_data={
+            "smoke_fire_odor": True,
+            "odor_intensity": "strong",
+            "visible_soot_deposits": True,
+            "soot_pattern_description": "Heavy soot deposits on corrugated metal ceiling, moderate wall discoloration",
+            "large_char_particles": True,
+            "char_density_estimate": "moderate",
+            "ash_like_residue": True,
+            "ash_color_texture": "Ash deposits on horizontal surfaces and upholstered furniture",
+            "surface_discoloration": True,
+            "discoloration_description": "Tan/brown soot staining on walls, yellowing on decorative elements",
+            "dust_loading_interference": False,
+            "dust_notes": "",
+            "wildfire_indicators": False,
+            "wildfire_notes": "",
+            "additional_notes": "",
+        },
+        image_files=[
+            "Bar and dining area1.jpg",
+            "Bar and dining area2.jpg",
+            "Bar and dining area3.jpg",
+        ],
+    ),
+    # 2. Bar Area
+    SampleScenario(
+        id="bar_area",
+        name="Bar Area",
+        description="3 images",
+        project_data={
+            "project_name": "Sample: Bar Area Fire Assessment",
+            "address": "1234 Main Street",
+            "city": "Springfield",
+            "state": "IL",
+            "zip_code": "62701",
+            "client_name": "Sample Test Client",
+            "fire_date": "2024-11-15",
+            "assessment_date": "2024-12-01",
+            "facility_classification": "non-operational",
+            "construction_era": "pre-1980",
+            "assessor_name": "Test Assessor",
+            "assessor_credentials": ["CIH"],
+        },
+        room_data={
+            "name": "Bar Area",
+            "floor": "Ground Floor",
+            "length_ft": 25.0,
+            "width_ft": 20.0,
+            "ceiling_height_ft": 14.0,
+        },
+        observations_data={
+            "smoke_fire_odor": True,
+            "odor_intensity": "strong",
+            "visible_soot_deposits": True,
+            "soot_pattern_description": "Dense black coating on ceiling/ductwork, severe overhead damage",
+            "large_char_particles": True,
+            "char_density_estimate": "dense",
+            "ash_like_residue": True,
+            "ash_color_texture": "Heavy ash on shelving and bottled goods",
+            "surface_discoloration": True,
+            "discoloration_description": "Metal oxidation, melted plastic signage, deformed ductwork",
+            "dust_loading_interference": False,
+            "dust_notes": "",
+            "wildfire_indicators": False,
+            "wildfire_notes": "",
+            "additional_notes": "",
+        },
+        image_files=[
+            "Bar area1.jpg",
+            "Bar area2.jpg",
+            "Bar area3.jpg",
+        ],
+    ),
+    # 3. Kitchen
+    SampleScenario(
+        id="kitchen",
+        name="Kitchen",
+        description="6 images",
+        project_data={
+            "project_name": "Sample: Kitchen Fire Assessment",
+            "address": "5678 Industrial Blvd",
+            "city": "Chicago",
+            "state": "IL",
+            "zip_code": "60601",
+            "client_name": "Sample Test Client",
+            "fire_date": "2024-10-20",
+            "assessment_date": "2024-11-05",
+            "facility_classification": "non-operational",
+            "construction_era": "1980-2000",
+            "assessor_name": "Test Assessor",
+            "assessor_credentials": ["CIH", "CSP"],
+        },
+        room_data={
+            "name": "Commercial Kitchen",
+            "floor": "Ground Floor",
+            "length_ft": 30.0,
+            "width_ft": 25.0,
+            "ceiling_height_ft": 10.0,
+        },
+        observations_data={
+            "smoke_fire_odor": True,
+            "odor_intensity": "strong",
+            "visible_soot_deposits": True,
+            "soot_pattern_description": "Heavy soot on all surfaces, ceiling collapse debris",
+            "large_char_particles": True,
+            "char_density_estimate": "dense",
+            "ash_like_residue": True,
+            "ash_color_texture": "Thick ash deposits on work surfaces, equipment heavily coated",
+            "surface_discoloration": True,
+            "discoloration_description": "Charred drywall, oxidized metal equipment, concrete staining",
+            "dust_loading_interference": False,
+            "dust_notes": "",
+            "wildfire_indicators": False,
+            "wildfire_notes": "",
+            "additional_notes": "",
+        },
+        image_files=[
+            "Kitchen 1.jpg",
+            "Kitchen 2.jpg",
+            "Kitchen 3.jpg",
+            "Kitchen 4.jpg",
+            "Kitchen 5.jpg",
+            "Kitchen 6.jpg",
+        ],
+    ),
+    # 4. Factory Area
+    SampleScenario(
+        id="factory",
+        name="Factory Area",
+        description="1 image",
+        project_data={
+            "project_name": "Sample: Factory Fire Assessment",
+            "address": "9999 Factory Way",
+            "city": "Detroit",
+            "state": "MI",
+            "zip_code": "48201",
+            "client_name": "Industrial Test Corp",
+            "fire_date": "2024-09-01",
+            "assessment_date": "2024-09-15",
+            "facility_classification": "operational",
+            "construction_era": "pre-1980",
+            "assessor_name": "Test Assessor",
+            "assessor_credentials": ["CIH", "PE"],
+        },
+        room_data={
+            "name": "Factory Production Area",
+            "floor": "Ground Floor",
+            "length_ft": 80.0,
+            "width_ft": 60.0,
+            "ceiling_height_ft": 25.0,
+        },
+        observations_data={
+            "smoke_fire_odor": True,
+            "odor_intensity": "strong",
+            "visible_soot_deposits": True,
+            "soot_pattern_description": "Complete structural compromise, deep char on all surfaces",
+            "large_char_particles": True,
+            "char_density_estimate": "dense",
+            "ash_like_residue": True,
+            "ash_color_texture": "Heavy ash coating throughout, debris accumulation",
+            "surface_discoloration": True,
+            "discoloration_description": "Extreme oxidation on metal framing, thermal spalling on concrete",
+            "dust_loading_interference": False,
+            "dust_notes": "",
+            "wildfire_indicators": False,
+            "wildfire_notes": "",
+            "additional_notes": "",
+        },
+        image_files=[
+            "factory_area.jpg",
+        ],
+    ),
+]
+
+# Create lookup dict for fast access
+SAMPLE_SCENARIOS_BY_ID = {s.id: s for s in SAMPLE_SCENARIOS}
+
+
+def get_sample_choices() -> list[tuple[str, str]]:
+    """Get dropdown choices for sample selector.
+
+    Returns:
+        List of (label, value) tuples for Gradio dropdown.
+    """
+    choices = [("Select a sample scenario...", "")]
+    for scenario in SAMPLE_SCENARIOS:
+        label = f"{scenario.name} ({scenario.description})"
+        choices.append((label, scenario.id))
+    return choices
+
+
+def load_sample_images(scenario: SampleScenario, room_id: str) -> list[ImageFormData]:
+    """Load sample images from disk into image_store.
+
+    Args:
+        scenario: The sample scenario to load images for.
+        room_id: The room ID to associate images with.
+
+    Returns:
+        List of ImageFormData objects for the loaded images.
+    """
+    image_metas = []
+
+    for filename in scenario.image_files:
+        filepath = SAMPLE_IMAGES_DIR / filename
+        if filepath.exists():
+            try:
+                # Read and convert image to PNG bytes
+                img = Image.open(filepath)
+                img_bytes = io.BytesIO()
+                img.save(img_bytes, format="PNG")
+
+                # Generate unique image ID
+                image_id = f"sample-{uuid.uuid4().hex[:8]}"
+
+                # Store in image_store
+                image_store.store(image_id, img_bytes.getvalue())
+
+                # Create metadata
+                image_metas.append(
+                    ImageFormData(
+                        id=image_id,
+                        filename=filename,
+                        room_id=room_id,
+                        description=f"Sample image: {filename}",
+                    )
+                )
+            except Exception:
+                # Skip files that can't be opened as images
+                continue
+
+    return image_metas
+
+
+def load_sample(scenario_id: str) -> SessionState | None:
+    """Load a sample scenario into a new SessionState.
+
+    Args:
+        scenario_id: The ID of the scenario to load.
+
+    Returns:
+        A new SessionState populated with the scenario data, or None if not found.
+    """
+    scenario = SAMPLE_SCENARIOS_BY_ID.get(scenario_id)
+    if not scenario:
+        return None
+
+    # Create room with unique ID
+    room_id = f"room-{uuid.uuid4().hex[:8]}"
+    room = RoomFormData(
+        id=room_id,
+        name=scenario.room_data["name"],
+        floor=scenario.room_data.get("floor", ""),
+        length_ft=scenario.room_data["length_ft"],
+        width_ft=scenario.room_data["width_ft"],
+        ceiling_height_ft=scenario.room_data["ceiling_height_ft"],
+    )
+
+    # Load images
+    images = load_sample_images(scenario, room_id)
+
+    # Create session
+    session = SessionState(
+        project=ProjectFormData(**scenario.project_data),
+        rooms=[room],
+        images=images,
+        observations=ObservationsFormData(**scenario.observations_data),
+        name=scenario.project_data["project_name"],
+    )
+
+    # Mark tabs as complete since we have all data
+    session.tab1_complete = True
+    session.tab2_complete = True
+    session.tab3_complete = len(images) > 0
+    session.tab4_complete = True
+
+    return session
+
+
+def get_scenario_by_id(scenario_id: str) -> SampleScenario | None:
+    """Get a sample scenario by its ID.
+
+    Args:
+        scenario_id: The scenario ID.
+
+    Returns:
+        The SampleScenario object or None if not found.
+    """
+    return SAMPLE_SCENARIOS_BY_ID.get(scenario_id)

ui/state.py

@@ -36,7 +36,7 @@ class ProjectFormData(BaseModel):
     facility_classification: FacilityClassification = "non-operational"
     construction_era: ConstructionEra = "post-2000"
     assessor_name: str = ""
-    assessor_credentials: str = ""
+    assessor_credentials: list[str] = Field(default_factory=list)  # Multiselect credentials
 
 
 class RoomFormData(BaseModel):
@@ -253,9 +253,24 @@ def session_to_json(session: SessionState) -> str:
 
 
 def session_from_json(json_str: str) -> SessionState:
-    """Deserialize session from JSON."""
+    """Deserialize session from JSON.
+
+    Includes migration for old sessions where assessor_credentials was a string.
+    """
     try:
-        return SessionState.model_validate_json(json_str)
+        # Parse JSON first to check for migrations needed
+        data = json.loads(json_str)
+
+        # Migration: Convert old string credentials to list
+        if "project" in data and isinstance(data["project"].get("assessor_credentials"), str):
+            old_creds = data["project"]["assessor_credentials"]
+            # Convert comma-separated string to list, or empty list if empty
+            if old_creds:
+                data["project"]["assessor_credentials"] = [c.strip() for c in old_creds.split(",") if c.strip()]
+            else:
+                data["project"]["assessor_credentials"] = []
+
+        return SessionState.model_validate(data)
     except Exception:
         return create_new_session()
 

ui/storage.py

@@ -170,9 +170,16 @@ async () => {
 """
 
 
-def get_head_html() -> str:
-    """Get HTML to inject into Gradio head for localStorage support."""
-    return LOCALSTORAGE_JS
+def get_head_html(additional_scripts: str = "") -> str:
+    """Get HTML to inject into Gradio head for localStorage support.
+
+    Args:
+        additional_scripts: Optional additional HTML/JS to include.
+
+    Returns:
+        Combined HTML string for head injection.
+    """
+    return LOCALSTORAGE_JS + additional_scripts
 
 
 def create_save_trigger_js(field_updates: dict[str, str]) -> str:

ui/tabs/images.py

@@ -28,10 +28,10 @@ def create_tab() -> dict[str, Any]:
 
     with gr.Row():
         with gr.Column(scale=2):
-            image_upload = gr.Image(
-                label="Upload Image",
-                type="pil",
-                sources=["upload"],
+            image_upload = gr.Files(
+                label="Upload Images (select multiple)",
+                file_count="multiple",
+                file_types=["image"],
                 elem_id="image_upload",
             )
             room_select = gr.Dropdown(
@@ -39,15 +39,17 @@ def create_tab() -> dict[str, Any]:
                 choices=[],
                 value=None,
                 elem_id="room_select",
+                info="All uploaded images will be assigned to this room",
             )
             image_description = gr.Textbox(
                 label="Description (optional)",
                 placeholder="e.g., View of ceiling deck from center aisle",
                 elem_id="image_description",
+                info="Applied to all images in batch",
             )
 
             with gr.Row():
-                add_image_btn = gr.Button("Add Image", variant="primary")
+                add_image_btn = gr.Button("Add Images", variant="primary")
                 clear_upload_btn = gr.Button("Clear", variant="secondary")
 
         with gr.Column(scale=3):
@@ -110,26 +112,40 @@ def create_tab() -> dict[str, Any]:
 
 def add_image(
     session: SessionState,
-    image: Optional[Image.Image],
+    files: list | None,
     room_id: str,
     description: str,
-) -> tuple[SessionState, list[tuple], str, str, None, None, str]:
-    """Add an image to the session.
+) -> tuple[SessionState, list[tuple], str, str, None, str, str]:
+    """Add one or more images to the session (batch upload).
+
+    Args:
+        session: Current session state.
+        files: List of uploaded file objects from gr.Files, each with a `name` attribute.
+        room_id: Room ID to associate images with.
+        description: Optional description applied to all images.
 
     Returns:
         Tuple of (session, gallery_data, validation_html, image_count,
-                  cleared_image, cleared_description, room_id).
+                  cleared_files, cleared_description, room_id).
     """
     validation_html = ""
 
     # Validate input
     errors = []
-    if image is None:
-        errors.append("Please upload an image")
+    if not files or len(files) == 0:
+        errors.append("Please upload at least one image")
     if not room_id:
-        errors.append("Please select a room for this image")
-    if len(session.images) >= settings.max_images_per_assessment:
-        errors.append(f"Maximum of {settings.max_images_per_assessment} images allowed")
+        errors.append("Please select a room for these images")
+
+    # Check capacity
+    current_count = len(session.images)
+    max_allowed = settings.max_images_per_assessment
+    if files and current_count + len(files) > max_allowed:
+        remaining = max_allowed - current_count
+        if remaining <= 0:
+            errors.append(f"Maximum of {max_allowed} images allowed (already at limit)")
+        else:
+            errors.append(f"Can only add {remaining} more image(s) (limit: {max_allowed})")
 
     if errors:
         error_items = "".join(f"<li>{e}</li>" for e in errors)
@@ -141,43 +157,66 @@ def add_image(
         </div>
         """
         gallery_data = _get_gallery_data(session)
-        count_str = f"{len(session.images)} / {settings.max_images_per_assessment}"
-        return session, gallery_data, validation_html, count_str, image, description, room_id
-
-    # Generate image ID
-    image_id = f"img-{uuid.uuid4().hex[:8]}"
-
-    # Store image bytes in memory
-    img_bytes = io.BytesIO()
-    image.save(img_bytes, format="PNG")
-    image_store.store(image_id, img_bytes.getvalue())
+        count_str = f"{len(session.images)} / {max_allowed}"
+        return session, gallery_data, validation_html, count_str, files, description, room_id
 
-    # Get room name for filename
+    # Get room name for filenames
     room_name = "unknown"
     for room in session.rooms:
         if room.id == room_id:
             room_name = room.name.replace(" ", "_")[:20]
             break
 
-    # Add image metadata to session
-    img_meta = ImageFormData(
-        id=image_id,
-        filename=f"{room_name}_{image_id}.png",
-        room_id=room_id,
-        description=description.strip() if description else "",
-    )
-    session.images.append(img_meta)
+    # Process each uploaded file
+    added_count = 0
+    for file_obj in files:
+        # Check if we've hit the limit
+        if len(session.images) >= max_allowed:
+            break
+
+        try:
+            # Open image from file path
+            img = Image.open(file_obj.name)
+
+            # Generate image ID
+            image_id = f"img-{uuid.uuid4().hex[:8]}"
+
+            # Store image bytes in memory
+            img_bytes = io.BytesIO()
+            img.save(img_bytes, format="PNG")
+            image_store.store(image_id, img_bytes.getvalue())
+
+            # Add image metadata to session
+            img_meta = ImageFormData(
+                id=image_id,
+                filename=f"{room_name}_{image_id}.png",
+                room_id=room_id,
+                description=description.strip() if description else "",
+            )
+            session.images.append(img_meta)
+            added_count += 1
+        except Exception:
+            # Skip files that can't be opened as images
+            continue
+
     session.update_timestamp()
 
     # Success message
-    validation_html = f"""
-    <div style="background: #e8f5e9; border: 1px solid #66bb6a; border-radius: 4px; padding: 10px;">
-        <span style="color: #2e7d32;">✓ Image added for room: {room_name}</span>
-    </div>
-    """
+    if added_count > 0:
+        validation_html = f"""
+        <div style="background: #e8f5e9; border: 1px solid #66bb6a; border-radius: 4px; padding: 10px;">
+            <span style="color: #2e7d32;">✓ {added_count} image(s) added for room: {room_name}</span>
+        </div>
+        """
+    else:
+        validation_html = """
+        <div style="background: #fff3e0; border: 1px solid #ffb74d; border-radius: 4px; padding: 10px;">
+            <span style="color: #e65100;">No images could be processed</span>
+        </div>
+        """
 
     gallery_data = _get_gallery_data(session)
-    count_str = f"{len(session.images)} / {settings.max_images_per_assessment}"
+    count_str = f"{len(session.images)} / {max_allowed}"
 
     # Clear form
     return session, gallery_data, validation_html, count_str, None, "", room_id
@@ -246,7 +285,7 @@ def validate_and_continue(session: SessionState) -> tuple[SessionState, str, int
             </p>
         </div>
         """
-        return session, html, 2  # Stay on Images tab
+        return session, html, gr.update(selected=2)  # Stay on Images tab
 
     is_valid, errors = session.validate_tab3()
 
@@ -258,7 +297,7 @@ def validate_and_continue(session: SessionState) -> tuple[SessionState, str, int
             <span style="color: #2e7d32;">✓ Images complete. Proceeding to Observations tab...</span>
         </div>
         """
-        return session, html, 3  # Go to tab index 3 (Observations)
+        return session, html, gr.update(selected=3)  # Go to tab index 3 (Observations)
     else:
         session.tab3_complete = False
         error_items = "".join(f"<li>{e}</li>" for e in errors)
@@ -270,7 +309,7 @@ def validate_and_continue(session: SessionState) -> tuple[SessionState, str, int
             </ul>
         </div>
         """
-        return session, html, 2  # Stay on current tab
+        return session, html, gr.update(selected=2)  # Stay on current tab
 
 
 def update_room_choices(session: SessionState) -> dict:

ui/tabs/observations.py

@@ -252,7 +252,7 @@ def validate_and_continue(
         <span style="color: #2e7d32;">✓ Observations saved. Proceeding to Generate Results...</span>
     </div>
     """
-    return session, html, 4  # Go to tab index 4 (Results)
+    return session, html, gr.update(selected=4)  # Go to tab index 4 (Results)
 
 
 def load_form_from_session(session: SessionState) -> tuple:

ui/tabs/project.py

@@ -3,10 +3,16 @@
 Collects project details, client information, and facility classification.
 """
 
+import re
 import gradio as gr
 from typing import Any
 
 from ui.state import SessionState, ProjectFormData
+from ui.constants import US_STATES, ASSESSOR_CREDENTIALS
+
+
+# ZIP code validation regex (5 digits or 5+4 format)
+ZIP_PATTERN = re.compile(r"^\d{5}(-\d{4})?$")
 
 
 # Map UI values to schema values
@@ -47,30 +53,39 @@ def create_tab() -> dict[str, Any]:
             )
             with gr.Row():
                 city = gr.Textbox(label="City *", elem_id="city")
-                state = gr.Textbox(
+                state = gr.Dropdown(
                     label="State *",
-                    max_lines=1,
+                    choices=US_STATES,
                     elem_id="state",
+                    allow_custom_value=True,  # Allow empty value for validation
                 )
-                zip_code = gr.Textbox(
-                    label="ZIP Code *",
-                    max_lines=1,
-                    elem_id="zip_code",
-                )
+                with gr.Column(scale=1):
+                    zip_code = gr.Textbox(
+                        label="ZIP Code *",
+                        max_lines=1,
+                        elem_id="zip_code",
+                        info="Format: 12345 or 12345-6789",
+                    )
+                    zip_validation = gr.HTML(
+                        value="",
+                        elem_id="zip_validation",
+                    )
 
         with gr.Column():
             client_name = gr.Textbox(
                 label="Client Name *",
                 elem_id="client_name",
             )
-            fire_date = gr.Textbox(
+            fire_date = gr.DateTime(
                 label="Fire Date *",
-                placeholder="YYYY-MM-DD",
+                include_time=False,
+                type="string",
                 elem_id="fire_date",
             )
-            assessment_date = gr.Textbox(
+            assessment_date = gr.DateTime(
                 label="Assessment Date *",
-                placeholder="YYYY-MM-DD",
+                include_time=False,
+                type="string",
                 elem_id="assessment_date",
             )
 
@@ -95,10 +110,12 @@ def create_tab() -> dict[str, Any]:
             label="Assessor Name *",
             elem_id="assessor_name",
         )
-        assessor_credentials = gr.Textbox(
+        assessor_credentials = gr.Dropdown(
             label="Credentials (optional)",
-            placeholder="CIH, CSP, etc.",
+            choices=ASSESSOR_CREDENTIALS,
+            multiselect=True,
             elem_id="assessor_credentials",
+            info="Select all that apply",
         )
 
     # Validation status display
@@ -120,6 +137,7 @@ def create_tab() -> dict[str, Any]:
         "city": city,
         "state": state,
         "zip_code": zip_code,
+        "zip_validation": zip_validation,
         "client_name": client_name,
         "fire_date": fire_date,
         "assessment_date": assessment_date,
@@ -145,7 +163,7 @@ def update_session_from_form(
     facility_classification: str,
     construction_era: str,
     assessor_name: str,
-    assessor_credentials: str,
+    assessor_credentials: list[str] | None,
 ) -> SessionState:
     """Update session state from form values."""
     session.project = ProjectFormData(
@@ -160,7 +178,7 @@ def update_session_from_form(
         facility_classification=FACILITY_MAP.get(facility_classification, "non-operational"),
         construction_era=ERA_MAP.get(construction_era, "post-2000"),
         assessor_name=assessor_name or "",
-        assessor_credentials=assessor_credentials or "",
+        assessor_credentials=assessor_credentials or [],
     )
     session.update_timestamp()
     return session
@@ -179,7 +197,7 @@ def validate_and_continue(
     facility_classification: str,
     construction_era: str,
     assessor_name: str,
-    assessor_credentials: str,
+    assessor_credentials: list[str] | None,
 ) -> tuple[SessionState, str, int]:
     """Validate Tab 1 and update session.
 
@@ -213,7 +231,7 @@ def validate_and_continue(
             <span style="color: #2e7d32;">✓ Project information complete. Proceeding to Rooms tab...</span>
         </div>
         """
-        return session, html, 1  # Go to tab index 1 (Rooms)
+        return session, html, gr.update(selected=1)  # Go to tab index 1 (Rooms)
     else:
         session.tab1_complete = False
         error_items = "".join(f"<li>{e}</li>" for e in errors)
@@ -225,7 +243,7 @@ def validate_and_continue(
             </ul>
         </div>
         """
-        return session, html, 0  # Stay on current tab
+        return session, html, gr.update(selected=0)  # Stay on current tab
 
 
 def load_form_from_session(session: SessionState) -> tuple:
@@ -249,3 +267,21 @@ def load_form_from_session(session: SessionState) -> tuple:
         p.assessor_name,
         p.assessor_credentials,
     )
+
+
+def validate_zip_format(zip_code: str) -> str:
+    """Validate ZIP code format and return validation HTML indicator.
+
+    Args:
+        zip_code: The ZIP code string to validate.
+
+    Returns:
+        HTML string with validation indicator (green check or red X).
+    """
+    if not zip_code:
+        return ""  # Empty - no indicator
+
+    if ZIP_PATTERN.match(zip_code.strip()):
+        return '<span style="color: #2e7d32; font-size: 12px;">✓ Valid format</span>'
+    else:
+        return '<span style="color: #c62828; font-size: 12px;">✗ Use format: 12345 or 12345-6789</span>'

ui/tabs/rooms.py

@@ -9,6 +9,7 @@ from typing import Any
 
 from ui.state import SessionState, RoomFormData
 from ui.components import create_room_table_data
+from ui.constants import FLOOR_OPTIONS, CEILING_HEIGHT_PRESETS
 
 
 def create_tab() -> dict[str, Any]:
@@ -27,9 +28,9 @@ def create_tab() -> dict[str, Any]:
                 placeholder="e.g., Warehouse Bay A",
                 elem_id="room_name",
             )
-            room_floor = gr.Textbox(
+            room_floor = gr.Dropdown(
                 label="Floor (optional)",
-                placeholder="e.g., Ground Floor, 2nd Floor",
+                choices=FLOOR_OPTIONS,
                 elem_id="room_floor",
             )
             with gr.Row():
@@ -45,11 +46,19 @@ def create_tab() -> dict[str, Any]:
                     value=None,
                     elem_id="room_width",
                 )
-                room_height = gr.Number(
-                    label="Ceiling Height (ft) *",
+            with gr.Row():
+                room_height_preset = gr.Dropdown(
+                    label="Ceiling Height *",
+                    choices=CEILING_HEIGHT_PRESETS,
+                    elem_id="room_height_preset",
+                    info="Select preset or choose Custom",
+                )
+                room_height_custom = gr.Number(
+                    label="Custom Height (ft)",
                     minimum=1,
                     value=None,
-                    elem_id="room_height",
+                    visible=False,
+                    elem_id="room_height_custom",
                 )
 
             with gr.Row():
@@ -104,7 +113,8 @@ def create_tab() -> dict[str, Any]:
         "room_floor": room_floor,
         "room_length": room_length,
         "room_width": room_width,
-        "room_height": room_height,
+        "room_height_preset": room_height_preset,
+        "room_height_custom": room_height_custom,
         "add_room_btn": add_room_btn,
         "clear_form_btn": clear_form_btn,
         "rooms_table": rooms_table,
@@ -122,19 +132,29 @@ def create_tab() -> dict[str, Any]:
 def add_room(
     session: SessionState,
     name: str,
-    floor: str,
+    floor: str | None,
     length: float,
     width: float,
-    height: float,
-) -> tuple[SessionState, list[list], str, str, str, str, str, float, float, float]:
+    height_preset: int | None,
+    height_custom: float | None,
+) -> tuple[SessionState, list[list], str, str, str, str, str | None, float | None, float | None, None, None]:
     """Add a room to the session.
 
     Returns:
         Tuple of (session, table_data, validation_html, room_count, total_area, total_volume,
-                  cleared_name, cleared_floor, cleared_length, cleared_width, cleared_height).
+                  cleared_name, cleared_floor, cleared_length, cleared_width,
+                  cleared_height_preset, cleared_height_custom).
     """
     validation_html = ""
 
+    # Determine actual ceiling height from preset or custom
+    if height_preset is not None:
+        height = float(height_preset)
+    elif height_custom is not None and height_custom > 0:
+        height = float(height_custom)
+    else:
+        height = None
+
     # Validate input
     errors = []
     if not name or not name.strip():
@@ -144,7 +164,7 @@ def add_room(
     if not width or width <= 0:
         errors.append("Width must be greater than 0")
     if not height or height <= 0:
-        errors.append("Ceiling height must be greater than 0")
+        errors.append("Ceiling height is required (select preset or enter custom)")
 
     if errors:
         error_items = "".join(f"<li>{e}</li>" for e in errors)
@@ -166,10 +186,11 @@ def add_room(
             stats["area"],
             stats["volume"],
             name or "",
-            floor or "",
+            floor,
             length,
             width,
-            height,
+            height_preset,
+            height_custom,
         )
 
     # Add the room
@@ -194,7 +215,7 @@ def add_room(
     table_data = create_room_table_data(session)
     stats = _calculate_stats(session)
 
-    # Clear form fields (return None for Number components)
+    # Clear form fields (return None for Number components, None for dropdowns)
     return (
         session,
         table_data,
@@ -203,13 +224,27 @@ def add_room(
         stats["area"],
         stats["volume"],
         "",  # Clear name
-        "",  # Clear floor
+        None,  # Clear floor dropdown
         None,  # Clear length
         None,  # Clear width
-        None,  # Clear height
+        None,  # Clear height preset
+        None,  # Clear height custom
     )
 
 
+def on_height_preset_change(preset_value: int | None) -> dict:
+    """Show/hide custom height input based on preset selection.
+
+    Args:
+        preset_value: The selected preset value, or None for "Custom".
+
+    Returns:
+        Gradio update dict for custom height visibility.
+    """
+    # If None (Custom selected), show custom input; otherwise hide it
+    return gr.update(visible=(preset_value is None))
+
+
 def remove_last_room(session: SessionState) -> tuple[SessionState, list[list], str, str, str]:
     """Remove the last room from the session."""
     if session.rooms:
@@ -261,7 +296,7 @@ def validate_and_continue(session: SessionState) -> tuple[SessionState, str, int
             <span style="color: #2e7d32;">✓ Rooms complete. Proceeding to Images tab...</span>
         </div>
         """
-        return session, html, 2  # Go to tab index 2 (Images)
+        return session, html, gr.update(selected=2)  # Go to tab index 2 (Images)
     else:
         session.tab2_complete = False
         error_items = "".join(f"<li>{e}</li>" for e in errors)
@@ -273,7 +308,7 @@ def validate_and_continue(session: SessionState) -> tuple[SessionState, str, int
             </ul>
         </div>
         """
-        return session, html, 1  # Stay on current tab
+        return session, html, gr.update(selected=1)  # Stay on current tab
 
 
 def load_from_session(session: SessionState) -> tuple[list[list], str, str, str]: