fix pr7 review findings

app.py

@@ -59,7 +59,17 @@ def _default_operator_state() -> dict[str, Any]:
 
 
 def _zero_gpu_entrypoint(fn: Any) -> Any:
-    """Expose one callback to ZeroGPU without making local development depend on Spaces."""
+    """
+    Optionally wrap a function with ZeroGPU acceleration.
+    
+    If the spaces module is available and provides GPU support, wraps the function with `spaces.GPU(duration=300)`. Otherwise, returns the function unchanged.
+    
+    Parameters:
+        fn: The callback function.
+    
+    Returns:
+        The function, optionally wrapped with ZeroGPU acceleration.
+    """
     gpu_decorator = getattr(spaces, "GPU", None) if spaces is not None else None
     if gpu_decorator is None:
         return fn
@@ -67,10 +77,22 @@ def _zero_gpu_entrypoint(fn: Any) -> Any:
 
 
 def _relay_snapshot(adult_mode: bool = False) -> dict[str, Any]:
+    """
+    Retrieves the relay dashboard snapshot based on visibility mode.
+    
+    Returns:
+        dict[str, Any]: Dashboard snapshot containing relay status and model information.
+    """
     return MODEL_RELAY.dashboard_snapshot(public_demo=not adult_mode)
 
 
 def _file_path(uploaded: Any) -> str | None:
+    """
+    Extract a file path from various upload input formats.
+    
+    Returns:
+        str | None: The file path string, or None if the input is None or lacks a valid path.
+    """
     if uploaded is None:
         return None
     if isinstance(uploaded, str):
@@ -80,17 +102,36 @@ def _file_path(uploaded: Any) -> str | None:
 
 
 def _safe_file_hash(path: str | None) -> tuple[str | None, int | None]:
+    """
+    Compute the SHA-256 hash and size of a file.
+    
+    Returns:
+        tuple[str | None, int | None]: The file's SHA-256 hash as a hex string and size in bytes. Returns (None, None) if the path is falsy or the file cannot be read.
+    """
     if not path:
         return None, None
     try:
         target = Path(path)
-        data = target.read_bytes()
+        sha256 = hashlib.sha256()
+        size = 0
+        with target.open("rb") as handle:
+            while chunk := handle.read(1024 * 1024):
+                sha256.update(chunk)
+                size += len(chunk)
     except OSError:
         return None, None
-    return hashlib.sha256(data).hexdigest(), len(data)
+    return sha256.hexdigest(), size
 
 
 def _safe_reference_url_metadata(reference_url: str | None) -> dict[str, Any] | None:
+    """
+    Validates a reference URL and extracts its metadata.
+    
+    Returns:
+        A dict with status "metadata_only" containing domain (lowercased) and URL hash if valid;
+        a dict with status "invalid_url" if the URL scheme is not HTTP(S) or domain is missing;
+        None if reference_url is falsy.
+    """
     if not reference_url:
         return None
     parsed = urlparse(reference_url.strip())
@@ -107,6 +148,20 @@ def _safe_reference_url_metadata(reference_url: str | None) -> dict[str, Any] |
 
 
 def _reference_metadata(uploaded: Any, reference_url: str | None, scan: dict[str, Any]) -> list[dict[str, Any]]:
+    """
+    Builds a list of metadata records from an uploaded file and/or reference URL.
+    
+    For an uploaded file, includes basename, SHA-256 hash, size, and scan results (status,
+    export gate, magic, extension). For a reference URL, includes domain, URL hash, and status.
+    
+    Parameters:
+    	uploaded: An uploaded file object, path string, or None.
+    	reference_url: Optional reference URL string.
+    	scan: Dictionary of ST3GG scan results for the uploaded file.
+    
+    Returns:
+    	List of metadata dictionaries for the file and/or URL. Empty if neither is provided.
+    """
     records: list[dict[str, Any]] = []
     path = _file_path(uploaded)
     if path:
@@ -140,6 +195,13 @@ def _creator_controls(
     hardware: str | None = None,
     locate_focus: list[str] | None = None,
 ) -> dict[str, Any]:
