chore(tests): stop tracking HF enrichment baseline snapshots

Remove tests/enrich_hf_validation/baselines/ from git tracking (.gitignore entry + git rm --cached). These contain README snapshots from community HF repos that may include NSFW/sensitive content. Local files are preserved on disk for offline reference.
chore(tests): update bash code block tests to match preserved-bash behavior
2026-08-08 23:10:15 -03:00 · 2026-07-06 01:08:25 +08:00 · 2026-07-06 01:02:04 +08:00 · 2026-07-06 00:40:35 +08:00 · 2026-07-06 00:34:18 +08:00 · 2026-07-06 00:10:30 +08:00
60 changed files with 7415 additions and 787 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -36,3 +36,7 @@ vue-widgets/dist/

 # Working/research notes (not committed)
 .docs/
+
+# HF enrichment validation baseline snapshots (contain potentially
+# NSFW README content fetched from community model repos)
+tests/enrich_hf_validation/baselines/
--- a/locales/de.json
+++ b/locales/de.json
@@ -662,7 +662,15 @@
            "title": "KI-Anbieter",
            "provider": "Anbieter",
            "providerHelp": "Wählen Sie Ihren LLM-Anbieter. OpenAI und Ollama verwenden voreingestellte API-Endpunkte. Mit \"Benutzerdefiniert\" können Sie jeden OpenAI-kompatiblen Endpunkt angeben.",
-            "custom": "Benutzerdefiniert (OpenAI-kompatibel)",
+            "providerOptions": {
+                "openai": "OpenAI",
+                "ollama": "Ollama (lokal)",
+                "deepseek": "DeepSeek",
+                "groq": "Groq",
+                "openrouter": "OpenRouter",
+                "opencode-go": "OpenCode Go",
+                "custom": "Benutzerdefiniert (OpenAI-kompatibel)"
+            },
            "apiBase": "API-Basis-URL",
            "apiBaseHelp": "Die Basis-URL für die LLM-API (z.B. https://api.openai.com/v1). Leer lassen, um die Anbietervoreinstellung zu verwenden.",
            "apiBasePlaceholder": "https://api.openai.com/v1",
@@ -673,7 +681,8 @@
            "apiKeyConfigured": "Konfiguriert",
            "apiKeySet": "Einrichten",
            "model": "Modell",
-            "modelHelp": "Der zu verwendende Modellname (z.B. deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). Prüfen Sie Ihren Anbieter auf verfügbare Modelle."
+            "modelHelp": "Der zu verwendende Modellname (z.B. deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). Prüfen Sie Ihren Anbieter auf verfügbare Modelle.",
+            "modelPlaceholder": "Modell auswählen..."
        }
    },
    "loras": {
@@ -772,7 +781,7 @@
                "complete": "Automatische Organisation abgeschlossen",
                "error": "Fehler: {error}"
            },
-            "enrichHfAgent": "Metadaten mit KI anreichern"
+            "enrichHfAgent": "HF-Metadaten mit KI anreichern"
        },
        "contextMenu": {
            "refreshMetadata": "Civitai-Daten aktualisieren",
@@ -797,7 +806,7 @@
            "viewAllLoras": "Alle LoRAs anzeigen",
            "downloadMissingLoras": "Fehlende LoRAs herunterladen",
            "deleteRecipe": "Rezept löschen",
-            "enrichHfAgent": "Metadaten mit KI anreichern"
+            "enrichHfAgent": "HF-Metadaten mit KI anreichern"
        }
    },
    "recipes": {
--- a/locales/en.json
+++ b/locales/en.json
@@ -661,10 +661,18 @@
    "aiProvider": {
      "title": "AI Provider",
      "provider": "Provider",
-      "providerHelp": "Choose your LLM provider. OpenAI and Ollama use preset API endpoints. Custom lets you specify any OpenAI-compatible endpoint.",
-      "custom": "Custom (OpenAI-compatible)",
+      "providerHelp": "Choose your LLM provider. Preset providers set the API base URL automatically. Custom lets you specify any OpenAI-compatible endpoint.",
+      "providerOptions": {
+        "openai": "OpenAI",
+        "ollama": "Ollama (local)",
+        "deepseek": "DeepSeek",
+        "groq": "Groq",
+        "openrouter": "OpenRouter",
+        "opencode-go": "OpenCode Go",
+        "custom": "Custom (OpenAI-compatible)"
+      },
      "apiBase": "API Base URL",
-      "apiBaseHelp": "The base URL for the LLM API (e.g. https://api.openai.com/v1). Leave empty to use the provider default.",
+      "apiBaseHelp": "The base URL for the LLM API. Select a preset or enter a custom URL. The dropdown shows presets for all supported providers.",
      "apiBasePlaceholder": "https://api.openai.com/v1",
      "apiKey": "API Key",
      "apiKeyHelp": "Your LLM provider API key. Stored locally, never sent to any server except your chosen LLM provider.",
@@ -673,7 +681,8 @@
      "apiKeyConfigured": "Configured",
      "apiKeySet": "Set up",
      "model": "Model",
-      "modelHelp": "The model name to use (e.g. deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). Check your provider for available models."
+      "modelHelp": "The model to use. Select from the dropdown (fetched from your provider) or type a custom model name.",
+      "modelPlaceholder": "Select a model..."
    }
  },
  "loras": {
@@ -772,7 +781,7 @@
        "complete": "Auto-organize complete",
        "error": "Error: {error}"
      },
-      "enrichHfAgent": "Enrich Metadata (Agent)"
+      "enrichHfAgent": "Enrich HF Metadata (AI)"
    },
    "contextMenu": {
      "refreshMetadata": "Refresh Civitai Data",
@@ -797,7 +806,7 @@
      "viewAllLoras": "View All LoRAs",
      "downloadMissingLoras": "Download Missing LoRAs",
      "deleteRecipe": "Delete Recipe",
-      "enrichHfAgent": "Enrich Metadata (Agent)"
+      "enrichHfAgent": "Enrich HF Metadata (AI)"
    }
  },
  "recipes": {
--- a/locales/es.json
+++ b/locales/es.json
@@ -662,7 +662,15 @@
            "title": "Proveedor de IA",
            "provider": "Proveedor",
            "providerHelp": "Elija su proveedor de LLM. OpenAI y Ollama usan endpoints predefinidos. Personalizado le permite especificar cualquier endpoint compatible con OpenAI.",
-            "custom": "Personalizado (compatible con OpenAI)",
+            "providerOptions": {
+                "openai": "OpenAI",
+                "ollama": "Ollama (local)",
+                "deepseek": "DeepSeek",
+                "groq": "Groq",
+                "openrouter": "OpenRouter",
+                "opencode-go": "OpenCode Go",
+                "custom": "Personalizado (compatible con OpenAI)"
+            },
            "apiBase": "URL base de la API",
            "apiBaseHelp": "La URL base para la API LLM (p.ej. https://api.openai.com/v1). Déjelo vacío para usar el valor predeterminado del proveedor.",
            "apiBasePlaceholder": "https://api.openai.com/v1",
@@ -673,7 +681,8 @@
            "apiKeyConfigured": "Configurada",
            "apiKeySet": "Configurar",
            "model": "Modelo",
-            "modelHelp": "El nombre del modelo a usar (p.ej. deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). Consulte a su proveedor para ver los modelos disponibles."
+            "modelHelp": "El nombre del modelo a usar (p.ej. deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). Consulte a su proveedor para ver los modelos disponibles.",
+            "modelPlaceholder": "Seleccionar un modelo..."
        }
    },
    "loras": {
@@ -772,7 +781,7 @@
                "complete": "Auto-organización completada",
                "error": "Error: {error}"
            },
-            "enrichHfAgent": "Enriquecer metadatos (IA)"
+            "enrichHfAgent": "Enriquecer metadatos HF (IA)"
        },
        "contextMenu": {
            "refreshMetadata": "Actualizar datos de Civitai",
@@ -797,7 +806,7 @@
            "viewAllLoras": "Ver todos los LoRAs",
            "downloadMissingLoras": "Descargar LoRAs faltantes",
            "deleteRecipe": "Eliminar receta",
-            "enrichHfAgent": "Enriquecer metadatos (IA)"
+            "enrichHfAgent": "Enriquecer metadatos HF (IA)"
        }
    },
    "recipes": {
--- a/locales/fr.json
+++ b/locales/fr.json
@@ -662,7 +662,15 @@
            "title": "Fournisseur d'IA",
            "provider": "Fournisseur",
            "providerHelp": "Choisissez votre fournisseur LLM. OpenAI et Ollama utilisent des endpoints prédéfinis. Personnalisé vous permet de spécifier n'importe quel endpoint compatible OpenAI.",
-            "custom": "Personnalisé (compatible OpenAI)",
+            "providerOptions": {
+                "openai": "OpenAI",
+                "ollama": "Ollama (local)",
+                "deepseek": "DeepSeek",
+                "groq": "Groq",
+                "openrouter": "OpenRouter",
+                "opencode-go": "OpenCode Go",
+                "custom": "Personnalisé (compatible OpenAI)"
+            },
            "apiBase": "URL de base de l'API",
            "apiBaseHelp": "L'URL de base pour l'API LLM (ex. https://api.openai.com/v1). Laissez vide pour utiliser le fournisseur par défaut.",
            "apiBasePlaceholder": "https://api.openai.com/v1",
@@ -673,7 +681,8 @@
            "apiKeyConfigured": "Configurée",
            "apiKeySet": "Configurer",
            "model": "Modèle",
-            "modelHelp": "Le nom du modèle à utiliser (ex. deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). Consultez votre fournisseur pour les modèles disponibles."
+            "modelHelp": "Le nom du modèle à utiliser (ex. deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). Consultez votre fournisseur pour les modèles disponibles.",
+            "modelPlaceholder": "Sélectionner un modèle..."
        }
    },
    "loras": {
@@ -772,7 +781,7 @@
                "complete": "Auto-organisation terminée",
                "error": "Erreur : {error}"
            },
-            "enrichHfAgent": "Enrichir les métadonnées (IA)"
+            "enrichHfAgent": "Enrichir les métadonnées HF (IA)"
        },
        "contextMenu": {
            "refreshMetadata": "Actualiser les données Civitai",
@@ -797,7 +806,7 @@
            "viewAllLoras": "Voir tous les LoRAs",
            "downloadMissingLoras": "Télécharger les LoRAs manquants",
            "deleteRecipe": "Supprimer la recipe",
-            "enrichHfAgent": "Enrichir les métadonnées (IA)"
+            "enrichHfAgent": "Enrichir les métadonnées HF (IA)"
        }
    },
    "recipes": {
--- a/locales/he.json
+++ b/locales/he.json
@@ -662,7 +662,15 @@
            "title": "ספק AI",
            "provider": "ספק",
            "providerHelp": "בחר את ספק ה-LLM שלך. OpenAI ו-Ollama משתמשים בנקודות קצה מוגדרות מראש. מותאם אישית מאפשר לך לציין כל נקודת קצה תואמת OpenAI.",
-            "custom": "מותאם אישית (תואם OpenAI)",
+            "providerOptions": {
+                "openai": "OpenAI",
+                "ollama": "Ollama (מקומי)",
+                "deepseek": "DeepSeek",
+                "groq": "Groq",
+                "openrouter": "OpenRouter",
+                "opencode-go": "OpenCode Go",
+                "custom": "מותאם אישית (תואם OpenAI)"
+            },
            "apiBase": "כתובת בסיס API",
            "apiBaseHelp": "כתובת ה-URL הבסיסית ל-API של LLM (לדוגמה https://api.openai.com/v1). השאר ריק לשימוש בברירת המחדל של הספק.",
            "apiBasePlaceholder": "https://api.openai.com/v1",
@@ -673,7 +681,8 @@
            "apiKeyConfigured": "הוגדר",
            "apiKeySet": "הגדר",
            "model": "מודל",
-            "modelHelp": "שם המודל לשימוש (לדוגמה deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). בדוק אצל הספק שלך אילו מודלים זמינים."
+            "modelHelp": "שם המודל לשימוש (לדוגמה deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). בדוק אצל הספק שלך אילו מודלים זמינים.",
+            "modelPlaceholder": "בחר מודל..."
        }
    },
    "loras": {
@@ -772,7 +781,7 @@
                "complete": "ארגון אוטומטי הושלם",
                "error": "שגיאה: {error}"
            },
-            "enrichHfAgent": "העשרת מטא-דאטה (AI)"
+            "enrichHfAgent": "העשרת HF מטא-דאטה (AI)"
        },
        "contextMenu": {
            "refreshMetadata": "רענן נתוני Civitai",
@@ -797,7 +806,7 @@
            "viewAllLoras": "הצג את כל ה-LoRAs",
            "downloadMissingLoras": "הורד LoRAs חסרים",
            "deleteRecipe": "מחק מתכון",
-            "enrichHfAgent": "העשרת מטא-דאטה (AI)"
+            "enrichHfAgent": "העשרת HF מטא-דאטה (AI)"
        }
    },
    "recipes": {
--- a/locales/ja.json
+++ b/locales/ja.json
@@ -662,7 +662,15 @@
            "title": "AIプロバイダー",
            "provider": "プロバイダー",
            "providerHelp": "LLMプロバイダーを選択してください。OpenAIとOllamaはプリセットのAPIエンドポイントを使用します。カスタムでは任意のOpenAI互換エンドポイントを指定できます。",
-            "custom": "カスタム（OpenAI互換）",
+            "providerOptions": {
+                "openai": "OpenAI",
+                "ollama": "Ollama（ローカル）",
+                "deepseek": "DeepSeek",
+                "groq": "Groq",
+                "openrouter": "OpenRouter",
+                "opencode-go": "OpenCode Go",
+                "custom": "カスタム（OpenAI 互換）"
+            },
            "apiBase": "APIベースURL",
            "apiBaseHelp": "LLM APIのベースURL（例：https://api.openai.com/v1）。空の場合はプロバイダーのデフォルトが使用されます。",
            "apiBasePlaceholder": "https://api.openai.com/v1",
@@ -673,7 +681,8 @@
            "apiKeyConfigured": "設定済み",
            "apiKeySet": "設定",
            "model": "モデル",
-            "modelHelp": "使用するモデル名（例：deepseek-v4-flash, gemini-2.5-flash, gemma4:12b）。プロバイダーで利用可能なモデルをご確認ください。"
+            "modelHelp": "使用するモデル名（例：deepseek-v4-flash, gemini-2.5-flash, gemma4:12b）。プロバイダーで利用可能なモデルをご確認ください。",
+            "modelPlaceholder": "モデルを選択..."
        }
    },
    "loras": {
@@ -772,7 +781,7 @@
                "complete": "自動整理が完了しました",
                "error": "エラー：{error}"
            },
-            "enrichHfAgent": "メタデータをAIで補完"
+            "enrichHfAgent": "HF メタデータをAIで補完"
        },
        "contextMenu": {
            "refreshMetadata": "Civitaiデータを更新",
@@ -797,7 +806,7 @@
            "viewAllLoras": "すべてのLoRAを表示",
            "downloadMissingLoras": "不足しているLoRAをダウンロード",
            "deleteRecipe": "レシピを削除",
-            "enrichHfAgent": "メタデータをAIで補完"
+            "enrichHfAgent": "HF メタデータをAIで補完"
        }
    },
    "recipes": {
--- a/locales/ko.json
+++ b/locales/ko.json
@@ -662,7 +662,15 @@
            "title": "AI 제공자",
            "provider": "제공자",
            "providerHelp": "LLM 제공자를 선택하세요. OpenAI와 Ollama는 사전 설정된 API 엔드포인트를 사용합니다. 사용자 정의를 선택하면 모든 OpenAI 호환 엔드포인트를 지정할 수 있습니다.",
-            "custom": "사용자 정의 (OpenAI 호환)",
+            "providerOptions": {
+                "openai": "OpenAI",
+                "ollama": "Ollama (로컬)",
+                "deepseek": "DeepSeek",
+                "groq": "Groq",
+                "openrouter": "OpenRouter",
+                "opencode-go": "OpenCode Go",
+                "custom": "사용자 정의 (OpenAI 호환)"
+            },
            "apiBase": "API 기본 URL",
            "apiBaseHelp": "LLM API의 기본 URL입니다 (예: https://api.openai.com/v1). 비워두면 제공자 기본값이 사용됩니다.",
            "apiBasePlaceholder": "https://api.openai.com/v1",
@@ -673,7 +681,8 @@
            "apiKeyConfigured": "설정됨",
            "apiKeySet": "설정",
            "model": "모델",
-            "modelHelp": "사용할 모델 이름 (예: deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). 제공자에서 사용 가능한 모델을 확인하세요."
+            "modelHelp": "사용할 모델 이름 (예: deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). 제공자에서 사용 가능한 모델을 확인하세요.",
+            "modelPlaceholder": "모델 선택..."
        }
    },
    "loras": {
@@ -772,7 +781,7 @@
                "complete": "자동 정리 완료",
                "error": "오류: {error}"
            },
-            "enrichHfAgent": "AI로 메타데이터 보강"
+            "enrichHfAgent": "HF AI로 메타데이터 보강"
        },
        "contextMenu": {
            "refreshMetadata": "Civitai 데이터 새로고침",
@@ -797,7 +806,7 @@
            "viewAllLoras": "모든 LoRA 보기",
            "downloadMissingLoras": "누락된 LoRA 다운로드",
            "deleteRecipe": "레시피 삭제",
-            "enrichHfAgent": "AI로 메타데이터 보강"
+            "enrichHfAgent": "HF AI로 메타데이터 보강"
        }
    },
    "recipes": {
--- a/locales/ru.json
+++ b/locales/ru.json
@@ -662,7 +662,15 @@
            "title": "Поставщик ИИ",
            "provider": "Поставщик",
            "providerHelp": "Выберите поставщика LLM. OpenAI и Ollama используют предустановленные API-эндпоинты. Пользовательский позволяет указать любой совместимый с OpenAI эндпоинт.",
-            "custom": "Пользовательский (совместимый с OpenAI)",
+            "providerOptions": {
+                "openai": "OpenAI",
+                "ollama": "Ollama (локальный)",
+                "deepseek": "DeepSeek",
+                "groq": "Groq",
+                "openrouter": "OpenRouter",
+                "opencode-go": "OpenCode Go",
+                "custom": "Пользовательский (совместимый с OpenAI)"
+            },
            "apiBase": "Базовый URL API",
            "apiBaseHelp": "Базовый URL для LLM API (например, https://api.openai.com/v1). Оставьте пустым, чтобы использовать значение по умолчанию.",
            "apiBasePlaceholder": "https://api.openai.com/v1",
@@ -673,7 +681,8 @@
            "apiKeyConfigured": "Настроен",
            "apiKeySet": "Настроить",
            "model": "Модель",
-            "modelHelp": "Имя модели для использования (например, deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). Проверьте доступные модели у вашего поставщика."
+            "modelHelp": "Имя модели для использования (например, deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). Проверьте доступные модели у вашего поставщика.",
+            "modelPlaceholder": "Выберите модель..."
        }
    },
    "loras": {
@@ -772,7 +781,7 @@
                "complete": "Автоматическая организация завершена",
                "error": "Ошибка: {error}"
            },
-            "enrichHfAgent": "Обогатить метаданные (ИИ)"
+            "enrichHfAgent": "Обогатить HF метаданные (ИИ)"
        },
        "contextMenu": {
            "refreshMetadata": "Обновить данные Civitai",
@@ -797,7 +806,7 @@
            "viewAllLoras": "Посмотреть все LoRAs",
            "downloadMissingLoras": "Загрузить отсутствующие LoRAs",
            "deleteRecipe": "Удалить рецепт",
-            "enrichHfAgent": "Обогатить метаданные (ИИ)"
+            "enrichHfAgent": "Обогатить HF метаданные (ИИ)"
        }
    },
    "recipes": {
--- a/locales/zh-CN.json
+++ b/locales/zh-CN.json
@@ -662,18 +662,27 @@
            "title": "AI 提供商",
            "provider": "提供商",
            "providerHelp": "选择您的 LLM 提供商。OpenAI 和 Ollama 使用预设的 API 端点。自定义允许您指定任何兼容 OpenAI 的端点。",
-            "custom": "自定义（兼容 OpenAI）",
+            "providerOptions": {
+                "openai": "OpenAI",
+                "ollama": "Ollama（本地）",
+                "deepseek": "DeepSeek",
+                "groq": "Groq",
+                "openrouter": "OpenRouter",
+                "opencode-go": "OpenCode Go",
+                "custom": "自定义（OpenAI 兼容）"
+            },
            "apiBase": "API 基础地址",
-            "apiBaseHelp": "LLM API 的基础 URL（例如 https://api.openai.com/v1）。留空则使用提供商默认地址。",
+            "apiBaseHelp": "LLM API 的基础地址。选择预设或输入自定义地址，下拉框显示所有支持的提供商预设。",
            "apiBasePlaceholder": "https://api.openai.com/v1",
            "apiKey": "API 密钥",
-            "apiKeyHelp": "您的 LLM 提供商 API 密钥。仅本地存储，不会发送到您选择的 LLM 提供商之外的任何服务器。",
+            "apiKeyHelp": "LLM 提供商的 API 密钥。本地存储，除您选择的 LLM 提供商外不会发送到任何服务器。",
            "apiKeyPlaceholder": "sk-...",
            "apiKeyNotSet": "未设置",
            "apiKeyConfigured": "已配置",
            "apiKeySet": "设置",
            "model": "模型",
-            "modelHelp": "要使用的模型名称（例如 deepseek-v4-flash, gemini-2.5-flash, gemma4:12b）。请查看您的提供商支持的可用模型列表。"
+            "modelHelp": "要使用的模型。从下拉框选择（从提供商获取）或输入自定义模型名称。",
+            "modelPlaceholder": "选择一个模型..."
        }
    },
    "loras": {
@@ -772,7 +781,7 @@
                "complete": "自动整理已完成",
                "error": "错误：{error}"
            },
-            "enrichHfAgent": "AI 元数据增强"
+            "enrichHfAgent": "AI HF 元数据增强"
        },
        "contextMenu": {
            "refreshMetadata": "刷新 Civitai 数据",
@@ -797,7 +806,7 @@
            "viewAllLoras": "查看所有 LoRA",
            "downloadMissingLoras": "下载缺失的 LoRA",
            "deleteRecipe": "删除配方",
-            "enrichHfAgent": "AI 元数据增强"
+            "enrichHfAgent": "AI HF 元数据增强"
        }
    },
    "recipes": {
--- a/locales/zh-TW.json
+++ b/locales/zh-TW.json
@@ -662,18 +662,27 @@
            "title": "AI 提供者",
            "provider": "提供者",
            "providerHelp": "選擇您的 LLM 提供者。OpenAI 和 Ollama 使用預設 API 端點。自訂允許您指定任何相容 OpenAI 的端點。",
-            "custom": "自訂（相容 OpenAI）",
-            "apiBase": "API 基礎位址",
-            "apiBaseHelp": "LLM API 的基礎 URL（例如 https://api.openai.com/v1）。留空則使用提供者預設位址。",
+            "providerOptions": {
+                "openai": "OpenAI",
+                "ollama": "Ollama（本地）",
+                "deepseek": "DeepSeek",
+                "groq": "Groq",
+                "openrouter": "OpenRouter",
+                "opencode-go": "OpenCode Go",
+                "custom": "自訂（OpenAI 相容）"
+            },
+            "apiBase": "API 基礎網址",
+            "apiBaseHelp": "LLM API 的基礎網址。選擇預設或輸入自訂網址，下拉選單顯示所有支援的提供者預設。",
            "apiBasePlaceholder": "https://api.openai.com/v1",
            "apiKey": "API 金鑰",
-            "apiKeyHelp": "您的 LLM 提供者 API 金鑰。僅儲存在本地，除了您選擇的 LLM 提供者外，不會發送到任何伺服器。",
-            "apiKeyPlaceholder": "sk-...",
+            "apiKeyHelp": "LLM 提供者的 API 金鑰。儲存在本地，除您選擇的 LLM 提供者外不會傳送到任何伺服器。",
+            "apiKeyPlaceholder": "[TODO: Translate] sk-...",
            "apiKeyNotSet": "未設定",
            "apiKeyConfigured": "已設定",
            "apiKeySet": "設定",
            "model": "模型",
-            "modelHelp": "要使用的模型名稱（例如 deepseek-v4-flash, gemini-2.5-flash, gemma4:12b）。請查看您的提供者支援的可用模型列表。"
+            "modelHelp": "要使用的模型。從下拉選單選擇（從提供者取得）或輸入自訂模型名稱。",
+            "modelPlaceholder": "選擇一個模型..."
        }
    },
    "loras": {
@@ -772,7 +781,7 @@
                "complete": "自動整理完成",
                "error": "錯誤：{error}"
            },
-            "enrichHfAgent": "AI 中繼資料增強"
+            "enrichHfAgent": "AI HF 中繼資料增強"
        },
        "contextMenu": {
            "refreshMetadata": "刷新 Civitai 資料",
@@ -797,7 +806,7 @@
            "viewAllLoras": "檢視全部 LoRA",
            "downloadMissingLoras": "下載缺少的 LoRA",
            "deleteRecipe": "刪除配方",
-            "enrichHfAgent": "AI 中繼資料增強"
+            "enrichHfAgent": "AI HF 中繼資料增強"
        }
    },
    "recipes": {
--- a/py/config.py
+++ b/py/config.py
@@ -177,8 +177,7 @@ class Config:

        # Load extra folder paths from active library settings before symlink scan
        # so both primary and extra paths are discovered in a single pass.
-        if not standalone_mode:
-            self._load_extra_paths_from_settings()
+        self._load_extra_paths_from_settings()

        # Scan symbolic links during initialization
        self._initialize_symlink_mappings()
@@ -193,7 +192,7 @@ class Config:
        Called during ``Config.__init__`` before the symlink scan so both primary and
        extra paths are discovered in a single pass.  Mirrors the extra-path
        portion of ``_apply_library_paths`` without replacing the primary roots
-        that were already resolved from ComfyUI's ``folder_paths``.
+        that were already resolved via ``folder_paths.get_folder_paths``.
        """
        try:
            from .services.settings_manager import get_settings_manager
--- a/py/lora_manager.py
+++ b/py/lora_manager.py
@@ -208,6 +208,10 @@ class LoraManager:
            # Initialize WebSocket manager
            await ServiceRegistry.get_websocket_manager()

+            # Preload LLM model catalog (background task, non-blocking)
+            from .services.llm_service import LLMService
+            await LLMService.get_instance()
+
            # Initialize scanners in background
            lora_scanner = await ServiceRegistry.get_lora_scanner()
            checkpoint_scanner = await ServiceRegistry.get_checkpoint_scanner()
--- a/py/metadata_ops/init.py
+++ b/py/metadata_ops/init.py
@@ -1,4 +1,4 @@
-"""Agent CLI — thin in-process wrappers around LoRA Manager internal services.
+"""Metadata operations — thin in-process wrappers around LoRA Manager internal services.

 All functions are simple Python async functions that delegate to the
 appropriate internal service.  They use **relative imports** within the
@@ -7,15 +7,15 @@ risk of double import or circular dependencies.

 Usage (in-process, primary)::

-    from py.agent_cli import list_base_models, read_metadata
+    from py.metadata_ops import list_base_models, read_metadata

    models = await list_base_models()
    meta   = await read_metadata("/path/to/model.safetensors")

 Usage (subprocess, debugging / external)::

-    python -m py.agent_cli base-models list
-    python -m py.agent_cli metadata read /path/to/model.safetensors
+    python -m py.metadata_ops base-models list
+    python -m py.metadata_ops metadata read /path/to/model.safetensors
 """

 from __future__ import annotations
@@ -32,23 +32,26 @@ logger = logging.getLogger(__name__)
 # Helpers
 # ---------------------------------------------------------------------------

-async def _find_scanner_for_model(
-    model_path: str,
-) -> tuple[object, object] | tuple[None, None]:
-    """Find the (scanner, cache_entry) responsible for *model_path*.
+SCANNER_TYPE_MAP: dict[str, str] = {
+    "get_lora_scanner": "lora",
+    "get_checkpoint_scanner": "checkpoint",
+    "get_embedding_scanner": "embedding",
+}

-    Iterates all known scanner types and returns the first one whose cache
-    contains the given path.  Returns ``(None, None)`` when no scanner
-    claims the model.
+SCANNER_GETTER_NAMES = tuple(SCANNER_TYPE_MAP.keys())
+
+
+async def _find_model_entry(
+    model_path: str,
+) -> tuple[object, object, str | None] | tuple[None, None, None]:
+    """Iterate all scanners and return the first (scanner, entry, getter_name)
+    that owns *model_path*.  Returns ``(None, None, None)`` when no scanner
+    claims it.
    """
    from ..services.service_registry import ServiceRegistry

    normalized = os.path.normpath(model_path)
-    for getter_name in (
-        "get_lora_scanner",
-        "get_checkpoint_scanner",
-        "get_embedding_scanner",
-    ):
+    for getter_name in SCANNER_GETTER_NAMES:
        getter = getattr(ServiceRegistry, getter_name, None)
        if getter is None:
            continue
@@ -59,15 +62,31 @@ async def _find_scanner_for_model(
            cache = await scanner.get_cached_data()
            for entry in cache.raw_data:
                if os.path.normpath(entry.get("file_path", "")) == normalized:
-                    return scanner, entry
+                    return scanner, entry, getter_name
        except Exception as exc:
            logger.debug(
                "Scanner %s check failed for %s: %s",
-                getter_name,
-                model_path,
-                exc,
+                getter_name, model_path, exc,
            )
-    return None, None
+    return None, None, None
+
+
+async def _find_scanner_for_model(
+    model_path: str,
+) -> tuple[object, object] | tuple[None, None]:
+    """Find the (scanner, cache_entry) responsible for *model_path*."""
+    scanner, entry, _ = await _find_model_entry(model_path)
+    return scanner, entry
+
+
+async def identify_model_type(model_path: str) -> str:
+    """Determine the model type (``\"lora\"``, ``\"checkpoint\"``, or
+    ``\"embedding\"``) for *model_path*.
+
+    Falls back to ``\"lora\"`` when unknown.
+    """
+    _, _, getter_name = await _find_model_entry(model_path)
+    return SCANNER_TYPE_MAP[getter_name] if getter_name else "lora"


 # ---------------------------------------------------------------------------
@@ -76,38 +95,29 @@ async def _find_scanner_for_model(


 async def list_base_models(limit: int = 0) -> List[str]:
-    """Return deduplicated base model names from all model caches.
+    """Return all valid CivitAI base model names.

-    The result is ordered by frequency (most common first).  Pass
-    *limit* = 0 (default) for all models.
+    Uses ``CivitaiBaseModelService.get_base_models()`` which merges a
+    hardcoded list (``SUPPORTED_DOWNLOAD_SKIP_BASE_MODELS``) with remote
+    models fetched from the CivitAI API.  Never empty — the hardcoded
+    fallback always provides a complete set.
+
+    The result is sorted alphabetically.  Pass *limit* = 0 for all models.
    """
-    from ..services.service_registry import ServiceRegistry
+    from ..services.civitai_base_model_service import (
+        CivitaiBaseModelService,
+    )

-    counts: Dict[str, int] = {}
-    for getter_name in (
-        "get_lora_scanner",
-        "get_checkpoint_scanner",
-        "get_embedding_scanner",
-    ):
-        getter = getattr(ServiceRegistry, getter_name, None)
-        if getter is None:
-            continue
-        try:
-            scanner = await getter()
-            if scanner is None:
-                continue
-            cache = await scanner.get_cached_data()
-            for entry in cache.raw_data:
-                bm = entry.get("base_model")
-                if bm:
-                    counts[bm] = counts.get(bm, 0) + 1
-        except Exception as exc:
-            logger.debug("list_base_models scanner %s error: %s", getter_name, exc)
-
-    sorted_names = [name for name, _ in sorted(counts.items(), key=lambda x: -x[1])]
+    try:
+        service = await CivitaiBaseModelService.get_instance()
+        response = await service.get_base_models()
+        names: List[str] = response.get("models", [])
+    except Exception as exc:
+        logger.warning("list_base_models failed: %s", exc)
+        names = []
    if limit > 0:
-        return sorted_names[:limit]
-    return sorted_names
+        return names[:limit]
+    return names


 async def read_metadata(model_path: str) -> Dict[str, Any]:
@@ -153,17 +163,17 @@ async def download_preview(
    *,
    target_width: int = 480,
    quality: int = 85,
-) -> bool:
+) -> str | None:
    """Download a preview image from *url*, optimise to .webp, and save it.

    The output file is placed alongside the model file with a ``.webp``
-    extension.  Returns ``True`` on success.
+    extension.  Returns the local file path on success, ``None`` on failure.
    """
    from ..services.downloader import get_downloader
    from ..utils.exif_utils import ExifUtils

    if not url or not url.strip():
-        return False
+        return None

    base_name = os.path.splitext(os.path.basename(model_path))[0]
    preview_dir = os.path.dirname(model_path)
@@ -186,8 +196,7 @@ async def download_preview(
            )
            with open(output_path, "wb") as f:
                f.write(optimized_data)
-            logger.info("Preview downloaded and optimised for %s", model_path)
-            return True
+            return output_path
        except Exception as exc:
            logger.warning("Preview optimisation failed, saving raw: %s", exc)
            # Fall through to raw save
@@ -196,12 +205,11 @@ async def download_preview(
    try:
        ok, _ = await downloader.download_file(url, output_path, use_auth=False)
        if ok:
-            logger.info("Preview downloaded (fallback) for %s", model_path)
-            return True
+            return output_path
    except Exception as exc:
        logger.warning("Preview fallback download failed for %s: %s", model_path, exc)

-    return False
+    return None


 async def refresh_cache(model_path: str) -> bool:
--- a/py/metadata_ops/main.py
+++ b/py/metadata_ops/main.py
@@ -1,17 +1,12 @@
-"""Subprocess entry point for AgentCLI (debugging / external use).
+"""Subprocess entry point for ``metadata_ops`` (debugging / external use).

 Usage::

-    python -m py.agent_cli base-models list [--limit N]
-    python -m py.agent_cli metadata read <path>
-    python -m py.agent_cli metadata update <path> --json '{...}'
-    python -m py.agent_cli preview download <path> --url <url>
-    python -m py.agent_cli cache refresh <path>
-
-NOTE: This is an **optional** convenience wrapper.  The primary consumer of
-AgentCLI is the :mod:`AgentService` (in-process).  This entry point exists
-for manual debugging and future integration with subprocess-based agent
-frameworks.
+    python -m py.metadata_ops base-models list [--limit N]
+    python -m py.metadata_ops metadata read <path>
+    python -m py.metadata_ops metadata update <path> --json '{...}'
+    python -m py.metadata_ops preview download <path> --url <url>
+    python -m py.metadata_ops cache refresh <path>
 """

 from __future__ import annotations
--- a/py/routes/handlers/agent_handlers.py
+++ b/py/routes/handlers/agent_handlers.py
@@ -99,12 +99,11 @@ class AgentHandler:
        # Launch execution in the background
        progress_reporter = AgentProgressReporter()
        logger.info(
-            "Agent skill '%s' starting for %d model(s) in background task",
+            "LLM enrichment '%s' starting for %d model(s)",
            skill_name, len(model_paths),
        )

        async def _run() -> None:
-            logger.info("_run background task started for skill '%s'", skill_name)
            try:
                result = await service.execute_skill(
                    skill_name=skill_name,
@@ -112,11 +111,11 @@ class AgentHandler:
                    progress_callback=progress_reporter,
                )
                logger.info(
-                    "Agent skill '%s' finished: success=%s, summary='%s', errors=%s",
+                    "LLM enrichment '%s' finished: success=%s, summary='%s', errors=%s",
                    skill_name, result.success, result.summary, result.errors,
                )
            except LLMNotConfiguredError as exc:
-                logger.warning("Agent skill '%s' not configured: %s", skill_name, exc)
+                logger.warning("LLM enrichment '%s' not configured: %s", skill_name, exc)
                await progress_reporter.on_progress(
                    {
                        "type": "agent_progress",
@@ -126,7 +125,7 @@ class AgentHandler:
                    }
                )
            except Exception as exc:
-                logger.error("Agent skill '%s' failed: %s", skill_name, exc, exc_info=True)
+                logger.error("LLM enrichment '%s' failed: %s", skill_name, exc, exc_info=True)
                await progress_reporter.on_progress(
                    {
                        "type": "agent_progress",
@@ -137,8 +136,7 @@ class AgentHandler:
                )

        # Fire and forget — progress comes via WebSocket
-        task = asyncio.create_task(_run())
-        logger.info("Agent skill '%s' background task created (id=%s)", skill_name, task)
+        asyncio.create_task(_run())

        return web.json_response(
            {
--- a/py/routes/handlers/misc_handlers.py
+++ b/py/routes/handlers/misc_handlers.py
@@ -38,6 +38,7 @@ from ...services.settings_manager import get_settings_manager
 from ...services.websocket_manager import ws_manager
 from ...services.downloader import get_downloader
 from ...services.errors import ResourceNotFoundError
+from ...services.llm_service import get_provider_model_ids, fetch_ollama_models
 from ...services.cache_health_monitor import CacheHealthMonitor, CacheHealthStatus
 from ...utils.models import BaseModelMetadata
 from ...utils.constants import (
@@ -1400,8 +1401,9 @@ class SettingsHandler:
            "libraries",
            "active_library",
            # Sensitive — never expose the actual value to the frontend;
-            # frontend receives a boolean instead (civitai_api_key_set).
+            # frontend receives a boolean instead (*_set).
            "civitai_api_key",
+            "llm_api_key",
        }
    )

@@ -1459,6 +1461,8 @@ class SettingsHandler:
            # Sensitive fields: only expose a boolean indicating whether set
            raw_key = self._settings.get("civitai_api_key")
            response_data["civitai_api_key_set"] = bool(raw_key)
+            raw_llm_key = self._settings.get("llm_api_key")
+            response_data["llm_api_key_set"] = bool(raw_llm_key)
            settings_file = getattr(self._settings, "settings_file", None)
            if settings_file:
                response_data["settings_file"] = settings_file
@@ -1563,6 +1567,42 @@ class SettingsHandler:
            logger.error("Error updating settings: %s", exc, exc_info=True)
            return web.Response(status=500, text=str(exc))

+    async def get_llm_models(self, request: web.Request) -> web.Response:
+        """Return the model list for a provider.
+
+        For ``ollama`` the list is fetched live from the local Ollama API
+        (only models actually pulled locally are shown).  For all other
+        providers the opencode model catalog is used.
+
+        Query parameters:
+            provider (required): Internal provider id (``openai``, ``ollama``, etc.).
+
+        Returns:
+            ``{"success": true, "models": ["gpt-4o", ...]}``.
+        """
+        provider_id = request.query.get("provider", "").strip()
+        if not provider_id:
+            return web.json_response(
+                {"success": False, "error": "provider query parameter is required", "models": []},
+                status=400,
+            )
+
+        try:
+            if provider_id == "ollama":
+                api_base = request.query.get("api_base", "").strip() or self._settings.get("llm_api_base", "")
+                if not api_base:
+                    api_base = "http://localhost:11434/v1"
+                models = await fetch_ollama_models(api_base)
+            else:
+                models = await get_provider_model_ids(provider_id)
+            return web.json_response({"success": True, "models": models})
+        except Exception as exc:
+            logger.warning("get_llm_models failed for %s: %s", provider_id, exc)
+            return web.json_response(
+                {"success": False, "error": str(exc), "models": []},
+                status=500,
+            )
+
    def _validate_example_images_path(self, folder_path: str) -> str | None:
        if not os.path.exists(folder_path):
            return f"Path does not exist: {folder_path}"
@@ -3354,6 +3394,7 @@ class MiscHandlerSet:
            "get_priority_tags": self.settings.get_priority_tags,
            "get_settings_libraries": self.settings.get_libraries,
            "activate_library": self.settings.activate_library,
+            "get_llm_models": self.settings.get_llm_models,
            "update_usage_stats": self.usage_stats.update_usage_stats,
            "get_usage_stats": self.usage_stats.get_usage_stats,
            "update_lora_code": self.lora_code.update_lora_code,
--- a/py/routes/handlers/model_handlers.py
+++ b/py/routes/handlers/model_handlers.py
@@ -154,6 +154,11 @@ class ModelPageView:
                )
                self._template_env._i18n_filter_added = True  # type: ignore[attr-defined]

+            from ...services.llm_service import PROVIDER_PRESETS, get_all_provider_models
+
+            catalog_provider_ids = [p for p in PROVIDER_PRESETS if p != "custom"]
+            provider_models = await get_all_provider_models(catalog_provider_ids)
+
            template_context = {
                "is_initializing": is_initializing,
                "settings": self._settings,
@@ -161,6 +166,8 @@ class ModelPageView:
                "folders": [],
                "t": self._server_i18n.get_translation,
                "version": self._get_app_version(),
+                "provider_presets_json": json.dumps(PROVIDER_PRESETS),
+                "provider_models_json": json.dumps(provider_models),
            }

            if not is_initializing:
--- a/py/routes/misc_route_registrar.py
+++ b/py/routes/misc_route_registrar.py
@@ -22,6 +22,7 @@ class RouteDefinition:
 MISC_ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
    RouteDefinition("GET", "/api/lm/settings", "get_settings"),
    RouteDefinition("POST", "/api/lm/settings", "update_settings"),
+    RouteDefinition("GET", "/api/lm/llm/models", "get_llm_models"),
    RouteDefinition("GET", "/api/lm/doctor/diagnostics", "get_doctor_diagnostics"),
    RouteDefinition("POST", "/api/lm/doctor/repair-cache", "repair_doctor_cache"),
    RouteDefinition("POST", "/api/lm/doctor/resolve-filename-conflicts", "resolve_doctor_filename_conflicts"),
--- a/py/services/agent/init.py
+++ b/py/services/agent/init.py
@@ -1,8 +1,12 @@
-"""Agent-powered skill system for LoRA Manager.
+"""LLM-powered metadata enrichment pipeline infrastructure.

-This package provides the orchestration layer for LLM/agent-powered features.
+This package provides the orchestration layer for LLM-powered features.
 Skills define *what* to do (prompt template).  The :class:`AgentService`
 handles *how* (LLM calls, context gathering, validation, progress).
+
+NOTE: The current implementation is a code-driven pipeline, not a true
+agent loop.  Future agent orchestration (LLM-driven tool selection) will
+live alongside this package with its own namespace.
 """

 from __future__ import annotations
--- a/py/services/agent/agent_service.py
+++ b/py/services/agent/agent_service.py
@@ -1,16 +1,17 @@
-"""Agent orchestration service.
+"""Pipeline orchestration service.

-The :class:`AgentService` coordinates skill execution:
+The :class:`AgentService` coordinates LLM-powered pipeline execution:

-1. Look up the skill in :class:`SkillRegistry`
-2. Validate input against the skill's ``input_schema``
-3. Prepare context via :mod:`~py.agent_cli` (read metadata, list base models, fetch HF README)
+1. Look up the pipeline definition in :class:`SkillRegistry`
+2. Validate input against its ``input_schema``
+3. Prepare context via :mod:`~py.metadata_ops` (read metadata, list base models, fetch HF README)
 4. If ``llm_required``: call :class:`LLMService` with the rendered prompt
-5. Post-process via :class:`PostProcessor` (delegates I/O to :mod:`~py.agent_cli`)
+5. Post-process via :class:`PostProcessor` (delegates I/O to :mod:`~py.metadata_ops`)
 6. Broadcast progress and completion via :class:`WebSocketManager`

-Skills define *what* to do (prompt template).  The AgentService handles *how*
-(LLM calls, context gathering, validation, progress).
+Pipeline definitions (*skills*) describe *what* to do (prompt template).
+The AgentService handles *how* (LLM calls, context gathering, validation,
+progress).
 """

 from __future__ import annotations
@@ -24,10 +25,17 @@ from typing import Any, Dict, List, Optional

 import aiohttp

+import os
+
+from ...config import config
 from ..llm_service import LLMService
 from ..websocket_manager import ws_manager
 from .post_processor import PostProcessor
 from .skill_registry import SkillRegistry
+from .skills.enrich_hf_metadata.readme_processor import (
+    clean_readme_for_llm,
+    extract_relevant_section,
+)

 logger = logging.getLogger(__name__)

@@ -195,11 +203,11 @@ class AgentService:
        input_data: Dict[str, Any],
        progress_callback: Optional[AgentProgressReporter] = None,
    ) -> SkillResult:
-        """Execute an agent skill.
+        """Execute a pipeline (skill) on the given models.

        Args:
-            skill_name: Name of the skill to execute
-            input_data: Input validated against the skill's ``input_schema``
+            skill_name: Name of the pipeline to execute
+            input_data: Input validated against the pipeline's ``input_schema``
            progress_callback: Optional WebSocket progress reporter

        Returns:
@@ -207,7 +215,6 @@ class AgentService:
        """

        registry = await self._ensure_registry()
-        logger.info("execute_skill '%s': looking up skill", skill_name)
        skill = registry.get_skill(skill_name)
        if skill is None:
            return SkillResult(
@@ -235,11 +242,11 @@ class AgentService:
        total = len(model_paths)
        processed = 0
        success_count = 0
+        skipped_count = 0
        updated_models: List[Dict[str, Any]] = []
        errors: List[str] = []
        post_processor = PostProcessor()

-        logger.info("execute_skill '%s': starting with %d model(s)", skill_name, total)
        await self._emit_progress(
            progress_callback, skill_name, status="started",
            total=total, processed=0, success=0,
@@ -249,52 +256,74 @@ class AgentService:
        llm_configured = llm.is_configured() if skill.llm_required else True

        for model_path in model_paths:
+            model_filename = os.path.basename(model_path)
            logger.info(
-                "execute_skill '%s': processing model %d/%d: %s",
-                skill_name, processed + 1, total, model_path,
+                "[%s] [%d/%d] %s",
+                skill_name, processed + 1, total, model_filename,
            )
+            updated_data: Dict[str, Any] = {}
+            skip_model = False
            try:
-                from ...agent_cli import read_metadata
+                from ...metadata_ops import read_metadata
                metadata = await read_metadata(model_path)

-                prompt_vars: Dict[str, Any] = {"model_path": model_path}
-                if skill.llm_required and llm_configured:
-                    prompt_vars = await self._build_prompt_context(
-                        skill_name, model_path, metadata, registry, llm,
-                    )
-
-                llm_response: Optional[Dict[str, Any]] = None
-                if skill.llm_required and llm_configured:
-                    prompt_template = registry.load_prompt(skill_name)
-                    rendered = _render_prompt(prompt_template, prompt_vars)
+                # Fast-fail: enrich_hf_metadata requires hf_url to have HF README context
+                if skill_name == "enrich_hf_metadata" and not metadata.get("hf_url", ""):
                    logger.info(
-                        "execute_skill '%s': LLM call for %s (prompt=%d chars)",
-                        skill_name, model_path, len(rendered),
+                        "[%s] SKIP %s — no hf_url in metadata",
+                        skill_name, model_filename,
                    )
-                    llm_response = await llm.chat_completion_json(
-                        system_prompt=prompt_vars.get(
-                            "system_prompt",
-                            "You are a helpful assistant that extracts structured metadata.",
-                        ),
-                        user_prompt=rendered,
+                    skipped_count += 1
+                    skip_model = True
+
+                if not skip_model:
+                    prompt_vars: Dict[str, Any] = {"model_path": model_path}
+                    if skill.llm_required and llm_configured:
+                        prompt_vars = await self._build_prompt_context(
+                            skill_name, model_path, metadata, registry, llm,
+                        )
+
+                    llm_response: Optional[Dict[str, Any]] = None
+                    if skill.llm_required and llm_configured:
+                        prompt_template = registry.load_prompt(skill_name)
+                        rendered = _render_prompt(prompt_template, prompt_vars)
+                        llm_response = await llm.chat_completion_json(
+                            system_prompt=prompt_vars.get(
+                                "system_prompt",
+                                "You are a helpful assistant that extracts structured metadata.",
+                            ),
+                            user_prompt=rendered,
+                        )
+                        if llm_response:
+                            logger.info(
+                                "[%s] [%d/%d] %s → base_model=%s confidence=%s",
+                                skill_name, processed + 1, total, model_filename,
+                                (llm_response.get("base_model") or "?")[:50],
+                                llm_response.get("confidence", "?"),
+                            )
+
+                    model_result = await post_processor.process(
+                        skill_name=skill_name,
+                        model_path=model_path,
+                        llm_output=llm_response or {},
+                        metadata=metadata,
+                        readme_content=prompt_vars.get("readme_content_full", ""),
                    )

-                model_result = await post_processor.process(
-                    skill_name=skill_name,
-                    model_path=model_path,
-                    llm_output=llm_response or {},
-                    metadata=metadata,
-                )
-
-                if model_result.get("success", True):
-                    success_count += 1
-                    uf = model_result.get("updated_fields", [])
-                    if uf:
-                        updated_models.append({"path": model_path, "updated_fields": uf})
-                else:
-                    errors.extend(
-                        model_result.get("errors", [model_result.get("error", "Unknown error")])
-                    )
+                    if model_result.get("success", True):
+                        success_count += 1
+                        uf = model_result.get("updated_fields", [])
+                        if uf:
+                            updated_models.append({"path": model_path, "updated_fields": uf})
+                        updated_data = model_result.get("updates", {})
+                        if "preview_url" in updated_data and updated_data["preview_url"]:
+                            updated_data["preview_url"] = config.get_preview_static_url(
+                                updated_data["preview_url"]
+                            )
+                    else:
+                        errors.extend(
+                            model_result.get("errors", [model_result.get("error", "Unknown error")])
+                        )

            except Exception as exc:
                logger.error("Skill %s failed for %s: %s", skill_name, model_path, exc)
@@ -304,25 +333,41 @@ class AgentService:
            await self._emit_progress(
                progress_callback, skill_name, status="processing",
                total=total, processed=processed, success=success_count,
+                skipped=skipped_count,
                current_path=model_path,
+                updated_data=updated_data,
            )

        result = SkillResult(
            success=success_count > 0,
            updated_models=updated_models,
            errors=errors,
-            summary=f"Processed {processed}/{total} models, {success_count} succeeded",
+            summary=f"Processed {processed}/{total} models, {success_count} succeeded, {skipped_count} skipped",
        )

-        logger.info("execute_skill '%s': done — %s", skill_name, result.summary)
        await self._emit_progress(
            progress_callback, skill_name, status="completed",
            total=total, processed=processed, success=success_count,
+            skipped=skipped_count,
            updated_models=updated_models, errors=errors, summary=result.summary,
        )

        return result

+    # ------------------------------------------------------------------
+    # Base model grouping (keeps the prompt compact)
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _format_base_models(models: List[str]) -> str:
+        """Format the base model list as a flat, one-per-line list.
+
+        Attempts to group by family consistently degraded LLM extraction
+        accuracy — the LLM finds individual model names harder to spot
+        in comma-separated groups than in a simple ``- Name`` list.
+        """
+        return "\n".join(f"- {m}" for m in models)
+
    async def _build_prompt_context(
        self,
        skill_name: str,
@@ -334,20 +379,29 @@ class AgentService:
        """Gather variables for the skill's prompt template.

        Reads metadata, fetches the HF README (if applicable), lists available
-        base models, and returns a dict that maps to ``{{variable}}``
-        placeholders in ``prompt.md``.
+        base models, loads user priority tags, and returns a dict that maps to
+        ``{{variable}}`` placeholders in ``prompt.md``.
        """
-        from ...agent_cli import list_base_models
+        from ...metadata_ops import identify_model_type, list_base_models
+        from ..settings_manager import SettingsManager

        context: Dict[str, Any] = {
            "model_path": model_path,
+            "model_basename": "",
            "hf_url": "",
            "repo": "",
            "readme_content": "",
+            "readme_content_full": "",
            "current_metadata": {},
            "base_models": [],
+            "priority_tags": "",
        }

+        # Extract model basename (filename without extension) for the LLM
+        # to use when locating the matching section in collection repos.
+        raw_basename = os.path.splitext(os.path.basename(model_path))[0]
+        context["model_basename"] = raw_basename or ""
+
        context["current_metadata"] = {
            "file_name": metadata.get("file_name", ""),
            "base_model": metadata.get("base_model", ""),
@@ -364,12 +418,34 @@ class AgentService:
        context["repo"] = repo or ""
        if repo:
            readme = await self._fetch_readme(repo)
-            context["readme_content"] = readme[:8000] if readme else "(README not available)"
+            # Trim README to the section relevant to this model file
+            # (collection repos often have multiple models in one README).
+            if readme and raw_basename:
+                trimmed = extract_relevant_section(readme, raw_basename)
+                cleaned = clean_readme_for_llm(trimmed) if trimmed else ""
+            else:
+                cleaned = clean_readme_for_llm(readme) if readme else ""
+            context["readme_content"] = cleaned if cleaned else "(README not available)"
+            context["readme_content_full"] = readme or ""

        try:
-            context["base_models"] = await list_base_models()
+            raw_models = await list_base_models()
+            context["base_models"] = self._format_base_models(raw_models)
        except Exception as exc:
            logger.debug("Failed to list base models: %s", exc)
+            context["base_models"] = "</not available>"
+
+        # Determine model type and load the corresponding priority_tags
+        try:
+            model_type = await identify_model_type(model_path)
+            context["model_type"] = model_type
+            settings = SettingsManager()
+            priority_config = settings.get_priority_tag_config()
+            context["priority_tags"] = priority_config.get(model_type, "")
+        except Exception as exc:
+            logger.debug("Failed to load priority tags: %s", exc)
+            context["model_type"] = "lora"
+            context["priority_tags"] = ""

        return context

--- a/py/services/agent/post_processor.py
+++ b/py/services/agent/post_processor.py
@@ -1,17 +1,19 @@
-"""Post-processing engine for agent skill outputs.
+"""Post-processing engine for skill pipeline outputs.

 The :class:`PostProcessor` takes the LLM's structured JSON output and applies
-it to a model's on-disk metadata via the :mod:`~py.agent_cli` functions.
+it to a model's on-disk metadata via the :mod:`~py.metadata_ops` functions.

 It handles all the skill-specific business logic — conditions, transformations,
 and orchestration of multiple side-effects (write metadata, download preview,
-refresh cache).  All actual I/O is delegated to :mod:`~py.agent_cli`.
+refresh cache).  All actual I/O is delegated to :mod:`~py.metadata_ops`.
 """

 from __future__ import annotations

+import json
 import logging
 import os
+import re
 from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional

@@ -19,7 +21,7 @@ logger = logging.getLogger(__name__)


 class PostProcessor:
-    """Deterministic post-processor for agent skill outputs.
+    """Deterministic post-processor for skill pipeline outputs.

    Usage (called by :class:`~py.services.agent.agent_service.AgentService`)::

@@ -28,7 +30,7 @@ class PostProcessor:
            skill_name="enrich_hf_metadata",
            model_path="/path/to/model.safetensors",
            llm_output={...},
-            metadata={...},    # from agent_cli.read_metadata()
+            metadata={...},    # from metadata_ops.read_metadata()
        )
    """

@@ -39,15 +41,20 @@ class PostProcessor:
        model_path: str,
        llm_output: Dict[str, Any],
        metadata: Dict[str, Any],
+        readme_content: str = "",
    ) -> Dict[str, Any]:
        """Route *llm_output* to the correct skill post-processor.

+        *readme_content* is optional raw markdown content (e.g. HF README)
+        that is converted to HTML and stored as ``modelDescription`` for
+        the description tab.
+
        Returns a dict with keys ``success`` (bool), ``updated_fields`` (list),
        ``preview_downloaded`` (bool), and ``errors`` (list).
        """
        if skill_name == "enrich_hf_metadata":
            return await self._process_enrich_hf_metadata(
-                model_path, llm_output, metadata,
+                model_path, llm_output, metadata, readme_content,
            )
        return {
            "success": False,
@@ -64,12 +71,22 @@ class PostProcessor:
        model_path: str,
        llm_output: Dict[str, Any],
        metadata: Dict[str, Any],
+        readme_content: str = "",
    ) -> Dict[str, Any]:
-        from ...agent_cli import (
+        from ...metadata_ops import (
            apply_metadata_updates,
            download_preview,
            refresh_cache,
        )
+        from .skills.enrich_hf_metadata.readme_processor import (
+            convert_readme_to_html,
+            extract_gallery_images,
+            extract_gallery_table_images,
+            extract_relevant_section,
+            extract_simple_markdown_images,
+            extract_html_img_tags,
+            extract_repo_from_hf_url,
+        )

        updated_fields: List[str] = []
        preview_downloaded = False
@@ -86,23 +103,89 @@ class PostProcessor:
        if new_base and self._should_overwrite(current_base, is_hf_model):
            updates["base_model"] = new_base

-        # trainedWords / trigger words
+        # trigger words → civitai.trainedWords
        new_triggers = llm_output.get("trigger_words", [])
+        trigger_words_empty = True
        if isinstance(new_triggers, list):
            cleaned = [t.strip() for t in new_triggers if t.strip()]
-            if cleaned:
-                current_triggers = metadata.get("trainedWords") or []
-                if self._should_overwrite_list(current_triggers, is_hf_model):
-                    updates["trainedWords"] = cleaned
+            cleaned = [t for t in cleaned if t.lower() not in ("none", "null", "n/a")]
+            trigger_words_empty = not cleaned
+            current_civitai = metadata.get("civitai") or {}
+            current_triggers = current_civitai.get("trainedWords") or []
+            if self._should_overwrite_list(current_triggers, is_hf_model):
+                trig_civitai = dict(current_civitai)
+                if "civitai" in updates and isinstance(updates["civitai"], dict):
+                    trig_civitai.update(updates["civitai"])
+                trig_civitai["trainedWords"] = cleaned
+                updates["civitai"] = trig_civitai

-        # modelDescription
-        new_desc = (llm_output.get("description") or "").strip()
-        if new_desc:
-            current_desc = metadata.get("modelDescription", "") or ""
-            if self._should_overwrite(current_desc, is_hf_model):
-                updates["modelDescription"] = new_desc
+        # modelDescription — from raw README content (converted to HTML)
+        if readme_content and is_hf_model:
+            converted = convert_readme_to_html(readme_content)
+            if converted:
+                updates["modelDescription"] = converted

-        # tags — merge with existing, deduplicate (case-insensitive)
+        # short_description → civitai.description (for "About this version")
+        short_desc = (llm_output.get("short_description") or "").strip()
+        if short_desc and is_hf_model:
+            current_civitai = metadata.get("civitai") or {}
+            desc_civitai = dict(current_civitai)
+            if "civitai" in updates and isinstance(updates["civitai"], dict):
+                desc_civitai.update(updates["civitai"])
+            desc_civitai["description"] = short_desc
+            updates["civitai"] = desc_civitai
+
+        # gallery images → civitai.images (from YAML frontmatter widget entries
+        # and Sample Gallery markdown tables in the README body)
+        gallery_images: List[Dict[str, Any]] = []
+        if readme_content and is_hf_model:
+            hf_url = metadata.get("hf_url", "") or ""
+            repo = extract_repo_from_hf_url(hf_url)
+            if repo:
+                rec_w = llm_output.get("recommended_width") or 0
+                rec_h = llm_output.get("recommended_height") or 0
+
+                # 1. Widget images (YAML frontmatter)
+                gallery = extract_gallery_images(
+                    readme_content, repo,
+                    default_width=rec_w, default_height=rec_h,
+                )
+
+                # 2. Sample Gallery table images (markdown body), deduplicated
+                existing_urls = {img["url"] for img in gallery if img.get("url")}
+                table_images = extract_gallery_table_images(
+                    readme_content, repo,
+                    existing_urls=existing_urls,
+                    default_width=rec_w, default_height=rec_h,
+                )
+                existing_urls.update(img["url"] for img in table_images if img.get("url"))
+
+                # 3. Simple markdown images `![alt](url)` in the body
+                simple_images = extract_simple_markdown_images(
+                    readme_content, repo,
+                    existing_urls=existing_urls,
+                    default_width=rec_w, default_height=rec_h,
+                )
+                existing_urls.update(img["url"] for img in simple_images if img.get("url"))
+
+                # 4. HTML `<img>` tags (used by many collection repos)
+                html_images = extract_html_img_tags(
+                    readme_content, repo,
+                    existing_urls=existing_urls,
+                    default_width=rec_w, default_height=rec_h,
+                )
+
+                all_images = gallery + table_images + simple_images + html_images
+                if all_images:
+                    gallery_images = all_images
+                    current_civitai = metadata.get("civitai") or {}
+                    gallery_civitai = dict(current_civitai)
+                    if "civitai" in updates and isinstance(updates["civitai"], dict):
+                        gallery_civitai.update(updates["civitai"])
+                    gallery_civitai["images"] = all_images
+                    updates["civitai"] = gallery_civitai
+
+        # tags
        new_tags = llm_output.get("tags", [])
        if isinstance(new_tags, list) and new_tags:
            existing_tags = metadata.get("tags") or []
@@ -114,16 +197,68 @@ class PostProcessor:
        updates["metadata_source"] = "agent:enrich_hf_metadata"
        updates["llm_enriched_at"] = datetime.now(timezone.utc).isoformat()

-        # -- Persist updates ------------------------------------------------
+        # Store LLM confidence in metadata so it's accessible for evaluation
+        raw_confidence = (llm_output.get("confidence") or "").strip()
+        if raw_confidence:
+            updates["_llm_confidence"] = raw_confidence
+
+        # Fallback: extract instance_prompt from YAML frontmatter when the LLM
+        # returned empty trigger words but the README has instance_prompt.
+        if trigger_words_empty:
+            instance_prompt = _extract_yaml_instance_prompt(readme_content)
+            if instance_prompt:
+                current_civitai = metadata.get("civitai") or {}
+                trig_civitai = dict(current_civitai)
+                if "civitai" in updates and isinstance(updates["civitai"], dict):
+                    trig_civitai.update(updates["civitai"])
+                trig_civitai["trainedWords"] = [instance_prompt]
+                updates["civitai"] = trig_civitai
+
+        preview_remote_url = (llm_output.get("preview_url") or "").strip()
+        # Fallback: if the LLM couldn't find a preview image in the cleaned
+        # README, find the first gallery image from the *model-specific
+        # section* of the README (not the repo-wide first image, which
+        # belongs to a different model in collection repos).
+        if not preview_remote_url and readme_content and is_hf_model:
+            model_basename = os.path.splitext(os.path.basename(model_path))[0]
+            relevant_section = extract_relevant_section(
+                readme_content, model_basename,
+            )
+            if relevant_section and relevant_section != readme_content:
+                for img in gallery_images:
+                    img_url = img.get("url", "")
+                    if img_url and img_url in relevant_section:
+                        preview_remote_url = img_url
+                        break
+        # Last resort: use the first gallery image from the full README.
+        if not preview_remote_url and gallery_images:
+            preview_remote_url = gallery_images[0].get("url", "")
+        current_preview = metadata.get("preview_url") or ""
+        if preview_remote_url and not (current_preview and os.path.exists(current_preview)):
+            local_path = await download_preview(model_path, preview_remote_url)
+            if local_path:
+                preview_downloaded = True
+                updates["preview_url"] = local_path
+
+        # notes — plain-text summary of usage info from the LLM
+        new_notes = (llm_output.get("notes") or "").strip()
+        if new_notes:
+            updates["notes"] = new_notes
+
+        # usage_tips — JSON string (e.g. {"strength_min":0.85,"strength_max":1.4})
+        raw_tips = (llm_output.get("usage_tips") or "").strip()
+        if raw_tips and raw_tips != "{}":
+            try:
+                json.loads(raw_tips)
+                updates["usage_tips"] = raw_tips
+            except (json.JSONDecodeError, TypeError):
+                logger.warning(
+                    "LLM returned invalid usage_tips JSON: %s", raw_tips[:200]
+                )
+
        if updates:
            updated_fields = await apply_metadata_updates(model_path, updates)

-        # -- Download preview -----------------------------------------------
-        preview_url = (llm_output.get("preview_url") or "").strip()
-        current_preview = metadata.get("preview_url") or ""
-        if preview_url and not (current_preview and os.path.exists(current_preview)):
-            preview_downloaded = await download_preview(model_path, preview_url)
-
        # -- Refresh scanner cache ------------------------------------------
        if updated_fields or preview_downloaded:
            await refresh_cache(model_path)
@@ -132,6 +267,7 @@ class PostProcessor:
            "success": True,
            "updated_fields": updated_fields,
            "preview_downloaded": preview_downloaded,
+            "updates": updates,
            "errors": [],
        }

@@ -166,3 +302,35 @@ class PostProcessor:
                merged.append(t)
                seen.add(t)
        return merged
+
+
+# ------------------------------------------------------------------
+# Module-level helpers
+# ------------------------------------------------------------------
+
+
+def _extract_yaml_instance_prompt(readme_content: str) -> str:
+    """Extract ``instance_prompt`` from the YAML frontmatter of a HF README.
+
+    Returns the prompt text, or empty string if not found.  Handles
+    ``null`` / ``~`` YAML null values by returning empty string.
+    """
+    if not readme_content or not readme_content.startswith("---"):
+        return ""
+
+    # Find end of frontmatter
+    end = readme_content.find("---", 3)
+    if end == -1:
+        return ""
+    frontmatter = readme_content[3:end]
+
+    for line in frontmatter.split("\n"):
+        line = line.strip()
+        m = re.match(r"^instance_prompt:\s*(.*)", line)
+        if m:
+            val = m.group(1).strip().strip('"').strip("'")
+            if val.lower() in ("null", "~", "none", ""):
+                return ""
+            return val
+
+    return ""
--- a/py/services/agent/skill_registry.py
+++ b/py/services/agent/skill_registry.py
@@ -1,7 +1,7 @@
-"""Discovery and loading of agent skills.
+"""Discovery and loading of prompt-based skills.

 Skills live in ``py/services/agent/skills/<name>/`` directories.  Each
-directory must contain a ``SKILL.md`` file with YAML frontmatter::
+directory must contain a ``prompt.md`` file with YAML frontmatter::

    ---
    name: my_skill
@@ -12,6 +12,8 @@ directory must contain a ``SKILL.md`` file with YAML frontmatter::

    Prompt template with ``{{variable}}`` placeholders.

+Legacy ``SKILL.md`` files are also supported for backward compatibility.
+
 The registry scans the skills directory on first access and caches results.
 """

@@ -32,6 +34,11 @@ logger = logging.getLogger(__name__)
 # Directory where built-in skills are stored
 _SKILLS_DIR = Path(__file__).parent / "skills"

+#: Preferred file names for prompt definition files (tried in order).
+#: ``prompt.md`` is the current convention; ``SKILL.md`` is the legacy name
+#: kept for backward compatibility.
+_PROMPT_FILE_NAMES: tuple[str, ...] = ("prompt.md", "SKILL.md")
+

 # ---------------------------------------------------------------------------
 # Frontmatter parser
@@ -43,7 +50,8 @@ _FRONTMATTER_RE = re.compile(


 def _parse_skill_file(path: Path) -> tuple[dict, str]:
-    """Read a ``SKILL.md`` file and return (frontmatter_dict, body_text).
+    """Read a prompt definition file (``prompt.md`` or legacy ``SKILL.md``) and
+    return (frontmatter_dict, body_text).

    Raises ``ValueError`` if the file lacks valid YAML frontmatter.
    """
@@ -95,6 +103,20 @@ class SkillRegistry:
    # Discovery
    # ------------------------------------------------------------------

+    @staticmethod
+    def _find_prompt_file(skill_dir: Path) -> Path | None:
+        """Return the first prompt definition file that exists in *skill_dir*.
+
+        Tries ``_PROMPT_FILE_NAMES`` in order so that new conventions
+        (``prompt.md``) take precedence while legacy ``SKILL.md`` files
+        still load without changes.
+        """
+        for name in _PROMPT_FILE_NAMES:
+            candidate = skill_dir / name
+            if candidate.exists():
+                return candidate
+        return None
+
    def _discover(self) -> None:
        """Scan the skills directory and load all valid skill definitions."""

@@ -107,31 +129,32 @@ class SkillRegistry:
        for entry in sorted(self._skills_dir.iterdir()):
            if not entry.is_dir():
                continue
-            skill_md = entry / "SKILL.md"
-            if not skill_md.exists():
+            prompt_file = self._find_prompt_file(entry)
+            if prompt_file is None:
                continue
            try:
-                definition = self._load_skill_definition(skill_md)
+                definition = self._load_skill_definition(prompt_file)
                if definition is not None:
                    self._skills[definition.name] = definition
                    logger.debug("Loaded skill: %s", definition.name)
            except Exception as exc:
-                logger.warning("Failed to load skill from %s: %s", skill_md, exc)
+                logger.warning("Failed to load skill from %s: %s", prompt_file, exc)

        self._loaded = True
-        logger.info("Discovered %d agent skills", len(self._skills))
+        logger.info("Discovered %d prompt-based skills", len(self._skills))

    def _load_skill_definition(self, path: Path) -> Optional[SkillDefinition]:
-        """Parse a ``SKILL.md`` frontmatter into a :class:`SkillDefinition`."""
+        """Parse a prompt definition file's frontmatter into a
+        :class:`SkillDefinition`."""

        try:
            data, _body = _parse_skill_file(path)
        except (ValueError, yaml.YAMLError) as exc:
-            logger.warning("Failed to parse SKILL.md %s: %s", path, exc)
+            logger.warning("Failed to parse prompt file %s: %s", path, exc)
            return None

        if "name" not in data:
-            logger.warning("SKILL.md missing required 'name' field: %s", path)
+            logger.warning("Prompt file %s missing required 'name' field", path)
            return None

        perm_data = data.get("permissions", {})
@@ -171,12 +194,15 @@ class SkillRegistry:
        return self._skills.get(name)

    def load_prompt(self, name: str) -> str:
-        """Load and return the prompt template body from a skill's ``SKILL.md``."""
+        """Load and return the prompt template body for the named skill."""

        skill_dir = self._skills_dir / name
-        skill_path = skill_dir / "SKILL.md"
-        if not skill_path.exists():
-            raise FileNotFoundError(f"SKILL.md not found: {skill_path}")
+        skill_path = self._find_prompt_file(skill_dir)
+        if skill_path is None:
+            raise FileNotFoundError(
+                f"Prompt file not found for skill '{name}' in {skill_dir} "
+                f"(tried {list(_PROMPT_FILE_NAMES)})"
+            )
        try:
            _frontmatter, body = _parse_skill_file(skill_path)
            return body
--- a/py/services/agent/skills/enrich_hf_metadata/SKILL.md
+++ b/py/services/agent/skills/enrich_hf_metadata/SKILL.md
@@ -1,89 +0,0 @@
---
-name: enrich_hf_metadata
-title: "Enrich Metadata from HuggingFace"
-description: >
-  Parse the HuggingFace model card via LLM to extract description, trigger
-  words, base model, tags, and preview image URL.
-llm_required: true
---
-
-You are an expert assistant for AI image generation models. Your task is to extract structured metadata from a HuggingFace model card (README.md).
-
-## Model Information
-
- **Repository**: {{hf_url}}
- **Model file path**: {{model_path}}
- **Repository ID**: {{repo}}
-
-## Current Metadata (may be incomplete)
-
-```json
-{{current_metadata}}
-```
-
-## Available Base Models
-
-The following base models are currently valid in this system:
-{{base_models}}
-
-## HuggingFace README Content
-
-```
-{{readme_content}}
-```
-
-## Extraction Instructions
-
-Extract the following information from the README content above:
-
-### base_model
-The base model this LoRA/checkpoint was trained on. Use EXACTLY one of the names from the **Available Base Models** list above. Do not invent new names or use aliases.
-
-Check the YAML frontmatter (between --- markers) for `base_model:` first, then look at the description text and safetensors metadata. If you cannot determine it, return an empty string.
-
-### trigger_words
-The trigger words or activation prompts needed to use this LoRA. Look for:
- `instance_prompt:` in the YAML frontmatter
- Phrases like "trigger word:", "trigger:", "use this prompt:", "activation prompt:"
- Example prompts at the start (usually the first word or phrase before any description)
-Return as an array of strings. If none found, return an empty array.
-
-### description
-A concise 1-2 sentence summary of what this model does. Extract from the "Model description" section or the first paragraph. Return empty string if the README is too minimal.
-
-### tags
-3-8 relevant tags for categorizing this model. Extract from:
- The YAML frontmatter `tags:` list (often contains excellent categorization tags)
- The model type (e.g. "lora", "checkpoint", "flux", "sdxl")
- The style/subject (e.g. "anime", "photorealistic", "style", "character")
-All lowercase, no spaces. Return empty array if none found.
-
-### preview_url
-The URL of the most suitable preview image from the README. Look for image tags (e.g. `![alt](url)`) and the YAML frontmatter `widget:` section (which often has `output.url` fields). Choose the first image that appears to be a generation example (not a logo or diagram). Construct the absolute URL as `https://huggingface.co/{{repo}}/resolve/main/{filename}`. If no suitable image is found, return an empty string.
-
-### confidence
-Your confidence level in the extracted data:
- "high" — most fields were explicitly stated in the README
- "medium" — some fields were inferred from context
- "low" — most fields are guesses based on limited information
-
-## Output Format
-
-Return ONLY a JSON object with exactly these fields (no markdown fences, no extra text):
-
-```json
-{
-  "model_path": "{{model_path}}",
-  "base_model": "<canonical name or empty string>",
-  "trigger_words": ["<word1>", "<word2>"],
-  "description": "<1-2 sentence summary>",
-  "tags": ["<tag1>", "<tag2>"],
-  "preview_url": "<image URL or empty string>",
-  "confidence": "<high|medium|low>"
-}
-```
-
-Important:
- Only include the JSON object, no other text
- If a field cannot be determined, use an empty string or empty array
- Do not fabricate information not supported by the README
--- a/py/services/agent/skills/enrich_hf_metadata/prompt.md
+++ b/py/services/agent/skills/enrich_hf_metadata/prompt.md
@@ -0,0 +1,165 @@
+---
+name: enrich_hf_metadata
+title: "Enrich Metadata from HuggingFace"
+description: >
+  Parse the HuggingFace model card via LLM to extract description, trigger
+  words, base model, tags, and preview image URL.
+llm_required: true
+---
+
+You are an expert assistant for AI image generation models. Your task is to extract structured metadata from a HuggingFace model card (README.md).
+
+## Model Information
+
+- **Repository**: {{hf_url}}
+- **Model file path**: {{model_path}}
+- **Model filename**: {{model_basename}}
+- **Repository ID**: {{repo}}
+
+## Current Metadata (may be incomplete)
+
+```json
+{{current_metadata}}
+```
+
+## User Priority Tags Reference
+
+The user has configured the following list of **meaningful tag categories** for this model type (`{{model_type}}`):
+
+```
+{{priority_tags}}
+```
+
+These are the subjects, styles, and concepts the user considers useful for categorization. Use this list as a **reference** when evaluating tags (see the **tags** section below).
+
+## Available Base Models
+
+The following base models are currently valid in this system.  Use the EXACT
+name listed — do not invent aliases or modify variant suffixes.
+
+{{base_models}}
+
+## HuggingFace README Content
+
+```
+{{readme_content}}
+```
+
+## Extraction Instructions
+
+Extract the following information from the README content above:
+
+### base_model
+The base model this model was trained on. Use EXACTLY one of the names from the **Available Base Models** list above. Do not invent new names or use aliases.
+
+Check the YAML frontmatter for ``base_model:`` first. If the frontmatter has no ``base_model:``, look at the **model filename** (``{{model_basename}}``), YAML ``tags:``, README title and first paragraph for clues — the base model family is often embedded in the name
+
+### trigger_words
+The trigger words or activation prompts needed to use this LoRA. Look for:
+- `instance_prompt:` in the YAML frontmatter
+- Phrases like "trigger word:", "trigger:", "use this prompt:", "activation prompt:"
+- In collection repos: the trigger section **specific to this model file** (look near matching download links or anchor IDs)
+- Example prompts at the start (usually the first word or phrase before any description)
+Return as an array of strings. If none found, return an empty array `[]`. **Never** return `["None"]` or any placeholder value — a truly empty list means no trigger words exist.
+
+### short_description
+A concise 1-2 sentence summary of what this model does. Extract from the "Model description" section or the first paragraph.  For collection repos, focus on the **specific model version** matching `{{model_basename}}`, not the repo as a whole.  Return empty string if the README is too minimal.
+
+### tags
+3-8 relevant tags for categorizing this model. **Quality over quantity.**
+
+Sources to consider:
+- The YAML frontmatter `tags:` list (filter out technical ones — see below)
+- The subject, style, character, or concept the model represents
+- The model filename itself may give clues (e.g. "pokemon", "anime", "pixelart")
+
+**Critical filtering rules — apply them strictly:**
+
+1. **Exclude technical/generic tags.** Reject any tag that describes the model's **training methodology, framework, architecture, or modality** rather than its content. Examples to exclude: `text-to-image`, `diffusers`, `lora`, `dreambooth`, `diffusers-training`, `flux`, `sdxl`, `checkpoint`, `pytorch`, `safetensors`, `fine-tuning`, `stable-diffusion`, and any variant of these.
+
+2. **Cross-reference against the priority_tags reference.** Only include a tag if it meaningfully describes what the model actually creates (subject, style, character type) and is semantically close to one of the priority_tags. If none of the README's tags match meaningful categories, prefer returning a smaller set or an empty array over including low-value tags.
+
+3. **All lowercase, no spaces, no hyphens** (use single words like `"photorealistic"`, `"anime"`, `"character"`).
+
+Return empty array if no meaningful content tags remain after filtering.
+
+### recommended_width, recommended_height
+The recommended image generation resolution for this model, in pixels. Look for sections like "Best Dimensions", "Recommended size", "Suggested resolution", or similar phrasing in the README. Prefer the explicitly marked "Best" or default resolution. If the table/list has multiple entries (e.g. "768 x 1024 (Best)" and "1024 x 1024 (Default)"), use the one marked "Best". Return integers. If no resolution can be determined, return 0 for both.
+
+### preview_url
+The URL of the most suitable preview image from the README. Look for:
+- Image tags near the section matching the model filename (`{{model_basename}}`)
+- The YAML frontmatter `widget:` section (which often has `output.url` fields)
+- In collection repos: the sample images listed **under the section** for this specific model version
+- Generic `![alt](url)` in the body
+Choose the first image that appears to be a generation example (not a logo or diagram). Construct the absolute URL as `https://huggingface.co/{{repo}}/resolve/main/{filename}`. If no suitable image is found, return an empty string.
+
+### notes
+A plain-text summary of the model card's key practical usage information. Combine trigger words, style modifiers, recommended parameters (steps, CFG, resolution, sampler), and any setup tips into a readable paragraph.  For collection repos, focus on the **specific model version** matching `{{model_basename}}`.  Return empty string if the README has no useful usage info.
+
+### usage_tips
+A JSON string with structured usage recommendations. Extract from the README any explicit ranges or recommended values (e.g. "Set LoRA strength: **0.85 - 1.4**", "CLIP strength: 0.5"). Possible fields (include only those you can determine):
+
+```json
+{
+  "strength_min": 0.85,
+  "strength_max": 1.4,
+  "strength_range": "0.85-1.4",
+  "strength": 0.6,
+  "clip_strength": 0.5,
+  "clip_skip": 2
+}
+```
+
+Return the JSON string (e.g. `'{"strength_min":0.85,"strength_max":1.4}'`). Return `"{}"` if nothing useful is found.
+
+### confidence
+Your confidence level in the extracted data:
+- "high" — most fields were explicitly stated in the README
+- "medium" — some fields were inferred from context
+- "low" — most fields are guesses based on limited information
+
+## Important: Handling Collection Repos (multiple model files)
+
+Many HuggingFace repos contain **multiple model files** in a single repository
+(e.g. a "LoRA collection" with different styles/characters in separate files).
+
+The model file currently being enriched is: **`{{model_basename}}`**
+
+To find the correct section in the README:
+
+1. **Search for download links** containing the filename — the surrounding paragraph is your section.
+2. **Search for anchor IDs** (`<a id="...">`) or section headings whose text matches words from the filename.
+3. **Search for HTML headings** (`<h1>`, `<h2>`, `<span>`) containing parts of the filename.
+4. If no match is found, use the full README as usual — the model may be the only one in the repo.
+
+When a matching section IS found, prefer metadata from that section.
+When no section matches (e.g. single-model repos or repos without per-file sections),
+extract metadata from the full README normally.  Do not return empty data just
+because the filename doesn't appear in the README.
+
+## Output Format
+
+Return ONLY a JSON object with exactly these fields (no markdown fences, no extra text):
+
+```json
+{
+  "model_path": "{{model_path}}",
+  "base_model": "<canonical name or empty string>",
+  "trigger_words": ["<word1>", "<word2>"],
+  "short_description": "<1-2 sentence summary>",
+  "tags": ["<tag1>", "<tag2>"],
+  "recommended_width": 768,
+  "recommended_height": 1024,
+  "preview_url": "<image URL or empty string>",
+  "notes": "<plain-text usage summary or empty string>",
+  "usage_tips": "<JSON string like '{\"strength_min\":0.85,\"strength_max\":1.4}' or '{}'>",
+  "confidence": "<high|medium|low>"
+}
+```
+
+Important:
+- Only include the JSON object, no other text
+- If a field cannot be determined, use an empty string or empty array
+- Do not fabricate information not supported by the README
+- Never use placeholder values like `"None"` or `"unknown"` for missing data — use empty string or empty array
--- a/py/services/agent/skills/enrich_hf_metadata/readme_processor.py
+++ b/py/services/agent/skills/enrich_hf_metadata/readme_processor.py
--- a/py/services/civitai_base_model_service.py
+++ b/py/services/civitai_base_model_service.py
@@ -213,6 +213,18 @@ class CivitaiBaseModelService:
            "wan video 2.2 i2v-a14b": "WAN",
            "wan video 2.5 t2v": "WAN",
            "wan video 2.5 i2v": "WAN",
+            "wan video 2.7": "WAN",
+            "wan image 2.7": "WI27",
+            "ace audio": "ACE",
+            "boogu": "BOOG",
+            "grok": "GROK",
+            "happyhorse": "HAPP",
+            "hidream-o1": "HIO1",
+            "lens": "LENS",
+            "mai": "MAI",
+            "upscaler": "UPSC",
+            "ideogram 4.0": "ID40",
+            "qwen 2": "QWN2",
        }

        if lower_name in special_cases:
@@ -392,6 +404,7 @@ class CivitaiBaseModelService:
                "LTXV2",
                "LTXV 2.3",
                "CogVideoX",
+                "HappyHorse",
                "Mochi",
                "Hunyuan Video",
                "Wan Video",
@@ -404,15 +417,25 @@ class CivitaiBaseModelService:
                "Wan Video 2.2 I2V-A14B",
                "Wan Video 2.5 T2V",
                "Wan Video 2.5 I2V",
+                "Wan Image 2.7",
+                "Wan Video 2.7",
            ],
            "Other Models": [
+                "ACE Audio",
                "Illustrious",
                "Pony",
                "Pony V7",
+                "Boogu",
                "HiDream",
+                "HiDream-O1",
+                "Ideogram 4.0",
                "Qwen",
+                "Qwen 2",
                "AuraFlow",
                "Chroma",
+                "Grok",
+                "Lens",
+                "MAI",
                "ZImageTurbo",
                "ZImageBase",
                "PixArt a",
@@ -426,6 +449,7 @@ class CivitaiBaseModelService:
                "Ernie Turbo",
                "Nucleus",
                "Krea 2",
+                "Upscaler",
            ],
        }

--- a/py/services/llm_service.py
+++ b/py/services/llm_service.py
@@ -19,11 +19,165 @@ from .errors import LLMNotConfiguredError, LLMRateLimitError, LLMResponseError

 logger = logging.getLogger(__name__)

-# Default API base URLs per provider
+# ---------------------------------------------------------------------------
+# Model catalog sourced from opencode's maintained model registry.
+# maps provider_id -> list of model IDs.
+# ---------------------------------------------------------------------------
+_MODEL_CATALOG_URL = "https://models.dev/api.json"
+
+# In-memory cache: maps provider slug -> list of model ID strings.
+_catalog_cache: Optional[Dict[str, List[str]]] = None
+_CATALOG_TIMEOUT = aiohttp.ClientTimeout(total=30)
+
+
+async def _load_model_catalog() -> Dict[str, List[str]]:
+    """Fetch and parse the model catalog, returning ``{provider_id: [model_id, ...]}``.
+
+    The JSON at ``_MODEL_CATALOG_URL`` is a dict keyed by provider slug; each
+    value has a ``models`` sub-dict keyed by model ID.  Only the model IDs are
+    kept.  The result is cached in memory after the first successful fetch.
+    Subsequent calls return the cached data immediately.
+    """
+    global _catalog_cache
+    if _catalog_cache is not None:
+        return _catalog_cache
+
+    try:
+        async with aiohttp.ClientSession(timeout=_CATALOG_TIMEOUT) as session:
+            async with session.get(_MODEL_CATALOG_URL) as resp:
+                if resp.status != 200:
+                    logger.warning("Model catalog returned HTTP %s", resp.status)
+                    return _catalog_cache or {}
+                data = await resp.json()
+    except (aiohttp.ClientError, asyncio.TimeoutError, json.JSONDecodeError) as exc:
+        logger.warning("Failed to fetch model catalog: %s", exc)
+        return _catalog_cache or {}
+
+    if not isinstance(data, dict):
+        logger.warning("Model catalog is not a dict, got %s", type(data).__name__)
+        return _catalog_cache or {}
+
+    result: Dict[str, List[str]] = {}
+    for provider_id, provider_info in data.items():
+        if not isinstance(provider_info, dict):
+            continue
+        models_dict = provider_info.get("models")
+        if not isinstance(models_dict, dict):
+            continue
+        model_ids = [str(mid) for mid in models_dict.keys() if isinstance(mid, str)]
+        if model_ids:
+            result[provider_id] = model_ids
+
+    _catalog_cache = result
+    logger.debug(
+        "Loaded model catalog: %d providers, %d total models",
+        len(result),
+        sum(len(m) for m in result.values()),
+    )
+    return result
+
+
+# Short timeout for Ollama's local API
+_OLLAMA_API_TIMEOUT = aiohttp.ClientTimeout(total=8)
+
+
+async def fetch_ollama_models(api_base: str) -> List[str]:
+    """Fetch locally available models from a running Ollama instance.
+
+    Uses Ollama's OpenAI-compatible ``GET {api_base}/models`` endpoint.
+    Returns an empty list if Ollama is not reachable (not running).
+    """
+    url = f"{api_base.rstrip('/')}/models"
+    try:
+        async with aiohttp.ClientSession(timeout=_OLLAMA_API_TIMEOUT) as session:
+            async with session.get(url) as resp:
+                if resp.status != 200:
+                    logger.debug("Ollama API returned HTTP %s from %s", resp.status, api_base)
+                    return []
+                data = await resp.json()
+    except (aiohttp.ClientError, asyncio.TimeoutError, json.JSONDecodeError) as exc:
+        logger.debug("Ollama not reachable at %s: %s", api_base, exc)
+        return []
+
+    raw = data.get("data") if isinstance(data, dict) else None
+    if not isinstance(raw, list):
+        return []
+
+    return [
+        str(entry["id"]) for entry in raw
+        if isinstance(entry, dict) and isinstance(entry.get("id"), str)
+    ]
+
+
+async def get_provider_model_ids(provider_id: str) -> List[str]:
+    """Return the list of known model IDs for *provider_id* from the catalog.
+
+    The catalog is loaded on first call and cached thereafter.  If the
+    provider is not found an empty list is returned (never raises).
+    """
+    catalog = await _load_model_catalog()
+    return catalog.get(provider_id, [])
+
+
+async def get_all_provider_models(
+    provider_ids: List[str],
+) -> Dict[str, List[str]]:
+    """Return model lists for a subset of providers in one call.
+
+    Loads the catalog (cached) and returns only the requested providers.
+    Handy for embedding lightweight data into the template context.
+    """
+    catalog = await _load_model_catalog()
+    return {
+        pid: catalog.get(pid, [])
+        for pid in provider_ids
+    }
+
+
+# Provider preset definitions.
+# Each entry contains display metadata and defaults for the UI.
+# The key is the internal provider id stored in ``llm_provider``.
+# Models are NOT listed here — they come from the opencode model catalog at
+# runtime (see :func:`get_provider_model_ids`).
+PROVIDER_PRESETS: Dict[str, Dict[str, Any]] = {
+    "openai": {
+        "name": "OpenAI",
+        "api_base": "https://api.openai.com/v1",
+        "requires_key": True,
+    },
+    "ollama": {
+        "name": "Ollama (local)",
+        "api_base": "http://localhost:11434/v1",
+        "requires_key": False,
+    },
+    "deepseek": {
+        "name": "DeepSeek",
+        "api_base": "https://api.deepseek.com/v1",
+        "requires_key": True,
+    },
+    "groq": {
+        "name": "Groq",
+        "api_base": "https://api.groq.com/openai/v1",
+        "requires_key": True,
+    },
+    "openrouter": {
+        "name": "OpenRouter",
+        "api_base": "https://openrouter.ai/api/v1",
+        "requires_key": True,
+    },
+    "opencode-go": {
+        "name": "OpenCode Go",
+        "api_base": "https://opencode.ai/zen/go/v1",
+        "requires_key": True,
+    },
+    # "custom" is handled specially (no preset api_base, requires user input)
+}
+
+# Legacy lookup derived from PROVIDER_PRESETS for backward compat.
 _PROVIDER_DEFAULTS: Dict[str, str] = {
-    "openai": "https://api.openai.com/v1",
-    "ollama": "http://localhost:11434/v1",
-    # "custom" requires an explicit llm_api_base from the user
+    pid: info["api_base"]
+    for pid, info in PROVIDER_PRESETS.items()
+    if info.get("api_base")
 }

 # Request timeout for LLM calls (seconds)
@@ -33,8 +187,8 @@ _LLM_TIMEOUT = aiohttp.ClientTimeout(total=120)
 class LLMService:
    """Centralized LLM API client.

-    All agent skills call LLMs through this service so that BYOK config,
-    retry logic, and error handling live in one place.
+    All LLM-based enrichment features call through this service so
+    that BYOK config, retry logic, and error handling live in one place.
    """

    _instance: Optional["LLMService"] = None
@@ -57,6 +211,10 @@ class LLMService:
                    from .settings_manager import get_settings_manager

                    cls._instance = cls(get_settings_manager())
+                    # Start preloading the model catalog in the background so
+                    # the settings UI never blocks on it.  The catalog is
+                    # cached after the first fetch (see _load_model_catalog).
+                    asyncio.create_task(_load_model_catalog())
        return cls._instance

    @classmethod
@@ -79,20 +237,31 @@ class LLMService:
            "model": self._settings.get("llm_model", ""),
        }

+    @staticmethod
+    def _provider_requires_key(provider: str) -> bool:
+        """Return ``False`` when the given provider id does not need an API key."""
+        preset = PROVIDER_PRESETS.get(provider, {})
+        return bool(preset.get("requires_key", True))
+
    def is_configured(self) -> bool:
        """Return ``True`` when the LLM provider is minimally configured.

        A provider is considered configured when ``llm_model`` is set and
-        (for non-Ollama) an API key is configured.
+        an API key is configured for providers that require one (e.g.
+        Ollama does not).
        """

        cfg = self._get_config()
        has_model = bool(cfg["model"])
-        has_key = bool(cfg["api_key"]) or cfg["provider"] == "ollama"
+        has_key = bool(cfg["api_key"]) or not self._provider_requires_key(cfg["provider"])
        return has_model and has_key

    def _resolve_api_base(self, provider: str, api_base: str) -> str:
-        """Resolve the API base URL for the given provider."""
+        """Resolve the API base URL for the given provider.
+
+        If ``api_base`` is explicitly set (non-empty), it takes priority.
+        Otherwise the default from :data:`PROVIDER_PRESETS` is used.
+        """

        if api_base:
            return api_base.rstrip("/")
@@ -115,12 +284,13 @@ class LLMService:

        cfg = self._get_config()
        has_model = bool(cfg["model"])
-        has_key = bool(cfg["api_key"]) or cfg["provider"] == "ollama"
+        needs_key = self._provider_requires_key(cfg["provider"])
+        has_key = bool(cfg["api_key"]) or not needs_key
        if not (has_model and has_key):
            parts = []
            if not has_model:
                parts.append("No LLM model specified")
-            if not has_key and cfg["provider"] != "ollama":
+            if not has_key and needs_key:
                parts.append("No LLM API key configured")
            detail = "; ".join(parts) if parts else "LLM provider is not configured"
            raise LLMNotConfiguredError(
@@ -163,18 +333,66 @@ class LLMService:

        cfg = self._ensure_configured()
        api_base = self._resolve_api_base(cfg["provider"], cfg["api_base"])
-        url = f"{api_base}/chat/completions"
        model_name = model or cfg["model"]

-        payload: Dict[str, Any] = {
-            "model": model_name,
-            "messages": messages,
-            "temperature": temperature,
-        }
-        if response_format is not None:
-            payload["response_format"] = response_format
-        if max_tokens is not None:
-            payload["max_tokens"] = max_tokens
+        is_ollama = cfg["provider"] == "ollama"
+
+        if is_ollama:
+            # Use Ollama's native /api/chat endpoint which does NOT expose
+            # a separate reasoning/thinking field (the model's full output
+            # lands directly in message.content).  The OpenAI-compatible
+            # endpoint splits thinking into the "reasoning" field, making
+            # content empty when thinking consumes all available tokens.
+            base = api_base.rstrip("/")
+            if base.endswith("/v1"):
+                base = base[:-3]
+            url = f"{base}/api/chat"
+        else:
+            url = f"{api_base}/chat/completions"
+
+        payload: Dict[str, Any]
+        if is_ollama:
+            payload = {
+                "model": model_name,
+                "messages": messages,
+                "stream": False,
+                # Suppress separate thinking trace — thinking still happens
+                # internally (accuracy preserved) but output goes directly to
+                # message.content instead of being split across content +
+                # thinking.  Without this the model can exhaust num_predict
+                # on thinking alone and leave content empty.
+                "think": False,
+                "options": {
+                    "temperature": temperature,
+                    # Allow up to 32K context so the model has room to think
+                    # AND produce output without hitting the 4K default limit.
+                    "num_ctx": 32768,
+                },
+            }
+            if response_format is not None:
+                payload["format"] = "json"
+            if max_tokens is not None:
+                payload["options"]["num_predict"] = max_tokens
+        else:
+            payload = {
+                "model": model_name,
+                "messages": messages,
+                "temperature": temperature,
+            }
+            if response_format is not None:
+                payload["response_format"] = response_format
+            if max_tokens is not None:
+                payload["max_tokens"] = max_tokens
+
+        if is_ollama:
+            logger.info(
+                "Ollama request: model=%s num_ctx=%s num_predict=%s format=%s think=%s",
+                payload.get("model"),
+                payload.get("options", {}).get("num_ctx"),
+                payload.get("options", {}).get("num_predict"),
+                payload.get("format", "none"),
+                payload.get("think"),
+            )

        headers = self._build_headers(cfg["api_key"])

@@ -217,8 +435,25 @@ class LLMService:

            # Parse response
            try:
-                content = data["choices"][0]["message"]["content"]
-                usage = data.get("usage", {})
+                if is_ollama:
+                    content = (data.get("message") or {}).get("content") or ""
+                    usage = {"completion_tokens": data.get("eval_count", 0)}
+                    finish_reason = data.get("done_reason", "")
+                    if not content:
+                        logger.warning(
+                            "LLM returned empty content. Provider=ollama, "
+                            "done_reason=%s, eval_count=%s",
+                            finish_reason,
+                            data.get("eval_count", 0),
+                        )
+                else:
+                    content = data["choices"][0]["message"].get("content") or ""
+                    usage = data.get("usage", {})
+                    if not content:
+                        logger.warning(
+                            "LLM returned empty content. Full response truncated: %s",
+                            json.dumps(data, ensure_ascii=False)[:1000],
+                        )
                return {
                    "content": content,
                    "usage": usage,
@@ -272,27 +507,43 @@ class LLMService:
            {"role": "user", "content": user_prompt},
        ]

-        # First attempt with JSON mode
+        # First attempt with JSON mode.
+        # Use a generous max_tokens so thinking-enabled models (e.g.
+        # gemma4 via Ollama) have room to reason AND still emit content.
+        effective_max = max_tokens or 131072
        result = await self.chat_completion(
            messages=messages,
            model=model,
            temperature=temperature,
            response_format={"type": "json_object"},
-            max_tokens=max_tokens,
+            max_tokens=effective_max,
        )

        try:
-            return json.loads(result["content"])
+            parsed = json.loads(result["content"])
+            logger.debug(
+                "LLM raw content: %s",
+                json.dumps(parsed, ensure_ascii=False)[:2000],
+            )
+            return parsed
        except (json.JSONDecodeError, TypeError) as exc:
+            logger.info(
+                "LLM raw response (first 800 chars): %s",
+                (result.get("content") or "")[:800],
+            )
            logger.warning(
                "LLM JSON parse failed on first attempt: %s. Retrying.", exc
            )

-        # Retry with explicit instruction to return valid JSON
+        # Retry WITHOUT response_format — some providers (Ollama with
+        # thinking-enabled models like gemma4) may return empty content
+        # when json_object mode is active.  Fall back to a textual
+        # instruction instead.
+        previous_content = result.get("content", "") or ""
        retry_messages = messages + [
            {
                "role": "assistant",
-                "content": result["content"],
+                "content": previous_content or "(empty response)",
            },
            {
                "role": "user",
@@ -308,14 +559,117 @@ class LLMService:
            messages=retry_messages,
            model=model,
            temperature=0.0,  # More deterministic for retry
-            response_format={"type": "json_object"},
-            max_tokens=max_tokens,
+            max_tokens=effective_max,
        )

-        try:
-            return json.loads(result["content"])
-        except (json.JSONDecodeError, TypeError) as exc:
+        content = result.get("content", "") or ""
+        if not content:
            raise LLMResponseError(
-                f"LLM response could not be parsed as JSON after retry: {exc}\n"
-                f"Raw content: {result['content'][:500]}"
-            ) from exc
+                "LLM response could not be parsed as JSON after retry: "
+                f"Expecting value: line 1 column 1 (char 0)\n"
+                f"Raw content: {content[:500]}"
+            )
+
+        try:
+            return json.loads(content)
+        except (json.JSONDecodeError, TypeError) as parse_err:
+            # Last resort: attempt to salvage partial JSON (closing unclosed
+            # brackets/braces, truncating incomplete strings, etc.)
+            salvaged = _try_salvage_json(content)
+            if salvaged is not None:
+                logger.warning(
+                    "LLM JSON salvaged from partial content (%d chars raw)",
+                    len(content),
+                )
+                return salvaged
+            raise LLMResponseError(
+                f"LLM response could not be parsed as JSON after retry: {parse_err}\n"
+                f"Raw content: {content[:500]}"
+            ) from parse_err
+
+
+def _try_salvage_json(raw: str) -> Dict[str, Any] | None:
+    """Attempt to repair and parse a truncated JSON string.
+
+    Handles common truncation patterns:
+
+    * Incomplete string value at the end (``"foo`` → ``"foo"``)
+    * Missing closing ``}`` or ``]`` (respecting nesting order)
+    * Trailing comma before closing bracket
+    * Extra text after the JSON object (e.g. markdown fences)
+
+    Returns the parsed dict on success, ``None`` if repair is impossible.
+    """
+    if not raw:
+        return None
+
+    text = raw.strip()
+
+    # Strip markdown fences if the LLM wrapped the JSON
+    if text.startswith("```"):
+        end = text.find("\n")
+        text = text[end + 1:] if end != -1 else text[3:]
+    if text.endswith("```"):
+        text = text[:-3].rstrip()
+
+    # Find the first '{' and strip everything before it
+    start = text.find("{")
+    if start == -1:
+        return None
+    text = text[start:]
+
+    # Try to close an incomplete string at the end (e.g. ``"https://huggingf``)
+    # Pattern: ends mid-string (last quote is open)
+    if text.count('"') % 2 == 1:
+        text += '"'
+
+    # Ensure trailing commas before closing braces work
+    text = _strip_trailing_commas(text)
+
+    # Walk through the text character by character to find unclosed
+    # brackets and close them in the correct (LIFO) order.
+    # We ignore brackets inside quoted strings.
+    stack: list[str] = []
+    in_string = False
+    escape = False
+    for ch in text:
+        if escape:
+            escape = False
+            continue
+        if ch == "\\":
+            escape = True
+            continue
+        if ch == '"':
+            in_string = not in_string
+            continue
+        if in_string:
+            continue
+        if ch in ("{", "["):
+            stack.append(ch)
+        elif ch == "}":
+            if stack and stack[-1] == "{":
+                stack.pop()
+            else:
+                return None  # Unmatched closer — unrecoverable
+        elif ch == "]":
+            if stack and stack[-1] == "[":
+                stack.pop()
+            else:
+                return None
+
+    # Close remaining open brackets in reverse order
+    for opener in reversed(stack):
+        text += "}" if opener == "{" else "]"
+
+    try:
+        return json.loads(text)
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+
+def _strip_trailing_commas(text: str) -> str:
+    """Remove commas that appear before a closing brace/bracket."""
+    import re as _re
+    text = _re.sub(r",\s*}", "}", text)
+    text = _re.sub(r",\s*]", "]", text)
+    return text
--- a/py/utils/constants.py
+++ b/py/utils/constants.py
@@ -226,9 +226,21 @@ SUPPORTED_DOWNLOAD_SKIP_BASE_MODELS = frozenset(
        "Wan Video 2.5 I2V",
        "Hunyuan Video",
        "Anima",
+        "ACE Audio",
+        "Boogu",
        "Ernie",
        "Ernie Turbo",
-        "Nucleus",
+        "Grok",
+        "HappyHorse",
+        "HiDream-O1",
+        "Ideogram 4.0",
        "Krea 2",
+        "Lens",
+        "MAI",
+        "Nucleus",
+        "Qwen 2",
+        "Upscaler",
+        "Wan Image 2.7",
+        "Wan Video 2.7",
    ]
 )
--- a/static/css/components/menu.css
+++ b/static/css/components/menu.css
@@ -40,6 +40,12 @@
    margin: 3px 0;
 }

+.context-menu-item.disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+    pointer-events: none;
+}
+
 .context-menu-item.delete-item {
    color: var(--danger-color);
 }
--- a/static/css/components/modal/settings-modal.css
+++ b/static/css/components/modal/settings-modal.css
@@ -1592,3 +1592,45 @@ input:checked + .toggle-slider:before {
    animation: settings-highlight-pulse 1.5s ease-in-out 3;
    border-radius: var(--border-radius-xs);
 }
+
+/* ---- Combobox panel for AI Provider settings ---- */
+/* The panel is appended to <body> by Combobox.js and positioned relative to
+   the enhanced <input>. Styles reuse settings-modal CSS variables. */
+
+.lm-combobox-panel {
+    position: absolute;
+    z-index: 10002;
+    max-height: 240px;
+    overflow-y: auto;
+    background: var(--lora-surface, #2a2a2a);
+    border: 1px solid var(--border-color, rgba(255, 255, 255, 0.12));
+    border-radius: var(--border-radius-xs, 6px);
+    box-shadow: var(--shadow-elevated, 0 6px 18px rgba(0, 0, 0, 0.45));
+    font-size: 0.95em;
+    color: var(--text-color, rgba(226, 232, 240, 0.9));
+    padding: 4px 0;
+    box-sizing: border-box;
+}
+
+.lm-combobox-option {
+    padding: 6px 12px;
+    cursor: pointer;
+    user-select: none;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.lm-combobox-option:hover,
+.lm-combobox-option.is-active {
+    background: rgba(from var(--lora-accent) r g b / 0.2);
+    color: var(--lora-accent);
+}
+
+.lm-combobox-empty {
+    padding: 8px 12px;
+    color: var(--text-color);
+    opacity: 0.45;
+    font-style: italic;
+    user-select: none;
+}
--- a/static/js/components/Combobox.js
+++ b/static/js/components/Combobox.js
@@ -0,0 +1,394 @@
+// Combobox.js — Reusable dropdown-suggestion + free-text input component.
+//
+// Enhances an existing <input> element with a dropdown panel that merges static
+// `presets` with asynchronously fetched options (`fetchOptions`). The input
+// remains a free-text field — selecting a dropdown option is optional, the
+// user can always type an arbitrary value.
+//
+// Zero dependencies: pure DOM manipulation. Exported on `window.Combobox`
+// so non-module callers can instantiate it, and as a named ES module export
+// for callers that import it directly.
+//
+// Usage:
+//   const box = new Combobox(inputEl, {
+//     presets: ['masterpiece', 'best quality'],
+//     fetchOptions: async (q) => await fetchSuggestions(q),
+//     placeholder: 'Type a value…',
+//     onSelect: (value) => console.log('chose', value),
+//   });
+//   box.updatePresets(['new', 'presets']);
+//   box.setValue('masterpiece');
+
+const DEBOUNCE_MS = 300;
+
+export class Combobox {
+    /**
+     * @param {HTMLInputElement} inputElement Existing <input> to enhance.
+     * @param {Object} options
+     * @param {string[]} [options.presets=[]] Static preset values shown in dropdown.
+     * @param {(inputValue: string) => Promise<string[]>} [options.fetchOptions]
+     *        Async function returning dynamic suggestions for the current input.
+     * @param {string} [options.placeholder] Placeholder text for the empty state.
+     * @param {(value: string) => void} [options.onSelect] Callback when an option is chosen.
+     */
+    constructor(inputElement, options = {}) {
+        if (!inputElement || inputElement.tagName !== 'INPUT') {
+            console.error('Combobox: expected an <input> element');
+            return;
+        }
+
+        this.input = inputElement;
+        this.presets = Array.isArray(options.presets) ? [...options.presets] : [];
+        this.fetchOptions = typeof options.fetchOptions === 'function' ? options.fetchOptions : null;
+        this.placeholder = options.placeholder || '';
+        this.onSelect = typeof options.onSelect === 'function' ? options.onSelect : null;
+
+        // Internal state
+        this._isOpen = false;
+        this._activeIndex = -1;
+        this._renderedOptions = []; // current visible option strings (de-duplicated, merged)
+        this._fetchToken = 0; // guards against out-of-order async fetch results
+        this._fetchTimer = null;
+        this._suppressInputOpen = false; // guards setValue() from reopening the dropdown
+
+        this._buildDropdown();
+        this._bindEvents();
+    }
+
+    // ---- public API ----
+
+    /**
+     * Replace the preset list. Re-renders the dropdown if it is open.
+     * @param {string[]} presets
+     * @returns {void}
+     */
+    updatePresets(presets) {
+        this.presets = Array.isArray(presets) ? [...presets] : [];
+        if (this._isOpen) {
+            this._refresh();
+        }
+    }
+
+    /**
+     * Set the input value programmatically without triggering the dropdown
+     * or firing synthetic events.
+     * @param {string} value
+     * @returns {void}
+     */
+    setValue(value) {
+        const prev = this._suppressInputOpen;
+        this._suppressInputOpen = true;
+        this.input.value = value ?? '';
+        this._suppressInputOpen = prev;
+        if (this._isOpen) {
+            this._refresh();
+        }
+    }
+
+    // ---- build ----
+
+    _buildDropdown() {
+        const panel = document.createElement('div');
+        panel.className = 'lm-combobox-panel';
+        panel.setAttribute('role', 'listbox');
+        panel.style.display = 'none';
+        // Append to <body> so the panel is never clipped by an overflow:hidden
+        // ancestor; positioning is recomputed on each open.
+        document.body.appendChild(panel);
+        this.panel = panel;
+
+        if (this.placeholder) {
+            this.input.setAttribute('placeholder', this.placeholder);
+        }
+        this.input.setAttribute('autocomplete', 'off');
+        this.input.setAttribute('role', 'combobox');
+        this.input.setAttribute('aria-autocomplete', 'list');
+        this.input.setAttribute('aria-expanded', 'false');
+    }
+
+    // ---- event wiring ----
+
+    _bindEvents() {
+        this.input.addEventListener('focus', () => {
+            if (this._suppressInputOpen) return;
+            this._open();
+        });
+
+        this.input.addEventListener('input', () => {
+            if (this._suppressInputOpen) return;
+            this._open();          // no-op if already open
+            this._refresh();       // re-filter by current input value
+            this._scheduleFetch();
+        });
+
+        this.input.addEventListener('keydown', (event) => this._onKeyDown(event));
+
+        // Click an option (delegated)
+        this.panel.addEventListener('click', (event) => {
+            const item = event.target.closest('.lm-combobox-option');
+            if (!item) return;
+            const value = item.dataset.value;
+            if (value !== undefined) {
+                this._choose(value);
+            }
+        });
+
+        // Hover updates the active highlight so keyboard + mouse stay in sync.
+        this.panel.addEventListener('mouseover', (event) => {
+            const item = event.target.closest('.lm-combobox-option');
+            if (!item) return;
+            const idx = Number(item.dataset.index);
+            if (!Number.isNaN(idx)) {
+                this._setActiveIndex(idx);
+            }
+        });
+
+        // Click outside closes the dropdown.
+        this._outsideClickHandler = (event) => {
+            if (this._isOpen && !this.input.contains(event.target) && !this.panel.contains(event.target)) {
+                this._close();
+            }
+        };
+        document.addEventListener('mousedown', this._outsideClickHandler);
+
+        // Reposition on viewport changes while open.
+        this._resizeHandler = () => {
+            if (this._isOpen) this._position();
+        };
+        window.addEventListener('resize', this._resizeHandler);
+        window.addEventListener('scroll', this._resizeHandler, true);
+    }
+
+    // ---- keyboard ----
+
+    _onKeyDown(event) {
+        if (!this._isOpen) {
+            if (event.key === 'ArrowDown') {
+                event.preventDefault();
+                this._open();
+                this._setActiveIndex(0);
+            }
+            return;
+        }
+
+        switch (event.key) {
+            case 'ArrowDown':
+                event.preventDefault();
+                this._setActiveIndex(this._activeIndex + 1);
+                break;
+
+            case 'ArrowUp':
+                event.preventDefault();
+                this._setActiveIndex(this._activeIndex - 1);
+                break;
+
+            case 'Enter':
+                // Only intercept Enter to pick an option when one is actively
+                // highlighted; otherwise let the input's default behavior
+                // (form submit / free-text commit) proceed.
+                if (this._activeIndex >= 0 && this._activeIndex < this._renderedOptions.length) {
+                    event.preventDefault();
+                    this._choose(this._renderedOptions[this._activeIndex]);
+                }
+                break;
+
+            case 'Escape':
+                event.preventDefault();
+                this._close();
+                this.input.focus();
+                break;
+
+            case 'Tab':
+                // Allow normal tab navigation; just close the panel.
+                this._close();
+                break;
+        }
+    }
+
+    // ---- open / close ----
+
+    _open() {
+        if (this._isOpen) return;
+        this._isOpen = true;
+        this.panel.style.display = 'block';
+        this.input.setAttribute('aria-expanded', 'true');
+        // On open, render ALL presets — do not filter by the current input
+        // value.  Filtering on the input event is handled separately.
+        this._render(this.presets);
+        this._position();
+    }
+
+    _close() {
+        if (!this._isOpen) return;
+        this._isOpen = false;
+        this.panel.style.display = 'none';
+        this.input.setAttribute('aria-expanded', 'false');
+        this._activeIndex = -1;
+        this._cancelFetch();
+    }
+
+    _position() {
+        const rect = this.input.getBoundingClientRect();
+        const panelHeight = this.panel.offsetHeight;
+        const viewportHeight = window.innerHeight;
+        const spaceBelow = viewportHeight - rect.bottom;
+        const spaceAbove = rect.top;
+
+        // Flip above the input when there is more room there.
+        const placeAbove = spaceBelow < panelHeight && spaceAbove > spaceBelow;
+        const top = placeAbove
+            ? rect.top + window.scrollY - panelHeight
+            : rect.bottom + window.scrollY;
+
+        this.panel.style.top = `${Math.max(0, top)}px`;
+        this.panel.style.left = `${rect.left + window.scrollX}px`;
+        this.panel.style.minWidth = `${rect.width}px`;
+    }
+
+    // ---- rendering ----
+
+    /** Render a list of strings into the panel. */
+    _render(items) {
+        this._renderedOptions = items;
+        this.panel.innerHTML = '';
+        if (items.length === 0) {
+            const empty = document.createElement('div');
+            empty.className = 'lm-combobox-empty';
+            empty.textContent = this.placeholder ? this.placeholder : 'No options';
+            this.panel.appendChild(empty);
+            this._activeIndex = -1;
+            return;
+        }
+
+        const fragment = document.createDocumentFragment();
+        items.forEach((opt, idx) => {
+            const item = document.createElement('div');
+            item.className = 'lm-combobox-option';
+            item.setAttribute('role', 'option');
+            item.dataset.value = opt;
+            item.dataset.index = String(idx);
+            item.textContent = opt;
+            if (idx === this._activeIndex) {
+                item.classList.add('is-active');
+            }
+            fragment.appendChild(item);
+        });
+        this.panel.appendChild(fragment);
+
+        if (this._activeIndex >= items.length) {
+            this._setActiveIndex(items.length - 1);
+        }
+    }
+
+    /** Filter presets by current input value and re-render. */
+    _refresh() {
+        const value = this.input.value;
+        const filtered = this._filterPresets(value);
+        const merged = this._mergeUnique(filtered, this._fetchedOptions || []);
+        this._render(merged);
+    }
+
+    _filterPresets(value) {
+        const v = (value || '').toLowerCase();
+        if (!v) return [...this.presets];
+        return this.presets.filter((p) => String(p).toLowerCase().startsWith(v));
+    }
+
+    _mergeUnique(...lists) {
+        const seen = new Set();
+        const out = [];
+        for (const list of lists) {
+            for (const item of list) {
+                const key = String(item);
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    out.push(key);
+                }
+            }
+        }
+        return out;
+    }
+
+    _setActiveIndex(idx) {
+        const max = this._renderedOptions.length - 1;
+        const clamped = Math.max(-1, Math.min(max, idx));
+        this._activeIndex = clamped;
+        // Update DOM classes without full re-render.
+        const items = this.panel.querySelectorAll('.lm-combobox-option');
+        items.forEach((el, i) => {
+            el.classList.toggle('is-active', i === clamped);
+        });
+        // Scroll the active item into view inside the panel.
+        if (clamped >= 0 && items[clamped]) {
+            items[clamped].scrollIntoView({ block: 'nearest' });
+        }
+    }
+
+    /**
+     * Remove the panel from the DOM and detach event listeners.
+     * Call this before discarding the Combobox instance.
+     */
+    destroy() {
+        this._close();
+        if (this.panel && this.panel.parentNode) {
+            this.panel.parentNode.removeChild(this.panel);
+        }
+        document.removeEventListener('mousedown', this._outsideClickHandler);
+        window.removeEventListener('resize', this._resizeHandler);
+        window.removeEventListener('scroll', this._resizeHandler, true);
+    }
+
+    _choose(value) {
+        this.input.value = value;
+        this._close();
+        if (typeof this.onSelect === 'function') {
+            this.onSelect(value);
+        }
+        // Re-focus without reopening the dropdown.
+        this._suppressInputOpen = true;
+        this.input.focus();
+        this._suppressInputOpen = false;
+    }
+
+    // ---- async fetch (debounced) ----
+
+    _scheduleFetch() {
+        if (!this.fetchOptions) return;
+        this._cancelFetch();
+        this._fetchTimer = setTimeout(() => {
+            this._fetchTimer = null;
+            this._runFetch();
+        }, DEBOUNCE_MS);
+    }
+
+    _cancelFetch() {
+        if (this._fetchTimer) {
+            clearTimeout(this._fetchTimer);
+            this._fetchTimer = null;
+        }
+        this._fetchToken++; // invalidate any in-flight result
+    }
+
+    async _runFetch() {
+        if (!this.fetchOptions) return;
+        const token = this._fetchToken;
+        const value = this.input.value;
+        let results;
+        try {
+            results = await this.fetchOptions(value);
+        } catch (err) {
+            console.error('Combobox fetchOptions error:', err);
+            results = [];
+        }
+        // Stale guard: a newer fetch or close superseded this one.
+        if (token !== this._fetchToken || !this._isOpen) return;
+        this._fetchedOptions = Array.isArray(results) ? results : [];
+        this._refresh();
+    }
+}
+
+// Expose for non-module callers (templates load via <script type="module">,
+// but some widget code reads globals off `window`).
+if (typeof window !== 'undefined') {
+    window.Combobox = Combobox;
+}
--- a/static/js/components/ContextMenu/BaseContextMenu.js
+++ b/static/js/components/ContextMenu/BaseContextMenu.js
@@ -27,8 +27,9 @@ export class BaseContextMenu {
            const menuItem = e.target.closest('.context-menu-item');
            if (!menuItem || !this.currentCard) return;

-            // Ignore clicks on submenu trigger (has-submenu parent)
+            // Ignore clicks on submenu trigger (has-submenu parent) or disabled items
            if (menuItem.classList.contains('has-submenu')) return;
+            if (menuItem.classList.contains('disabled')) return;

            const action = menuItem.dataset.action;
            if (!action) return;
--- a/static/js/components/ContextMenu/BulkContextMenu.js
+++ b/static/js/components/ContextMenu/BulkContextMenu.js
@@ -274,7 +274,7 @@ export class BulkContextMenu extends BaseContextMenu {
            case 'resume-metadata-refresh':
                bulkManager.setSkipMetadataRefresh(false);
                break;
-            case 'enrich-hf-agent-bulk':
+            case 'enrich-hf-llm-bulk':
                this.enrichBulkWithAgent();
                break;
            case 'delete-all':
@@ -377,7 +377,6 @@ export class BulkContextMenu extends BaseContextMenu {

        const { agentManager } = await import('../../managers/AgentManager.js');

-        // Check if LLM is configured
        const configured = await agentManager.isLlmConfigured();
        if (!configured) {
            showToast('toast.agent.llmNotConfigured', {}, 'warning');
@@ -386,23 +385,39 @@ export class BulkContextMenu extends BaseContextMenu {

        const modelPaths = [...state.selectedModels];

-        // Connect WebSocket for progress
        agentManager.connect();

-        // Set up one-time completion handler
+        const progressUI = state.loadingManager.showEnhancedProgress(
+            `Enriching metadata for ${modelPaths.length} models...`
+        );
+
+        const onProgress = (data) => {
+            if (data.status === 'processing' && data.current_path && data.updated_data && Object.keys(data.updated_data).length > 0) {
+                if (state.virtualScroller?.updateSingleItem) {
+                    state.virtualScroller.updateSingleItem(data.current_path, data.updated_data);
+                }
+                const pct = data.total > 0 ? Math.floor((data.processed / data.total) * 100) : 0;
+                const name = data.current_path.split('/').pop();
+                progressUI.updateProgress(pct, name, `Processing ${data.processed}/${data.total}: ${name}`);
+            }
+        };
+        agentManager.onProgress(onProgress);
+
        const onComplete = (data) => {
-            const idx = agentManager.completeCallbacks.indexOf(onComplete);
-            if (idx >= 0) agentManager.completeCallbacks.splice(idx, 1);
+            const pIdx = agentManager.progressCallbacks.indexOf(onProgress);
+            if (pIdx >= 0) agentManager.progressCallbacks.splice(pIdx, 1);
+            const cIdx = agentManager.completeCallbacks.indexOf(onComplete);
+            if (cIdx >= 0) agentManager.completeCallbacks.splice(cIdx, 1);

            if (data.status === 'completed') {
+                progressUI.complete(data.summary || 'Enrich complete');
                showToast(
                    'toast.agent.enrichComplete',
                    { summary: data.summary || 'Done' },
                    'success'
                );
-                // Soft reload to reflect updated metadata
-                window.location.reload();
            } else if (data.status === 'error') {
+                state.loadingManager.hide();
                showToast(
                    'toast.agent.enrichFailed',
                    { error: data.error || 'Unknown error' },
@@ -412,15 +427,14 @@ export class BulkContextMenu extends BaseContextMenu {
        };
        agentManager.onComplete(onComplete);

-        showToast(
-            'toast.agent.enrichStarted',
-            { count: modelPaths.length },
-            'info'
-        );
-
        try {
            await agentManager.executeSkill('enrich_hf_metadata', modelPaths);
        } catch (error) {
+            const pIdx = agentManager.progressCallbacks.indexOf(onProgress);
+            if (pIdx >= 0) agentManager.progressCallbacks.splice(pIdx, 1);
+            const cIdx = agentManager.completeCallbacks.indexOf(onComplete);
+            if (cIdx >= 0) agentManager.completeCallbacks.splice(cIdx, 1);
+            state.loadingManager.hide();
            showToast(
                'toast.agent.enrichFailed',
                { error: error.message },
--- a/static/js/components/ContextMenu/LoraContextMenu.js
+++ b/static/js/components/ContextMenu/LoraContextMenu.js
@@ -1,5 +1,6 @@
 import { BaseContextMenu } from './BaseContextMenu.js';
 import { ModelContextMenuMixin } from './ModelContextMenuMixin.js';
+import { state } from '../../state/index.js';
 import { getModelApiClient, resetAndReload } from '../../api/modelApiFactory.js';
 import { copyLoraSyntax, sendLoraToWorkflow, buildLoraSyntax, showToast } from '../../utils/uiHelpers.js';
 import { showExcludeModal, showDeleteModal } from '../../utils/modalUtils.js';
@@ -23,6 +24,14 @@ export class LoraContextMenu extends BaseContextMenu {
    showMenu(x, y, card) {
        super.showMenu(x, y, card);
        this.updateExcludeMenuItem();
+        this.updateEnrichMenuItem(card);
+    }
+
+    updateEnrichMenuItem(card) {
+        const enrichItem = this.menu?.querySelector('[data-action="enrich-hf-llm"]');
+        if (!enrichItem) return;
+        const hasHfUrl = !!card.dataset.hf_url;
+        enrichItem.classList.toggle('disabled', !hasHfUrl);
    }

    handleMenuAction(action, menuItem) {
@@ -63,7 +72,7 @@ export class LoraContextMenu extends BaseContextMenu {
            case 'refresh-metadata':
                getModelApiClient().refreshSingleModelMetadata(this.currentCard.dataset.filepath);
                break;
-            case 'enrich-hf-agent':
+            case 'enrich-hf-llm':
                this.enrichWithAgent(this.currentCard.dataset.filepath);
                break;
            case 'exclude':
@@ -78,39 +87,54 @@ export class LoraContextMenu extends BaseContextMenu {
    async enrichWithAgent(filePath) {
        const { agentManager } = await import('../../managers/AgentManager.js');

-        // Check if LLM is configured
        const configured = await agentManager.isLlmConfigured();
        if (!configured) {
            showToast('toast.agent.llmNotConfigured', {}, 'warning');
            return;
        }

-        // Connect WebSocket for progress
        agentManager.connect();

-        // Set up one-time completion handler
+        const progressUI = state.loadingManager.showEnhancedProgress(
+            'Enriching metadata with AI...'
+        );
+
+        const onProgress = (data) => {
+            if (data.status === 'processing' && data.current_path && data.updated_data && Object.keys(data.updated_data).length > 0) {
+                if (state.virtualScroller?.updateSingleItem) {
+                    state.virtualScroller.updateSingleItem(data.current_path, data.updated_data);
+                }
+                const pct = data.total > 0 ? Math.floor((data.processed / data.total) * 100) : 0;
+                const name = data.current_path.split('/').pop();
+                progressUI.updateProgress(pct, name, `Processing ${name}`);
+            }
+        };
+        agentManager.onProgress(onProgress);
+
        const onComplete = (data) => {
-            const idx = agentManager.completeCallbacks.indexOf(onComplete);
-            if (idx >= 0) agentManager.completeCallbacks.splice(idx, 1);
+            const pIdx = agentManager.progressCallbacks.indexOf(onProgress);
+            if (pIdx >= 0) agentManager.progressCallbacks.splice(pIdx, 1);
+            const cIdx = agentManager.completeCallbacks.indexOf(onComplete);
+            if (cIdx >= 0) agentManager.completeCallbacks.splice(cIdx, 1);

            if (data.status === 'completed') {
+                progressUI.complete(data.summary || 'Enrich complete');
                showToast('toast.agent.enrichComplete', { summary: data.summary || 'Done' }, 'success');
-                // Soft reload to reflect updated metadata
-                if (typeof resetAndReload === 'function') {
-                    resetAndReload();
-                }
            } else if (data.status === 'error') {
+                state.loadingManager.hide();
                showToast('toast.agent.enrichFailed', { error: data.error || 'Unknown error' }, 'error');
            }
        };
        agentManager.onComplete(onComplete);

-        // Show progress toast
-        showToast('toast.agent.enrichStarted', {}, 'info');
-
        try {
            await agentManager.executeSkill('enrich_hf_metadata', [filePath]);
        } catch (error) {
+            const pIdx = agentManager.progressCallbacks.indexOf(onProgress);
+            if (pIdx >= 0) agentManager.progressCallbacks.splice(pIdx, 1);
+            const cIdx = agentManager.completeCallbacks.indexOf(onComplete);
+            if (cIdx >= 0) agentManager.completeCallbacks.splice(cIdx, 1);
+            state.loadingManager.hide();
            showToast('toast.agent.enrichFailed', { error: error.message }, 'error');
        }
    }
--- a/static/js/components/shared/showcase/ShowcaseView.js
+++ b/static/js/components/shared/showcase/ShowcaseView.js
@@ -174,7 +174,10 @@ function renderMediaItem(img, index, exampleFiles) {
    const localUrl = localFile ? localFile.path : '';
    
    // Calculate appropriate aspect ratio
-    const aspectRatio = (img.height / img.width) * 100;
+    // Defensive fallback: 0 width/height → 4:3 default (prevents NaN layout)
+    const safeW = img.width || 4;
+    const safeH = img.height || 3;
+    const aspectRatio = (safeH / safeW) * 100;
    const containerWidth = 800; // modal content maximum width
    const minHeightPercent = 40; 
    const maxHeightPercent = (window.innerHeight * 0.6 / containerWidth) * 100;
--- a/static/js/core.js
+++ b/static/js/core.js
@@ -15,6 +15,7 @@ import { initTheme, initBackToTop } from './utils/uiHelpers.js';
 import { initializeInfiniteScroll } from './utils/infiniteScroll.js';
 import { i18n } from './i18n/index.js';
 import { onboardingManager } from './managers/OnboardingManager.js';
+import './components/Combobox.js';
 import { BulkContextMenu } from './components/ContextMenu/BulkContextMenu.js';
 import { createPageContextMenu, createGlobalContextMenu } from './components/ContextMenu/index.js';
 import { initializeEventManagement } from './utils/eventManagementInit.js';
--- a/static/js/managers/AgentManager.js
+++ b/static/js/managers/AgentManager.js
@@ -165,6 +165,18 @@ class AgentManager {
     *
     * @returns {Promise<boolean>}
     */
+    _readProviderRequiresKey(providerId) {
+        const script = document.getElementById('llmProviderPresets');
+        if (!script) return true; // safe default
+        try {
+            const presets = JSON.parse(script.textContent);
+            const preset = presets[providerId];
+            return preset ? preset.requires_key !== false : true;
+        } catch {
+            return true;
+        }
+    }
+
    async isLlmConfigured() {
        try {
            const response = await fetch('/api/lm/settings');
@@ -172,8 +184,9 @@ class AgentManager {
            const data = await response.json();
            const provider = data.settings?.llm_provider;
            const hasModel = !!data.settings?.llm_model;
-            const hasKey = !!data.settings?.llm_api_key;
-            return hasModel && (hasKey || provider === 'ollama');
+            const hasKey = !!(data.settings?.llm_api_key_set || data.settings?.llm_api_key);
+            const needsKey = this._readProviderRequiresKey(provider);
+            return hasModel && (hasKey || !needsKey);
        } catch {
            return false;
        }
--- a/static/js/managers/SettingsManager.js
+++ b/static/js/managers/SettingsManager.js
@@ -829,20 +829,106 @@ export class SettingsManager {
        this.updateApiKeyStatus();
        this.updateLlmApiKeyStatus();

-        // AI Provider settings
+        // ── AI Provider settings ──────────────────────────────────────
+        // Load provider presets from the JSON script tag embedded in the template
+        this._providerPresets = {};
+        this._providerModels = {};
+        const presetsScript = document.getElementById('llmProviderPresets');
+        if (presetsScript) {
+            try {
+                this._providerPresets = JSON.parse(presetsScript.textContent);
+            } catch (_) {
+                this._providerPresets = {};
+            }
+        }
+        const modelsScript = document.getElementById('llmProviderModels');
+        if (modelsScript) {
+            try {
+                this._providerModels = JSON.parse(modelsScript.textContent);
+            } catch (_) {
+                this._providerModels = {};
+            }
+        }
+
        const llmProviderSelect = document.getElementById('llmProvider');
        if (llmProviderSelect) {
            llmProviderSelect.value = state.global.settings.llm_provider || 'openai';
        }

+        // Destroy previous combobox instances before creating new ones,
+        // since loadSettingsToUI() runs on every modal open.
+        if (this._llmApiBaseCombobox) { this._llmApiBaseCombobox.destroy(); }
+        if (this._llmModelCombobox) { this._llmModelCombobox.destroy(); }
+
        const llmApiBaseInput = document.getElementById('llmApiBase');
        if (llmApiBaseInput) {
            llmApiBaseInput.value = state.global.settings.llm_api_base || '';
+            const presetUrls = Object.values(this._providerPresets)
+                .map(p => p.api_base)
+                .filter(Boolean);
+            if (typeof Combobox !== 'undefined') {
+                this._llmApiBaseCombobox = new Combobox(llmApiBaseInput, {
+                    presets: presetUrls,
+                    placeholder: 'https://api.openai.com/v1',
+                });
+            }
        }

+        // Helper to update model Combobox presets from catalog / Ollama API
        const llmModelInput = document.getElementById('llmModel');
-        if (llmModelInput) {
-            llmModelInput.value = state.global.settings.llm_model || '';
+        this._llmModelCombobox = null;
+        if (llmModelInput && typeof Combobox !== 'undefined') {
+            const currentProvider = llmProviderSelect ? llmProviderSelect.value : 'openai';
+            const fallbackModels = currentProvider === 'ollama' ? [] : (this._providerModels[currentProvider] || []);
+            this._llmModelCombobox = new Combobox(llmModelInput, {
+                presets: fallbackModels,
+                placeholder: translate('settings.aiProvider.modelPlaceholder', {}, 'Select a model...'),
+                onSelect: (value) => {
+                    state.global.settings.llm_model = value;
+                    this.saveSetting('llm_model', value)
+                        .then(() => showToast('toast.settings.settingsUpdated', { setting: 'model' }, 'success'))
+                        .catch(() => {});
+                },
+            });
+        }
+
+        const _loadModelPresets = async (provider) => {
+            if (!this._llmModelCombobox) return;
+            if (provider === 'ollama') {
+                try {
+                    const apiBase = document.getElementById('llmApiBase')?.value?.trim() || 'http://localhost:11434/v1';
+                    const resp = await fetch(`/api/lm/llm/models?provider=ollama&api_base=${encodeURIComponent(apiBase)}`);
+                    if (resp.ok) {
+                        const data = await resp.json();
+                        if (data.success && Array.isArray(data.models)) {
+                            this._llmModelCombobox.updatePresets(data.models);
+                            return;
+                        }
+                    }
+                } catch (_) {}
+                this._llmModelCombobox.updatePresets([]);
+            } else {
+                this._llmModelCombobox.updatePresets(this._providerModels[provider] || []);
+            }
+        };
+        _loadModelPresets(llmProviderSelect ? llmProviderSelect.value : 'openai');
+
+        // Provider change → auto-fill API Base URL + update model presets
+        if (llmProviderSelect) {
+            llmProviderSelect.addEventListener('change', () => {
+                const provider = llmProviderSelect.value;
+                const preset = this._providerPresets[provider];
+                if (preset) {
+                    if (llmApiBaseInput && preset.api_base) {
+                        llmApiBaseInput.value = preset.api_base;
+                        if (this._llmApiBaseCombobox) {
+                            this._llmApiBaseCombobox.setValue(preset.api_base);
+                        }
+                        llmApiBaseInput.dispatchEvent(new Event('blur'));
+                    }
+                }
+                _loadModelPresets(provider);
+            });
        }

        const civitaiHostSelect = document.getElementById('civitaiHost');
@@ -2949,7 +3035,7 @@ export class SettingsManager {
    }

    updateLlmApiKeyStatus() {
-        const hasKey = !!state.global.settings.llm_api_key;
+        const hasKey = !!(state.global.settings.llm_api_key_set || state.global.settings.llm_api_key);
        const statusText = document.getElementById('llmApiKeyStatusText');
        const actionBtn = document.getElementById('llmApiKeyActionBtn');
        if (!statusText || !actionBtn) return;
--- a/static/js/utils/constants.js
+++ b/static/js/utils/constants.js
@@ -66,11 +66,23 @@ export const BASE_MODELS = {
    HUNYUAN_VIDEO: "Hunyuan Video",
    // Other models
    ANIMA: "Anima",
+    ACE_AUDIO: "ACE Audio",
+    BOOGU: "Boogu",
    ERNIE: "Ernie",
    ERNIE_TURBO: "Ernie Turbo",
-    NUCLEUS: "Nucleus",
-    PONY_V7: "Pony V7",
+    GROK: "Grok",
+    HAPPY_HORSE: "HappyHorse",
+    HIDREAM_O1: "HiDream-O1",
+    IDEOGRAM_4_0: "Ideogram 4.0",
    KREA_2: "Krea 2",
+    LENS: "Lens",
+    PONY_V7: "Pony V7",
+    MAI: "MAI",
+    NUCLEUS: "Nucleus",
+    QWEN_2: "Qwen 2",
+    UPSCALER: "Upscaler",
+    WAN_IMAGE_2_7: "Wan Image 2.7",
+    WAN_VIDEO_2_7: "Wan Video 2.7",
    // Default
    UNKNOWN: "Other"
 };
@@ -143,22 +155,6 @@ export const BASE_MODEL_ABBREVIATIONS = {
    [BASE_MODELS.FLUX_2_KLEIN_4B]: 'FK4',
    [BASE_MODELS.FLUX_2_KLEIN_4B_BASE]: 'FK4B',

-    // Other diffusion models
-    [BASE_MODELS.AURAFLOW]: 'AF',
-    [BASE_MODELS.CHROMA]: 'CHR',
-    [BASE_MODELS.PIXART_A]: 'PXA',
-    [BASE_MODELS.PIXART_E]: 'PXE',
-    [BASE_MODELS.HUNYUAN_1]: 'HY',
-    [BASE_MODELS.LUMINA]: 'L',
-    [BASE_MODELS.KOLORS]: 'KLR',
-    [BASE_MODELS.NOOBAI]: 'NAI',
-    [BASE_MODELS.ILLUSTRIOUS]: 'IL',
-    [BASE_MODELS.PONY]: 'PONY',
-    [BASE_MODELS.HIDREAM]: 'HID',
-    [BASE_MODELS.QWEN]: 'QWEN',
-    [BASE_MODELS.ZIMAGE_TURBO]: 'ZIT',
-    [BASE_MODELS.ZIMAGE_BASE]: 'ZIB',
-
    // Video models
    [BASE_MODELS.SVD]: 'SVD',
    [BASE_MODELS.LTXV]: 'LTXV',
@@ -195,10 +191,22 @@ export const BASE_MODEL_ABBREVIATIONS = {
    [BASE_MODELS.ZIMAGE_TURBO]: 'ZIT',
    [BASE_MODELS.ZIMAGE_BASE]: 'ZIB',
    [BASE_MODELS.ANIMA]: 'ANI',
+    [BASE_MODELS.ACE_AUDIO]: 'ACE',
+    [BASE_MODELS.BOOGU]: 'BOOG',
    [BASE_MODELS.ERNIE]: 'ERNI',
    [BASE_MODELS.ERNIE_TURBO]: 'ETRB',
-    [BASE_MODELS.NUCLEUS]: 'NUCL',
+    [BASE_MODELS.GROK]: 'GROK',
+    [BASE_MODELS.HAPPY_HORSE]: 'HAPP',
+    [BASE_MODELS.HIDREAM_O1]: 'HIO1',
+    [BASE_MODELS.IDEOGRAM_4_0]: 'ID40',
    [BASE_MODELS.KREA_2]: 'KR2',
+    [BASE_MODELS.LENS]: 'LENS',
+    [BASE_MODELS.MAI]: 'MAI',
+    [BASE_MODELS.NUCLEUS]: 'NUCL',
+    [BASE_MODELS.QWEN_2]: 'QWN2',
+    [BASE_MODELS.UPSCALER]: 'UPSC',
+    [BASE_MODELS.WAN_IMAGE_2_7]: 'WI27',
+    [BASE_MODELS.WAN_VIDEO_2_7]: 'WAN',

    // Default
    [BASE_MODELS.UNKNOWN]: 'OTH'
@@ -394,7 +402,9 @@ export const BASE_MODEL_CATEGORIES = {
        BASE_MODELS.WAN_VIDEO_14B_I2V_480P, BASE_MODELS.WAN_VIDEO_14B_I2V_720P,
        BASE_MODELS.WAN_VIDEO_2_2_TI2V_5B, BASE_MODELS.WAN_VIDEO_2_2_T2V_A14B,
        BASE_MODELS.WAN_VIDEO_2_2_I2V_A14B, BASE_MODELS.WAN_VIDEO_2_5_T2V,
-        BASE_MODELS.WAN_VIDEO_2_5_I2V
+        BASE_MODELS.WAN_VIDEO_2_5_I2V,
+        BASE_MODELS.HAPPY_HORSE,
+        BASE_MODELS.WAN_IMAGE_2_7, BASE_MODELS.WAN_VIDEO_2_7
    ],
    'Flux Models': [BASE_MODELS.FLUX_1_D, BASE_MODELS.FLUX_1_S, BASE_MODELS.FLUX_1_KONTEXT, BASE_MODELS.FLUX_1_KREA, BASE_MODELS.FLUX_2_D, BASE_MODELS.FLUX_2_KLEIN_9B, BASE_MODELS.FLUX_2_KLEIN_9B_BASE, BASE_MODELS.FLUX_2_KLEIN_4B, BASE_MODELS.FLUX_2_KLEIN_4B_BASE],
    'Other Models': [
@@ -402,8 +412,10 @@ export const BASE_MODEL_CATEGORIES = {
        BASE_MODELS.QWEN, BASE_MODELS.AURAFLOW, BASE_MODELS.CHROMA, BASE_MODELS.ZIMAGE_TURBO, BASE_MODELS.ZIMAGE_BASE,
        BASE_MODELS.PIXART_A, BASE_MODELS.PIXART_E, BASE_MODELS.HUNYUAN_1,
        BASE_MODELS.LUMINA, BASE_MODELS.KOLORS, BASE_MODELS.NOOBAI, BASE_MODELS.ANIMA,
-        BASE_MODELS.ERNIE, BASE_MODELS.ERNIE_TURBO, BASE_MODELS.NUCLEUS,
-        BASE_MODELS.KREA_2,
+        BASE_MODELS.ACE_AUDIO, BASE_MODELS.BOOGU, BASE_MODELS.ERNIE, BASE_MODELS.ERNIE_TURBO,
+        BASE_MODELS.GROK, BASE_MODELS.HIDREAM_O1, BASE_MODELS.IDEOGRAM_4_0,
+        BASE_MODELS.LENS, BASE_MODELS.MAI, BASE_MODELS.NUCLEUS,
+        BASE_MODELS.QWEN_2, BASE_MODELS.KREA_2, BASE_MODELS.UPSCALER,
        BASE_MODELS.UNKNOWN
    ]
 };
--- a/templates/components/context_menu.html
+++ b/templates/components/context_menu.html
@@ -12,12 +12,12 @@
    <div class="context-menu-item" data-action="check-updates">
        <i class="fas fa-bell"></i> <span>{{ t('loras.contextMenu.checkUpdates') }}</span>
    </div>
-    <div class="context-menu-item" data-action="enrich-hf-agent">
-        <i class="fas fa-wand-magic-sparkles"></i> <span>{{ t('loras.contextMenu.enrichHfAgent') }}</span>
-    </div>
    <div class="context-menu-item" data-action="relink-civitai">
        <i class="fas fa-link"></i> <span>{{ t('loras.contextMenu.relinkCivitai') }}</span>
    </div>
+    <div class="context-menu-item" data-action="enrich-hf-llm">
+        <i class="fas fa-wand-magic-sparkles"></i> <span>{{ t('loras.contextMenu.enrichHfAgent') }}</span>
+    </div>
    <div class="context-menu-separator menu-section-break"></div>
    <!-- Workflow -->
    <div class="context-menu-item" data-action="copyname">
@@ -86,7 +86,7 @@
        <div class="context-menu-item" data-action="resume-metadata-refresh">
            <i class="fas fa-redo"></i> <span>{{ t('loras.bulkOperations.resumeMetadataRefresh') }}</span>
        </div>
-        <div class="context-menu-item" data-action="enrich-hf-agent-bulk">
+        <div class="context-menu-item" data-action="enrich-hf-llm-bulk">
            <i class="fas fa-wand-magic-sparkles"></i> <span>{{ t('loras.bulkOperations.enrichHfAgent') }}</span>
        </div>
    </div>
--- a/templates/components/modals/settings_modal.html
+++ b/templates/components/modals/settings_modal.html
@@ -157,9 +157,13 @@
                                    </div>
                                    <div class="setting-control select-control">
                                        <select id="llmProvider" onchange="settingsManager.saveSelectSetting('llmProvider', 'llm_provider')">
-                                            <option value="openai">OpenAI</option>
-                                            <option value="ollama">Ollama (local)</option>
-                                            <option value="custom">{{ t('settings.aiProvider.custom') }}</option>
+                                            <option value="openai">{{ t('settings.aiProvider.providerOptions.openai') }}</option>
+                                            <option value="ollama">{{ t('settings.aiProvider.providerOptions.ollama') }}</option>
+                                            <option value="deepseek">{{ t('settings.aiProvider.providerOptions.deepseek') }}</option>
+                                            <option value="groq">{{ t('settings.aiProvider.providerOptions.groq') }}</option>
+                                            <option value="openrouter">{{ t('settings.aiProvider.providerOptions.openrouter') }}</option>
+                                            <option value="opencode-go">{{ t('settings.aiProvider.providerOptions.opencode-go') }}</option>
+                                            <option value="custom">{{ t('settings.aiProvider.providerOptions.custom') }}</option>
                                        </select>
                                    </div>
                                </div>
@@ -171,10 +175,12 @@
                                        <i class="fas fa-info-circle info-icon" data-tooltip="{{ t('settings.aiProvider.apiBaseHelp') }}"></i>
                                    </div>
                                    <div class="setting-control">
-                                        <div class="text-input-wrapper">
+                                        <div class="text-input-wrapper lm-combobox-container">
                                            <input type="text" id="llmApiBase"
+                                                   class="lm-combobox-input"
                                                   value="{{ settings.get('llm_api_base', '') }}"
                                                   placeholder="{{ t('settings.aiProvider.apiBasePlaceholder') }}"
+                                                   autocomplete="off"
                                                   onblur="settingsManager.saveInputSetting('llmApiBase', 'llm_api_base')"
                                                   onkeydown="if(event.key === 'Enter') { this.blur(); }" />
                                        </div>
@@ -222,10 +228,12 @@
                                        <i class="fas fa-info-circle info-icon" data-tooltip="{{ t('settings.aiProvider.modelHelp') }}"></i>
                                    </div>
                                    <div class="setting-control">
-                                        <div class="text-input-wrapper">
+                                        <div class="text-input-wrapper lm-combobox-container">
                                            <input type="text" id="llmModel"
+                                                   class="lm-combobox-input"
                                                   value="{{ settings.get('llm_model', '') }}"
-                                                   placeholder="e.g. gpt-4o-mini"
+                                                   placeholder="{{ t('settings.aiProvider.modelPlaceholder') }}"
+                                                   autocomplete="off"
                                                   onblur="settingsManager.saveInputSetting('llmModel', 'llm_model')"
                                                   onkeydown="if(event.key === 'Enter') { this.blur(); }" />
                                        </div>
@@ -234,6 +242,14 @@
                            </div>
                        </div>

+                        <!-- Provider presets + model lists for frontend -->
+                        <script id="llmProviderPresets" type="application/json">
+                            {{ provider_presets_json | safe }}
+                        </script>
+                        <script id="llmProviderModels" type="application/json">
+                            {{ provider_models_json | safe }}
+                        </script>
+
                        <div class="settings-subsection">
                            <div class="settings-subsection-header">
                                <h4>{{ t('settings.sections.downloads') }}</h4>
--- a/tests/init.py
+++ b/tests/init.py
@@ -0,0 +1 @@
+# Test suite package.
--- a/tests/agent_cli/test_agent_cli.py
+++ b/tests/agent_cli/test_agent_cli.py
@@ -1,317 +0,0 @@
-"""Tests for the AgentCLI module (py/agent_cli/).
-
-All tests mock the underlying services (scanner, MetadataManager, downloader)
-since the AgentCLI is a thin delegation layer.
-
-Mock targets must match where imports are resolved inside each function
-(lazy imports via ``from X import Y`` inside function body).
-"""
-
-from __future__ import annotations
-
-from unittest import mock
-
-import pytest
-
-from py.agent_cli import (
-    list_base_models,
-    read_metadata,
-    apply_metadata_updates,
-    download_preview,
-    refresh_cache,
-)
-
-
-# ======================================================================
-# Helpers
-# ======================================================================
-
-
-class MockCache:
-    def __init__(self, raw_data: list[dict] | None = None):
-        self.raw_data = raw_data or []
-
-
-class MockScanner:
-    """Simulates a ModelScanner for testing."""
-
-    def __init__(self, raw_data: list[dict] | None = None):
-        self._raw_data = raw_data or []
-        self.update_single_model_cache = mock.AsyncMock(return_value=True)
-
-    async def get_cached_data(self):
-        return MockCache(self._raw_data)
-
-
-# ======================================================================
-# list_base_models  --  imports ServiceRegistry internally
-# ======================================================================
-
-
-class TestListBaseModels:
-
-    @pytest.mark.asyncio
-    async def test_empty_cache(self):
-        scanner = MockScanner([])
-        with mock.patch(
-            "py.services.service_registry.ServiceRegistry",
-            get_lora_scanner=mock.AsyncMock(return_value=scanner),
-            get_checkpoint_scanner=mock.AsyncMock(return_value=None),
-            get_embedding_scanner=mock.AsyncMock(return_value=None),
-        ):
-            result = await list_base_models()
-        assert result == []
-
-    @pytest.mark.asyncio
-    async def test_merges_all_scanners(self):
-        lora_scanner = MockScanner([
-            {"base_model": "SDXL 1.0"},
-            {"base_model": "Flux.1 D"},
-            {"base_model": "SDXL 1.0"},
-        ])
-        ckpt_scanner = MockScanner([
-            {"base_model": "SDXL 1.0"},
-            {"base_model": "SD 1.5"},
-        ])
-        with mock.patch(
-            "py.services.service_registry.ServiceRegistry",
-            get_lora_scanner=mock.AsyncMock(return_value=lora_scanner),
-            get_checkpoint_scanner=mock.AsyncMock(return_value=ckpt_scanner),
-            get_embedding_scanner=mock.AsyncMock(return_value=None),
-        ):
-            result = await list_base_models()
-        assert result == ["SDXL 1.0", "Flux.1 D", "SD 1.5"]
-
-    @pytest.mark.asyncio
-    async def test_limit(self):
-        scanner = MockScanner([
-            {"base_model": "A"}, {"base_model": "B"}, {"base_model": "C"},
-        ])
-        with mock.patch(
-            "py.services.service_registry.ServiceRegistry",
-            get_lora_scanner=mock.AsyncMock(return_value=scanner),
-            get_checkpoint_scanner=mock.AsyncMock(return_value=None),
-            get_embedding_scanner=mock.AsyncMock(return_value=None),
-        ):
-            result = await list_base_models(limit=2)
-        assert result == ["A", "B"]
-
-    @pytest.mark.asyncio
-    async def test_all_scanners_return_none(self):
-        with mock.patch(
-            "py.services.service_registry.ServiceRegistry",
-            get_lora_scanner=mock.AsyncMock(return_value=None),
-            get_checkpoint_scanner=mock.AsyncMock(return_value=None),
-            get_embedding_scanner=mock.AsyncMock(return_value=None),
-        ):
-            result = await list_base_models()
-        assert result == []
-
-    @pytest.mark.asyncio
-    async def test_skips_empty_or_missing_base_model(self):
-        scanner = MockScanner([
-            {"base_model": "SDXL 1.0"},
-            {"file_name": "foo.safetensors"},  # no base_model key
-            {"base_model": ""},                 # empty
-        ])
-        with mock.patch(
-            "py.services.service_registry.ServiceRegistry",
-            get_lora_scanner=mock.AsyncMock(return_value=scanner),
-            get_checkpoint_scanner=mock.AsyncMock(return_value=None),
-            get_embedding_scanner=mock.AsyncMock(return_value=None),
-        ):
-            result = await list_base_models()
-        assert result == ["SDXL 1.0"]
-
-
-# ======================================================================
-# read_metadata  --  imports MetadataManager from py.utils.metadata_manager
-# ======================================================================
-
-
-class TestReadMetadata:
-
-    @pytest.mark.asyncio
-    async def test_delegates_to_metadata_manager(self):
-        fake = {"file_name": "test", "base_model": "SDXL 1.0"}
-        with mock.patch("py.utils.metadata_manager.MetadataManager") as mm:
-            mm.load_metadata_payload = mock.AsyncMock(return_value=fake)
-            result = await read_metadata("/p.safetensors")
-        assert result == fake
-
-    @pytest.mark.asyncio
-    async def test_exception_returns_empty_dict(self):
-        with mock.patch("py.utils.metadata_manager.MetadataManager") as mm:
-            mm.load_metadata_payload = mock.AsyncMock(side_effect=ValueError("x"))
-            result = await read_metadata("/p.safetensors")
-        assert result == {}
-
-    @pytest.mark.asyncio
-    async def test_none_coerces_to_empty_dict(self):
-        with mock.patch("py.utils.metadata_manager.MetadataManager") as mm:
-            mm.load_metadata_payload = mock.AsyncMock(return_value=None)
-            result = await read_metadata("/p.safetensors")
-        assert result == {}
-
-
-# ======================================================================
-# apply_metadata_updates  --  uses read_metadata + MetadataManager.save_metadata
-# ======================================================================
-
-
-class TestApplyMetadataUpdates:
-
-    @pytest.mark.asyncio
-    async def test_updates_field(self):
-        with (
-            mock.patch("py.agent_cli.read_metadata") as mock_read,
-            mock.patch("py.utils.metadata_manager.MetadataManager") as mm,
-        ):
-            mock_read.return_value = {"base_model": "", "tags": []}
-            mm.save_metadata = mock.AsyncMock(return_value=True)
-            updated = await apply_metadata_updates(
-                "/p.safetensors", {"base_model": "Flux.1 D"}
-            )
-        assert updated == ["base_model"]
-        mm.save_metadata.assert_awaited_once_with(
-            "/p.safetensors", {"base_model": "Flux.1 D", "tags": []},
-        )
-
-    @pytest.mark.asyncio
-    async def test_noop_when_value_unchanged(self):
-        with (
-            mock.patch("py.agent_cli.read_metadata") as mock_read,
-            mock.patch("py.utils.metadata_manager.MetadataManager") as mm,
-        ):
-            mock_read.return_value = {"base_model": "Flux.1 D"}
-            updated = await apply_metadata_updates(
-                "/p.safetensors", {"base_model": "Flux.1 D"}
-            )
-        assert updated == []
-        mm.save_metadata.assert_not_called()
-
-    @pytest.mark.asyncio
-    async def test_multiple_fields(self):
-        with (
-            mock.patch("py.agent_cli.read_metadata") as mock_read,
-            mock.patch("py.utils.metadata_manager.MetadataManager") as mm,
-        ):
-            mm.save_metadata = mock.AsyncMock(return_value=True)
-            mock_read.return_value = {
-                "base_model": "", "modelDescription": "", "tags": [],
-            }
-            updated = await apply_metadata_updates(
-                "/p.safetensors",
-                {"base_model": "SDXL 1.0", "modelDescription": "A", "tags": ["flux"]},
-            )
-        assert sorted(updated) == sorted(["base_model", "modelDescription", "tags"])
-        saved = mm.save_metadata.call_args[0][1]
-        assert saved["base_model"] == "SDXL 1.0"
-
-    @pytest.mark.asyncio
-    async def test_empty_updates_noop(self):
-        with (
-            mock.patch("py.agent_cli.read_metadata"),
-            mock.patch("py.utils.metadata_manager.MetadataManager") as mm,
-        ):
-            updated = await apply_metadata_updates("/p.safetensors", {})
-        assert updated == []
-        mm.save_metadata.assert_not_called()
-
-
-# ======================================================================
-# download_preview  --  imports get_downloader + ExifUtils
-# ======================================================================
-
-
-class TestDownloadPreview:
-
-    @pytest.mark.asyncio
-    async def test_empty_url_returns_false(self, tmp_path):
-        mp = tmp_path / "m.safetensors"
-        mp.write_bytes(b"fake")
-        assert await download_preview(str(mp), "") is False
-        assert await download_preview(str(mp), "   ") is False
-
-    @pytest.mark.asyncio
-    async def test_successful_download_and_optimise(self, tmp_path):
-        mp = tmp_path / "t.safetensors"
-        mp.write_bytes(b"fake")
-        with (
-            mock.patch("py.services.downloader.get_downloader") as get_dl,
-            mock.patch("py.utils.exif_utils.ExifUtils") as exif,
-        ):
-            dl = mock.AsyncMock()
-            dl.download_to_memory = mock.AsyncMock(return_value=(True, b"raw", {}))
-            get_dl.return_value = dl
-            exif.optimize_image.return_value = (b"optimized_webp", {})
-            result = await download_preview(str(mp), "https://ex.com/i.png")
-        assert result is True
-        assert (tmp_path / "t.webp").exists()
-        assert (tmp_path / "t.webp").read_bytes() == b"optimized_webp"
-
-    @pytest.mark.asyncio
-    async def test_download_failure_returns_false(self, tmp_path):
-        mp = tmp_path / "t.safetensors"
-        mp.write_bytes(b"fake")
-        with mock.patch("py.services.downloader.get_downloader") as get_dl:
-            dl = mock.AsyncMock()
-            dl.download_to_memory = mock.AsyncMock(return_value=(False, None, {}))
-            dl.download_file = mock.AsyncMock(return_value=(False, None))
-            get_dl.return_value = dl
-            result = await download_preview(str(mp), "https://ex.com/i.png")
-        assert result is False
-        assert not (tmp_path / "t.webp").exists()
-
-
-# ======================================================================
-# refresh_cache  --  uses _find_scanner_for_model (ServiceRegistry)
-# ======================================================================
-
-
-class TestRefreshCache:
-
-    @pytest.mark.asyncio
-    async def test_found_and_refreshed(self):
-        scanner = MockScanner([{"file_path": "/some/path.safetensors"}])
-        with (
-            mock.patch(
-                "py.services.service_registry.ServiceRegistry",
-                get_lora_scanner=mock.AsyncMock(return_value=scanner),
-                get_checkpoint_scanner=mock.AsyncMock(return_value=None),
-                get_embedding_scanner=mock.AsyncMock(return_value=None),
-            ),
-            mock.patch("py.agent_cli.read_metadata") as mock_read,
-        ):
-            mock_read.return_value = {"base_model": "SDXL 1.0"}
-            result = await refresh_cache("/some/path.safetensors")
-        assert result is True
-        scanner.update_single_model_cache.assert_awaited_once()
-
-    @pytest.mark.asyncio
-    async def test_not_found_in_any_scanner(self):
-        scanner = MockScanner([])
-        with mock.patch(
-            "py.services.service_registry.ServiceRegistry",
-            get_lora_scanner=mock.AsyncMock(return_value=scanner),
-            get_checkpoint_scanner=mock.AsyncMock(return_value=None),
-            get_embedding_scanner=mock.AsyncMock(return_value=None),
-        ):
-            result = await refresh_cache("/nonexistent/path.safetensors")
-        assert result is False
-
-    @pytest.mark.asyncio
-    async def test_no_metadata_returns_false(self):
-        scanner = MockScanner([{"file_path": "/some/path.safetensors"}])
-        with (
-            mock.patch(
-                "py.services.service_registry.ServiceRegistry",
-                get_lora_scanner=mock.AsyncMock(return_value=scanner),
-                get_checkpoint_scanner=mock.AsyncMock(return_value=None),
-                get_embedding_scanner=mock.AsyncMock(return_value=None),
-            ),
-            mock.patch("py.agent_cli.read_metadata") as mock_read,
-        ):
-            mock_read.return_value = {}
-            result = await refresh_cache("/some/path.safetensors")
-        assert result is False
--- a/tests/enrich_hf_validation/init.py
+++ b/tests/enrich_hf_validation/init.py
@@ -0,0 +1 @@
+# HF Metadata Enrichment validation suite.
--- a/tests/enrich_hf_validation/config.py
+++ b/tests/enrich_hf_validation/config.py
@@ -0,0 +1,133 @@
+"""Configuration for the HF metadata enrichment validation suite.
+
+Loads user settings, defines paths, and pulls constants from the main
+codebase (``py.utils.constants``).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, Dict, List
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Default paths
+# ---------------------------------------------------------------------------
+
+_DEFAULT_MODELS_FILE = os.path.join(
+    os.path.dirname(__file__), "test_data", "hf_lora_models_with_safetensors.txt"
+)
+_DEFAULT_SETTINGS_PATH = os.path.expanduser(
+    "~/.config/ComfyUI-LoRA-Manager/settings.json"
+)
+_DEFAULT_OUTPUT_DIR = "/tmp/hf_enrich_validation"
+
+# ---------------------------------------------------------------------------
+# Constants from the main codebase (copied at import time)
+# ---------------------------------------------------------------------------
+
+# Priority tags used in the LLM prompt for tag selection guidance.
+CIVITAI_MODEL_TAGS: List[str] = [
+    "character", "concept", "clothing", "realistic", "anime", "toon",
+    "furry", "style", "poses", "background", "tool", "vehicle",
+    "buildings", "objects", "assets", "animal", "action",
+]
+
+# ---------------------------------------------------------------------------
+# Base model resolution — dynamically fetched from production code
+# ---------------------------------------------------------------------------
+
+# Module-level cache — populated by init_supported_base_models().
+# Falls back to a comprehensive hardcoded list when the live fetch fails.
+SUPPORTED_BASE_MODELS: List[str] = []
+
+# Fallback base models when the production list_base_models() is unavailable.
+_FALLBACK_BASE_MODELS: List[str] = [
+    "SD 1.4", "SD 1.5", "SD 1.5 LCM", "SD 1.5 Hyper",
+    "SD 2.0", "SD 2.1",
+    "SD 3", "SD 3.5", "SD 3.5 Medium", "SD 3.5 Large", "SD 3.5 Large Turbo",
+    "SDXL 1.0", "SDXL Lightning", "SDXL Hyper",
+    "Flux.1 D", "Flux.1 S", "Flux.1 Krea", "Flux.1 Kontext",
+    "Flux.2 D", "Flux.2 Klein 9B", "Flux.2 Klein 9B-base",
+    "Flux.2 Klein 4B", "Flux.2 Klein 4B-base",
+    "AuraFlow", "Chroma", "PixArt a", "PixArt E",
+    "Hunyuan 1", "Lumina", "Kolors",
+    "NoobAI", "Illustrious", "Pony", "Pony V7",
+    "HiDream", "Qwen", "ZImageTurbo", "ZImageBase",
+    "SVD", "LTXV", "LTXV2", "LTXV 2.3",
+    "CogVideoX", "Mochi",
+    "Wan Video", "Wan Video 1.3B t2v", "Wan Video 14B t2v",
+    "Wan Video 14B i2v 480p", "Wan Video 14B i2v 720p",
+    "Wan Video 2.2 TI2V-5B", "Wan Video 2.2 T2V-A14B",
+    "Wan Video 2.2 I2V-A14B",
+    "Wan Video 2.5 T2V", "Wan Video 2.5 I2V",
+    "Hunyuan Video", "Anima", "Ernie", "Ernie Turbo",
+    "Nucleus", "Krea 2",
+]
+
+
+async def init_supported_base_models() -> None:
+    """Populate ``SUPPORTED_BASE_MODELS`` from the production codebase.
+
+    Calls ``py.metadata_ops.list_base_models()`` which merges a hardcoded
+    fallback with models fetched from the CivitAI API.  When the call
+    fails (e.g. offline, API error), falls back to ``_FALLBACK_BASE_MODELS``.
+
+    Must be called from within an async event loop (i.e. during
+    ``run_validation.main()``, not at module level).
+    """
+    try:
+        from py.metadata_ops import list_base_models
+
+        models = await list_base_models()
+        if models:
+            SUPPORTED_BASE_MODELS[:] = models
+            logger.info("Loaded %d base models from production code", len(models))
+            return
+        logger.warning("list_base_models returned empty list, using fallback")
+    except Exception as exc:
+        logger.warning("Failed to load base models from production: %s", exc)
+
+    SUPPORTED_BASE_MODELS[:] = _FALLBACK_BASE_MODELS
+    logger.info("Using fallback base model list (%d entries)", len(SUPPORTED_BASE_MODELS))
+
+
+# Placeholder values the LLM sometimes emits that should count as "empty".
+PLACEHOLDER_VALUES = frozenset({
+    "none", "null", "n/a", "unknown", "not available",
+    "not specified", "no trigger words", "no trigger word",
+})
+
+
+# ---------------------------------------------------------------------------
+# User settings loader
+# ---------------------------------------------------------------------------
+
+
+def load_settings(settings_path: str) -> Dict[str, Any]:
+    """Load LoRA Manager settings from *settings_path*.
+
+    Returns a flat dict with the LLM configuration fields that the
+    enrichment pipeline depends on.
+    """
+    path = os.path.expanduser(settings_path)
+    if not os.path.exists(path):
+        raise FileNotFoundError(
+            f"Settings file not found: {path}\n"
+            "Please provide a valid --settings path."
+        )
+
+    with open(path, "r", encoding="utf-8") as fh:
+        raw: Dict[str, Any] = json.load(fh)
+
+    # Extract LLM-relevant config
+    return {
+        "llm_provider": raw.get("llm_provider", "ollama"),
+        "llm_model": raw.get("llm_model", "qwen3.5:9b"),
+        "llm_api_base": raw.get("llm_api_base", "http://localhost:11434/v1"),
+        "llm_api_key": raw.get("llm_api_key", ""),
+        "settings_path": path,
+    }
--- a/tests/enrich_hf_validation/enrichment_runner.py
+++ b/tests/enrich_hf_validation/enrichment_runner.py
@@ -0,0 +1,208 @@
+"""Execute the ``enrich_hf_metadata`` skill serially over a list of models.
+
+Design decisions (local Ollama, no rate limits):
+
+- Sequential execution: one model at a time.  100 models at ~30-90 s/call
+  → roughly 1-2 h total.
+- Progress persisted to a JSON checkpoint file so the run can be resumed
+  with ``--resume``.
+- Per-model timeout guards against a stuck Ollama inference.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import time
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+_SKILL_NAME = "enrich_hf_metadata"
+
+# How long to wait for a single LLM call before marking it timed-out.
+_PER_MODEL_TIMEOUT = 240  # seconds
+
+# ---------------------------------------------------------------------------
+# Progress checkpoint helpers
+# ---------------------------------------------------------------------------
+
+_PROGRESS_FILE = "progress.json"
+
+
+def _load_progress(output_dir: str) -> Dict[str, Any]:
+    path = os.path.join(output_dir, _PROGRESS_FILE)
+    if os.path.exists(path):
+        with open(path, "r") as fh:
+            return json.load(fh)
+    return {"completed": [], "failed": [], "timed_out": []}
+
+
+def _save_progress(output_dir: str, progress: Dict[str, Any]) -> None:
+    path = os.path.join(output_dir, _PROGRESS_FILE)
+    with open(path, "w") as fh:
+        json.dump(progress, fh, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Core runner
+# ---------------------------------------------------------------------------
+
+
+class EnrichmentRunner:
+    """Serial enrichment runner with checkpoint resume."""
+
+    def __init__(
+        self,
+        output_dir: str,
+        *,
+        per_model_timeout: int = _PER_MODEL_TIMEOUT,
+    ) -> None:
+        self._output_dir = output_dir
+        self._per_model_timeout = per_model_timeout
+        self._agent_service: Optional[Any] = None
+
+    async def _ensure_agent_service(self) -> Any:
+        """Lazy-init AgentService (expensive — needs LLMService init)."""
+        if self._agent_service is not None:
+            return self._agent_service
+        from py.services.agent.agent_service import AgentService
+
+        self._agent_service = await AgentService.get_instance()
+        return self._agent_service
+
+    async def run(
+        self,
+        model_paths: List[str],
+        repos: List[str],
+    ) -> Dict[str, Any]:
+        """Run enrichment over *model_paths* (one-by-one).
+
+        Args:
+            model_paths: model paths in the same order as *repos*.
+            repos: HF repo IDs (for display / checkpoint labelling).
+
+        Returns:
+            A dict with keys ``results``, ``progress``, ``durations``.
+        """
+        assert len(model_paths) == len(repos)
+
+        progress = _load_progress(self._output_dir)
+        completed_set = set(progress["completed"])
+        failed_set = set(progress["failed"])
+        timed_out_set = set(progress.get("timed_out", []))
+
+        agent = await self._ensure_agent_service()
+        results: List[Dict[str, Any]] = []
+        durations: Dict[str, float] = {}
+
+        total = len(model_paths)
+        processed_before = len(completed_set | failed_set | timed_out_set)
+
+        logger.info(
+            "Enrichment runner: %d models total, %d already processed",
+            total,
+            processed_before,
+        )
+
+        for idx, (model_path, repo_id) in enumerate(zip(model_paths, repos)):
+            if repo_id in completed_set:
+                logger.info("[%d/%d] SKIP (already done): %s", idx + 1, total, repo_id)
+                continue
+            if repo_id in failed_set or repo_id in timed_out_set:
+                logger.info(
+                    "[%d/%d] SKIP (previously failed/timeout): %s",
+                    idx + 1, total, repo_id,
+                )
+                continue
+
+            logger.info(
+                "[%d/%d] Enriching %s ...", idx + 1, total, repo_id,
+            )
+            t0 = time.perf_counter()
+
+            try:
+                result = await asyncio.wait_for(
+                    agent.execute_skill(
+                        skill_name=_SKILL_NAME,
+                        input_data={"model_paths": [model_path]},
+                        progress_callback=None,
+                    ),
+                    timeout=self._per_model_timeout,
+                )
+
+                elapsed = time.perf_counter() - t0
+                durations[repo_id] = round(elapsed, 2)
+
+                if result.success:
+                    completed_set.add(repo_id)
+                    progress["completed"].append(repo_id)
+                    logger.info(
+                        "  ✓ %s  (%.1f s) — %s",
+                        repo_id, elapsed, result.summary,
+                    )
+                else:
+                    failed_set.add(repo_id)
+                    progress["failed"].append(repo_id)
+                    logger.warning(
+                        "  ✗ %s  (%.1f s) — %s",
+                        repo_id, elapsed,
+                        "; ".join(result.errors) if result.errors else result.summary,
+                    )
+
+                results.append({
+                    "repo_id": repo_id,
+                    "model_path": model_path,
+                    "success": result.success,
+                    "updated_fields": result.updated_models,
+                    "errors": result.errors,
+                    "summary": result.summary,
+                    "duration_s": round(elapsed, 2),
+                })
+
+            except asyncio.TimeoutError:
+                elapsed = time.perf_counter() - t0
+                durations[repo_id] = round(elapsed, 2)
+                timed_out_set.add(repo_id)
+                progress.setdefault("timed_out", []).append(repo_id)
+                logger.warning(
+                    "  ⏱ TIMEOUT %s  (%.1f s, limit=%ds)",
+                    repo_id, elapsed, self._per_model_timeout,
+                )
+                results.append({
+                    "repo_id": repo_id,
+                    "model_path": model_path,
+                    "success": False,
+                    "errors": [f"Timeout after {self._per_model_timeout}s"],
+                    "summary": "LLM call timed out",
+                    "duration_s": round(elapsed, 2),
+                })
+
+            except Exception as exc:
+                elapsed = time.perf_counter() - t0
+                durations[repo_id] = round(elapsed, 2)
+                failed_set.add(repo_id)
+                progress["failed"].append(repo_id)
+                logger.error(
+                    "  ✗ %s  (%.1f s) — %s",
+                    repo_id, elapsed, exc,
+                )
+                results.append({
+                    "repo_id": repo_id,
+                    "model_path": model_path,
+                    "success": False,
+                    "errors": [str(exc)],
+                    "summary": f"Exception: {exc}",
+                    "duration_s": round(elapsed, 2),
+                })
+
+            # Checkpoint after each model
+            _save_progress(self._output_dir, progress)
+
+        return {
+            "results": results,
+            "progress": progress,
+            "durations": durations,
+        }
--- a/tests/enrich_hf_validation/evaluation_engine.py
+++ b/tests/enrich_hf_validation/evaluation_engine.py
@@ -0,0 +1,352 @@
+"""Evaluate enriched ``.metadata.json`` quality across multiple dimensions.
+
+Scoring rubric (per field):
+
+- **Completeness**: Is the field populated with meaningful content?
+- **Validity**: Does the value conform to expected constraints (controlled
+  vocab, non-placeholder, parsable JSON)?
+- **Accuracy**: (sub-sample only — requires manual verification against
+  the HF README).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, Dict, List, Optional, Set
+
+from .config import (
+    CIVITAI_MODEL_TAGS,
+    PLACEHOLDER_VALUES,
+    SUPPORTED_BASE_MODELS,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Scoring helpers
+# ---------------------------------------------------------------------------
+
+_MIN_TAGS = 1
+_MAX_TAGS = 8
+_MIN_DESC_LENGTH = 20
+_MIN_NOTES_LENGTH = 30
+
+# Tags that the LLM sometimes emits but which are not meaningful content tags.
+_TECH_TAGS = frozenset({
+    "lora", "dreambooth", "text-to-image", "diffusers", "flux",
+    "sdxl", "checkpoint", "pytorch", "safetensors", "fine-tuning",
+    "stable-diffusion", "training", "stablediffusion",
+})
+
+
+def _is_placeholder(val: str) -> bool:
+    return val.strip().lower() in PLACEHOLDER_VALUES
+
+
+def _is_valid_trigger_words(words: List[str]) -> bool:
+    """Return True if *words* is a non-empty list of real trigger words."""
+    if not words:
+        return False
+    cleaned = [w.strip() for w in words if w.strip()]
+    if not cleaned:
+        return False
+    # Reject if ALL entries are placeholders
+    non_placeholder = [w for w in cleaned if not _is_placeholder(w)]
+    return len(non_placeholder) > 0
+
+
+def _is_valid_tags(tags: List[str]) -> bool:
+    """Return True if *tags* is a reasonable list of content tags."""
+    if not tags:
+        return False
+    cleaned = [t.strip().lower() for t in tags if t.strip()]
+    if not cleaned:
+        return False
+    # At least one tag that isn't a technical keyword
+    meaningful = [t for t in cleaned if t not in _TECH_TAGS]
+    return len(meaningful) >= _MIN_TAGS
+
+
+def _tag_priority_coverage(tags: List[str]) -> float:
+    """Fraction of tags that align with the user's priority tag vocabulary."""
+    if not tags:
+        return 0.0
+    priority_lower = {t.lower() for t in CIVITAI_MODEL_TAGS}
+    matched = sum(1 for t in tags if t.strip().lower() in priority_lower)
+    return matched / len(tags)
+
+
+# ---------------------------------------------------------------------------
+# Per-model evaluation
+# ---------------------------------------------------------------------------
+
+# Type alias for a score record
+ScoreRecord = Dict[str, Any]
+
+
+def evaluate_model(
+    metadata: Dict[str, Any],
+    model_path: str,
+    repo_id: str,
+    *,
+    enrichment_success: bool,
+    enrichment_errors: List[str],
+) -> ScoreRecord:
+    """Score a single enriched model's metadata.
+
+    Returns a dict with per-field scores, a total score, and a list of
+    flagged issues.
+    """
+    civitai = metadata.get("civitai") or {}
+    trained_words: List[str] = civitai.get("trainedWords") or metadata.get("trainedWords") or []
+    short_desc: str = civitai.get("description") or ""
+    tags: List[str] = metadata.get("tags") or []
+    notes: str = metadata.get("notes") or ""
+    usage_tips_raw: str = metadata.get("usage_tips") or "{}"
+    model_description: str = metadata.get("modelDescription") or ""
+    base_model: str = metadata.get("base_model") or ""
+    preview_url: str = metadata.get("preview_url") or ""
+    confidence: str = metadata.get("_llm_confidence") or ""
+
+    # --- base_model ---
+    base_model_valid = base_model in SUPPORTED_BASE_MODELS
+    base_model_filled = bool(base_model) and base_model != "Unknown"
+
+    # --- trigger_words (trainedWords) ---
+    triggers_valid = _is_valid_trigger_words(trained_words)
+
+    # --- short_description (civitai.description) ---
+    desc_filled = len(short_desc.strip()) >= _MIN_DESC_LENGTH
+
+    # --- tags ---
+    tags_valid = _is_valid_tags(tags)
+    tags_priority_coverage = _tag_priority_coverage(tags)
+    tags_no_technical = (
+        sum(1 for t in tags if t.strip().lower() not in _TECH_TAGS) >= _MIN_TAGS
+        if tags else False
+    )
+
+    # --- notes ---
+    notes_filled = len(notes.strip()) >= _MIN_NOTES_LENGTH
+
+    # --- usage_tips ---
+    usage_tips_valid = False
+    if usage_tips_raw.strip() and usage_tips_raw.strip() != "{}":
+        try:
+            parsed = json.loads(usage_tips_raw)
+            if isinstance(parsed, dict) and len(parsed) > 0:
+                usage_tips_valid = True
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+    # --- modelDescription (README → HTML) ---
+    desc_html_filled = len(model_description.strip()) > 100
+
+    # --- preview_url ---
+    preview_filled = bool(preview_url) and os.path.exists(preview_url)
+
+    # ------------------------------------------------------------------
+    # Composite score (0-100)
+    # ------------------------------------------------------------------
+
+    field_scores = {
+        "base_model": _score_bool(base_model_filled and base_model_valid, weight=15),
+        "trigger_words": _score_bool(triggers_valid, weight=15),
+        "short_description": _score_bool(desc_filled, weight=10),
+        "tags": _score_bool(tags_valid, weight=15),
+        "tags_priority_coverage": _score_continuous(tags_priority_coverage, weight=5),
+        "notes": _score_bool(notes_filled, weight=5),
+        "usage_tips": _score_bool(usage_tips_valid, weight=5),
+        "modelDescription_html": _score_bool(desc_html_filled, weight=10),
+        "preview_downloaded": _score_bool(preview_filled, weight=10),
+    }
+
+    # Deduct points for enrichment-level failures
+    penalty = 0
+    if enrichment_errors:
+        penalty += 10
+    if not enrichment_success:
+        penalty += 20
+
+    total_raw = sum(field_scores.values())
+    total = max(0, min(100, total_raw - penalty))
+
+    # ------------------------------------------------------------------
+    # Flagged issues
+    # ------------------------------------------------------------------
+
+    issues: List[str] = []
+    if not base_model_filled:
+        issues.append("base_model is empty or 'Unknown'")
+    elif not base_model_valid:
+        issues.append(f"base_model '{base_model}' not in SUPPORTED_BASE_MODELS")
+    if not triggers_valid:
+        issues.append("trigger_words are missing or contain only placeholders")
+    if not desc_filled:
+        issues.append("short_description is too short or empty")
+    if not tags_valid:
+        issues.append("tags are missing, too few, or purely technical")
+    if tags_valid and tags_priority_coverage < 0.5:
+        issues.append("tags have low overlap with priority_tags (< 50%)")
+    if not notes_filled:
+        issues.append("notes are too short or empty")
+    if not usage_tips_valid:
+        issues.append("usage_tips is empty or invalid JSON")
+    if not desc_html_filled:
+        issues.append("modelDescription is too short (README may not have been converted)")
+    if not preview_filled:
+        issues.append("preview image not downloaded (URL missing or download failed)")
+
+    return {
+        "repo_id": repo_id,
+        "model_path": model_path,
+        "enrichment_success": enrichment_success,
+        "total_score": total,
+        "field_scores": field_scores,
+        "issues": issues,
+        "confidence_from_llm": confidence,
+        "raw_values": {
+            "base_model": base_model,
+            "trigger_words": trained_words,
+            "short_description": short_desc,
+            "tags": tags,
+            "notes": notes,
+            "usage_tips": usage_tips_raw,
+            "preview_url": preview_url,
+            "has_modelDescription": len(model_description) > 0,
+        },
+    }
+
+
+def _score_bool(condition: bool, weight: int = 10) -> int:
+    return weight if condition else 0
+
+
+def _score_continuous(value: float, weight: int = 10) -> int:
+    """Linear interpolation: value 0.0 → 0, value 1.0 → *weight*."""
+    return int(round(value * weight))
+
+
+# ---------------------------------------------------------------------------
+# Batch evaluation
+# ---------------------------------------------------------------------------
+
+
+def evaluate_batch(
+    enriched: List[Dict[str, Any]],
+) -> List[ScoreRecord]:
+    """Evaluate a list of enrichment results.
+
+    Each entry in *enriched* should have keys:
+      ``repo_id``, ``model_path``, ``metadata`` (the enriched dict),
+      ``success``, ``errors``.
+    """
+    scores: List[ScoreRecord] = []
+    for entry in enriched:
+        record = evaluate_model(
+            metadata=entry.get("metadata", {}),
+            model_path=entry.get("model_path", ""),
+            repo_id=entry.get("repo_id", ""),
+            enrichment_success=entry.get("success", False),
+            enrichment_errors=entry.get("errors", []),
+        )
+        scores.append(record)
+    return scores
+
+
+# ---------------------------------------------------------------------------
+# Aggregate statistics
+# ---------------------------------------------------------------------------
+
+
+def aggregate_scores(scores: List[ScoreRecord]) -> Dict[str, Any]:
+    """Compute aggregate stats across all scored models."""
+    n = len(scores)
+    if n == 0:
+        return {"error": "no scores to aggregate"}
+
+    field_names = [
+        "base_model", "trigger_words", "short_description", "tags",
+        "tags_priority_coverage", "notes", "usage_tips",
+        "modelDescription_html", "preview_downloaded",
+    ]
+    possible = {f: 15 if f == "base_model" or f == "trigger_words" or f == "tags" else
+                   10 if f == "short_description" or f == "modelDescription_html" or f == "preview_downloaded" else
+                   5
+                for f in field_names}
+
+    # Per-field aggregate
+    field_agg: Dict[str, Any] = {}
+    for fn in field_names:
+        vals = [s["field_scores"].get(fn, 0) for s in scores]
+        max_per_field = possible[fn]
+        field_agg[fn] = {
+            "mean": round(sum(vals) / n, 1) if n else 0,
+            "fill_rate_pct": round(
+                sum(1 for v in vals if v >= max_per_field) / n * 100, 1
+            ) if n else 0.0,
+            "partial_rate_pct": round(
+                sum(1 for v in vals if 0 < v < max_per_field) / n * 100, 1
+            ) if n else 0.0,
+            "empty_rate_pct": round(
+                sum(1 for v in vals if v == 0) / n * 100, 1
+            ) if n else 0.0,
+        }
+
+    # Total score distribution
+    total_scores = [s["total_score"] for s in scores]
+    total_agg = {
+        "mean": round(sum(total_scores) / n, 1) if n else 0,
+        "median": _median(total_scores),
+        "min": min(total_scores) if total_scores else 0,
+        "max": max(total_scores) if total_scores else 0,
+        "bins": {
+            "excellent_80+": sum(1 for s in total_scores if s >= 80),
+            "good_60_79": sum(1 for s in total_scores if 60 <= s < 80),
+            "fair_40_59": sum(1 for s in total_scores if 40 <= s < 60),
+            "poor_20_39": sum(1 for s in total_scores if 20 <= s < 40),
+            "bad_0_19": sum(1 for s in total_scores if s < 20),
+        },
+    }
+
+    # Issue frequency
+    issue_counter: Dict[str, int] = {}
+    for s in scores:
+        for issue in s["issues"]:
+            issue_counter[issue] = issue_counter.get(issue, 0) + 1
+    top_issues = sorted(issue_counter.items(), key=lambda x: -x[1])
+
+    # Confidence distribution
+    conf_counter: Dict[str, int] = {"high": 0, "medium": 0, "low": 0, "": 0}
+    for s in scores:
+        c = (s.get("confidence_from_llm") or "").strip().lower()
+        if c in conf_counter:
+            conf_counter[c] += 1
+        else:
+            conf_counter[""] += 1
+
+    # Success / timeout / failure stats
+    success_count = sum(1 for s in scores if s["enrichment_success"])
+    fail_count = n - success_count
+
+    return {
+        "model_count": n,
+        "success_count": success_count,
+        "fail_count": fail_count,
+        "total_score": total_agg,
+        "field_aggregates": field_agg,
+        "top_issues": top_issues[:15],
+        "confidence_distribution": conf_counter,
+    }
+
+
+def _median(values: List[float]) -> float:
+    if not values:
+        return 0.0
+    sorted_v = sorted(values)
+    m = len(sorted_v) // 2
+    if len(sorted_v) % 2 == 0:
+        return round((sorted_v[m - 1] + sorted_v[m]) / 2, 1)
+    return round(sorted_v[m], 1)
--- a/tests/enrich_hf_validation/metadata_constructor.py
+++ b/tests/enrich_hf_validation/metadata_constructor.py
@@ -0,0 +1,202 @@
+"""Construct initial ``.metadata.json`` sidecars for HF model repos.
+
+Each HF repo + safetensors pair gets a minimal metadata file — no real model
+file is needed.  The enrichment pipeline reads only the sidecar.
+
+Data format (one line per entry)::
+
+    repo_id, model_name.safetensors
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, Dict, List, Tuple
+
+from .config import CIVITAI_MODEL_TAGS
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Data types
+# ---------------------------------------------------------------------------
+
+# A validated entry parsed from the models file:
+#   (repo_id, safetensors_name)
+RepoEntry = Tuple[str, str]
+
+
+def load_repo_ids(path: str, max_models: int | None = None) -> List[RepoEntry]:
+    """Read ``repo_id, safetensors_name`` pairs from *path*.
+
+    Format (one per line, blanks and ``#`` comments ignored)::
+
+        user/repo-name, lora_zimage_turbo_myjs_alpha01.safetensors
+
+    Returns a list of ``(repo_id, safetensors_name)`` tuples.
+    """
+    path = os.path.expanduser(path)
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"Models file not found: {path}")
+
+    entries: List[RepoEntry] = []
+    with open(path, "r", encoding="utf-8") as fh:
+        for raw_line in fh:
+            line = raw_line.strip()
+            if not line or line.startswith("#"):
+                continue
+
+            # Split on the first comma
+            if "," not in line:
+                logger.warning("Skipping malformed line (no comma): %s", raw_line.rstrip())
+                continue
+
+            repo_id, safetensors_name = [part.strip() for part in line.split(",", 1)]
+            if not repo_id or not safetensors_name:
+                logger.warning("Skipping malformed line (empty fields): %s", raw_line.rstrip())
+                continue
+            if not safetensors_name.lower().endswith(".safetensors"):
+                logger.warning(
+                    "Skipping line — safetensors_name doesn't end with .safetensors: %s",
+                    raw_line.rstrip(),
+                )
+                continue
+
+            entries.append((repo_id, safetensors_name))
+
+    if max_models is not None and max_models > 0:
+        entries = entries[:max_models]
+
+    logger.info("Loaded %d HF repo entries from %s", len(entries), path)
+    return entries
+
+
+def sanitize_repo_id(repo_id: str) -> str:
+    """Turn ``user/repo-name`` into a safe directory name."""
+    return repo_id.replace("/", "__").replace(".", "_")
+
+
+def build_model_dir(output_dir: str, repo_id: str) -> str:
+    """Return the per-model working directory."""
+    return os.path.join(output_dir, "models", sanitize_repo_id(repo_id))
+
+
+def build_model_path(model_dir: str, safetensors_name: str) -> str:
+    """Return the model file path using the real safetensors filename."""
+    return os.path.join(model_dir, safetensors_name)
+
+
+def build_metadata_path(model_path: str) -> str:
+    """Return the sidecar path for a model file.
+
+    This MUST match the convention used by ``MetadataManager`` /
+    ``apply_metadata_updates``, which derives the sidecar path via
+    ``os.path.splitext(model_path)[0] + '.metadata.json'``.
+    For a model file ``lora_x.safetensors`` the sidecar is
+    ``lora_x.metadata.json`` — *not* ``lora_x.safetensors.metadata.json``.
+    """
+    return f"{os.path.splitext(model_path)[0]}.metadata.json"
+
+
+def create_initial_metadata(
+    output_dir: str,
+    repo_id: str,
+    safetensors_name: str,
+) -> str:
+    """Write a minimal ``.metadata.json`` for *repo_id* + *safetensors_name*.
+
+    Args:
+        output_dir: Root output directory.
+        repo_id: HuggingFace repo identifier (``user/repo``).
+        safetensors_name: The specific model file name (e.g.
+            ``lora_zimage_turbo_myjs_alpha01.safetensors``).
+
+    Returns the **model path** (the ``.safetensors`` path whose sidecar was
+    written).  The caller passes this path to ``AgentService.execute_skill``.
+    The basename (filename without extension) will match the real model file,
+    so ``extract_relevant_section`` can reliably match against the README.
+    """
+    model_dir = build_model_dir(output_dir, repo_id)
+    os.makedirs(model_dir, exist_ok=True)
+    model_path = build_model_path(model_dir, safetensors_name)
+    metadata_path = build_metadata_path(model_path)
+
+    hf_url = f"https://huggingface.co/{repo_id}"
+    file_name = safetensors_name
+
+    metadata: Dict[str, Any] = {
+        "file_name": file_name,
+        "model_name": safetensors_name,
+        "file_path": model_path.replace(os.sep, "/"),
+        "size": 0,
+        "modified": 0,
+        "sha256": "",
+        "base_model": "Unknown",
+        "preview_url": "",
+        "preview_nsfw_level": 0,
+        "notes": "",
+        "from_civitai": False,
+        "civitai": {},
+        "tags": [],
+        "modelDescription": "",
+        "civitai_deleted": False,
+        "favorite": False,
+        "exclude": False,
+        "db_checked": False,
+        "skip_metadata_refresh": False,
+        "metadata_source": "",
+        "last_checked_at": 0,
+        "hash_status": "completed",
+        "trainedWords": [],
+        "hf_url": hf_url,
+        "usage_tips": "{}",
+    }
+
+    with open(metadata_path, "w", encoding="utf-8") as fh:
+        json.dump(metadata, fh, indent=2, ensure_ascii=False)
+
+    logger.debug("Created initial metadata for %s -> %s", repo_id, metadata_path)
+    return model_path
+
+
+def create_all_initial_metadata(
+    entries: List[RepoEntry],
+    output_dir: str,
+    *,
+    skip_existing: bool = True,
+) -> Tuple[List[str], List[str]]:
+    """Create initial metadata for every repo entry.
+
+    Args:
+        entries: List of ``(repo_id, safetensors_name)`` tuples.
+        output_dir: Root output directory.
+        skip_existing: If True, skip repos whose metadata already exists.
+
+    Returns:
+        A tuple ``(model_paths, repo_ids)`` — two parallel lists in the same
+        order as *entries*.  This keeps downstream code (enrichment runner,
+        evaluation engine) unchanged.
+    """
+    model_paths: List[str] = []
+    repo_ids: List[str] = []
+    for repo_id, safetensors_name in entries:
+        model_dir = build_model_dir(output_dir, repo_id)
+        model_path = build_model_path(model_dir, safetensors_name)
+        metadata_path = build_metadata_path(model_path)
+
+        if skip_existing and os.path.exists(metadata_path):
+            model_paths.append(model_path)
+            repo_ids.append(repo_id)
+            continue
+
+        model_paths.append(create_initial_metadata(output_dir, repo_id, safetensors_name))
+        repo_ids.append(repo_id)
+
+    logger.info(
+        "Constructed initial metadata for %d/%d repos",
+        len(model_paths),
+        len(entries),
+    )
+    return model_paths, repo_ids
--- a/tests/enrich_hf_validation/preprocessing_auditor.py
+++ b/tests/enrich_hf_validation/preprocessing_auditor.py
@@ -0,0 +1,467 @@
+"""Preprocessing audit for the HF metadata enrichment validation pipeline.
+
+Phase 1.5 — runs between Phase 1 (metadata creation) and Phase 2 (enrichment).
+
+Audits the README preprocessing pipeline (section extraction + cleaning)
+for each repo in the dataset, capturing intermediate outputs so we can
+distinguish between:
+
+    (A) Preprocessing failed → LLM never saw the right content
+    (B) Preprocessing succeeded → LLM/prompt needs improvement
+
+This prevents wasted effort optimizing prompts when the actual problem is
+that ``extract_relevant_section`` or ``clean_readme_for_llm`` removed or
+misaligned the content the LLM needed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import re
+import time
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, List, Tuple
+
+import aiohttp
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Audit record
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class AuditRecord:
+    """Preprocessing audit for a single repo entry."""
+
+    # Identity
+    repo_id: str
+    safetensors_name: str
+    basename: str  # filename without .safetensors
+
+    # Raw README stats
+    raw_readme_length: int
+    raw_readme_line_count: int
+    has_yaml_frontmatter: bool
+    yaml_has_base_model: bool
+    yaml_has_tags: bool
+
+    # Section extraction
+    section_extraction_activated: bool  # output < 95% of input length
+    section_length: int
+    section_line_count: int
+    basename_in_section: bool  # basename appears in extracted section text
+
+    # Cleaning
+    cleaned_length: int
+    cleaned_line_count: int
+    compression_pct: float  # (1 - cleaned/raw) * 100
+
+    # Widget section (stripped by _strip_widget_section)
+    widget_section_found: bool
+    widget_section_length: int
+
+    # Flags (list of anomaly descriptions)
+    flags: List[str] = field(default_factory=list)
+
+    # Local file path to the saved raw README (for cross-reference)
+    readme_file: str = ""
+
+    # Staged intermediate output for report detail
+    raw_readme_preview: str = ""  # first 200 chars
+    section_preview: str = ""  # first 300 chars
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_HF_RAW_URL = "https://huggingface.co/{repo_id}/raw/main/README.md"
+
+# Thresholds for flagging
+_SECTION_ACTIVATION_RATIO = 0.95
+_MIN_CLEANED_LENGTH = 100
+_MAX_COMPRESSION_PCT = 99.0
+_MIN_SECTION_LINES = 3
+
+
+# ---------------------------------------------------------------------------
+# Module loader — bypasses parent-package __init__ that imports ComfyUI
+# ---------------------------------------------------------------------------
+
+_readme_processor_module = None
+
+
+def _load_readme_processor():
+    """Import ``readme_processor`` without triggering ``folder_paths`` import.
+
+    The normal import path (``py.services.agent.skills.enrich_hf_metadata.
+    readme_processor``) triggers ``py.services.agent.__init__`` which
+    imports ``agent_service.py`` → ``py/config.py`` → ComfyUI's
+    ``folder_paths``, which is not available in standalone mode.
+    """
+    global _readme_processor_module
+    if _readme_processor_module is not None:
+        return _readme_processor_module
+
+    import importlib.util
+
+    _RP_PATH = os.path.join(
+        os.path.dirname(__file__),  # tests/enrich_hf_validation/
+        "..", "..",
+        "py", "services", "agent", "skills", "enrich_hf_metadata",
+        "readme_processor.py",
+    )
+    rp_path = os.path.normpath(_RP_PATH)
+    if not os.path.exists(rp_path):
+        logger.error("readme_processor.py not found at %s", rp_path)
+        return None
+
+    spec = importlib.util.spec_from_file_location(
+        "readme_processor", rp_path,
+    )
+    if spec is None or spec.loader is None:
+        logger.error("Could not create spec for readme_processor.py")
+        return None
+
+    mod = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(mod)
+    except Exception as exc:
+        logger.error("Failed to load readme_processor.py: %s", exc)
+        return None
+
+    _readme_processor_module = mod
+    return mod
+
+
+# ---------------------------------------------------------------------------
+# HF README fetcher
+# ---------------------------------------------------------------------------
+
+
+async def _fetch_readme(repo_id: str, session: aiohttp.ClientSession) -> str:
+    """Fetch the raw README.md from HuggingFace."""
+    url = _HF_RAW_URL.format(repo_id=repo_id)
+    try:
+        async with session.get(url, timeout=aiohttp.ClientTimeout(total=30)) as resp:
+            if resp.status == 200:
+                return await resp.text()
+            logger.warning("Failed to fetch README for %s: HTTP %d", repo_id, resp.status)
+            return ""
+    except (asyncio.TimeoutError, aiohttp.ClientError) as exc:
+        logger.warning("Failed to fetch README for %s: %s", repo_id, exc)
+        return ""
+
+
+# ---------------------------------------------------------------------------
+# Analysis helpers
+# ---------------------------------------------------------------------------
+
+
+def _has_yaml_frontmatter(text: str) -> bool:
+    return bool(text.strip().startswith("---"))
+
+
+def _extract_yaml_field(text: str, field: str) -> bool:
+    """Check if the given YAML field exists in the frontmatter."""
+    lines = text.split("\n")
+    if not lines or not lines[0].strip().startswith("---"):
+        return False
+    end = 1
+    while end < len(lines):
+        if lines[end].strip().startswith("---"):
+            break
+        end += 1
+    if end >= len(lines):
+        return False
+    frontmatter = "\n".join(lines[1:end])
+    pattern = rf"^{field}:"
+    return bool(re.search(pattern, frontmatter, re.MULTILINE))
+
+
+def _find_widget_section_length(text: str) -> int:
+    """Find the ``widget:`` YAML section and return its length (0 if none)."""
+    if not _has_yaml_frontmatter(text):
+        return 0
+    frontmatter_end = text.find("---", 3)
+    if frontmatter_end == -1:
+        return 0
+    frontmatter = text[3:frontmatter_end]
+
+    # Match widget: through to the next top-level key or frontmatter end
+    m = re.search(r"\nwidget:", frontmatter)
+    if not m:
+        return 0
+    # Length from widget: to end of frontmatter (the next \n\w+: or \n---)
+    return len(frontmatter[m.start():])
+
+
+# ---------------------------------------------------------------------------
+# Core auditor
+# ---------------------------------------------------------------------------
+
+
+async def run_audit(
+    entries: List[Tuple[str, str]],
+    *,
+    concurrency: int = 10,
+    readmes_dir: str | None = None,
+) -> Tuple[List[AuditRecord], Dict[str, Any]]:
+    """Run the preprocessing audit over all repo entries.
+
+    Args:
+        entries: List of ``(repo_id, safetensors_name)``.
+        concurrency: Max parallel fetches to HuggingFace.
+        readmes_dir: If set, saves each fetched README as
+            ``{sanitized_repo_id}.md`` in this directory for offline
+            cross-reference against audit results.
+
+    Returns:
+        Tuple of ``(records, summary)`` where *summary* is a dict with
+        aggregate statistics.
+    """
+    semaphore = asyncio.Semaphore(concurrency)
+    records: List[AuditRecord] = []
+    flag_counter: Dict[str, int] = {}
+
+    if readmes_dir:
+        os.makedirs(readmes_dir, exist_ok=True)
+
+    connector = aiohttp.TCPConnector(limit=concurrency)
+    async with aiohttp.ClientSession(connector=connector) as session:
+        tasks = [_audit_one(entry, session, semaphore, readmes_dir=readmes_dir) for entry in entries]
+        gathered = await asyncio.gather(*tasks, return_exceptions=True)
+
+        for entry, result in zip(entries, gathered):
+            if isinstance(result, Exception):
+                logger.error("Audit failed for %s: %s", entry[0], result)
+                records.append(
+                    AuditRecord(
+                        repo_id=entry[0],
+                        safetensors_name=entry[1],
+                        basename=os.path.splitext(entry[1])[0],
+                        raw_readme_length=0,
+                        raw_readme_line_count=0,
+                        has_yaml_frontmatter=False,
+                        yaml_has_base_model=False,
+                        yaml_has_tags=False,
+                        section_extraction_activated=False,
+                        section_length=0,
+                        section_line_count=0,
+                        basename_in_section=False,
+                        cleaned_length=0,
+                        cleaned_line_count=0,
+                        compression_pct=0.0,
+                        widget_section_found=False,
+                        widget_section_length=0,
+                        readme_file="",
+                        flags=[f"Audit exception: {result}"],
+                    )
+                )
+                continue
+
+            # The continue above ensures result is AuditRecord here
+            assert isinstance(result, AuditRecord)
+            records.append(result)
+            for flag in result.flags:
+                flag_counter[flag] = flag_counter.get(flag, 0) + 1
+
+    summary = _build_summary(records, flag_counter)
+    return records, summary
+
+
+def _sanitize_repo_id(repo_id: str) -> str:
+    """Turn ``user/repo-name`` into a safe filename."""
+    return repo_id.replace("/", "__").replace(".", "_")
+
+
+async def _audit_one(
+    entry: Tuple[str, str],
+    session: aiohttp.ClientSession,
+    semaphore: asyncio.Semaphore,
+    *,
+    readmes_dir: str | None = None,
+) -> AuditRecord:
+    """Audit a single repo entry."""
+    repo_id, safetensors_name = entry
+    basename = os.path.splitext(safetensors_name)[0]
+
+    async with semaphore:
+        # Import production preprocessing functions.
+        # Use importlib to bypass py.services.agent.__init__ which triggers
+        # ComfyUI's folder_paths module (not available in standalone mode).
+        _rp = _load_readme_processor()
+        if _rp is None:
+            return AuditRecord(
+                repo_id=repo_id,
+                safetensors_name=safetensors_name,
+                basename=basename,
+                raw_readme_length=0, raw_readme_line_count=0,
+                has_yaml_frontmatter=False, yaml_has_base_model=False, yaml_has_tags=False,
+                readme_file="",
+                section_extraction_activated=False, section_length=0, section_line_count=0,
+                basename_in_section=False, cleaned_length=0, cleaned_line_count=0,
+                compression_pct=0.0, widget_section_found=False, widget_section_length=0,
+                flags=["IMPORT_FAILED"],
+            )
+        clean_readme_for_llm = _rp.clean_readme_for_llm
+        extract_relevant_section = _rp.extract_relevant_section
+
+        # Step 1: Fetch the raw README
+        raw_text = await _fetch_readme(repo_id, session)
+        if not raw_text:
+            return AuditRecord(
+                repo_id=repo_id,
+                safetensors_name=safetensors_name,
+                basename=basename,
+                raw_readme_length=0,
+                raw_readme_line_count=0,
+                has_yaml_frontmatter=False,
+                yaml_has_base_model=False,
+                yaml_has_tags=False,
+                section_extraction_activated=False,
+                section_length=0,
+                section_line_count=0,
+                basename_in_section=False,
+                readme_file="",
+                cleaned_length=0,
+                cleaned_line_count=0,
+                compression_pct=0.0,
+                widget_section_found=False,
+                widget_section_length=0,
+                flags=["README_FETCH_FAILED"],
+            )
+
+        # Save the raw README to disk for offline cross-reference
+        readme_path = ""
+        if readmes_dir:
+            safe_name = _sanitize_repo_id(repo_id)
+            readme_path = os.path.join(readmes_dir, f"{safe_name}.md")
+            try:
+                with open(readme_path, "w", encoding="utf-8") as fh:
+                    fh.write(raw_text)
+            except OSError as exc:
+                logger.warning("Failed to save README for %s: %s", repo_id, exc)
+                readme_path = ""
+
+        raw_lines = raw_text.split("\n")
+        raw_len = len(raw_text)
+        raw_line_count = len(raw_lines)
+
+        # Step 2: Analyze raw README
+        yaml_fm = _has_yaml_frontmatter(raw_text)
+        yaml_has_bm = _extract_yaml_field(raw_text, "base_model") if yaml_fm else False
+        yaml_has_tg = _extract_yaml_field(raw_text, "tags") if yaml_fm else False
+        widget_len = _find_widget_section_length(raw_text)
+
+        # Step 3: Section extraction
+        section = extract_relevant_section(raw_text, basename)
+        section_len = len(section)
+        section_line_count = len(section.split("\n"))
+        section_activated = section_len < raw_len * _SECTION_ACTIVATION_RATIO
+        basename_in_sec = basename.lower() in section.lower()
+
+        # Step 4: Cleaning for LLM
+        cleaned = clean_readme_for_llm(section)
+        cleaned_len = len(cleaned)
+        cleaned_line_count = len(cleaned.split("\n"))
+        compression_pct = round((1 - cleaned_len / raw_len) * 100, 1) if raw_len else 0.0
+
+        # Step 5: Flag anomalies
+        flags: List[str] = []
+        if not raw_text.strip():
+            flags.append("README_EMPTY")
+        if not yaml_fm:
+            flags.append("NO_YAML_FRONTMATTER")
+        if not section_activated:
+            # Check if basename is extremely short/generic (likely synthetic)
+            if len(basename) <= 5:
+                flags.append("BASENAME_TOO_SHORT_SECTION_NOT_EXPECTED")
+            else:
+                flags.append("SECTION_EXTRACTION_NOT_ACTIVATED")
+        elif not basename_in_sec:
+            flags.append("BASENAME_NOT_IN_EXTRACTED_SECTION")
+        if widget_len == 0:
+            # Not necessarily a problem — many repos lack a widget section
+            pass
+        if cleaned_len < _MIN_CLEANED_LENGTH:
+            flags.append("CLEANED_README_TOO_SHORT")
+        if compression_pct > _MAX_COMPRESSION_PCT:
+            flags.append("EXTREME_COMPRESSION")
+        if section_activated and section_line_count < _MIN_SECTION_LINES:
+            flags.append("SECTION_TOO_SMALL")
+
+        return AuditRecord(
+            repo_id=repo_id,
+            safetensors_name=safetensors_name,
+            basename=basename,
+            raw_readme_length=raw_len,
+            raw_readme_line_count=raw_line_count,
+            has_yaml_frontmatter=yaml_fm,
+            yaml_has_base_model=yaml_has_bm,
+            yaml_has_tags=yaml_has_tg,
+            section_extraction_activated=section_activated,
+            section_length=section_len,
+            section_line_count=section_line_count,
+            basename_in_section=basename_in_sec,
+            cleaned_length=cleaned_len,
+            cleaned_line_count=cleaned_line_count,
+            compression_pct=compression_pct,
+            widget_section_found=widget_len > 0,
+            widget_section_length=widget_len,
+            readme_file=readme_path,
+            flags=flags,
+            raw_readme_preview=raw_text[:200],
+            section_preview=section[:300],
+        )
+
+
+def _build_summary(
+    records: List[AuditRecord],
+    flag_counter: Dict[str, int],
+) -> Dict[str, Any]:
+    """Aggregate audit statistics."""
+    n = len(records)
+    if n == 0:
+        return {"error": "no records", "model_count": 0}
+
+    activated = sum(1 for r in records if r.section_extraction_activated)
+    basename_hit = sum(1 for r in records if r.basename_in_section)
+    with_yaml = sum(1 for r in records if r.has_yaml_frontmatter)
+    with_widget = sum(1 for r in records if r.widget_section_found)
+    fetch_failed = sum(1 for r in records if "README_FETCH_FAILED" in r.flags)
+
+    avg_compression = round(
+        sum(r.compression_pct for r in records if r.raw_readme_length > 0) / max(n - fetch_failed, 1),
+        1,
+    )
+    avg_cleaned = round(
+        sum(r.cleaned_length for r in records if r.raw_readme_length > 0) / max(n - fetch_failed, 1),
+    )
+
+    top_flags = sorted(flag_counter.items(), key=lambda x: -x[1])[:10]
+
+    return {
+        "model_count": n,
+        "fetch_failed_count": fetch_failed,
+        "section_extraction_activated": activated,
+        "section_extraction_pct": round(activated / max(n - fetch_failed, 1) * 100, 1),
+        "basename_in_section": basename_hit,
+        "basename_in_section_pct": round(basename_hit / max(n - fetch_failed, 1) * 100, 1),
+        "with_yaml_frontmatter": with_yaml,
+        "with_yaml_frontmatter_pct": round(with_yaml / max(n - fetch_failed, 1) * 100, 1),
+        "with_widget_section": with_widget,
+        "avg_compression_pct": avg_compression,
+        "avg_cleaned_length": avg_cleaned,
+        "top_flags": top_flags,
+    }
+
+
+def audit_records_to_serializable(records: List[AuditRecord]) -> List[Dict[str, Any]]:
+    """Convert AuditRecord dataclasses to plain dicts for JSON serialization."""
+    return [asdict(r) for r in records]
--- a/tests/enrich_hf_validation/report_generator.py
+++ b/tests/enrich_hf_validation/report_generator.py
@@ -0,0 +1,391 @@
+"""Generate structured reports from evaluation results.
+
+Produces:
+
+1. A JSON data dump (``report.json``) with all scores and aggregations.
+2. A human-readable Markdown report (``report.md``) with summary stats,
+   issue patterns, and actionable optimisation suggestions.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from datetime import datetime
+from typing import Any, Dict, List
+
+from .config import SUPPORTED_BASE_MODELS
+from .evaluation_engine import ScoreRecord
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Markdown report
+# ---------------------------------------------------------------------------
+
+
+def _fmt_pct(value: float) -> str:
+    return f"{value:.1f}%"
+
+
+def _bar(value: float, width: int = 20) -> str:
+    filled = int(round(value / 100 * width))
+    return "█" * filled + "░" * (width - filled)
+
+
+def generate_optimisation_suggestions(
+    agg: Dict[str, Any],
+    scores: List[ScoreRecord],
+) -> List[str]:
+    """Analyse evaluation results and produce concrete suggestions."""
+    suggestions: List[str] = []
+    fa = agg.get("field_aggregates", {})
+
+    # --- base_model ---
+    bm = fa.get("base_model", {})
+    if bm and bm.get("empty_rate_pct", 0) > 30:
+        suggestions.append(
+            "- **base_model 空置率高 ({:.0f}%)**: 多数 HF 模型卡片未在 YAML frontmatter 中声明 "
+            "`base_model:` 字段，LLM 无法推断。可考虑在 prompt 中增加 \"look at the model file name "
+            "for clues\" 的引导，或在后处理中增加基于文件名规则的 fallback 猜测。".format(
+                bm.get("empty_rate_pct", 0)
+            )
+        )
+    bm_invalid = sum(
+        1
+        for s in scores
+        if s["raw_values"]["base_model"]
+        and s["raw_values"]["base_model"] != "Unknown"
+        and s["raw_values"]["base_model"] not in set(SUPPORTED_BASE_MODELS)
+    )
+    if bm_invalid > 5:
+        suggestions.append(
+            "- **base_model 含非标准值 ({} 个)**: LLM 输出了未在当前生产系统的 base model 列表 "
+            "中的名称。建议在 prompt 中强调 \"Use EXACTLY one name from the list\" 并在 "
+            "`PostProcessor` 中加一层验证过滤，非标准值直接丢弃。".format(bm_invalid)
+        )
+
+    # --- trigger_words ---
+    tw = fa.get("trigger_words", {})
+    if tw and tw.get("empty_rate_pct", 0) > 40:
+        suggestions.append(
+            "- **trigger_words 空置率高 ({:.0f}%)**: 大量 HF 模型卡没有明确的 "
+            "`instance_prompt:` 或 trigger word 说明。当前 prompt 已覆盖常见模式。若确认这些模型确实"
+            "没有 trigger words（例如 style lora），空数组是正确结果，不需优化。".format(
+                tw.get("empty_rate_pct", 0)
+            )
+        )
+
+    # --- tags ---
+    tag = fa.get("tags", {})
+    if tag and tag.get("empty_rate_pct", 0) > 30:
+        suggestions.append(
+            "- **tags 空置率高 ({:.0f}%)**: 当前 prompt 要求 tags 必须与 "
+            "`priority_tags`（CIVITAI_MODEL_TAGS）对齐。HF 模型的标签体系与 Civitai 不同，"
+            "很多 model card 使用细粒度标签（如 `pokemon`、`watercolor`）而不在 priority list 中。"
+            "建议: 扩大 priority_tags 范围，或允许 LLM 自由生成 tags 后只做去重不做严格过滤。".format(
+                tag.get("empty_rate_pct", 0)
+            )
+        )
+
+    # --- tags priority coverage ---
+    low_coverage = sum(
+        1
+        for s in scores
+        if s["field_scores"].get("tags_priority_coverage", 5) < 3  # < 60% of max
+        and s["field_scores"].get("tags", 0) > 0
+    )
+    if low_coverage > 10:
+        suggestions.append(
+            "- **{} 个模型的 tags 与 priority_tags 匹配度低于 60%**: "
+            "LLM 生成了有意义但不属于 CIVITAI_MODEL_TAGS 的标签。这说明 priority_tags "
+            "的覆盖范围对 HF 模型不足，建议按 HF 模型的实际分布补充新类别。".format(low_coverage)
+        )
+
+    # --- preview ---
+    prev = fa.get("preview_downloaded", {})
+    if prev and prev.get("empty_rate_pct", 0) > 50:
+        suggestions.append(
+            "- **预览图下载成功率低 ({:.0f}%)**: 很多 HF 模型卡没有 embed 图片（仅使用 YAML widget "
+            "或 external link）。当前 `readme_processor.py` 的 `extract_gallery_images` 和 "
+            "`extract_gallery_table_images` 已覆盖了多数场景。若预览图不重要，可降低此字段权重。".format(
+                prev.get("empty_rate_pct", 0)
+            )
+        )
+
+    # --- usage_tips ---
+    ut = fa.get("usage_tips", {})
+    if ut and ut.get("empty_rate_pct", 0) > 70:
+        suggestions.append(
+            "- **usage_tips 空置率极高 ({:.0f}%)**: 这是预期行为。HF 模型卡通常不包含 LoRA "
+            "强度/CLIP skip 等结构化参数。当前提取策略已合理。若需要可用数据，"
+            "可以考虑使用模型类型的通用默认值。".format(
+                ut.get("empty_rate_pct", 0)
+            )
+        )
+
+    # --- short_description ---
+    sd = fa.get("short_description", {})
+    if sd and sd.get("empty_rate_pct", 0) > 40:
+        suggestions.append(
+            "- **short_description 空置率 ({:.0f}%)**: 部分 HF 模型卡 README 内容极少（仅含标签和训练参数）。".format(
+                sd.get("empty_rate_pct", 0)
+            )
+        )
+
+    if not suggestions:
+        suggestions.append("- 未发现明显问题模式，各字段填充率均在可接受范围。")
+
+    return suggestions
+
+
+def generate_markdown_report(
+    agg: Dict[str, Any],
+    scores: List[ScoreRecord],
+    output_dir: str,
+    duration_summary: Dict[str, Any] | None = None,
+    *,
+    audit_summary: Dict[str, Any] | None = None,
+    config_warnings: List[str] | None = None,
+) -> str:
+    """Write ``report.md`` and return its content.
+
+    Args:
+        agg: Aggregate evaluation scores.
+        scores: Per-model evaluation records.
+        output_dir: Output directory for the report file.
+        duration_summary: Optional timing statistics.
+        audit_summary: Optional preprocessing audit summary (Phase 1.5).
+        config_warnings: Optional LLM config consistency warnings.
+    """
+    lines: List[str] = []
+    def wl(text: str = "") -> None:
+        lines.append(text)
+
+    wl("# HF Metadata Enrichment Validation Report")
+    wl()
+    wl(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    wl(f"Models evaluated: **{agg.get('model_count', 0)}**")
+    wl(f"Successful enrichments: **{agg.get('success_count', 0)}**")
+    wl(f"Failures: **{agg.get('fail_count', 0)}**")
+    wl()
+
+    # ---- Preprocessing Audit Section ----
+    if audit_summary and audit_summary.get("model_count", 0) > 0:
+        wl("## Preprocessing Audit")
+        wl()
+        wl(f"| Metric | Value |")
+        wl(f"|--------|-------|")
+        wl(f"| Models audited | {audit_summary.get('model_count', 0)} |")
+        wl(f"| README fetch failed | {audit_summary.get('fetch_failed_count', 0)} |")
+        wl(f"| Section extraction activated | {_fmt_pct(audit_summary.get('section_extraction_pct', 0))} |")
+        wl(f"| Basename found in section | {_fmt_pct(audit_summary.get('basename_in_section_pct', 0))} |")
+        wl(f"| Has YAML frontmatter | {_fmt_pct(audit_summary.get('with_yaml_frontmatter_pct', 0))} |")
+        wl(f"| Has YAML widget section | {_fmt_pct(audit_summary.get('with_widget_section', 0))} |")
+        wl(f"| Avg README compression | {audit_summary.get('avg_compression_pct', 0)}% |")
+        wl(f"| Avg cleaned length | {audit_summary.get('avg_cleaned_length', 0)} chars |")
+        wl()
+
+        if audit_summary.get("top_flags"):
+            wl("### Audit Flags (most frequent)")
+            wl()
+            for flag, count in audit_summary["top_flags"]:
+                wl(f"- **{flag}**: {count}x")
+            wl()
+
+        wl("**Interpretation:**")
+        wl()
+        act_pct = audit_summary.get("section_extraction_pct", 0)
+        if act_pct < 50:
+            wl(
+                "- ⚠️ Section extraction activated for fewer than 50% of repos. "
+                "This may indicate the basename doesn't match README content, or the "
+                "repos are mostly single-model (where full README is expected)."
+            )
+        else:
+            wl(
+                "- ✅ Section extraction is working for most repos — the LLM is "
+                "receiving focused README sections."
+            )
+
+        if audit_summary.get("basename_in_section_pct", 100) < 80:
+            wl(
+                "- ⚠️ The safetensors basename was NOT found in the extracted section "
+                "for many repos. This could mean the section extraction matched the wrong "
+                "section, or the README doesn't explicitly reference the filename."
+            )
+        wl()
+
+    # ---- Config warnings ----
+    if config_warnings:
+        wl("## ⚠️ Configuration Warnings")
+        wl()
+        for w in config_warnings:
+            wl(f"- {w}")
+        wl()
+
+    # ---- Duration ----
+    if duration_summary:
+        wl("## Timing")
+        wl()
+        wl(f"- Total wall time: **{duration_summary.get('total_wall_s', 0):.0f} s** ")
+        wl(f"  ({duration_summary.get('total_wall_s', 0) / 60:.1f} min)")
+        wl(f"- Mean per model: **{duration_summary.get('mean_s', 0):.1f} s**")
+        wl(f"- Median per model: **{duration_summary.get('median_s', 0):.1f} s**")
+        wl(f"- Fastest: **{duration_summary.get('min_s', 0):.1f} s**")
+        wl(f"- Slowest: **{duration_summary.get('max_s', 0):.1f} s**")
+        wl()
+
+    # ---- Overall score ----
+    ts = agg.get("total_score", {})
+    wl("## Overall Score Distribution  (0–100)")
+    wl()
+    wl(f"| Metric | Value |")
+    wl(f"|--------|-------|")
+    wl(f"| Mean   | {ts.get('mean', 'N/A')} |")
+    wl(f"| Median | {ts.get('median', 'N/A')} |")
+    wl(f"| Min    | {ts.get('min', 'N/A')} |")
+    wl(f"| Max    | {ts.get('max', 'N/A')} |")
+    wl()
+    for label, key in [
+        ("Excellent (≥80)", "excellent_80+"),
+        ("Good (60–79)", "good_60_79"),
+        ("Fair (40–59)", "fair_40_59"),
+        ("Poor (20–39)", "poor_20_39"),
+        ("Bad (<20)", "bad_0_19"),
+    ]:
+        count = ts.get("bins", {}).get(key, 0)
+        pct = count / agg["model_count"] * 100 if agg["model_count"] else 0
+        wl(f"- **{label}**: {count} models ({_fmt_pct(pct)})")
+    wl()
+
+    # ---- Per-field aggregates ----
+    wl("## Per-Field Completeness")
+    wl()
+    wl("| Field | Mean Score | Fill Rate | Empty Rate |")
+    wl("|-------|-----------:|----------:|-----------:|")
+    fa = agg.get("field_aggregates", {})
+    for fn in [
+        "base_model", "trigger_words", "short_description", "tags",
+        "tags_priority_coverage", "notes", "usage_tips",
+        "modelDescription_html", "preview_downloaded",
+    ]:
+        f = fa.get(fn, {})
+        if not f:
+            continue
+        wl(
+            f"| {fn} "
+            f"| {f.get('mean', 'N/A')} "
+            f"| {_fmt_pct(f.get('fill_rate_pct', 0))} "
+            f"| {_fmt_pct(f.get('empty_rate_pct', 0))} |"
+        )
+    wl()
+
+    # ---- Confidence distribution ----
+    wl("## LLM Confidence Distribution")
+    wl()
+    cd = agg.get("confidence_distribution", {})
+    total_conf = sum(cd.values()) or 1
+    for level in ["high", "medium", "low", ""]:
+        count = cd.get(level, 0)
+        label = level if level else "(not reported)"
+        pct = count / total_conf * 100
+        bar = _bar(pct)
+        wl(f"- **{label}**: {count}  {bar}  {_fmt_pct(pct)}")
+    wl()
+
+    # ---- Top issues ----
+    wl("## Most Frequent Issues")
+    wl()
+    for issue, count in agg.get("top_issues", []):
+        pct = count / agg["model_count"] * 100 if agg["model_count"] else 0
+        wl(f"- **{issue}** — {count}/{agg['model_count']} ({_fmt_pct(pct)})")
+    wl()
+
+    # ---- Optimisation suggestions ----
+    wl("## Optimisation Suggestions")
+    wl()
+    suggestions = generate_optimisation_suggestions(agg, scores)
+    for s in suggestions:
+        wl(s)
+    wl()
+
+    # ---- Per-model detail ----
+    wl("## Per-Model Detail")
+    wl()
+    wl("<details>")
+    wl("<summary>Click to expand</summary>")
+    wl()
+    wl("| # | Repo ID | Score | Issues | Confidence |")
+    wl("|---|---------|------:|--------|------------|")
+    for i, s in enumerate(scores, 1):
+        issue_count = len(s["issues"])
+        issue_str = (
+            f"{issue_count} issue(s)" if issue_count else "✓ ok"
+        )
+        wl(
+            f"| {i} "
+            f"| {s['repo_id']} "
+            f"| {s['total_score']} "
+            f"| {issue_str} "
+            f"| {s.get('confidence_from_llm', '') or '-'} |"
+        )
+    wl()
+    wl("</details>")
+    wl()
+
+    content = "\n".join(lines)
+    report_path = os.path.join(output_dir, "report.md")
+    with open(report_path, "w", encoding="utf-8") as fh:
+        fh.write(content)
+    logger.info("Markdown report written to %s", report_path)
+    return content
+
+
+# ---------------------------------------------------------------------------
+# JSON dump
+# ---------------------------------------------------------------------------
+
+
+def save_json_report(
+    agg: Dict[str, Any],
+    scores: List[ScoreRecord],
+    enrichment_results: List[Dict[str, Any]],
+    output_dir: str,
+    duration_summary: Dict[str, Any] | None = None,
+    *,
+    audit_summary: Dict[str, Any] | None = None,
+    config_warnings: List[str] | None = None,
+) -> str:
+    """Write ``report.json`` and return the path.
+
+    Args:
+        agg: Aggregate evaluation scores.
+        scores: Per-model evaluation records.
+        enrichment_results: Raw enrichment phase results.
+        output_dir: Output directory.
+        duration_summary: Optional timing statistics.
+        audit_summary: Optional preprocessing audit summary.
+        config_warnings: Optional LLM config consistency warnings.
+    """
+    report: Dict[str, Any] = {
+        "metadata": {
+            "generated_at": datetime.now().isoformat(),
+            "model_count": agg.get("model_count", 0),
+        },
+        "aggregate": agg,
+        "timing": duration_summary or {},
+        "per_model_scores": scores,
+        "enrichment_results": enrichment_results,
+    }
+    if audit_summary:
+        report["preprocessing_audit"] = audit_summary
+    if config_warnings:
+        report["config_warnings"] = config_warnings
+
+    path = os.path.join(output_dir, "report.json")
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(report, fh, indent=2, ensure_ascii=False)
+    logger.info("JSON report written to %s", path)
+    return path
--- a/tests/enrich_hf_validation/run_validation.py
+++ b/tests/enrich_hf_validation/run_validation.py
@@ -0,0 +1,451 @@
+#!/usr/bin/env python3
+"""CLI entry point for the HF metadata enrichment validation suite.
+
+Usage::
+
+    # Full run (44 models, serial, ~1-2 h)
+    python -m tests.enrich_hf_validation.run_validation \\
+        --output /tmp/hf_enrich_validation
+
+    # Quick smoke test with 2 models
+    python -m tests.enrich_hf_validation.run_validation --sample 2
+
+    # Resume from a previous partial run
+    python -m tests.enrich_hf_validation.run_validation --resume
+
+    # Audit preprocessing only (no LLM calls, fast)
+    python -m tests.enrich_hf_validation.run_validation --audit-only
+
+    # Custom settings file
+    python -m tests.enrich_hf_validation.run_validation \\
+        --settings /custom/path/settings.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import os
+import sys
+import time
+from typing import Any, Dict, List, Tuple
+
+# Ensure the project root is on sys.path so that ``from py import ...`` works.
+_PROJECT_ROOT = os.path.normpath(
+    os.path.join(os.path.dirname(__file__), "..", "..")
+)
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+# Add ComfyUI root to sys.path so ``folder_paths`` can be imported.
+# Project layout: ComfyUI/custom_nodes/ComfyUI-Lora-Manager/
+_COMFYUI_ROOT = os.path.normpath(os.path.join(_PROJECT_ROOT, "..", ".."))
+if _COMFYUI_ROOT not in sys.path:
+    sys.path.insert(0, _COMFYUI_ROOT)
+
+from tests.enrich_hf_validation.config import (
+    init_supported_base_models,
+    load_settings,
+)
+from tests.enrich_hf_validation.metadata_constructor import (
+    RepoEntry,
+    create_all_initial_metadata,
+    load_repo_ids,
+)
+from tests.enrich_hf_validation.enrichment_runner import EnrichmentRunner
+from tests.enrich_hf_validation.evaluation_engine import (
+    aggregate_scores,
+    evaluate_batch,
+)
+from tests.enrich_hf_validation.preprocessing_auditor import (
+    audit_records_to_serializable,
+    run_audit,
+)
+from tests.enrich_hf_validation.report_generator import (
+    generate_markdown_report,
+    save_json_report,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _setup_logging(verbose: bool) -> None:
+    level = logging.DEBUG if verbose else logging.INFO
+    fmt = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+    logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
+
+    # Quiet noisy third-party loggers
+    for name in ("aiohttp", "asyncio", "urllib3"):
+        logging.getLogger(name).setLevel(logging.WARNING)
+
+
+def _parse_args(argv: List[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Validate and optimise HF metadata enrichment via LLM.",
+    )
+    parser.add_argument(
+        "--models",
+        default=os.path.join(os.path.dirname(__file__), "test_data", "hf_lora_models_with_safetensors.txt"),
+        help="Path to the HF repo entries file (format: repo_id, model_name.safetensors per line)",
+    )
+    parser.add_argument(
+        "--settings",
+        default="~/.config/ComfyUI-LoRA-Manager/settings.json",
+        help="Path to LoRA Manager settings.json",
+    )
+    parser.add_argument(
+        "--output",
+        default="/tmp/hf_enrich_validation",
+        help="Output directory for reports and intermediate data",
+    )
+    parser.add_argument(
+        "--sample",
+        type=int,
+        default=0,
+        help="Process only the first N models (for quick smoke tests)",
+    )
+    parser.add_argument(
+        "--resume",
+        action="store_true",
+        help="Resume from previous partial run (uses progress.json)",
+    )
+    parser.add_argument(
+        "--no-enrich",
+        action="store_true",
+        help="Skip enrichment phase (evaluate existing metadata only)",
+    )
+    parser.add_argument(
+        "--audit-only",
+        action="store_true",
+        help="Run preprocessing audit only (no enrichment, no evaluation)",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=240,
+        help="Per-model LLM timeout in seconds (default: 240)",
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Enable debug logging",
+    )
+    return parser.parse_args(argv)
+
+
+# ---------------------------------------------------------------------------
+# Phase helpers
+# ---------------------------------------------------------------------------
+
+
+def _phase_header(label: str) -> None:
+    sep = "=" * 60
+    print(f"\n{sep}", file=sys.stderr)
+    print(f"  PHASE: {label}", file=sys.stderr)
+    print(sep, file=sys.stderr)
+
+
+# ---------------------------------------------------------------------------
+# Read back LLM config after enrichment (for consistency reporting)
+# ---------------------------------------------------------------------------
+
+
+def _get_actual_llm_config() -> Dict[str, str]:
+    """Read what LLMService is actually using, if initialized.
+
+    Only meaningful when called AFTER enrichment has started (i.e. after
+    ``AgentService.get_instance()`` has been called).
+    """
+    try:
+        from py.services.llm_service import LLMService
+
+        instance = LLMService._instance
+        if instance is None:
+            return {"status": "not initialized"}
+        cfg = instance._get_config()
+        return {
+            "provider": cfg.get("provider", ""),
+            "model": cfg.get("model", ""),
+            "api_base": cfg.get("api_base", ""),
+        }
+    except Exception as exc:
+        return {"status": f"error: {exc}"}
+
+
+def _compare_llm_config(
+    pipeline_cfg: Dict[str, Any],
+    actual_cfg: Dict[str, str],
+) -> List[str]:
+    """Compare pipeline-loaded vs LLMService-used config.
+
+    Returns warning messages if they differ.
+    """
+    warnings: List[str] = []
+    if not actual_cfg or actual_cfg.get("status", "") == "not initialized":
+        warnings.append(
+            "LLMService was not initialized during this run — cannot verify "
+            "config consistency."
+        )
+        return warnings
+
+    field_map = [
+        ("llm_provider", "provider"),
+        ("llm_model", "model"),
+        ("llm_api_base", "api_base"),
+    ]
+    for pipeline_key, llm_key in field_map:
+        pv = (pipeline_cfg.get(pipeline_key) or "").strip()
+        lv = (actual_cfg.get(llm_key) or "").strip()
+        if pv and lv and pv != lv:
+            warnings.append(
+                f"LLM config mismatch: --settings has '{pv}' for {pipeline_key}, "
+                f"but LLMService uses '{lv}'. "
+                f"The pipeline's --settings path ({pipeline_cfg.get('settings_path', '?')}) "
+                "may differ from where SettingsManager reads."
+            )
+    if not warnings and actual_cfg:
+        warnings.append(
+            "✅ LLM config matches between pipeline --settings and LLMService."
+        )
+    return warnings
+
+
+# ---------------------------------------------------------------------------
+# Phase 1.5: preprocessing audit
+# ---------------------------------------------------------------------------
+
+
+async def _run_preprocessing_audit(
+    entries: List[RepoEntry],
+    output_dir: str,
+) -> Dict[str, Any]:
+    """Execute the preprocessing audit and save results."""
+    _phase_header("Preprocessing audit")
+    print(f"  Auditing {len(entries)} repos ...", file=sys.stderr)
+
+    readmes_dir = os.path.join(output_dir, "readmes")
+    t0 = time.perf_counter()
+    records, summary = await run_audit(entries, readmes_dir=readmes_dir)
+    elapsed = time.perf_counter() - t0
+
+    # Save audit data
+    audit_path = os.path.join(output_dir, "preprocessing_audit.json")
+    with open(audit_path, "w", encoding="utf-8") as fh:
+        json.dump(
+            {
+                "summary": summary,
+                "records": audit_records_to_serializable(records),
+            },
+            fh,
+            indent=2,
+            ensure_ascii=False,
+        )
+
+    print(f"  Audit complete: {len(records)} repos in {elapsed:.0f}s", file=sys.stderr)
+    print(f"  Section extraction activated: {summary.get('section_extraction_pct', 0)}%", file=sys.stderr)
+    print(f"  Basename in extracted section: {summary.get('basename_in_section_pct', 0)}%", file=sys.stderr)
+    print(f"  Avg compression: {summary.get('avg_compression_pct', 0)}%", file=sys.stderr)
+    print(f"  Avg cleaned length: {summary.get('avg_cleaned_length', 0)} chars", file=sys.stderr)
+    print(f"  Audit data: {audit_path}", file=sys.stderr)
+
+    if summary.get("top_flags"):
+        print("  Top flags:", file=sys.stderr)
+        for flag, count in summary["top_flags"][:5]:
+            print(f"    - {flag}: {count}x", file=sys.stderr)
+
+    return summary
+
+
+async def _run_enrichment(
+    model_paths: List[str],
+    repos: List[str],
+    output_dir: str,
+    timeout: int,
+    verbose: bool,
+) -> Dict[str, Any]:
+    """Execute the enrichment phase."""
+    runner = EnrichmentRunner(
+        output_dir=output_dir,
+        per_model_timeout=timeout,
+    )
+    result = await runner.run(model_paths, repos)
+
+    # Print quick summary
+    progress = result["progress"]
+    total_done = (
+        len(progress.get("completed", []))
+        + len(progress.get("failed", []))
+        + len(progress.get("timed_out", []))
+    )
+    print(
+        f"\n  Enrichment complete: {total_done} processed "
+        f"({len(progress.get('completed', []))} ok, "
+        f"{len(progress.get('failed', []))} failed, "
+        f"{len(progress.get('timed_out', []))} timed out)",
+        file=sys.stderr,
+    )
+    return result
+
+
+def _collect_enriched_metadata(
+    model_paths: List[str],
+    repos: List[str],
+    results: List[Dict[str, Any]],
+) -> List[Dict[str, Any]]:
+    """Read enriched .metadata.json for each model.
+
+    Uses the same path convention as the rest of the codebase:
+    ``os.path.splitext(model_path)[0] + '.metadata.json'``.
+
+    Returns a list of dicts with keys: repo_id, model_path, success,
+    errors, metadata.
+    """
+    enriched: List[Dict[str, Any]] = []
+    # Build a lookup from repo_id to enrichment result
+    result_lookup: Dict[str, Dict[str, Any]] = {}
+    for r in results:
+        result_lookup[r["repo_id"]] = r
+
+    for model_path, repo_id in zip(model_paths, repos):
+        res = result_lookup.get(repo_id, {})
+        metadata_path = f"{os.path.splitext(model_path)[0]}.metadata.json"
+        metadata: Dict[str, Any] = {}
+        if os.path.exists(metadata_path):
+            try:
+                with open(metadata_path, "r", encoding="utf-8") as fh:
+                    metadata = json.load(fh)
+            except (json.JSONDecodeError, OSError) as exc:
+                logger.warning("Failed to read %s: %s", metadata_path, exc)
+        else:
+            logger.warning(
+                "Metadata file not found for %s (expected: %s)",
+                repo_id, metadata_path,
+            )
+
+        enriched.append({
+            "repo_id": repo_id,
+            "model_path": model_path,
+            "success": res.get("success", False),
+            "errors": res.get("errors", []),
+            "metadata": metadata,
+        })
+
+    return enriched
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+async def main(argv: List[str]) -> int:
+    args = _parse_args(argv)
+    _setup_logging(args.verbose)
+
+    output_dir = os.path.abspath(os.path.expanduser(args.output))
+    os.makedirs(output_dir, exist_ok=True)
+
+    # ---- Phase 0: Initialise shared state ----
+    _phase_header("Initialise")
+    settings = load_settings(args.settings)
+    logger.info(
+        "LLM config from --settings: provider=%s model=%s api_base=%s",
+        settings["llm_provider"],
+        settings["llm_model"],
+        settings["llm_api_base"],
+    )
+    # Load the production base model list (replaces the old hardcoded list)
+    await init_supported_base_models()
+
+    # ---- Load entries ----
+    _phase_header("Load repo entries & construct initial metadata")
+    entries = load_repo_ids(args.models, max_models=args.sample if args.sample > 0 else None)
+    model_paths, repo_ids = create_all_initial_metadata(
+        entries, output_dir, skip_existing=True,
+    )
+    print(f"  {len(model_paths)} repos ready", file=sys.stderr)
+
+    # ---- Phase 1.5: Preprocessing audit ----
+    audit_summary: Dict[str, Any] = {}
+    t_start = time.perf_counter()
+    audit_summary = await _run_preprocessing_audit(entries, output_dir)
+
+    if args.audit_only:
+        total_wall = time.perf_counter() - t_start
+        print(f"\n  Audit-only done in {total_wall:.0f}s", file=sys.stderr)
+        print(f"  Audit data: {output_dir}/preprocessing_audit.json", file=sys.stderr)
+        return 0
+
+    # ---- Phase 2: Enrichment ----
+    enrichment_results: List[Dict[str, Any]] = []
+    if not args.no_enrich:
+        _phase_header("Enrich metadata via LLM")
+        enrichment_out = await _run_enrichment(
+            model_paths, repo_ids, output_dir, args.timeout, args.verbose,
+        )
+        enrichment_results = enrichment_out["results"]
+    else:
+        print("  Enrichment skipped (--no-enrich)", file=sys.stderr)
+
+    t_enrich = time.perf_counter()
+
+    # ---- Phase 3: Evaluation ----
+    _phase_header("Evaluate enriched metadata")
+    enriched = _collect_enriched_metadata(model_paths, repo_ids, enrichment_results)
+    scores = evaluate_batch(enriched)
+    agg = aggregate_scores(scores)
+    print(
+        f"  Mean total score: {agg.get('total_score', {}).get('mean', 'N/A')} / 100",
+        file=sys.stderr,
+    )
+    print(
+        f"  Models scored: {agg.get('model_count', 0)}",
+        file=sys.stderr,
+    )
+
+    # ---- Phase 4: Report generation ----
+    _phase_header("Generate reports")
+    duration_summary: Dict[str, Any] | None = None
+    if enrichment_results:
+        durations = [r.get("duration_s", 0) for r in enrichment_results if r.get("duration_s")]
+        if durations:
+            sorted_d = sorted(durations)
+            m = len(sorted_d) // 2
+            duration_summary = {
+                "total_wall_s": round(t_enrich - t_start, 1),
+                "mean_s": round(sum(durations) / len(durations), 1),
+                "median_s": round(sorted_d[m] if len(sorted_d) % 2 else (sorted_d[m - 1] + sorted_d[m]) / 2, 1),
+                "min_s": round(min(durations), 1),
+                "max_s": round(max(durations), 1),
+            }
+
+    # Check LLM config consistency after enrichment (LLMService is now initialized)
+    actual_llm_cfg = _get_actual_llm_config()
+    config_warnings = _compare_llm_config(settings, actual_llm_cfg)
+
+    save_json_report(
+        agg, scores, enrichment_results, output_dir, duration_summary,
+        audit_summary=audit_summary, config_warnings=config_warnings,
+    )
+    generate_markdown_report(
+        agg, scores, output_dir, duration_summary,
+        audit_summary=audit_summary, config_warnings=config_warnings,
+    )
+
+    # ---- Final summary ----
+    total_wall = time.perf_counter() - t_start
+    print(f"\n  Done in {total_wall:.0f}s ({total_wall / 60:.1f} min)", file=sys.stderr)
+    print(f"  Reports: {output_dir}/report.md, {output_dir}/report.json", file=sys.stderr)
+    print(file=sys.stderr)
+
+    return 0 if agg.get("success_count", 0) > 0 else 1
+
+
+def entry_point() -> int:
+    return asyncio.run(main(sys.argv[1:]))
+
+
+if __name__ == "__main__":
+    sys.exit(entry_point())
--- a/tests/enrich_hf_validation/test_data/base_model_ground_truth.json
+++ b/tests/enrich_hf_validation/test_data/base_model_ground_truth.json
@@ -0,0 +1,376 @@
+{
+  "description": "Ground truth base_model mapping for HF LoRA enrichment test data",
+  "generated_at": "2026-07-05T18:20:00+08:00",
+  "inference_method": "Manual analysis of YAML base_model field + README content + filename clues",
+  "canonical_list_source": "Fallback list in config.py + CivitAI production API (73 models total)",
+  "entries": [
+    {
+      "repo_id": "k2styles/krea-2-cobalt-sky-anime-lora",
+      "safetensors_name": "cobalt-sky-anime.safetensors",
+      "yaml_base_model_raw": "krea/Krea-2-Turbo",
+      "correct_base_model": "Krea 2",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "k2styles/krea-2-azure-gouache-daylight-lora",
+      "safetensors_name": "azure-gouache-daylight.safetensors",
+      "yaml_base_model_raw": "krea/Krea-2-Turbo",
+      "correct_base_model": "Krea 2",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "TheDivergentAI/krea2-turbo-distill-lora",
+      "safetensors_name": "krea2_turbo_distill_r128.safetensors",
+      "yaml_base_model_raw": "krea/Krea-2-Raw",
+      "correct_base_model": "Krea 2",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "DeverStyle/Krea2-Loras",
+      "safetensors_name": "n0t_f4l_000001000.safetensors",
+      "yaml_base_model_raw": "krea/Krea-2-Turbo",
+      "correct_base_model": "Krea 2",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "Komorebi1995/krea2-raw-jpaf-celpaint-lora",
+      "safetensors_name": "krea2_raw_jpaf_celpaint_full_v1.safetensors",
+      "yaml_base_model_raw": null,
+      "correct_base_model": "Krea 2",
+      "confidence": "high",
+      "evidence": "Filename contains 'krea2'"
+    },
+    {
+      "repo_id": "artificialguybr/pixelartredmond-1-5v-pixel-art-loras-for-sd-1-5",
+      "safetensors_name": "PixelArtRedmond15V-PixelArt-PIXARFK.safetensors",
+      "yaml_base_model_raw": "runwayml/stable-diffusion-v1-5",
+      "correct_base_model": "SD 1.5",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "Shakker-Labs/FLUX.1-dev-LoRA-Logo-Design",
+      "safetensors_name": "FLUX-dev-lora-Logo-Design.safetensors",
+      "yaml_base_model_raw": "black-forest-labs/FLUX.1-dev",
+      "correct_base_model": "Flux.1 D",
+      "confidence": "high",
+      "evidence": "YAML base_model: FLUX.1-dev → dev → D"
+    },
+    {
+      "repo_id": "glif-loradex-trainer/bingbangboom_flux_surf",
+      "safetensors_name": "flux_surf_000001500.safetensors",
+      "yaml_base_model_raw": "black-forest-labs/FLUX.1-dev",
+      "correct_base_model": "Flux.1 D",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "prithivMLmods/Ton618-Epic-Realism-Flux-LoRA",
+      "safetensors_name": "Epic-Realism-Unpruned.safetensors",
+      "yaml_base_model_raw": "black-forest-labs/FLUX.1-dev",
+      "correct_base_model": "Flux.1 D",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "prithivMLmods/Fashion-Hut-Modeling-LoRA",
+      "safetensors_name": "Fashion-Modeling.safetensors",
+      "yaml_base_model_raw": "black-forest-labs/FLUX.1-dev",
+      "correct_base_model": "Flux.1 D",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "prithivMLmods/Retro-Pixel-Flux-LoRA",
+      "safetensors_name": "Retro-Pixel.safetensors",
+      "yaml_base_model_raw": "black-forest-labs/FLUX.1-dev",
+      "correct_base_model": "Flux.1 D",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "D1-3105/HiDream-E1-Full_lora",
+      "safetensors_name": "HiDream-E1-Full.safetensors",
+      "yaml_base_model_raw": "HiDream-ai/HiDream-E1-Full",
+      "correct_base_model": "HiDream",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field; filename contains 'HiDream'"
+    },
+    {
+      "repo_id": "renderartist/Classic-Painting-Z-Image-Turbo-LoRA",
+      "safetensors_name": "Classic_Painting_Z_Image_Turbo_v1_renderartist_1750.safetensors",
+      "yaml_base_model_raw": "Tongyi-MAI/Z-Image-Turbo",
+      "correct_base_model": "ZImageTurbo",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field; filename contains 'Z-Image-Turbo'"
+    },
+    {
+      "repo_id": "DeverStyle/Z-Image-loras",
+      "safetensors_name": "z_image_archer_style.safetensors",
+      "yaml_base_model_raw": "Tongyi-MAI/Z-Image-Turbo",
+      "correct_base_model": "ZImageTurbo",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "deadman44/Z-Image_LoRA",
+      "safetensors_name": "lora_zimage_turbo_myjs_alpha01.safetensors",
+      "yaml_base_model_raw": null,
+      "correct_base_model": "ZImageTurbo",
+      "confidence": "high",
+      "evidence": "Filename contains 'zimage_turbo'"
+    },
+    {
+      "repo_id": "zyuzuguldu/vton-lora-linen",
+      "safetensors_name": "pytorch_lora_weights.safetensors",
+      "yaml_base_model_raw": "stabilityai/stable-diffusion-xl-base-1.0",
+      "correct_base_model": "SDXL 1.0",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "svntax-dev/pixel_spritesheet_4walk_small_lora_v1",
+      "safetensors_name": "pixel_4walk_small_flux2_klein_base_4b_v1_000002750.safetensors",
+      "yaml_base_model_raw": "black-forest-labs/FLUX.2-klein-base-4B",
+      "correct_base_model": "Flux.2 Klein 4B-base",
+      "confidence": "high",
+      "evidence": "YAML base_model: FLUX.2-klein-base-4B"
+    },
+    {
+      "repo_id": "Haruka041/z-image-anime-lora",
+      "safetensors_name": "sk_anime_style_v1.0.safetensors",
+      "yaml_base_model_raw": "Tongyi-MAI/Z-Image-Turbo",
+      "correct_base_model": "ZImageTurbo",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "systms/SYSTMS-INFL8-LoRA-Wan22",
+      "safetensors_name": "SYSTMS_INFL8_LORA_WAN22_low_noise.safetensors",
+      "yaml_base_model_raw": "Wan-AI/Wan2.2-I2V-A14B",
+      "correct_base_model": "Wan Video 2.2 I2V-A14B",
+      "confidence": "high",
+      "evidence": "YAML base_model: Wan2.2-I2V-A14B"
+    },
+    {
+      "repo_id": "crafiq/flux-2-klein-9b-360-panorama-lora",
+      "safetensors_name": "flux-2-klein-9b-360-panorama-lora.safetensors",
+      "yaml_base_model_raw": "black-forest-labs/FLUX.2-klein-base-9B",
+      "correct_base_model": "Flux.2 Klein 9B-base",
+      "confidence": "high",
+      "evidence": "YAML base_model: FLUX.2-klein-base-9B; filename contains 'flux-2-klein-9b'"
+    },
+    {
+      "repo_id": "Leon1000/pixel_spritesheet_4walk_small_lora_v1",
+      "safetensors_name": "pixel_4walk_small_flux2_klein_base_4b_v1_000002750.safetensors",
+      "yaml_base_model_raw": "black-forest-labs/FLUX.2-klein-base-4B",
+      "correct_base_model": "Flux.2 Klein 4B-base",
+      "confidence": "high",
+      "evidence": "YAML base_model: FLUX.2-klein-base-4B; filename contains 'flux2_klein_base_4b'"
+    },
+    {
+      "repo_id": "Muapi/pov-missionary-legs-together-lora",
+      "safetensors_name": "pov-missionary-legs-together-lora.safetensors",
+      "yaml_base_model_raw": "OnomaAIResearch/Illustrious-xl-early-release-v0",
+      "correct_base_model": "Illustrious",
+      "confidence": "high",
+      "evidence": "YAML base_model: OnomaAIResearch/Illustrious-*"
+    },
+    {
+      "repo_id": "ostris/ideogram_4_unconditional_lora",
+      "safetensors_name": "ideogram_4_unconditional_lora_r16.safetensors",
+      "yaml_base_model_raw": "ideogram-ai/ideogram-4-fp8",
+      "correct_base_model": "Ideogram 4.0",
+      "confidence": "high",
+      "evidence": "YAML base_model: ideogram-ai/ideogram-4 → Ideogram 4.0; filename contains 'ideogram_4'"
+    },
+    {
+      "repo_id": "ilkerzgi/krea-2-bleached-surreal-uncanny-lora",
+      "safetensors_name": "bleached-surreal-uncanny-comfy.safetensors",
+      "yaml_base_model_raw": "krea/Krea-2-Turbo",
+      "correct_base_model": "Krea 2",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "ilkerzgi/krea-2-azure-surreal-collage-lora",
+      "safetensors_name": "azure-surreal-collage-comfy.safetensors",
+      "yaml_base_model_raw": "krea/Krea-2-Turbo",
+      "correct_base_model": "Krea 2",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "ilkerzgi/krea-2-airy-gouache-minimalist-lora",
+      "safetensors_name": "airy-gouache-minimalist-comfy.safetensors",
+      "yaml_base_model_raw": "krea/Krea-2-Turbo",
+      "correct_base_model": "Krea 2",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "k2styles/krea-2-airy-watercolor-chibi-lora",
+      "safetensors_name": "airy-watercolor-chibi.safetensors",
+      "yaml_base_model_raw": "krea/Krea-2-Turbo",
+      "correct_base_model": "Krea 2",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "TakeAswing/sdxl-lora-lofi",
+      "safetensors_name": "pytorch_lora_weights.safetensors",
+      "yaml_base_model_raw": "stabilityai/stable-diffusion-xl-base-1.0",
+      "correct_base_model": "SDXL 1.0",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field; repo name contains 'sdxl'"
+    },
+    {
+      "repo_id": "heville/anna-lora-krea2",
+      "safetensors_name": "pytorch_lora_weights.safetensors",
+      "yaml_base_model_raw": "krea/Krea-2-Raw",
+      "correct_base_model": "Krea 2",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field; repo name contains 'krea2'"
+    },
+    {
+      "repo_id": "Brioch/krea2_loras",
+      "safetensors_name": "mashap_ohwx_woman_krea2.safetensors",
+      "yaml_base_model_raw": "krea/Krea-2-Raw",
+      "correct_base_model": "Krea 2",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "hr16/Miwano-Rag-LoRA",
+      "safetensors_name": "Miwano-Rag-epoch10.lora.safetensors",
+      "yaml_base_model_raw": null,
+      "correct_base_model": "SD 1.5",
+      "confidence": "high",
+      "evidence": "README: base model is Kanianime (SD 1.5 fine-tune)"
+    },
+    {
+      "repo_id": "ikuseiso/Personal_Lora_collections",
+      "safetensors_name": "vergil_devil_may_cry.safetensors",
+      "yaml_base_model_raw": null,
+      "correct_base_model": "SD 1.5",
+      "confidence": "high",
+      "evidence": "Sample prompt shows Model: AbyssOrangeMix (SD 1.5), 512x768"
+    },
+    {
+      "repo_id": "Tanger/LoraByTanger",
+      "safetensors_name": "(v4)layila-000005.safetensors",
+      "yaml_base_model_raw": null,
+      "correct_base_model": "SD 1.5",
+      "confidence": "high",
+      "evidence": "README: trained on anything4.5 (SD 1.5) and nai (SD 1.5); test images on AbyssOrangeMix2_hard"
+    },
+    {
+      "repo_id": "DS-Archive/ds-LoRA",
+      "safetensors_name": "dsharu-v2_lc.safetensors",
+      "yaml_base_model_raw": null,
+      "correct_base_model": "SD 1.5",
+      "confidence": "high",
+      "evidence": "README explicitly states 'Stable Diffusion 1.5'"
+    },
+    {
+      "repo_id": "soknife/loras",
+      "safetensors_name": "irys-regular-subject-more.safetensors",
+      "yaml_base_model_raw": null,
+      "correct_base_model": "SD 1.5",
+      "confidence": "high",
+      "evidence": "README mentions SD 1.5 fine-tune models (PastelMix, AbyssOrangeMix, Anything)"
+    },
+    {
+      "repo_id": "prompthero/openjourney-lora",
+      "safetensors_name": "openjourneyLora.safetensors",
+      "yaml_base_model_raw": "stabilityai/stable-diffusion-2-1-base",
+      "correct_base_model": "SD 2.1",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "Banano/banchan-lora",
+      "safetensors_name": "Bananochan-PonySDXL-v2.safetensors",
+      "yaml_base_model_raw": null,
+      "correct_base_model": "Pony",
+      "confidence": "medium",
+      "evidence": "Filename contains 'PonySDXL-v2' → Pony base model"
+    },
+    {
+      "repo_id": "Maisman/No-Game-NoLife-LoRAs",
+      "safetensors_name": "ShiroNGNL2_Lora.safetensors",
+      "yaml_base_model_raw": null,
+      "correct_base_model": "SD 1.5",
+      "confidence": "high",
+      "evidence": "Sample prompts show Model: abyssorangemix2_Hardcore (SD 1.5), 512x768"
+    },
+    {
+      "repo_id": "EarthnDusk/Gambit_Xmen_Anime_Lora_V1.1",
+      "safetensors_name": "RemyLebeau.safetensors",
+      "yaml_base_model_raw": null,
+      "correct_base_model": "SD 1.5",
+      "confidence": "high",
+      "evidence": "Trained Feb 2023 via Kohya LoRA (pre-SDXL era), SD 1.5 lineage"
+    },
+    {
+      "repo_id": "EarthnDusk/DuskfallArt_LoRa",
+      "safetensors_name": "DuskfallArt.safetensors",
+      "yaml_base_model_raw": "stable-diffusion-v1-5/stable-diffusion-v1-5",
+      "correct_base_model": "SD 1.5",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "gaoxiao/pokemon-lora",
+      "safetensors_name": "pytorch_lora_weights.safetensors",
+      "yaml_base_model_raw": "runwayml/stable-diffusion-v1-5",
+      "correct_base_model": "SD 1.5",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "wtcherr/sd-unsplash_10k_canny-model-control-lora",
+      "safetensors_name": "diffusion_pytorch_model.safetensors",
+      "yaml_base_model_raw": "runwayml/stable-diffusion-v1-5",
+      "correct_base_model": "SD 1.5",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "wtcherr/sd-unsplash_10k_blur_rand_KS-model-control-lora",
+      "safetensors_name": "diffusion_pytorch_model.safetensors",
+      "yaml_base_model_raw": "runwayml/stable-diffusion-v1-5",
+      "correct_base_model": "SD 1.5",
+      "confidence": "high",
+      "evidence": "YAML frontmatter base_model field"
+    },
+    {
+      "repo_id": "samurai-architects/lora-starbucks",
+      "safetensors_name": "starbucks_interior.safetensors",
+      "yaml_base_model_raw": null,
+      "correct_base_model": null,
+      "confidence": "none",
+      "evidence": "README too minimal, no base_model in YAML, cannot determine"
+    },
+    {
+      "repo_id": "prithivMLmods/Flux-Long-Toon-LoRA",
+      "safetensors_name": "Long-Toon.safetensors",
+      "yaml_base_model_raw": "black-forest-labs/FLUX.1-dev",
+      "correct_base_model": "Flux.1 D",
+      "confidence": "high",
+      "evidence": "YAML base_model: FLUX.1-dev (dev → D)"
+    },
+    {
+      "repo_id": "Limbicnation/pixel-art-lora",
+      "safetensors_name": "pytorch_lora_weights.comfyui.safetensors",
+      "yaml_base_model_raw": "black-forest-labs/FLUX.2-klein-4B",
+      "correct_base_model": "Flux.2 Klein 4B",
+      "confidence": "high",
+      "evidence": "YAML base_model: FLUX.2-klein-4B; README explicitly states base model"
+    }
+  ]
+}
--- a/tests/enrich_hf_validation/test_data/hf_lora_models_with_safetensors.txt
+++ b/tests/enrich_hf_validation/test_data/hf_lora_models_with_safetensors.txt
@@ -0,0 +1,46 @@
+k2styles/krea-2-cobalt-sky-anime-lora, cobalt-sky-anime.safetensors
+k2styles/krea-2-azure-gouache-daylight-lora, azure-gouache-daylight.safetensors
+TheDivergentAI/krea2-turbo-distill-lora, krea2_turbo_distill_r128.safetensors
+DeverStyle/Krea2-Loras, n0t_f4l_000001000.safetensors
+Komorebi1995/krea2-raw-jpaf-celpaint-lora, krea2_raw_jpaf_celpaint_full_v1.safetensors
+artificialguybr/pixelartredmond-1-5v-pixel-art-loras-for-sd-1-5, PixelArtRedmond15V-PixelArt-PIXARFK.safetensors
+Shakker-Labs/FLUX.1-dev-LoRA-Logo-Design, FLUX-dev-lora-Logo-Design.safetensors
+glif-loradex-trainer/bingbangboom_flux_surf, flux_surf_000001500.safetensors
+prithivMLmods/Ton618-Epic-Realism-Flux-LoRA, Epic-Realism-Unpruned.safetensors
+prithivMLmods/Fashion-Hut-Modeling-LoRA, Fashion-Modeling.safetensors
+prithivMLmods/Retro-Pixel-Flux-LoRA, Retro-Pixel.safetensors
+D1-3105/HiDream-E1-Full_lora, HiDream-E1-Full.safetensors
+renderartist/Classic-Painting-Z-Image-Turbo-LoRA, Classic_Painting_Z_Image_Turbo_v1_renderartist_1750.safetensors
+DeverStyle/Z-Image-loras, z_image_archer_style.safetensors
+deadman44/Z-Image_LoRA, lora_zimage_turbo_myjs_alpha01.safetensors
+zyuzuguldu/vton-lora-linen, pytorch_lora_weights.safetensors
+svntax-dev/pixel_spritesheet_4walk_small_lora_v1, pixel_4walk_small_flux2_klein_base_4b_v1_000002750.safetensors
+Haruka041/z-image-anime-lora, sk_anime_style_v1.0.safetensors
+systms/SYSTMS-INFL8-LoRA-Wan22, SYSTMS_INFL8_LORA_WAN22_low_noise.safetensors
+crafiq/flux-2-klein-9b-360-panorama-lora, flux-2-klein-9b-360-panorama-lora.safetensors
+Leon1000/pixel_spritesheet_4walk_small_lora_v1, pixel_4walk_small_flux2_klein_base_4b_v1_000002750.safetensors
+Muapi/pov-missionary-legs-together-lora, pov-missionary-legs-together-lora.safetensors
+ostris/ideogram_4_unconditional_lora, ideogram_4_unconditional_lora_r16.safetensors
+ilkerzgi/krea-2-bleached-surreal-uncanny-lora, bleached-surreal-uncanny-comfy.safetensors
+ilkerzgi/krea-2-azure-surreal-collage-lora, azure-surreal-collage-comfy.safetensors
+ilkerzgi/krea-2-airy-gouache-minimalist-lora, airy-gouache-minimalist-comfy.safetensors
+k2styles/krea-2-airy-watercolor-chibi-lora, airy-watercolor-chibi.safetensors
+TakeAswing/sdxl-lora-lofi, pytorch_lora_weights.safetensors
+heville/anna-lora-krea2, pytorch_lora_weights.safetensors
+Brioch/krea2_loras, mashap_ohwx_woman_krea2.safetensors
+hr16/Miwano-Rag-LoRA, Miwano-Rag-epoch10.lora.safetensors
+ikuseiso/Personal_Lora_collections, vergil_devil_may_cry.safetensors
+Tanger/LoraByTanger, (v4)layila-000005.safetensors
+DS-Archive/ds-LoRA, dsharu-v2_lc.safetensors
+soknife/loras, irys-regular-subject-more.safetensors
+prompthero/openjourney-lora, openjourneyLora.safetensors
+Banano/banchan-lora, Bananochan-PonySDXL-v2.safetensors
+Maisman/No-Game-NoLife-LoRAs, ShiroNGNL2_Lora.safetensors
+EarthnDusk/Gambit_Xmen_Anime_Lora_V1.1, RemyLebeau.safetensors
+EarthnDusk/DuskfallArt_LoRa, DuskfallArt.safetensors
+gaoxiao/pokemon-lora, pytorch_lora_weights.safetensors
+wtcherr/sd-unsplash_10k_canny-model-control-lora, diffusion_pytorch_model.safetensors
+wtcherr/sd-unsplash_10k_blur_rand_KS-model-control-lora, diffusion_pytorch_model.safetensors
+samurai-architects/lora-starbucks, starbucks_interior.safetensors
+prithivMLmods/Flux-Long-Toon-LoRA, Long-Toon.safetensors
+Limbicnation/pixel-art-lora, pytorch_lora_weights.comfyui.safetensors
--- a/tests/metadata_ops/init.py
+++ b/tests/metadata_ops/init.py
--- a/tests/metadata_ops/test_metadata_ops.py
+++ b/tests/metadata_ops/test_metadata_ops.py
--- a/tests/metadata_ops/test_readme_processor.py
+++ b/tests/metadata_ops/test_readme_processor.py
@@ -0,0 +1,490 @@
+"""Tests for ``readme_processor.py`` — HF README processing for enrich_hf_metadata.
+
+Import via ``importlib`` to avoid the ``folder_paths`` dependency in
+``py.services.agent.__init__``.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+from pathlib import Path
+
+import pytest
+
+_MODULE_PATH = Path(__file__).parents[2] / "py" / "services" / "agent" / "skills" / "enrich_hf_metadata" / "readme_processor.py"
+
+
+@pytest.fixture(scope="session")
+def R():
+    """Load the ``readme_processor`` module once per session."""
+    spec = importlib.util.spec_from_file_location("readme_processor", str(_MODULE_PATH))
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+# ======================================================================
+# extract_gallery_images
+# ======================================================================
+
+
+class TestExtractGalleryImages:
+    def test_empty(self, R):
+        assert R.extract_gallery_images("", "repo") == []
+        assert R.extract_gallery_images("no frontmatter", "repo") == []
+
+    def test_no_widget(self, R):
+        readme = "---\ntags: [test]\n---\nbody"
+        assert R.extract_gallery_images(readme, "repo") == []
+
+    def test_widget_simple_text(self, R):
+        """YAML ``text: 'plain'`` → extracted as-is."""
+        readme = """---
+widget:
+- text: 'a cute cat'
+  output:
+    url: images/cat.png
+---"""
+        imgs = R.extract_gallery_images(readme, "user/repo")
+        assert len(imgs) == 1
+        assert imgs[0]["meta"]["prompt"] == "a cute cat"
+        assert "images/cat.png" in imgs[0]["url"]
+
+    def test_widget_unquoted_text(self, R):
+        """YAML ``text: plain value`` without quotes."""
+        readme = """---
+widget:
+- text: simple text
+  output:
+    url: img.png
+---"""
+        imgs = R.extract_gallery_images(readme, "user/repo")
+        assert len(imgs) == 1
+        assert imgs[0]["meta"]["prompt"] == "simple text"
+
+    def test_widget_block_scalar(self, R):
+        """YAML ``text: >-`` folded block scalar — extract actual content."""
+        readme = """---
+widget:
+- text: >-
+    Long toons, a close-up of a cartoon characters face is featured in a
+    vibrant red backdrop.
+  output:
+    url: images/LT4.png
+---"""
+        imgs = R.extract_gallery_images(readme, "user/repo")
+        assert len(imgs) == 1
+        prompt = imgs[0]["meta"]["prompt"]
+        assert "Long toons" in prompt
+        assert "vibrant red backdrop" in prompt
+        assert prompt != ">-"
+
+    def test_widget_dash_prefix_output(self, R):
+        """YAML ``- output:`` (dash prefix) — regression for widget parsing."""
+        readme = """---
+widget:
+- output:
+    url: images/test.png
+  text: dash test
+---"""
+        imgs = R.extract_gallery_images(readme, "user/repo")
+        assert len(imgs) == 1
+        assert imgs[0]["meta"]["prompt"] == "dash test"
+        assert "images/test.png" in imgs[0]["url"]
+
+    def test_widget_mixed_entries(self, R):
+        """Multiple widget entries with different text styles."""
+        readme = """---
+widget:
+- text: >-
+    First entry description.
+  output:
+    url: img1.png
+- text: second entry
+  output:
+    url: img2.png
+- text: 'third entry'
+  output:
+    url: img3.png
+---"""
+        imgs = R.extract_gallery_images(readme, "user/repo")
+        assert len(imgs) == 3
+        assert imgs[0]["meta"]["prompt"] == "First entry description."
+        assert imgs[1]["meta"]["prompt"] == "second entry"
+        assert imgs[2]["meta"]["prompt"] == "third entry"
+
+
+# ======================================================================
+# extract_simple_markdown_images
+# ======================================================================
+
+
+class TestExtractSimpleMarkdownImages:
+    def test_empty(self, R):
+        assert R.extract_simple_markdown_images("", "repo") == []
+
+    def test_basic_markdown_image(self, R):
+        """``![alt](./img.png)`` → absolute URL."""
+        imgs = R.extract_simple_markdown_images("![test](./image_0.png)", "u/r")
+        assert len(imgs) == 1
+        assert "image_0.png" in imgs[0]["url"]
+        assert imgs[0]["meta"]["prompt"] == "test"
+
+    def test_absolute_url(self, R):
+        """``![alt](https://...)`` → keep as-is."""
+        imgs = R.extract_simple_markdown_images(
+            "![img](https://example.com/img.png)", "u/r"
+        )
+        assert len(imgs) == 1
+        assert imgs[0]["url"] == "https://example.com/img.png"
+
+    def test_skips_code_fences(self, R):
+        """Inside ``` blocks should be ignored."""
+        text = """outside
+```
+![inside](./img.png)
+```
+outside again
+![valid](./valid.png)"""
+        imgs = R.extract_simple_markdown_images(text, "u/r")
+        assert len(imgs) == 1
+        assert "valid.png" in imgs[0]["url"]
+
+    def test_deduplicates(self, R):
+        text = "![a](./img.png)\n![b](./img.png)"
+        imgs = R.extract_simple_markdown_images(text, "u/r")
+        assert len(imgs) == 1  # deduplicated
+
+
+# ======================================================================
+# extract_html_img_tags
+# ======================================================================
+
+
+class TestExtractHtmlImgTags:
+    def test_double_quoted_src(self, R):
+        imgs = R.extract_html_img_tags('<img src="./img.png">', "u/r")
+        assert len(imgs) == 1
+        assert "img.png" in imgs[0]["url"]
+
+    def test_single_quoted_src(self, R):
+        imgs = R.extract_html_img_tags("<img src='./img.png'>", "u/r")
+        assert len(imgs) == 1
+        assert "img.png" in imgs[0]["url"]
+
+    def test_absolute_url(self, R):
+        imgs = R.extract_html_img_tags(
+            '<img src="https://cdn.example.com/img.png">', "u/r"
+        )
+        assert len(imgs) == 1
+        assert imgs[0]["url"] == "https://cdn.example.com/img.png"
+
+    def test_deduplicates_across_formats(self, R):
+        text = '<img src="./img.png">\n<img src=\'./img.png\'>'
+        imgs = R.extract_html_img_tags(text, "u/r")
+        assert len(imgs) == 1
+
+
+# ======================================================================
+# extract_gallery_table_images
+# ======================================================================
+
+
+class TestExtractGalleryTableImages:
+    def test_gallery_table(self, R):
+        text = """| Preview | Prompt |
+|--------|--------|
+| ![img](./a.png) | a cat |
+| ![img](./b.png) | a dog |"""
+        imgs = R.extract_gallery_table_images(text, "u/r")
+        assert len(imgs) == 2
+        assert imgs[0]["meta"]["prompt"] == "a cat"
+        assert "a.png" in imgs[0]["url"]
+        assert imgs[1]["meta"]["prompt"] == "a dog"
+
+    def test_skips_non_gallery_table(self, R):
+        text = """| Parameter | Value |
+|----------|-------|
+| Steps    | 4     |"""
+        imgs = R.extract_gallery_table_images(text, "u/r")
+        assert len(imgs) == 0
+
+
+# ======================================================================
+# clean_readme_for_llm  +  strip helpers
+# ======================================================================
+
+
+class TestCleanReadmeForLlm:
+    def test_preserves_plain_code_block(self, R):
+        """`` ``` `` without language tag → preserved (trigger words)."""
+        text = """Before
+```
+pixel art sprite, game asset
+```
+After"""
+        cleaned = R.clean_readme_for_llm(text)
+        assert "pixel art sprite" in cleaned
+        assert "game asset" in cleaned
+
+    def test_strips_fenced_code_with_lang(self, R):
+        """`` ```python `` → stripped."""
+        text = "before\n```python\nimport torch\n```\nafter"
+        cleaned = R.clean_readme_for_llm(text)
+        assert "import torch" not in cleaned
+        assert "before" in cleaned
+        assert "after" in cleaned
+
+    def test_preserves_markdown_image_url(self, R):
+        """``![alt](url)`` → URL kept for LLM preview extraction."""
+        text = "![sample](./preview.png)"
+        cleaned = R.clean_readme_for_llm(text)
+        assert "./preview.png" in cleaned
+
+    def test_converts_html_img_tag_to_markdown_image(self, R):
+        """``<img src="...">`` → ``![](src)`` preserving URL for LLM."""
+        text = 'before\n<img src="logo.png">\nafter'
+        cleaned = R.clean_readme_for_llm(text)
+        assert "![](logo.png)" in cleaned
+        assert "logo.png" in cleaned  # URL preserved for LLM extraction
+
+    def test_widget_stripped_frontmatter_preserved(self, R):
+        """Widget YAML stripped but ``base_model:`` kept."""
+        text = """---
+tags: [test]
+widget:
+- text: >-
+    long description here
+  output:
+    url: img.png
+base_model: black-forest-labs/FLUX.1-dev
+instance_prompt: test
+---"""
+        cleaned = R.clean_readme_for_llm(text)
+        assert "widget:" not in cleaned
+        assert "black-forest-labs/FLUX.1-dev" in cleaned
+        assert "instance_prompt: test" in cleaned
+
+    def test_training_table_stripped(self, R):
+        """Training-parameter table → stripped."""
+        text = """before
+| LR Scheduler | constant |
+|--------------|---------|
+| Optimizer    | AdamW   |
+after"""
+        cleaned = R.clean_readme_for_llm(text)
+        assert "LR Scheduler" not in cleaned
+        assert "Optimizer" not in cleaned
+        assert "before" in cleaned
+        assert "after" in cleaned
+
+    def test_best_dimensions_table_kept(self, R):
+        """Non-training table (Best Dimensions) → kept."""
+        text = """## Best Dimensions
+- 768 x 1024 (Best)
+- 1024 x 1024 (Default)"""
+        cleaned = R.clean_readme_for_llm(text)
+        assert "768 x 1024" in cleaned
+
+    def test_boilerplate_section_stripped(self, R):
+        text = """stuff
+## Download model
+[link](url)
+## Next section
+content"""
+        cleaned = R.clean_readme_for_llm(text)
+        assert "Download model" not in cleaned
+        assert "Next section" in cleaned
+        assert "content" in cleaned
+
+    def test_returns_empty_for_none(self, R):
+        assert R.clean_readme_for_llm(None) == ""
+
+    def test_returns_empty_for_empty(self, R):
+        assert R.clean_readme_for_llm("") == ""
+
+
+# ======================================================================
+# _is_heading  /  _heading_level
+# ======================================================================
+
+
+class TestHeadingDetection:
+    @pytest.mark.parametrize(
+        "line,expected",
+        [
+            ("# Title", 1),
+            ("## Sub", 2),
+            ("### Subsub", 3),
+            ("#### Subsubsub", 4),
+            ("<h1>Title</h1>", 1),
+            ("<h2>Sub</h2>", 2),
+            ("<h3 class='x'>Sub</h3>", 3),
+            ("<h4 id='y'>Sub</h4>", 4),
+            ("not a heading", 0),
+            ("###", 0),  # no text after ###
+            ("</h2>", 0),  # closing tag, not a heading
+            ("", 0),
+        ],
+    )
+    def test_heading_level(self, R, line, expected):
+        assert R._heading_level(line) == expected
+
+    @pytest.mark.parametrize(
+        "line,expected",
+        [
+            ("# Title", True),
+            ("<h2>Sub</h2>", True),
+            ("</h2>", False),  # closing tag
+            ("not heading", False),
+        ],
+    )
+    def test_is_heading(self, R, line, expected):
+        assert R._is_heading(line) == expected
+
+
+# ======================================================================
+# extract_relevant_section
+# ======================================================================
+
+
+class TestExtractRelevantSection:
+    def test_fallback_full_readme(self, R):
+        """No match → full README returned."""
+        readme = "# Title\n\nsome content"
+        assert R.extract_relevant_section(readme, "nonexistent") == readme
+
+    def test_empty_basename_returns_full(self, R):
+        readme = "# Title"
+        assert R.extract_relevant_section(readme, "") == readme
+
+    def test_match_heading_includes_yaml(self, R):
+        """Matching heading should still include YAML frontmatter."""
+        readme = """---
+base_model: foo
+---
+# My-Model-Title
+
+content
+## Subsection
+more"""
+        section = R.extract_relevant_section(readme, "My-Model")
+        assert "base_model: foo" in section
+        assert "content" in section
+        assert "Subsection" in section
+
+    def test_match_heading_includes_subheadings(self, R):
+        """``# Title`` match includes all ``##`` children."""
+        readme = """# Main Title
+
+## Child A
+content A
+## Child B
+content B
+## Child C
+content C"""
+        section = R.extract_relevant_section(readme, "Main Title")
+        assert "Child A" in section
+        assert "Child B" in section
+        assert "Child C" in section
+
+    def test_match_download_link(self, R):
+        """Download link containing basename → section extracted."""
+        readme = """# Collection
+## Model A
+[Download](./model_a.safetensors)
+## MyModel
+[Download](./mymodel.safetensors)
+content here
+## Model B
+other"""
+        section = R.extract_relevant_section(readme, "mymodel")
+        assert "content here" in section
+        assert "Model A" not in section  # should not include sibling
+
+    def test_heading_closing_tag_not_boundary(self, R):
+        """``</h2>`` should NOT be treated as a section boundary."""
+        readme = """# Title
+<p>some text</p>
+</h2>
+## Real Section
+content"""
+        section = R.extract_relevant_section(readme, "Title")
+        assert "Real Section" in section  # forward walk should not stop at </h2>
+        assert "content" in section
+
+
+# ======================================================================
+# _extract_frontmatter
+# ======================================================================
+
+
+class TestExtractFrontmatter:
+    def test_basic(self, R):
+        assert R._extract_frontmatter("---\ntags: [a]\n---\nbody") == "\ntags: [a]\n"
+
+    def test_no_frontmatter(self, R):
+        assert R._extract_frontmatter("no dashes") == ""
+
+    def test_empty_string(self, R):
+        assert R._extract_frontmatter("") == ""
+
+
+# ======================================================================
+# _strip_widget_section
+# ======================================================================
+
+
+class TestStripWidgetSection:
+    def test_strip_widget_keep_base_model(self, R):
+        """Widget stripped but ``base_model:`` preserved."""
+        text = """---
+tags: [test]
+widget:
+- text: >-
+    long text
+  output:
+    url: img.png
+base_model: black-forest-labs/FLUX.1-dev
+---"""
+        result = R._strip_widget_section(text)
+        assert "widget:" not in result
+        assert "black-forest-labs/FLUX.1-dev" in result
+
+    def test_no_widget_no_change(self, R):
+        text = "---\ntags: [a]\n---"
+        assert R._strip_widget_section(text) == text
+
+    def test_widget_at_end_of_frontmatter(self, R):
+        """Widget is the last YAML key before closing ---."""
+        text = """---
+base_model: a
+widget:
+- text: x
+  output:
+    url: y.png
+---"""
+        result = R._strip_widget_section(text)
+        assert "widget:" not in result
+        assert "base_model: a" in result
+
+
+# ======================================================================
+# _strip_fenced_code_blocks
+# ======================================================================
+
+
+class TestStripFencedCodeBlocks:
+    def test_strips_with_language(self, R):
+        text = "a\n```python\ncode\n```\nb"
+        assert R._strip_fenced_code_blocks(text) == "a\nb"
+
+    def test_keeps_plain_fence(self, R):
+        """`` ``` `` without language → preserved."""
+        text = "a\n```\ntrigger words\n```\nb"
+        assert "trigger words" in R._strip_fenced_code_blocks(text)
+
+    def test_pattern(self, R):
+        text = "x\n```yaml\nkey: val\n```\ny"
+        assert "key: val" not in R._strip_fenced_code_blocks(text)
--- a/tests/routes/snapshots/test_api_snapshots.ambr
+++ b/tests/routes/snapshots/test_api_snapshots.ambr
@@ -28,6 +28,7 @@
    'settings': dict({
      'civitai_api_key_set': True,
      'language': 'en',
+      'llm_api_key_set': False,
      'theme': 'dark',
    }),
    'success': True,
--- a/tests/services/test_post_processor.py
+++ b/tests/services/test_post_processor.py
@@ -39,12 +39,12 @@ class TestProcessDispatch:
    @pytest.mark.asyncio
    async def test_enrich_hf_metadata_routes_correctly(self, processor):
        with (
-            mock.patch("py.agent_cli.apply_metadata_updates") as mock_apply,
-            mock.patch("py.agent_cli.download_preview") as mock_dl,
-            mock.patch("py.agent_cli.refresh_cache") as mock_ref,
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview") as mock_dl,
+            mock.patch("py.metadata_ops.refresh_cache") as mock_ref,
        ):
            mock_apply.return_value = ["metadata_source"]
-            mock_dl.return_value = False
+            mock_dl.return_value = None

            result = await processor.process(
                skill_name="enrich_hf_metadata",
@@ -67,8 +67,10 @@ class TestEnrichHfMetadata:
    MIN_LLM_OUTPUT = {
        "base_model": "",
        "trigger_words": [],
-        "description": "",
+        "short_description": "",
        "tags": [],
+        "recommended_width": 0,
+        "recommended_height": 0,
        "preview_url": "",
        "confidence": "low",
    }
@@ -80,9 +82,9 @@ class TestEnrichHfMetadata:
        """Empty current base_model → new value is applied."""
        llm = {**self.MIN_LLM_OUTPUT, "base_model": "Flux.1 D"}
        with (
-            mock.patch("py.agent_cli.apply_metadata_updates") as mock_apply,
-            mock.patch("py.agent_cli.download_preview", return_value=False),
-            mock.patch("py.agent_cli.refresh_cache"),
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview", return_value=False),
+            mock.patch("py.metadata_ops.refresh_cache"),
        ):
            await processor.process(
                skill_name="enrich_hf_metadata",
@@ -98,9 +100,9 @@ class TestEnrichHfMetadata:
        """Existing base_model from CivitAI → not overwritten."""
        llm = {**self.MIN_LLM_OUTPUT, "base_model": "Flux.1 D"}
        with (
-            mock.patch("py.agent_cli.apply_metadata_updates") as mock_apply,
-            mock.patch("py.agent_cli.download_preview", return_value=False),
-            mock.patch("py.agent_cli.refresh_cache"),
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview", return_value=False),
+            mock.patch("py.metadata_ops.refresh_cache"),
        ):
            await processor.process(
                skill_name="enrich_hf_metadata",
@@ -117,9 +119,9 @@ class TestEnrichHfMetadata:
        """Existing base_model from HF → overwritten (LLM is more reliable)."""
        llm = {**self.MIN_LLM_OUTPUT, "base_model": "Flux.1 D"}
        with (
-            mock.patch("py.agent_cli.apply_metadata_updates") as mock_apply,
-            mock.patch("py.agent_cli.download_preview", return_value=False),
-            mock.patch("py.agent_cli.refresh_cache"),
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview", return_value=False),
+            mock.patch("py.metadata_ops.refresh_cache"),
        ):
            await processor.process(
                skill_name="enrich_hf_metadata",
@@ -134,9 +136,9 @@ class TestEnrichHfMetadata:
    async def test_base_model_skipped_when_llm_empty(self, processor):
        """LLM returns empty base_model → nothing written."""
        with (
-            mock.patch("py.agent_cli.apply_metadata_updates") as mock_apply,
-            mock.patch("py.agent_cli.download_preview", return_value=False),
-            mock.patch("py.agent_cli.refresh_cache"),
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview", return_value=False),
+            mock.patch("py.metadata_ops.refresh_cache"),
        ):
            await processor.process(
                skill_name="enrich_hf_metadata",
@@ -154,9 +156,9 @@ class TestEnrichHfMetadata:
        """New trigger words written when current list is empty."""
        llm = {**self.MIN_LLM_OUTPUT, "trigger_words": ["trigger1", "trigger2"]}
        with (
-            mock.patch("py.agent_cli.apply_metadata_updates") as mock_apply,
-            mock.patch("py.agent_cli.download_preview", return_value=False),
-            mock.patch("py.agent_cli.refresh_cache"),
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview", return_value=None),
+            mock.patch("py.metadata_ops.refresh_cache"),
        ):
            await processor.process(
                skill_name="enrich_hf_metadata",
@@ -165,25 +167,142 @@ class TestEnrichHfMetadata:
                metadata={"trainedWords": []},
            )
        applied = mock_apply.call_args[0][1]
-        assert applied["trainedWords"] == ["trigger1", "trigger2"]
+        assert applied["civitai"]["trainedWords"] == ["trigger1", "trigger2"]

-    # -- description -----------------------------------------------------
+    # -- short_description → civitai.description -------------------------

    @pytest.mark.asyncio
-    async def test_description_set_when_empty(self, processor):
-        llm = {**self.MIN_LLM_OUTPUT, "description": "A model description"}
+    async def test_short_description_written_to_civitai(self, processor):
+        """short_description written to civitai.description for HF models."""
+        llm = {**self.MIN_LLM_OUTPUT, "short_description": "A short summary"}
        with (
-            mock.patch("py.agent_cli.apply_metadata_updates") as mock_apply,
-            mock.patch("py.agent_cli.download_preview", return_value=False),
-            mock.patch("py.agent_cli.refresh_cache"),
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview", return_value=None),
+            mock.patch("py.metadata_ops.refresh_cache"),
        ):
            await processor.process(
                skill_name="enrich_hf_metadata",
                model_path="/p.safetensors",
                llm_output=llm,
-                metadata={"modelDescription": ""},
+                metadata={"from_civitai": False},
            )
-        assert "modelDescription" in mock_apply.call_args[0][1]
+        applied = mock_apply.call_args[0][1]
+        assert applied["civitai"]["description"] == "A short summary"
+
+    @pytest.mark.asyncio
+    async def test_short_description_skipped_for_civitai_model(self, processor):
+        """short_description NOT written for CivitAI models (has own description)."""
+        llm = {**self.MIN_LLM_OUTPUT, "short_description": "A short summary"}
+        with (
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview", return_value=None),
+            mock.patch("py.metadata_ops.refresh_cache"),
+        ):
+            await processor.process(
+                skill_name="enrich_hf_metadata",
+                model_path="/p.safetensors",
+                llm_output=llm,
+                metadata={"from_civitai": True},
+            )
+        applied = mock_apply.call_args[0][1]
+        assert "civitai" not in applied or "description" not in applied.get("civitai", {})
+
+    # -- readme_content → modelDescription -------------------------------
+
+    @pytest.mark.asyncio
+    async def test_readme_content_converted_to_model_description(self, processor):
+        """Raw README converted to HTML and stored as modelDescription."""
+        with (
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview", return_value=None),
+            mock.patch("py.metadata_ops.refresh_cache"),
+        ):
+            await processor.process(
+                skill_name="enrich_hf_metadata",
+                model_path="/p.safetensors",
+                llm_output=self.MIN_LLM_OUTPUT,
+                metadata={"from_civitai": False},
+                readme_content="# Hello\n\nThis is **bold**.",
+            )
+        applied = mock_apply.call_args[0][1]
+        assert "<h1>Hello</h1>" in applied.get("modelDescription", "")
+        assert "<strong>bold</strong>" in applied.get("modelDescription", "")
+
+    @pytest.mark.asyncio
+    async def test_readme_content_skipped_for_civitai_model(self, processor):
+        """README content NOT converted for CivitAI models."""
+        with (
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview", return_value=None),
+            mock.patch("py.metadata_ops.refresh_cache"),
+        ):
+            await processor.process(
+                skill_name="enrich_hf_metadata",
+                model_path="/p.safetensors",
+                llm_output=self.MIN_LLM_OUTPUT,
+                metadata={"from_civitai": True},
+                readme_content="# Hello",
+            )
+        applied = mock_apply.call_args[0][1]
+        assert "modelDescription" not in applied
+
+    # -- gallery images → civitai.images ---------------------------------
+
+    @pytest.mark.asyncio
+    async def test_gallery_images_extracted_from_readme(self, processor):
+        """Widget entries in README → civitai.images."""
+        readme = """---
+widget:
+- text: "a cat"
+  output:
+    url: images/cat.png
+---
+Content
+"""
+        with (
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview", return_value=None),
+            mock.patch("py.metadata_ops.refresh_cache"),
+        ):
+            await processor.process(
+                skill_name="enrich_hf_metadata",
+                model_path="/p.safetensors",
+                llm_output=self.MIN_LLM_OUTPUT,
+                metadata={
+                    "from_civitai": False,
+                    "hf_url": "https://huggingface.co/user/repo",
+                },
+                readme_content=readme,
+            )
+        applied = mock_apply.call_args[0][1]
+        images = applied.get("civitai", {}).get("images", [])
+        assert len(images) == 1
+        assert images[0]["url"] == (
+            "https://huggingface.co/user/repo/resolve/main/images/cat.png"
+        )
+        assert images[0]["meta"]["prompt"] == "a cat"
+
+    @pytest.mark.asyncio
+    async def test_gallery_images_skipped_for_civitai_model(self, processor):
+        """Gallery images NOT extracted for CivitAI models."""
+        with (
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview", return_value=None),
+            mock.patch("py.metadata_ops.refresh_cache"),
+        ):
+            await processor.process(
+                skill_name="enrich_hf_metadata",
+                model_path="/p.safetensors",
+                llm_output=self.MIN_LLM_OUTPUT,
+                metadata={
+                    "from_civitai": True,
+                    "hf_url": "https://huggingface.co/user/repo",
+                },
+                readme_content="---\nwidget:\n- text: a\n  output:\n    url: x.png\n---\n",
+            )
+        applied = mock_apply.call_args[0][1]
+        civitai = applied.get("civitai", {})
+        assert "images" not in civitai

    # -- tags ------------------------------------------------------------

@@ -191,9 +310,9 @@ class TestEnrichHfMetadata:
    async def test_tags_merged_and_deduplicated(self, processor):
        llm = {**self.MIN_LLM_OUTPUT, "tags": ["flux", "lora", "STYLE"]}
        with (
-            mock.patch("py.agent_cli.apply_metadata_updates") as mock_apply,
-            mock.patch("py.agent_cli.download_preview", return_value=False),
-            mock.patch("py.agent_cli.refresh_cache"),
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview", return_value=False),
+            mock.patch("py.metadata_ops.refresh_cache"),
        ):
            await processor.process(
                skill_name="enrich_hf_metadata",
@@ -213,9 +332,9 @@ class TestEnrichHfMetadata:
    @pytest.mark.asyncio
    async def test_audit_fields_always_set(self, processor):
        with (
-            mock.patch("py.agent_cli.apply_metadata_updates") as mock_apply,
-            mock.patch("py.agent_cli.download_preview", return_value=False),
-            mock.patch("py.agent_cli.refresh_cache"),
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview", return_value=False),
+            mock.patch("py.metadata_ops.refresh_cache"),
        ):
            await processor.process(
                skill_name="enrich_hf_metadata",
@@ -233,11 +352,11 @@ class TestEnrichHfMetadata:
    async def test_preview_downloaded_when_url_provided(self, processor):
        llm = {**self.MIN_LLM_OUTPUT, "preview_url": "https://ex.com/img.png"}
        with (
-            mock.patch("py.agent_cli.apply_metadata_updates") as mock_apply,
-            mock.patch("py.agent_cli.download_preview") as mock_dl,
-            mock.patch("py.agent_cli.refresh_cache"),
+            mock.patch("py.metadata_ops.apply_metadata_updates") as mock_apply,
+            mock.patch("py.metadata_ops.download_preview") as mock_dl,
+            mock.patch("py.metadata_ops.refresh_cache"),
        ):
-            mock_dl.return_value = True
+            mock_dl.return_value = "/p.webp"
            result = await processor.process(
                skill_name="enrich_hf_metadata",
                model_path="/p.safetensors",
@@ -246,15 +365,17 @@ class TestEnrichHfMetadata:
            )
        assert result["preview_downloaded"] is True
        mock_dl.assert_awaited_once_with("/p.safetensors", "https://ex.com/img.png")
+        applied = mock_apply.call_args[0][1]
+        assert applied["preview_url"] == "/p.webp"

    @pytest.mark.asyncio
    async def test_preview_skipped_when_exists(self, processor):
        """If current_preview file exists on disk, skip download."""
        llm = {**self.MIN_LLM_OUTPUT, "preview_url": "https://ex.com/img.png"}
        with (
-            mock.patch("py.agent_cli.apply_metadata_updates"),
-            mock.patch("py.agent_cli.download_preview") as mock_dl,
-            mock.patch("py.agent_cli.refresh_cache"),
+            mock.patch("py.metadata_ops.apply_metadata_updates"),
+            mock.patch("py.metadata_ops.download_preview") as mock_dl,
+            mock.patch("py.metadata_ops.refresh_cache"),
            mock.patch("os.path.exists", return_value=True),
        ):
            await processor.process(
@@ -271,9 +392,9 @@ class TestEnrichHfMetadata:
    async def test_cache_refreshed_when_updates_applied(self, processor):
        llm = {**self.MIN_LLM_OUTPUT, "base_model": "Flux.1 D"}
        with (
-            mock.patch("py.agent_cli.apply_metadata_updates", return_value=["base_model"]),
-            mock.patch("py.agent_cli.download_preview", return_value=False),
-            mock.patch("py.agent_cli.refresh_cache") as mock_ref,
+            mock.patch("py.metadata_ops.apply_metadata_updates", return_value=["base_model"]),
+            mock.patch("py.metadata_ops.download_preview", return_value=False),
+            mock.patch("py.metadata_ops.refresh_cache") as mock_ref,
        ):
            await processor.process(
                skill_name="enrich_hf_metadata",
@@ -286,9 +407,9 @@ class TestEnrichHfMetadata:
    @pytest.mark.asyncio
    async def test_cache_not_refreshed_when_nothing_changed(self, processor):
        with (
-            mock.patch("py.agent_cli.apply_metadata_updates", return_value=[]),
-            mock.patch("py.agent_cli.download_preview", return_value=False),
-            mock.patch("py.agent_cli.refresh_cache") as mock_ref,
+            mock.patch("py.metadata_ops.apply_metadata_updates", return_value=[]),
+            mock.patch("py.metadata_ops.download_preview", return_value=False),
+            mock.patch("py.metadata_ops.refresh_cache") as mock_ref,
        ):
            await processor.process(
                skill_name="enrich_hf_metadata",
--- a/tests/services/test_skill_registry.py
+++ b/tests/services/test_skill_registry.py
@@ -1,4 +1,4 @@
-"""Tests for the SkillRegistry."""
+"""Tests for the SkillRegistry (``prompt.md`` discovery + prompt loading)."""

 from __future__ import annotations

@@ -30,7 +30,7 @@ class TestSkillRegistryDiscovery:

    def test_skill_has_correct_model_type_filter(self, registry):
        skill = registry.get_skill("enrich_hf_metadata")
-        # model_type_filter was removed from SKILL.md — defaults to None (all types)
+        # model_type_filter was removed from prompt.md — defaults to None (all types)
        assert skill.model_type_filter is None

    def test_skill_has_permissions(self, registry):
Author	SHA1	Message	Date
Will Miao	07fa454f72	chore(tests): stop tracking HF enrichment baseline snapshots Remove tests/enrich_hf_validation/baselines/ from git tracking (.gitignore entry + git rm --cached). These contain README snapshots from community HF repos that may include NSFW/sensitive content. Local files are preserved on disk for offline reference.	2026-07-06 01:08:25 +08:00
Will Miao	4b5aa45379	chore(tests): update bash code block tests to match preserved-bash behavior Commit `9a0d866b` changed _strip_fenced_code_blocks to preserve bash/shell code blocks (they carry CLI setup and trigger-word metadata signal). Update the two affected tests to expect bash content in the output instead of asserting it is stripped. - Rename test_bash_code_block_stripped → test_bash_code_block_preserved - Update assertions: expect 'pip install' in result	2026-07-06 01:02:04 +08:00
Will Miao	9a0d866be4	fix(agent): preserve bash/shell code blocks in readme_processor during README cleaning	2026-07-06 00:40:35 +08:00
Will Miao	308d8f71b8	feat(ui): gray out enrich-hf-llm when no hf_url, add backend fast-fail, rename labels across locales, reposition menu item	2026-07-06 00:34:18 +08:00
Will Miao	d0e8938039	fix(agent): call _format_base_models via self. to prevent NameError The bare call inside _build_prompt_context would raise NameError because class methods don't close over class-level scope. Use instead to trigger attribute lookup. Update enrich_hf_metadata prompt.md clue locations for better LLM accuracy. Update baseline report to v2 (mean 69.0, 46 models, +2.2pp vs baseline 71.1%). Consolidate README snapshots into baselines/readmes/.	2026-07-06 00:10:30 +08:00
Will Miao	13ed898b6b	chore(tests): add base_model ground truth mapping for all 46 test entries	2026-07-05 20:47:30 +08:00
Will Miao	e1dfd1c2a6	chore(tests): add two test entries and their HF README snapshots	2026-07-05 20:45:01 +08:00
Will Miao	e3e944911b	refactor(agent): extract shared scanner iteration into _find_model_entry _Previous_ _find_scanner_for_model and identify_model_type contained ~25 lines of identical scanner-iteration + path-matching logic. Factor it into _find_model_entry() so a new scanner type or edge-case fix can't drift apart.	2026-07-05 18:03:57 +08:00
Will Miao	51c0135250	refactor(agent): rename agent_cli to metadata_ops, strip temp debug logs - Rename py/agent_cli/ -> py/metadata_ops/ (module was never agent-related) - Rename tests/agent_cli/ -> tests/metadata_ops/ - Remove 9 low-value/debug INFO log points across agent_handlers.py, agent_service.py, llm_service.py, and metadata_ops/__init__.py - Keep LLM raw response at DEBUG level for diagnostics - Consolidate per-model progress + LLM result into single concise log line with basename instead of full path - Update package/class/method docstrings to clarify this is a pipeline infrastructure, not a true agent loop	2026-07-05 18:00:58 +08:00
Will Miao	7b19bbb14e	fix(agent): preserve preview URLs for collection repo models with flat heading structure Three-part fix for enrich_hf_metadata failing to extract correct preview_url from HuggingFace collection repos where models share flat heading levels: 1. _strip_standalone_images() now converts <img> tags to markdown image syntax ![alt](src) instead of stripping the URL entirely, so the LLM can still extract preview URLs. 2. _extract_section() uses a line-count-based forward window (stopping at <a id> anchors) for non-heading matches, instead of stopping at the very next heading. This prevents same-level sub-headings (# Download, # Trigger, # Sample prompt within a single model section) from truncating the window before sample images are included. 3. Post-processor preview fallback now filters gallery images to the model-specific README section before falling back to the repo-wide first image.	2026-07-05 17:05:47 +08:00
Will Miao	5494a70f40	chore(tests): commit validation dataset and baseline reports into repo Move the HF model list from ~/Documents/ into tests/enrich_hf_validation/test_data/ and commit the pipeline validation baseline artifacts (report.json, preprocessing_audit.json, README snapshots) into baselines/. Update config.py and run_validation.py defaults to use repo-relative paths via os.path.dirname(__file__) instead of ~/Documents/ hardcode. Originates from changes in `8fb00998` (validation pipeline audit).	2026-07-05 17:03:45 +08:00
Will Miao	26c9ade1c9	feat(agent): optimize base model prompt — grouped display, comprehensive mapping rules, filename inference - agent_service._format_base_models: output bullet list instead of JSON array for cleaner LLM parsing - prompt.md mapping section: replace 14-row HF→CivitAI table with compact rule set covering 14 mapping paths including new entries for HiDream-ai, OnomaAIResearch/Illustrious, ideogram-ai/ideogram, Tongyi-MAI/Z-Image-Turbo, and Wan-AI/Wan2.* - base_model extraction instruction: add guidance to infer from model filename, YAML tags, and README body text when YAML frontmatter has no explicit base_model:	2026-07-05 15:45:17 +08:00
Will Miao	87db23825f	feat(constants): add 12 new CivitAI base models from API, sync JS/Python abbreviations and categories	2026-07-05 11:44:53 +08:00
Will Miao	8fb00998a7	feat(agent): fix extract_relevant_section false positives, add validation pipeline audit - extract_relevant_section: raise token threshold >3, verify anchor sections contain basename, require 2+ heading token overlaps, skip TOC-style headings (markdown links), verify heading section size - metadata_constructor: parse repo_id,model_name.safetensors format so model_path basename matches real filename - config: replace hardcoded SUPPORTED_BASE_MODELS with dynamic init_supported_base_models() using production list_base_models() - preprocessing_auditor: new Phase 1.5 audit module — fetches each README, runs extract_relevant_section + clean_readme_for_llm, records stats and flags, saves raw READMEs for cross-reference - run_validation: integrate audit phase, add --audit-only mode, add LLM config consistency check, add ComfyUI root to sys.path - report_generator: add Preprocessing Audit and Config Warnings sections to both markdown and JSON reports	2026-07-05 11:18:48 +08:00
Will Miao	dd3aa97d0a	refactor(agent): rename md_to_html to readme_processor, fix section extraction, widget parsing, and list_base_models - Rename md_to_html.py → readme_processor.py (file no longer just HTML conversion) - _extract_section: include YAML frontmatter, use heading-level-aware forward walk (sub-headings under # are included), increase walk limit past 30 lines - _is_heading: exclude </hN> closing tags from boundary detection - _heading_level: new helper for heading-level-aware section matching - css: yield 0 for heading like closing tags, was unexpectedly caught by _is_heading - extract_gallery_images: fix YAML block scalar (text: >-) prompt extraction; use endswith instead of == to detect the block marker - _strip_widget_section: add to clean_readme_for_llm (widget text is handled by post-processor, not needed in LLM prompt) - _strip_standalone_images: keep markdown image URLs intact for LLM preview extraction (was stripping to alt text only) - list_base_models: switch from scanner-cache aggregation to CivitaiBaseModelService.get_base_models() - always returns full list - Ollama: add num_ctx=32768 to payload options so thinking models have room to both reason and produce output - Add tests/agent_cli/test_readme_processor.py: 59 tests covering extraction, cleaning, section matching, heading detection - Update existing tests for behavioral changes	2026-07-05 06:39:54 +08:00
Will Miao	905c37290f	chore: update runtime logs to use 'LLM enrichment' instead of 'Agent skill' - agent_handlers.py: 'Agent skill' -> 'LLM enrichment' in all log messages - skill_registry.py: 'agent skills' -> 'prompt-based skills' in discovery log - llm_service.py: docstring 'agent skills' -> 'LLM-based enrichment features'	2026-07-04 16:53:41 +08:00
Will Miao	f7632a47f9	feat(agent): enrich_hf_metadata with per-model progress and in-place card update - PostProcessor returns updates dict from enrich_hf_metadata - AgentService includes updated_data per model in WebSocket progress events - Convert preview_url to HTTP URL via config.get_preview_static_url() - LoraContextMenu: showEnhancedProgress + updateSingleItem per model - BulkContextMenu: same pattern, remove window.location.reload() - Guard empty updated_data and clean up callbacks on HTTP error	2026-07-04 16:50:56 +08:00
Will Miao	646f1ddfb1	refactor(agent): align 'Agent' naming to 'AI/LLM' to match current implementation - locales/en.json: 'Enrich Metadata (Agent)' -> 'Enrich Metadata (AI)' - Rename SKILL.md -> prompt.md with backward compat in skill_registry.py - JS context menu action IDs: enrich-hf-agent -> enrich-hf-llm - HTML template data-action attributes synced to match - docstring cleanup: 'agent skill' -> 'skill pipeline' / 'feature'	2026-07-04 14:06:50 +08:00
Will Miao	170c8068c5	feat(agent): enrich_hf_metadata — filename-aware section matching, preview extraction for markdown/HTML/widget, JSON salvage, instance_prompt fallback, and validation suite - extract_relevant_section(): trim README to model-filename-matching section for collection repos (download link, anchor ID, heading strategies) - _strip_standalone_images(): preserve markdown image URLs so LLM can extract preview_url; strip only HTML <img> tags - extract_simple_markdown_images(): extract civitai.images from ![]() body - extract_html_img_tags(): extract from <img src="..."> (deadman44-style) - extract_gallery_images(): fix widget parser for YAML - output: dash prefix - _is_heading: exclude </hN> closing tags from boundary detection - _extract_section: start at matching heading when match IS a heading line - _try_salvage_json(): recover truncated JSON (close braces/brackets in LIFO order, close unterminated strings, strip trailing commas) - PostProcessor: store _llm_confidence, add instance_prompt YAML fallback - agent_service: pass model_basename to prompt, trim README via extract_relevant_section before clean_readme_for_llm - Add tests/enrich_hf_validation/ suite: 100-model pipeline with progress checkpoint/resume, per-field scoring, markdown+JSON reporting - Fix evaluation_engine: read _llm_confidence (not _llm_response)	2026-07-04 12:00:15 +08:00
Will Miao	a1fd4e150b	feat(agent): optimize enrich_hf_metadata with README cleaning, Ollama native API, and expanded fields - Add clean_readme_for_llm() to strip noise from README before LLM injection - Keep widget section text (valuable tag signal) and unmarked code blocks (trigger words) - Preserve standalone image alt text instead of removing entirely - Switch Ollama to native /api/chat with think:false to fix empty content on thinking models - Extract Sample Gallery table images and deduplicate with widget images - Only strip code blocks with explicit language tags (bash) - Add notes and usage_tips fields to SKILL.md output format and post-processor - Clean up dead code, fix regex edge cases, remove double type annotation	2026-07-04 08:01:50 +08:00
Will Miao	b22f09bd1d	fix(standalone): load extra folder paths from library settings in standalone mode	2026-07-03 19:21:56 +08:00
Will Miao	4ed9169646	feat(ui): redesign AI Provider settings with provider presets and model catalog - Replace hardcoded provider list with PROVIDER_PRESETS (OpenAI, Ollama, DeepSeek, Groq, OpenRouter, OpenCode Go, Custom) - Load model lists from models.dev/api.json catalog at startup - Add Combobox vanilla JS component for model/base-URL selection - Fetch local Ollama models via live API instead of catalog - Hide API key values from frontend (boolean-only llm_api_key_set) - Add i18n translations for all 9+ locales - Update snapshot tests for new response fields	2026-07-03 16:08:51 +08:00
Will Miao	f06c60bd47	fix(agent): handle plain YAML scalar text in extract_gallery_images Widget entries with unquoted multi-line YAML scalars (e.g. "text: two samurais...\n continuation") were not parsed, leaving gallery image prompts empty. Add a third branch for plain scalar format alongside the existing quoted and >- folded block handlers.	2026-07-03 07:34:24 +08:00
Will Miao	ee8250c26c	feat(agent): extract HF widget gallery images into civitai.images with recommended dimensions - Add extract_gallery_images() to parse YAML widget entries from README frontmatter, convert relative image URLs to absolute HF URLs, and build civitai.images-compatible entries with prompt metadata - LLM now extracts recommended_width/recommended_height from README (e.g. "Best Dimensions"), used as gallery image dimensions - extract_gallery_images() accepts default_width/height parameters, falling back to 512x512 when LLM provides no recommendation - Frontend ShowcaseView.js: defensive NaN guard for 0 width/height - post_processor: consistently merge civitai updates across triggers, description, and gallery blocks with distinct variable names - SKILL.md: add recommended_width/recommended_height to output schema - 62 tests pass, including gallery extraction and dimension tests	2026-07-03 07:07:19 +08:00
Will Miao	88349bf944	feat(agent): render HF README as HTML in modelDescription, move converter to skill-local module - Add inline convert_readme_to_html() in new skill-local md_to_html.py (zero external deps, handles h1-h4/bold/italic/code/lists/tables/links/hr) - Strip YAML frontmatter, <Gallery />, badge images, HTML comments pre-conversion - Fix indented whitespace after lists being misidentified as code blocks - Fix HTML double-escaping in _inline_md (each pattern escapes independently) - LLM short_description → civitai.description ("About this version" sidebar) - raw README HTML → modelDescription (description tab, always available offline) - Pass full readme_content from agent_service to post_processor - 51 tests for converter + 4 updated/added post-processor tests	2026-07-02 23:34:52 +08:00
Will Miao	a8adcaf023	feat(agent): improve enrich_hf_metadata skill with priority_tags, preview_url fix, civitai.trainedWords - Add identify_model_type() helper to determine lora/checkpoint/embedding - Pass priority_tags from user settings to LLM prompt for tag relevance - SKILL.md: instruct LLM to exclude technical/generic HF tags, cross-reference against priority_tags; forbid ['None'] placeholder for trigger words - post_processor: fix preview_url not updated after download (now writes local .webp path to metadata); write trigger words to civitai.trainedWords instead of top-level; sanitize ['None']/'null'/'n/a' placeholder values to [] - download_preview() now returns str \| None (local path) instead of bool - Update tests for new return type and nested civitai.trainedWords structure	2026-07-02 22:14:44 +08:00