+    """
+    Create a control object combining wardrobe selections with generation policy and reasoning configuration.
+    
+    Returns:
+        dict: Nested structure containing reasoning mode, video preset, wardrobe selections with locked slots,
+              and FLUX generation configuration.
+    """
     wardrobe = {
         "silhouette": silhouette or "structured long coat",
         "outerwear": outerwear or "black patent leather long coat",
@@ -163,6 +225,18 @@ def _creator_controls(
 
 
 def _prompt_with_controls(prompt: str, controls: dict[str, Any]) -> str:
+    """
+    Augments a prompt with wardrobe control parameters.
+    
+    If any wardrobe fields are specified in the controls, appends them to the
+    prompt with a "Wardrobe controls:" prefix. Otherwise returns the prompt unchanged.
+    
+    Parameters:
+    	controls (dict[str, Any]): A controls dictionary containing a "wardrobe" key with fields for silhouette, outerwear, upper_body, footwear, palette, and hardware.
+    
+    Returns:
+    	str: The prompt with wardrobe controls appended, or the original prompt if no wardrobe items are specified.
+    """
     wardrobe = controls.get("wardrobe", {})
     additions = [
         wardrobe.get("silhouette"),
@@ -177,12 +251,24 @@ def _prompt_with_controls(prompt: str, controls: dict[str, Any]) -> str:
 
 
 def _generated_output_path(operator_state: dict[str, Any] | None) -> str | None:
+    """
+    Extract the generated artifact output path from the operator state.
+    
+    Returns:
+        The output path string if a generated artifact exists, None otherwise.
+    """
     generation = (operator_state or {}).get("generation") or {}
     output_path = generation.get("output_path")
     return str(output_path) if output_path else None
 
 
 def _authoritative_generated_scan(operator_state: dict[str, Any] | None) -> dict[str, Any]:
+    """
+    Obtain the current scan for a generated artifact.
+    
+    Returns:
+    	dict[str, Any]: A scan record sourced from the generated output file, stored state, or a default scan.
+    """
     output_path = _generated_output_path(operator_state)
     if output_path:
         return scan_file(output_path)
@@ -191,6 +277,15 @@ def _authoritative_generated_scan(operator_state: dict[str, Any] | None) -> dict
 
 
 def _checkpoint_seed(checkpoint_id: str) -> int:
+    """
+    Derives a numeric seed from a checkpoint ID.
+    
+    Parameters:
+        checkpoint_id (str): A checkpoint identifier string.
+    
+    Returns:
+        int: An integer seed bounded to less than 1,000,000, or 0 if no valid seed data can be extracted from the checkpoint ID.
+    """
     suffix = "".join(char for char in checkpoint_id[-8:] if char in "0123456789abcdefABCDEF")
     if not suffix:
         return 0
@@ -201,6 +296,12 @@ def _checkpoint_seed(checkpoint_id: str) -> int:
 
 
 def _wardrobe_summary(run: Any) -> str:
+    """
+    Formats outfit wardrobe slots into a semicolon-separated summary string.
+    
+    Returns:
+        A semicolon-separated string listing each outfit slot's name, description, material, palette, and locked status.
+    """
     slots = getattr(getattr(run, "outfit", None), "slots", []) or []
     return "; ".join(
         f"{slot.name}: {slot.description}, material={slot.material}, palette={slot.palette}, locked={slot.locked}"
@@ -244,6 +345,14 @@ def run_weave(
     hardware: str | None = None,
     reference_url: str | None = None,
 ) -> tuple[Any, ...]:
+    """
+    Execute the complete weaving workflow from prompt through image generation and evaluation.
+    
+    Assembles wardrobe controls, generates an image via FLUX, scans and judges the output through ST3GG scanning and dual judges (Minicpm and Nemotron), and compiles operator state reflecting generation status, checkpoint readiness, and export gating.
+    
+    Returns:
+        Tuple containing dashboard region HTML fragments (topbar, command_rail, workflow, operations, inspector, drawer, status, artifacts, providers), catalog HTML, run data, catalog summary, scan results, operator state with generation details and judge evidence, and button state updates.
+    """
     prompt = prompt.strip() or DEFAULT_PROMPT
     controls = _creator_controls(
         reasoning_mode=reasoning_mode,
@@ -333,6 +442,14 @@ def toggle_adult_visibility(
     active_section: str,
     upload: Any,
 ) -> tuple[Any, ...]:
+    """
+    Update the dashboard to reflect a change in adult content visibility.
+    
+    Re-scans any uploaded file and regenerates all dashboard regions to show or hide adult content while maintaining ST3GG, consent, and export gates.
+    
+    Returns:
+    	tuple: Updated UI fragments and state (topbar, command rail, operations, inspector, artifacts, providers, catalog table, catalog summary, scan metadata, operator state).
+    """
     scan = scan_file(_file_path(upload))
     operator_state = {
         **_default_operator_state(),
@@ -361,10 +478,12 @@ def refresh_section(
     operator_state: dict[str, Any] | None,
 ) -> tuple[str, str, str, str, str, dict[str, Any]]:
     """
-    Updates dashboard regions for the selected navigation section.
-
+    Render dashboard regions for the currently selected navigation section.
+    
     Returns:
-        A tuple containing HTML strings for command_rail, operations, inspector, artifacts, and providers regions, followed by the security scan results.
+        A tuple of (command_rail, operations, inspector, artifacts, providers, scan),
+        where the first five elements are HTML strings for dashboard regions and the last
+        is the ST3GG scan results dictionary.
     """
     scan = scan or scan_file(None)
     regions = _dashboard_regions(
@@ -384,6 +503,25 @@ def _render_stateful(
     active_section: str,
     operator_state: dict[str, Any],
 ) -> tuple[Any, ...]:
+    """
+    Render the dashboard with current state and return all UI outputs and state objects.
+    
+    Ensures scan data exists, calls the dashboard region renderer with current state, and assembles
+    a comprehensive tuple of HTML fragments, state objects, and button updates for Gradio output.
+    
+    Parameters:
+    	run: The current run object, or None if no run is active.
+    	adult_mode: Whether adult-mode visibility is enabled.
+    	scan: Scan/ST3GG evidence dict. If None or falsy, defaults to empty scan from scan_file.
+    	active_section: The currently active dashboard section identifier.
+    	operator_state: Current operator state dict containing provider status, checkpoint, export, and messaging.
+    
+    Returns:
+    	A tuple containing: topbar, command_rail, workflow, operations, inspector, drawer, status,
+    	artifacts, providers (all HTML fragments), catalog table HTML, run dict (or empty dict),
+    	catalog summary, scan dict, operator_state dict, and a Gradio update object for the stop
+    	button (interactive if run exists and provider is neither idle, stopped, nor exported).
+    """
     scan = scan or scan_file(None)
     regions = _dashboard_regions(
         run=run,
@@ -419,6 +557,16 @@ def scan_reference(
     operator_state: dict[str, Any] | None,
     reference_url: str | None = None,
 ) -> tuple[Any, ...]:
+    """
+    Scan and evaluate a reference image or URL, updating the operator state with findings.
+    
+    Parameters:
+        reference_url (str | None): Optional URL for reference metadata validation.
+            Only domain and URL hash are recorded; no content crawling or copying occurs.
+    
+    Returns:
+        Rendered dashboard outputs and the computed generated scan.
+    """
     state = operator_state or _default_operator_state()
     reference_path = _file_path(upload)
     reference_scan = scan_file(reference_path)
@@ -456,6 +604,12 @@ def approve_checkpoint(
     active_section: str,
     operator_state: dict[str, Any] | None,
 ) -> tuple[Any, ...]:
+    """
+    Approves the checkpoint if a run and generated artifact exist, blocking approval otherwise. Sets provider readiness based on the ST3GG export gate status.
+    
+    Returns:
+    	tuple[Any, ...]: Updated dashboard and operator state reflecting the checkpoint decision.
+    """
     state = operator_state or _default_operator_state()
     scan = _authoritative_generated_scan(state)
     if run is None:
@@ -488,6 +642,26 @@ def export_packet(
     operator_state: dict[str, Any] | None,
     override_reason: str | None = None,
 ) -> tuple[Any, ...]:
+    """
+    Prepare an export packet for the generated artifact with precondition validation and ST3GG gating.
+    
+    Validates that a run, approved checkpoint, and generated artifact exist, and checks the
+    ST3GG export gate status. Blocks export if any precondition fails or if the gate is not
+    clear (unless an explicit override reason is provided). Writes a governed export packet
+    when the gate is clear, or an audit-marked packet when overridden.
+    
+    Parameters:
+        run: Active run packet; export is blocked if None.
+        adult_mode: Whether adult content is enabled for the export.
+        scan: ST3GG scan results; checked for export gate status.
+        active_section: Current UI section for rendering.
+        operator_state: Current operator state; defaults to idle state if None.
+        override_reason: Reason to override when ST3GG gate is not clear.
+    
+    Returns:
+        Tuple containing dashboard region HTML, run dict, catalog outputs, scan, operator state,
+        and stop button interactive state.
+    """
     state = operator_state or _default_operator_state()
     scan = _authoritative_generated_scan(state)
     override_reason = (override_reason or "").strip()
@@ -524,6 +698,15 @@ def stop_provider_job(
     active_section: str,
     operator_state: dict[str, Any] | None,
 ) -> tuple[Any, ...]:
+    """
+    Stop the active provider job.
+    
+    Halts the current image generation or provider handoff, preserving local evidence and 
+    the dry-run packet. Re-renders the dashboard with provider state set to stopped.
+    
+    Returns:
+        tuple[Any, ...]: Dashboard region HTML fragments, run dict, scan dict, operator state, and UI control updates.
+    """
     scan = scan or scan_file(None)
     next_state = {
         **(operator_state or _default_operator_state()),
@@ -537,6 +720,12 @@ def reset_demo(
     adult_mode: bool,
     active_section: str,
 ) -> tuple[Any, ...]:
+    """
+    Reset the application to its initial state by clearing all generated evidence and reinitializing operator state.
+    
+    Returns:
+    	tuple[Any, ...]: Dashboard region HTML fragments, catalog table, empty run state, catalog summary, scan state, operator state, and button state for a reset application.
+    """
     scan = scan_file(None)
     operator_state = _default_operator_state()
     regions = _dashboard_regions(adult_mode=adult_mode, scan=scan, active_section=active_section, operator_state=operator_state)

src/nexus_visual_weaver/catalog.py

@@ -204,6 +204,15 @@ PRIVATE_RESEARCH_STACK = [
 
 
 def filter_catalog(adult_mode: bool = False) -> tuple[list[ModelCandidate], list[AdapterRecipe]]:
+    """
+    Filter the model and adapter catalogs based on visibility settings.
+    
+    Parameters:
+    	adult_mode (bool): When False, only public, non-adult content is included. When True, all content is included.
+    
+    Returns:
+    	tuple: (models, adapters) - filtered lists of ModelCandidate and AdapterRecipe objects matching the visibility criteria.
+    """
     models = [
         model
         for model in MODEL_CATALOG
@@ -214,6 +223,12 @@ def filter_catalog(adult_mode: bool = False) -> tuple[list[ModelCandidate], list
 
 
 def active_stack(adult_mode: bool = False) -> list[ModelCandidate]:
+    """
+    Builds the active model stack based on access mode.
+    
+    Returns:
+        list[ModelCandidate]: The active model candidates visible for the given mode.
+    """
     allowed, _ = filter_catalog(adult_mode)
     by_id = {model.repo_id: model for model in allowed}
     stack_ids = PRIVATE_RESEARCH_STACK if adult_mode else DEFAULT_ACTIVE_STACK
@@ -221,6 +236,22 @@ def active_stack(adult_mode: bool = False) -> list[ModelCandidate]:
 
 
 def parameter_budget(stack: list[ModelCandidate] | None = None) -> dict[str, float | str]:
+    """
+    Calculates the parameter budget summary for a model stack.
+    
+    Computes the total parameter count of models in the provided stack,
+    checks it against a 32 billion parameter limit, and returns budget details.
+    
+    Parameters:
+        stack: Model candidates to evaluate. If None, uses the default active stack.
+    
+    Returns:
+        A dictionary with the following keys:
+            - active_b (float): Total parameters in billions
+            - limit_b (float): Budget limit in billions
+            - remaining_b (float): Remaining budget in billions
+            - status (str): "pass" if within budget, "over_budget" otherwise
+    """
     chosen = stack or active_stack(False)
     total = round(sum(model.params_b for model in chosen), 2)
     return {
@@ -232,6 +263,12 @@ def parameter_budget(stack: list[ModelCandidate] | None = None) -> dict[str, flo
 
 
 def catalog_summary(adult_mode: bool = False) -> dict[str, int | float | str]:
+    """
+    Generates a summary of visible catalog entries and active model parameter budget.
+    
+    Returns:
+    	dict: A dictionary containing visible model and adapter counts, adult catalog status ("enabled" or "hidden"), and parameter budget metrics including total budget used, limit, remaining, and status ("pass" or "over_budget").
+    """
     models, adapters = filter_catalog(adult_mode)
     budget = parameter_budget(active_stack(adult_mode))
     return {

src/nexus_visual_weaver/exporter.py

@@ -6,7 +6,7 @@ import json
 import os
 import re
 import time
-from pathlib import Path
+from pathlib import Path, PureWindowsPath
 from typing import Any
 
 from .catalog import active_stack, parameter_budget
@@ -20,6 +20,12 @@ ALLOWED_LOCAL_EXPORT_ROOTS = (
 
 
 def _is_within(path: Path, root: Path) -> bool:
+    """
+    Checks if a path is within a given root directory.
+    
+    Returns:
+        True if the path is within the root directory, False otherwise.
+    """
     try:
         path.relative_to(root)
         return True
@@ -28,6 +34,12 @@ def _is_within(path: Path, root: Path) -> bool:
 
 
 def _safe_export_candidate(candidate: Path) -> Path | None:
+    """
+    Validates and resolves an export directory candidate against allowed roots.
+    
+    Returns:
+        Path | None: The resolved path if within an allowed export root, `None` otherwise.
+    """
     if not candidate.is_absolute():
         candidate = REPO_ROOT / candidate
     resolved = candidate.resolve(strict=False)
@@ -44,6 +56,12 @@ def _safe_export_candidate(candidate: Path) -> Path | None:
 
 
 def _artifact_name(output_path: Any) -> str | None:
+    """
+    Extract the filename from a file path.
+    
+    Returns:
+        filename (str | None): The filename if output_path is provided, None otherwise.
+    """
     if not output_path:
         return None
     return Path(str(output_path)).name
@@ -56,9 +74,15 @@ WINDOWS_PATH_RE = re.compile(r"[A-Za-z]:[\\/][^\s\"']+")
 
 
 def _sanitize_text(value: str) -> str:
+    """
+    Redacts sensitive information and normalizes text for safe export.
+    
+    Returns:
+        str: Text with secrets, credentials, and paths replaced with placeholders, truncated to 1000 characters if necessary.
+    """
     text = SECRET_VALUE_RE.sub("[redacted_secret]", value)
     text = CREDENTIAL_NAME_RE.sub("[redacted_credential_name]", text)
-    text = WINDOWS_PATH_RE.sub(lambda match: f"[local_path]/{Path(match.group(0)).name}", text)
+    text = WINDOWS_PATH_RE.sub(lambda match: f"[local_path]/{PureWindowsPath(match.group(0)).name}", text)
     repo_text = str(REPO_ROOT)
     if repo_text in text:
         text = text.replace(repo_text, "[repo]")
@@ -70,6 +94,20 @@ def _sanitize_text(value: str) -> str:
 
 
 def _safe_dict(value: Any, *, allow_size_bytes: bool = False) -> Any:
+    """
+    Recursively sanitize data structures to remove sensitive keys and redact sensitive values.
+    
+    Dictionary keys matching sensitive patterns are dropped unless the key is 'size_bytes' and 
+    allow_size_bytes is True. Lists are limited to the first 40 elements. String values are sanitized 
+    to remove secrets and credentials. Other types are returned unchanged.
+    
+    Parameters:
+    	allow_size_bytes (bool): If True, preserves the 'size_bytes' key in dictionaries even if it 
+    		matches a sensitive pattern. Defaults to False.
+    
+    Returns:
+    	The sanitized input value with sensitive data redacted and sensitive keys removed.
+    """
     if isinstance(value, dict):
         clean: dict[str, Any] = {}
         for key, item in value.items():
@@ -86,6 +124,13 @@ def _safe_dict(value: Any, *, allow_size_bytes: bool = False) -> Any:
 
 
 def _safe_scan(scan: dict[str, Any]) -> dict[str, Any]:
+    """
+    Extract and sanitize selected fields from a scan dictionary.
+    
+    Returns:
+        A dictionary containing status, scanner, export_gate, extension, magic, 
+        findings, and purification_actions.
+    """
     return {
         "status": scan.get("status"),
         "scanner": scan.get("scanner"),
@@ -98,6 +143,15 @@ def _safe_scan(scan: dict[str, Any]) -> dict[str, Any]:
 
 
 def _safe_provider(provider: dict[str, Any] | None) -> dict[str, Any]:
+    """
+    Normalize provider metadata by extracting safe fields and sanitizing sensitive data.
+    
+    Parameters:
+        provider: Provider metadata dict, or None.
+    
+    Returns:
+        Normalized provider dict with extracted and sanitized fields.
+    """
     provider = provider or {}
     evidence = provider.get("evidence") if isinstance(provider.get("evidence"), dict) else {}
     return {
@@ -113,6 +167,12 @@ def _safe_provider(provider: dict[str, Any] | None) -> dict[str, Any]:
 
 
 def _safe_reference_metadata(records: Any) -> list[dict[str, Any]]:
+    """
+    Filters and sanitizes reference metadata records.
+    
+    Returns:
+        A list of sanitized reference metadata dicts, limited to the first 20 records.
+    """
     if not isinstance(records, list):
         return []
     cleaned: list[dict[str, Any]] = []
@@ -139,6 +199,13 @@ def _safe_reference_metadata(records: Any) -> list[dict[str, Any]]:
 
 
 def export_root() -> Path:
+    """
+    Selects and creates a permitted directory for writing export JSON packets.
+    
+    Returns:
+        Path: An existing export directory, prioritizing environment configuration
+            and system locations over the repository fallback.
+    """
     requested = os.environ.get("NEXUS_EXPORT_DIR")
     candidates = [Path(requested)] if requested else []
     if Path("/data").exists():
@@ -165,6 +232,19 @@ def write_export_packet(
     operator_state: dict[str, Any],
     adult_mode: bool,
 ) -> dict[str, Any]:
+    """
+    Builds a sanitized JSON export packet and writes it to disk.
+    
+    Sanitizes sensitive metadata from run, scan, and operator state, then writes the
+    resulting packet to a controlled export directory.
+    
+    Parameters:
+        run: Run object containing checkpoint, request, model_stack, and refined_prompt data.
+    
+    Returns:
+        Dictionary with "path" (str) pointing to the written JSON file and "packet" (dict)
+        containing the constructed export packet.
+    """
     run_id = getattr(getattr(run, "checkpoint", None), "checkpoint_id", f"nw-{int(time.time())}")
     run_adult_mode = bool(getattr(getattr(run, "request", None), "adult_mode", adult_mode))
     stack = list(getattr(run, "model_stack", None) or active_stack(run_adult_mode))

src/nexus_visual_weaver/hf_runtime.py

@@ -40,6 +40,12 @@ class HFGenerationResult:
     primary_error: str | None = None
 
     def to_dict(self) -> dict[str, Any]:
+        """
+        Convert the result to a dictionary.
+        
+        Returns:
+            The result as a dictionary.
+        """
         return asdict(self)
 
 
@@ -75,10 +81,24 @@ def _short_error(exc: BaseException) -> str:
 
 
 def _hf_token() -> str | None:
+    """
+    Retrieve the HuggingFace authentication token from environment variables.
+    
+    Checks HF_TOKEN first, then HUGGING_FACE_HUB_TOKEN.
+    
+    Returns:
+    	str | None: The token if available, None otherwise.
+    """
     return os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
 
 
 def active_flux_repo_id() -> str:
+    """
+    Determines the FLUX repository ID based on environment configuration.
+    
+    Returns:
+        str: The FLUX repository ID to use for image generation.
+    """
     configured = os.environ.get("NEXUS_FLUX_REPO_ID")
     if configured:
         return configured
@@ -88,6 +108,20 @@ def active_flux_repo_id() -> str:
 
 
 def _repo_candidates(repo_id: str) -> list[str]:
+    """
+    Return a list of repository candidates for generation attempts.
+    
+    The primary repo_id is always included. If repo_id is not the Tiny Titan
+    model and fallback is not disabled via NEXUS_DISABLE_TINY_TITAN_FALLBACK,
+    the Tiny Titan repository is appended as a fallback candidate.
+    
+    Parameters:
+        repo_id (str): The primary FLUX model repository identifier.
+    
+    Returns:
+        list[str]: Repository IDs to attempt, starting with the primary repo
+        and optionally including a fallback candidate.
+    """
     candidates = [repo_id]
     if repo_id != TINY_TITAN_FLUX_REPO_ID and os.environ.get("NEXUS_DISABLE_TINY_TITAN_FALLBACK") != "1":
         candidates.append(TINY_TITAN_FLUX_REPO_ID)
@@ -95,6 +129,18 @@ def _repo_candidates(repo_id: str) -> list[str]:
 
 
 def _get_flux_pipe(repo_id: str, torch_module: Any, pipeline_cls: Any, token: str | None) -> Any:
+    """
+    Get or load a cached FLUX pipeline from a Hugging Face repository.
+    
+    Maintains a thread-safe cache of pipelines keyed by repository ID to avoid repeated loading.
+    
+    Parameters:
+        torch_module: The torch module, providing the dtype for the pipeline.
+        pipeline_cls: The pipeline class (e.g., Flux2KleinPipeline) to instantiate.
+    
+    Returns:
+        A FLUX pipeline instance.
+    """
     with _PIPELINE_CACHE_LOCK:
         cached = _PIPELINE_CACHE.get(repo_id)
         if cached is not None:
@@ -106,12 +152,32 @@ def _get_flux_pipe(repo_id: str, torch_module: Any, pipeline_cls: Any, token: st
 
 
 def _adapter_recipe(repo_id: str | None) -> AdapterRecipe | None:
+    """
+    Retrieves an adapter recipe from the catalog by repository identifier.
+    
+    Returns:
+        AdapterRecipe | None: The matching adapter recipe, or None if no recipe is found.
+    """
     if not repo_id:
         return None
     return next((recipe for recipe in ADAPTER_CATALOG if recipe.repo_id == repo_id), None)
 
 
 def default_lora_repo_id(target_repo_id: str) -> str | None:
+    """
+    Selects the default LoRA adapter compatible with a FLUX repository.
+    
+    Returns the repository ID of the first adapter that is runtime-enabled, is not
+    adult-only, does not require an input image, and is compatible with the target
+    repository.
+    
+    Parameters:
+        target_repo_id (str): The FLUX repository ID to find a compatible adapter for.
+    
+    Returns:
+        The repository ID of the first matching adapter, or `None` if no compatible
+        adapter is found.
+    """
     for recipe in ADAPTER_CATALOG:
         compatible_ids = {recipe.adapter_for, *recipe.compatible_repo_ids}
         if recipe.runtime_enabled and not recipe.adult_only and not recipe.requires_image and target_repo_id in compatible_ids:
@@ -129,6 +195,12 @@ def generate_flux_image(
     lora_repo_id: str | None = None,
     adult_mode: bool = False,
 ) -> HFGenerationResult:
+    """
+    Generate a FLUX.2 image from a text prompt with optional LoRA adapter application.
+    
+    Returns:
+        HFGenerationResult: Immutable container with generation status, image output path, execution latency, and LoRA application results.
+    """
     repo_id = active_flux_repo_id()
     selected_lora = lora_repo_id if lora_repo_id is not None else default_lora_repo_id(repo_id)
     recipe = _adapter_recipe(selected_lora)

src/nexus_visual_weaver/lora_adapter.py

@@ -9,6 +9,12 @@ from .schema import AdapterRecipe
 
 
 def _status(status: str, recipe: AdapterRecipe | None = None, **extra: Any) -> dict[str, Any]:
+    """
+    Build a status dictionary with adapter metadata and additional fields.
+    
+    Returns:
+        dict[str, Any]: A dictionary containing the status and optional recipe fields (repo_id, adapter_for, weight), merged with any extra keyword arguments.
+    """
     payload: dict[str, Any] = {
         "status": status,
         "repo_id": recipe.repo_id if recipe else None,
@@ -20,6 +26,18 @@ def _status(status: str, recipe: AdapterRecipe | None = None, **extra: Any) -> d
 
 
 def _short_error(exc: BaseException) -> str:
+    """
+    Format an exception message with truncation for compact display.
+    
+    Returns the exception class name and message as "{ClassName}: {message}",
+    truncated to 240 characters.
+    
+    Parameters:
+        exc (BaseException): The exception to format.
+    
+    Returns:
+        str: The formatted exception message.
+    """
     text = str(exc).replace("\n", " ").strip()
     if len(text) > 240:
         text = text[:237] + "..."
@@ -27,10 +45,24 @@ def _short_error(exc: BaseException) -> str:
 
 
 def adapter_to_dict(recipe: AdapterRecipe) -> dict[str, Any]:
+    """
+    Convert an AdapterRecipe instance to a dictionary.
+    
+    Returns:
+    	dict[str, Any]: Dictionary representation of the recipe's fields.
+    """
     return asdict(recipe)
 
 
 def is_compatible(pipe: Any, recipe: AdapterRecipe, target_repo_id: str, *, adult_mode: bool = False) -> bool:
+    """
+    Determines whether a LoRA adapter is compatible with a pipeline and target model.
+    
+    Returns:
+        `true` if the recipe is runtime-enabled, not blocked by adult-mode restrictions,
+        does not require image input, the pipeline has LoRA support, and the target model
+        is compatible; `false` otherwise.
+    """
     if not recipe.runtime_enabled:
         return False
     if recipe.adult_only and not adult_mode:
@@ -54,6 +86,16 @@ def load_and_apply(
     adult_mode: bool = False,
     adapter_name: str = "nexus_style",
 ) -> dict[str, Any]:
+    """
+    Load and apply a LoRA adapter to a pipeline when permitted, returning structured operation status.
+    
+    Parameters:
+        recipe: Adapter configuration. If None, the function returns a disabled status without attempting to load.
+        target_repo_id: The model repository ID to verify adapter compatibility against.
+    
+    Returns:
+        A dictionary with keys: status (disabled, skipped_incompatible, unsupported_pipeline, loaded, or failed), repo_id, adapter_for, weight, adapter_name, and message.
+    """
     if recipe is None:
         return _status("disabled", message="No LoRA adapter selected for this run.")
     if recipe.adult_only and not adult_mode:
@@ -78,6 +120,9 @@ def load_and_apply(
 
 
 def unload_all(pipe: Any) -> None:
+    """
+    Unload all LoRA adapter weights from the pipeline if supported.
+    """
     try:
         if hasattr(pipe, "unload_lora_weights"):
             pipe.unload_lora_weights()

src/nexus_visual_weaver/model_relay.py

@@ -179,6 +179,14 @@ class WeaverModelRelay:
         public_demo: bool = True,
         strategy: str = "quality_first",
     ) -> LaneDecision:
+        """
+        Selects a helper model for the given lane based on budget, quota, and selection strategy.
+        
+        Returns:
+            LaneDecision: A decision containing the selected primary model (if any), fallback
+                options, the selection strategy used, selection reasoning, expected cost estimate,
+                quota impact details, and information about skipped ineligible candidates.
+        """
         lane = self.normalize_lane(lane)
         strategy = self.normalize_strategy(strategy)
         budget_b = float(budget if budget is not None else (32.0 if lane in PINNED_LANES else DEFAULT_ROTATION_BUDGET_B))
@@ -430,6 +438,12 @@ class WeaverModelRelay:
 
 
 def default_model_records() -> list[ModelRecord]:
+    """
+    Provides the default registry of helper models across all lanes.
+    
+    Returns:
+    	list[ModelRecord]: A list of preconfigured model records spanning pinned lanes (image_generation, grounding, security) and rotatable lanes (prompt_router, taste_judge, audio_lore_tts, video_repair, hf_catalog_research, modal_job_runner, private_image_research), each with quota limits, performance metrics, and fallback chains.
+    """
     return [
         ModelRecord(
             model_id="flux2-klein-9b-quality",

src/nexus_visual_weaver/planner.py

@@ -20,6 +20,20 @@ def build_command_center_run(
     creator_controls: dict | None = None,
     reference_metadata: list[dict] | None = None,
 ) -> GenerationRun:
+    """
+    Assemble a complete generation run by processing a creative prompt through refinement, outfit generation, inspection, and planning stages, then recommend approval or revision via a human checkpoint.
+    
+    Parameters:
+        prompt: The creative prompt to generate from.
+        mode: Operation mode (e.g., "Strict", "Frontier"); determines checkpoint requirements.
+        video_preset: Video generation preset identifier.
+        adult_mode: Whether to enable adult content handling.
+        creator_controls: Optional dictionary of creator-specified controls (e.g., wardrobe preferences).
+        reference_metadata: Optional list of reference metadata dictionaries with id, basename, or url_hash keys.
+    
+    Returns:
+        A GenerationRun containing the refined prompt, generated outfit, inspection results, model stack, adapters, video plan, lore components, and a human checkpoint with approval recommendation based on a computed trust score.
+    """
     controls = creator_controls or {}
     references = reference_metadata or []
     request = CreativeRequest(

src/nexus_visual_weaver/provider_runtime.py

@@ -31,10 +31,22 @@ class ProviderJudgeResult:
     latency_seconds: float | None = None
 
     def to_dict(self) -> dict[str, Any]:
+        """
+        Convert the dataclass instance to a dictionary.
+        
+        Returns:
+        	dict[str, Any]: A dictionary representation of the dataclass fields.
+        """
         return asdict(self)
 
 
 def _short_error(exc: BaseException) -> str:
+    """
+    Format an exception as a compact single-line error string.
+    
+    Returns:
+    	A string with the exception class name and message, truncated to approximately 360 characters.
+    """
     text = str(exc).replace("\n", " ").strip()
     if len(text) > 360:
         text = text[:357] + "..."
@@ -42,6 +54,12 @@ def _short_error(exc: BaseException) -> str:
 
 
 def _image_data_url(path: str | None) -> str | None:
+    """
+    Generates a data URL from a local image file.
+    
+    Returns:
+        A data URL string if the file exists and is readable, None otherwise.
+    """
     if not path:
         return None
     target = Path(path)
@@ -57,6 +75,19 @@ def _image_data_url(path: str | None) -> str | None:
 
 
 def _post_json(url: str, token: str, payload: dict[str, Any], timeout: float) -> dict[str, Any]:
+    """
+    Send an authenticated JSON POST request and return the parsed response.
+    
+    Raises ValueError if the URL is not an HTTP or HTTPS URL with a host.
+    
+    Parameters:
+    	token (str): Authorization credential passed through the request header
+    	payload (dict[str, Any]): Data to send as JSON in the request body
+    	timeout (float): Request timeout in seconds
+    
+    Returns:
+    	dict[str, Any]: Parsed JSON response body
+    """
     parsed = urllib.parse.urlparse(url)
     if parsed.scheme not in {"http", "https"} or not parsed.netloc:
         raise ValueError(f"Invalid URL: expected http(s) URL with host, got {url!r}.")
@@ -75,6 +106,17 @@ def _post_json(url: str, token: str, payload: dict[str, Any], timeout: float) ->
 
 
 def _extract_content(response: dict[str, Any]) -> str:
+    """
+    Extract the message content from a chat-completions-style response.
+    
+    If the extracted content is a string, returns it as-is. If it is another type, serializes it to JSON. Returns an empty string if no choices are present in the response.
+    
+    Parameters:
+        response: A dictionary representing a chat-completions API response.
+    
+    Returns:
+        The extracted content as a string, or an empty string if unavailable.
+    """
     choices = response.get("choices") or []
     if not choices:
         return ""
@@ -86,6 +128,14 @@ def _extract_content(response: dict[str, Any]) -> str:
 
 
 def _safe_json_from_text(text: str) -> dict[str, Any]:
+    """
+    Extract and parse a JSON object from text, falling back to raw text summary.
+    
+    Attempts to parse JSON from the input, extracting the outermost braces-delimited substring if necessary. If parsing fails or the result is not a dictionary, returns a dictionary with the input text (first 1200 characters) under the "raw_summary" key. Returns an empty dictionary if the input is empty after whitespace stripping.
+    
+    Returns:
+        dict[str, Any]: Parsed JSON object if valid, or a dictionary with "raw_summary" key and text if parsing fails or result is not a dict.
+    """
     stripped = text.strip()
     if not stripped:
         return {}
@@ -108,6 +158,23 @@ def judge_with_minicpm(
     wardrobe_summary: str,
     timeout: float = 45.0,
 ) -> ProviderJudgeResult:
+    """
+    Evaluate a generated image against visual and wardrobe requirements using MiniCPM-V.
+    
+    Configuration is read from environment variables: MINICPM_BASE_URL, MINICPM_API_KEY 
+    (or OPENBMB_API_KEY), and optionally MINICPM_MODEL.
+    
+    Parameters:
+        prompt (str): Brief describing the visual and style requirements.
+        image_path (str | None): Path to the generated image file.
+        scan (dict[str, Any]): Metadata including 'export_gate' status.
+        wardrobe_summary (str): Wardrobe context and constraints.
+        timeout (float): Request timeout in seconds. Default is 45.0.
+    
+    Returns:
+        ProviderJudgeResult: A result object with judgment status (success, failed, 
+        missing_secret, no_artifact), provider metadata, evidence dict, and request latency.
+    """
     base_url = os.environ.get("MINICPM_BASE_URL", "").rstrip("/")
     token = os.environ.get("MINICPM_API_KEY") or os.environ.get("OPENBMB_API_KEY")
     model = os.environ.get("MINICPM_MODEL", "MiniCPM-V-4.6")
@@ -187,6 +254,20 @@ def judge_with_nemotron(
     minicpm_result: dict[str, Any] | None = None,
     timeout: float = 45.0,
 ) -> ProviderJudgeResult:
+    """
+    Call Nemotron to generate structured evidence for a visual creation run.
+    
+    Returns a standardized ProviderJudgeResult with status "success" (including parsed
+    evidence and measured latency), "missing_secret" if credentials are not configured,
+    or "failed" if the API call encounters an error.
+    
+    Parameters:
+        minicpm_result (dict[str, Any] | None): Optional prior judgment output from MiniCPM.
+        timeout (float): Request timeout in seconds (default: 45.0).
+    
+    Returns:
+        ProviderJudgeResult: Result with status, evidence, and measured latency.
+    """
     base_url = os.environ.get("NEMOTRON_BASE_URL", "").rstrip("/")
     token = os.environ.get("NEMOTRON_API_KEY") or os.environ.get("NVIDIA_API_KEY")
     model = os.environ.get("NEMOTRON_MODEL", "nvidia/NVIDIA-Nemotron-Parse-v1.2")

src/nexus_visual_weaver/render.py

@@ -12,6 +12,16 @@ from .schema import GenerationRun
 
 
 def badge(label: str, tone: str = "neutral") -> str:
+    """
+    Generate an HTML badge element with a tone-specific CSS class.
+    
+    Parameters:
+        label (str): The badge text content.
+        tone (str): A CSS class modifier for the badge style; defaults to "neutral".
+    
+    Returns:
+        str: An HTML span element with the specified tone class.
+    """
     return f'<span class="nw-badge nw-{tone}">{escape(label)}</span>'
 
 
@@ -45,10 +55,23 @@ def _metric(label: str, value: str, tone: str = "neutral") -> str:
 
 
 def _env_configured(*names: str) -> bool:
+    """
+    Determine whether any of the provided environment variables are set and truthy.
+    
+    Returns:
+        True if any of the environment variables exists and is truthy, False otherwise.
+    """
     return any(bool(os.environ.get(name)) for name in names)
 
 
 def _provider_configured(base_url_name: str, *key_names: str) -> bool:
+    """
+    Determines if a provider is configured with both a base URL and authentication keys.
+    
+    Returns:
+        True if the base URL environment variable is set and at least one of the
+        provided key environment variables is set, False otherwise.
+    """
     return bool(os.environ.get(base_url_name)) and _env_configured(*key_names)
 
 
@@ -64,6 +87,17 @@ _SCAN_REDACTION_TERMS = (
 
 
 def _redact_scan_text(value: object) -> str:
+    """
+    Sanitizes scan text by redacting sensitive content and truncating excessively long values.
+    
+    Parameters:
+        value (object): A scan detail to sanitize.
+    
+    Returns:
+        str: A redaction notice if the text contains sensitive terms; the original text truncated
+             to 177 characters plus "..." if it exceeds 180 characters; otherwise the original
+             text converted to a string.
+    """
     text = str(value)
     lowered = text.lower()
     if any(term in lowered for term in _SCAN_REDACTION_TERMS):
@@ -74,6 +108,12 @@ def _redact_scan_text(value: object) -> str:
 
 
 def _space_runtime_status() -> dict[str, str]:
+    """
+    Determines the current runtime environment and active provider configuration.
+    
+    Returns:
+        dict[str, str]: A dict with `space_id`, `hardware`, `bucket`, and `secrets` keys describing the deployment context and configured provider secrets.
+    """
     space_id = os.environ.get("SPACE_ID") or os.environ.get("HF_SPACE_ID") or "local-preview"
     hardware = os.environ.get("SPACE_HARDWARE") or os.environ.get("NEXUS_SPACE_HARDWARE") or "ZeroGPU"
     bucket = "/data mounted" if os.path.isdir("/data") else "bucket optional"
@@ -96,6 +136,12 @@ def _space_runtime_status() -> dict[str, str]:
 
 
 def _image_data_uri(path: str | None) -> str | None:
+    """
+    Create a data URI string from a file's contents, selecting MIME type by extension.
+    
+    Returns:
+    	data_uri (str | None): A data URI string with base64-encoded file contents if the path exists and is readable; `None` otherwise. MIME type is determined by file extension (.png, .jpg/.jpeg, .webp; otherwise application/octet-stream).
+    """
     if not path:
         return None
     target = Path(path)
@@ -108,6 +154,12 @@ def _image_data_uri(path: str | None) -> str | None:
 
 
 def render_command_header() -> str:
+    """
+    Render the command header section of the dashboard.
+    
+    Returns:
+        An HTML string containing the command header, description, and status badges.
+    """
     return f"""
     <section class="nw-command-header">
       <div>
@@ -127,12 +179,24 @@ def render_command_header() -> str:
 
 
 def render_trust_strip(scan: dict | None = None, operator_state: dict | None = None) -> str:
+    """
+    Renders a trust model strip showing scan findings, export gate status, and safety checkpoint state.
+    
+    Returns:
+        An HTML string for the trust strip section containing badge cards with redacted scan details.
+    """
     scan = scan or {"status": "idle", "export_gate": "pending", "findings": [], "purification_actions": []}
     operator_state = operator_state or {}
     status = str(scan.get("status", "idle")).upper()
     export_gate = str(scan.get("export_gate", "pending")).upper()
     checkpoint = str(operator_state.get("checkpoint", "pending")).replace("_", " ").title()
-    findings = [_redact_scan_text(item) for item in (scan.get("findings") or ["No upload selected. Always-on scanner ready."])]
+    raw_findings = scan.get("findings")
+    if raw_findings is None:
+        default_finding = "No upload selected. Always-on scanner ready." if status == "IDLE" else "No findings."
+        raw_findings = [default_finding]
+    elif not raw_findings:
+        raw_findings = ["No findings." if status != "IDLE" else "No upload selected. Always-on scanner ready."]
+    findings = [_redact_scan_text(item) for item in raw_findings]
     actions = [_redact_scan_text(item) for item in (scan.get("purification_actions") or [
         "strip metadata before export",
         "truncate PNG after IEND when needed",
@@ -161,13 +225,15 @@ def render_topbar(
     operator_state: dict | None = None,
 ) -> str:
     """
-    Renders the application topbar with budget metrics, relay status, and adult mode controls.
+    Render the dashboard topbar with budget metrics, relay status, adult mode controls, and trust model information.
     
     Parameters:
-        relay_status: Dictionary containing relay rotation safety information. Defaults to empty if None.
+        relay_status: Dictionary with relay rotation safety information.
+        scan: Dictionary with scan status and findings.
+        operator_state: Dictionary with operator checkpoint and provider state.
     
     Returns:
-        HTML markup for the topbar section including brand, project, parameter budget meter, connection status, and mode indicators.
+        HTML markup for the topbar and trust strip sections.
     """
     summary = catalog_summary(adult_mode)
     active = float(summary["active_b"])
@@ -218,6 +284,12 @@ def render_left_rail(active_section: str = "Forge") -> str:
 
 
 def render_command_rail(active_section: str = "Forge") -> str:
+    """
+    Render a contextual command rail for the selected section.
+    
+    Returns:
+    	str: An HTML string with the command rail displaying the section's title, description, and selection badge.
+    """
     section = escape(active_section)
     hints = {
         "Forge": ("Active Weave", "Prompt, judge, locate, generate, checkpoint."),
@@ -238,6 +310,22 @@ def render_command_rail(active_section: str = "Forge") -> str:
 
 
 def render_workflow(run: GenerationRun | None = None, operator_state: dict | None = None) -> str:
+    """
+    Render an SVG workflow diagram and console showing the generation pipeline.
+    
+    The diagram visualizes a multi-stage workflow (seed prompt, refine, judge, locate, generate, video, checkpoint)
+    with nodes, edges, and status indicators. Node content and labels reflect the provided run and operator context.
+    
+    Parameters:
+    	run: GenerationRun object providing run-specific values for trust score, checkpoint ID, model labels,
+    	     video preset, and required actions. Defaults to mock values if None.
+    	operator_state: Dict containing operator context including checkpoint status, provider state, recommendation,
+    	                 and message. Defaults to an empty dict.
+    
+    Returns:
+    	str: HTML section containing SVG workflow graph, legend badges, and console cards with checkpoint,
+    	     action, model lane, and signal information.
+    """
     operator_state = operator_state or {}
     score = run.checkpoint.trust_score if run else 0.82
     checkpoint_id = run.checkpoint.checkpoint_id if run else "nw-dry-run"
@@ -345,6 +433,24 @@ def render_workflow(run: GenerationRun | None = None, operator_state: dict | Non
 
 
 def render_artifact_lane(run: GenerationRun | None = None, scan: dict | None = None, operator_state: dict | None = None) -> str:
+    """
+    Render an artifact preview panel with generated output and status cards.
+    
+    Displays the current artifact output (if available from a provider call), preview metadata 
+    about checkpoint and export status, and a grid of artifact cards showing progress through 
+    generation stages. Supports both dry-run and live provider output scenarios.
+    
+    Parameters:
+        run (GenerationRun | None): Generation run with output image path, refined prompt, and continuity data. 
+            If None, shows dry-run placeholder content.
+        scan (dict | None): Security scan state with status and export gate information.
+            Defaults to {"status": "idle", "export_gate": "pending"}.
+        operator_state (dict | None): Operator context including checkpoint status, provider state, and generated output.
+            Defaults to {}.
+    
+    Returns:
+        str: HTML markup for the artifact preview section.
+    """
     scan = scan or {"status": "idle", "export_gate": "pending"}
     operator_state = operator_state or {}
     prompt_label = "Prompt proof"
@@ -431,14 +537,15 @@ def render_operations_panel(
     """
     Render an operations panel with section-specific operation cards.
     
-    Generates an HTML section containing three operation cards tailored to the selected section.
-    Card content includes operational details drawn from run, scan, and relay status data.
+    Generates an HTML section containing three operation cards tailored to the selected section,
+    with content drawn from run state, scan results, relay decisions, and operator context.
     Invalid section names default to "Forge".
     
     Parameters:
     	active_section (str): The section name determining which operation cards to display.
     		Valid sections are "Forge", "Wardrobe", "Lore", "Models", "Security", and "Runs".
     	adult_mode (bool): If True, scope label is "Private research scope"; otherwise "Public demo scope".
+    	operator_state (dict | None): Operator context dict with "provider_state" and "message" keys.
     
     Returns:
     	str: HTML string representing the operations panel section.
@@ -531,6 +638,12 @@ def _short_repo(repo_id: str) -> str:
 
 
 def _render_relay_panel(relay_status: dict | None = None) -> str:
+    """
+    Render an HTML panel summarizing model relay decisions and pinned lanes.
+    
+    Returns:
+    	str: An HTML string containing the GMR panel with pinned core lanes, up to two decisions, and dedup metrics.
+    """
     relay_status = relay_status or {}
     pinned = relay_status.get("pinned", {})
     decisions = relay_status.get("decisions", [])
@@ -577,14 +690,16 @@ def _render_relay_panel(relay_status: dict | None = None) -> str:
 
 def render_provider_cards(relay_status: dict | None = None, adult_mode: bool = False) -> str:
     """
-    Render provider handoff cards based on relay decisions and operational mode.
+    Generates an HTML panel displaying provider cards with operational status and licensing information.
+    
+    Constructs cards for each relay-decided provider showing the lane, repository, provider name, license gate status, and health meter. Includes optional provider cards for off-by-default gateways. The panel header shows the current operational mode (private research or public demo).
     
     Parameters:
-    	relay_status (dict | None): Relay status containing provider decisions with quota and license gate information.
-    	adult_mode (bool): If True, displays "PRIVATE RESEARCH" label; otherwise "PUBLIC DEMO SAFE".
+        relay_status (dict | None): Relay status containing provider decisions with quota impact and license gate data. If None, defaults to empty dict.
+        adult_mode (bool): If True, displays "PRIVATE RESEARCH" mode label; otherwise displays "PUBLIC DEMO SAFE".
     
     Returns:
-    	str: HTML section markup for the provider cards panel.
+        str: HTML section markup for the provider cards panel.
     """
     relay_status = relay_status or {}
     decisions = relay_status.get("decisions", [])
@@ -646,6 +761,12 @@ def render_provider_cards(relay_status: dict | None = None, adult_mode: bool = F
 
 
 def _scan_status_tone(scan_status: str) -> str:
+    """
+    Map a scan status to a display tone.
+    
+    Returns:
+        str: "pass" if status is "pass", "warn" if status is "review" or "error", "muted" otherwise.
+    """
     if scan_status == "pass":
         return "pass"
     if scan_status in {"review", "error"}:
@@ -659,6 +780,12 @@ def render_inspector(
     relay_status: dict | None = None,
     operator_state: dict | None = None,
 ) -> str:
+    """
+    Render an inspector sidebar with taste profile, material checklist, model stack, sponsor evidence, and ST3GG scan details.
+    
+    Returns:
+        str: HTML markup for the inspector panel.
+    """
     if run:
         checks = [
             ("Patent Leather", True),
@@ -862,19 +989,18 @@ def render_dashboard_regions(
     operator_state: dict | None = None,
 ) -> dict[str, str]:
     """
-    Render all dashboard UI regions.
-    
-    Returns a dictionary of HTML strings, each representing a rendered dashboard region.
+    Assemble all dashboard UI regions into a dictionary of HTML markup.
     
     Parameters:
-        run: A generation run, or None for dry-run defaults.
+        run: A generation run or None.
         adult_mode: Whether to render adult-mode content.
-        scan: Scanner status and findings, or None for idle defaults.
-        relay_status: Model relay configuration and decisions, or None for defaults.
+        scan: Scanner status and findings or None.
+        relay_status: Model relay configuration or None.
         active_section: The currently active navigation section.
+        operator_state: Operator control state or None.
     
     Returns:
-        dict[str, str]: HTML markup strings keyed by region name (topbar, rail, command_rail, workflow, operations, inspector, drawer, status, artifacts, providers).
+        dict[str, str]: HTML markup strings for each dashboard region.
     """
     return {
         "topbar": render_topbar(adult_mode, relay_status, scan, operator_state),

src/nexus_visual_weaver/wardrobe.py

@@ -18,6 +18,17 @@ SLOT_BLUEPRINTS: list[tuple[str, str, str, str, str]] = [
 
 
 def build_outfit_graph(prompt: str, adult_mode: bool = False, controls: dict | None = None) -> OutfitGraph:
+    """
+    Constructs an outfit graph with wardrobe slots configured by prompt analysis and optional controls.
+    
+    Parameters:
+    	prompt (str): Text to analyze for slot configuration and locking keywords.
+    	adult_mode (bool): If True, marks upper_body and lower_body slots as adult-only. Defaults to False.
+    	controls (dict | None): Optional configuration dict with keys: locked_slots, locate_focus, outerwear, upper_body, footwear, hardware, palette.
+    
+    Returns:
+    	OutfitGraph: Graph containing configured wardrobe slots and a computed score.
+    """
     lowered = prompt.lower()
     controls = controls or {}
     locked_slots = set(controls.get("locked_slots") or [])

tests/test_app_callbacks.py

@@ -1,4 +1,6 @@
 import app
+import hashlib
+from pathlib import Path
 from nexus_visual_weaver.planner import build_command_center_run
 
 
@@ -43,6 +45,21 @@ def test_checkpoint_seed_uses_only_last_8_chars() -> None:
     assert result == int("11223344", 16) % 1_000_000
 
 
+def test_safe_file_hash_streams_digest_and_size() -> None:
+    payload = b"nexus-visual-weaver" * 1024
+    target = Path("outputs/test-hash-reference.bin")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(payload)
+
+    try:
+        digest, size = app._safe_file_hash(str(target))
+
+        assert digest == hashlib.sha256(payload).hexdigest()
+        assert size == len(payload)
+    finally:
+        target.unlink(missing_ok=True)
+
+
 # --- _wardrobe_summary tests ---
 
 def test_wardrobe_summary_returns_string_with_slot_fields() -> None:

tests/test_command_center.py

@@ -74,6 +74,9 @@ def test_public_stack_uses_flux_9b_and_excludes_offellia() -> None:
 
 
 def test_private_catalog_keeps_stronger_research_models_available() -> None:
+    """
+    Verify that private catalog mode includes OFFELLIA and other research models alongside standard models.
+    """
     private_models, _ = filter_catalog(True)
     repo_ids = {model.repo_id for model in private_models}
 
@@ -259,6 +262,14 @@ def test_render_trust_strip_pass_scan_shows_clear_export() -> None:
     assert "all checks passed" in html
 
 
+def test_render_trust_strip_clean_empty_findings_shows_no_findings() -> None:
+    scan = {"status": "pass", "export_gate": "clear", "findings": [], "purification_actions": []}
+    html = render_trust_strip(scan=scan)
+
+    assert "No findings." in html
+    assert "No upload selected. Always-on scanner ready." not in html
+
+
 def test_render_trust_strip_review_scan_shows_blocked_export() -> None:
     scan = {"status": "review", "export_gate": "blocked", "findings": ["trailing data after IEND"], "purification_actions": ["truncate PNG"]}
     html = render_trust_strip(scan=scan)

tests/test_exporter.py

@@ -6,6 +6,15 @@ from nexus_visual_weaver.planner import build_command_center_run
 
 
 def _make_base_state(**overrides):
+    """
+    Create a test operator state payload with optional field overrides.
+    
+    Parameters:
+    	**overrides: Fields to override in the base state dictionary.
+    
+    Returns:
+    	dict: A dictionary containing operator state data for export packet testing.
+    """
     state = {
         "provider_state": "export_ready",
         "checkpoint": "approved",
@@ -189,6 +198,12 @@ def test_export_root_falls_back_to_outputs_when_no_env(monkeypatch) -> None:
     original_exists = Path.exists
 
     def patched_exists(self):
+        """
+        Custom exists check that treats "/data" as non-existent.
+        
+        Returns:
+        	False if the path is "/data", otherwise the original exists check result.
+        """
         if str(self) == "/data":
             return False
         return original_exists(self)
@@ -271,6 +286,25 @@ def test_export_packet_redacts_raw_payload_paths_and_secret_like_values(monkeypa
     assert payload["provider_states"]["minicpm"] == "failed"
 
 
+def test_export_packet_redacts_windows_backslash_paths_on_linux(monkeypatch) -> None:
+    monkeypatch.setenv("NEXUS_EXPORT_DIR", "outputs/test-exports")
+    run = build_command_center_run("redaction brief")
+    scan = {
+        "status": "review",
+        "export_gate": "blocked",
+        "findings": [r"raw hidden bytes at C:\Users\speci.000\Downloads\thing.png"],
+        "purification_actions": [],
+    }
+    state = _make_base_state()
+
+    result = write_export_packet(run=run, scan=scan, operator_state=state, adult_mode=False)
+    payload = json.loads(Path(result["path"]).read_text(encoding="utf-8"))
+    serialized = json.dumps(payload)
+
+    assert r"C:\Users\speci.000\Downloads" not in serialized
+    assert "[local_path]/thing.png" in serialized
+
+
 def test_export_packet_records_st3gg_override_reason(monkeypatch) -> None:
     monkeypatch.setenv("NEXUS_EXPORT_DIR", "outputs/test-exports")
     run = build_command_center_run("gothic patent leather platform boots")

tests/test_lora_adapter.py

@@ -9,9 +9,15 @@ class FakeLoraPipe:
         self.unloaded = False
 
     def load_lora_weights(self, repo_id: str, **kwargs) -> None:
+        """
+        Record a call to load LoRA weights for later assertion in tests.
+        """
         self.loaded.append((repo_id, kwargs))
 
     def set_adapters(self, adapter_names: list[str], adapter_weights: list[float]) -> None:
+        """
+        Store adapter names and their corresponding weights for later inspection.
+        """
         self.adapters = (adapter_names, adapter_weights)
 
     def unload_lora_weights(self) -> None: