feat(ui): load provider model catalog asynchronously to avoid blocking page render

fix(llm): require api_base for custom provider without preset default
fix(agent): use status= instead of status_code in json_response calls
2026-08-11 08:20:14 -03:00 · 2026-07-06 10:02:09 +08:00 · 2026-07-06 10:02:04 +08:00 · 2026-07-06 10:02:00 +08:00 · 2026-07-06 09:13:42 +08:00 · 2026-07-06 01:08:25 +08:00
91 changed files with 14955 additions and 2439 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,10 @@ py/run_test.py
 .vscode/
 cache/
 civitai/
+stats/
+wildcards/
+backups/
+logs/
 node_modules/
 coverage/
 .coverage
@@ -32,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/README.md
+++ b/README.md
--- a/docs/agent_skills.md
+++ b/docs/agent_skills.md
@@ -0,0 +1,208 @@
+# Agent Skills System
+
+The LoRA Manager agent skills system enables LLM-powered metadata enrichment and other AI-driven tasks. Users configure their own LLM provider (BYOK), and skills are executed through right-click context menu actions.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────┐
+│              LoRA Manager Backend             │
+│                                               │
+│  ┌──────────────┐    ┌────────────────┐       │
+│  │ LLMService    │───▶│ LLM Provider   │       │
+│  │ (BYOK config, │◀───│ (OpenAI/Ollama │       │
+│  │  API calls)   │    │ /custom)       │       │
+│  └───────┬───────┘    └────────────────┘       │
+│          │                                     │
+│  ┌───────▼───────────────────────┐             │
+│  │     AgentService              │             │
+│  │  (orchestration: validate     │             │
+│  │   → LLM call → post-process   │             │
+│  │   → WebSocket broadcast)      │             │
+│  └───────┬───────────────────────┘             │
+│          │                                     │
+│  ┌───────▼───────────────────────┐             │
+│  │     SkillRegistry             │             │
+│  │  ┌─────────────────────────┐  │             │
+│  │  │ enrich_hf_metadata:     │  │             │
+│  │  │  - skill.yaml           │  │             │
+│  │  │  - prompt.md            │  │             │
+│  │  │  - handler.py           │  │             │
+│  │  └─────────────────────────┘  │             │
+│  └───────────────────────────────┘             │
+└──────────────────────────────────────────────┘
+```
+
+### Key Design Principle
+
+**Skills define *what* to do (prompt + post-processing). The AgentService handles *how* (LLM calls, validation, progress).**
+
+Skills never call the LLM directly. This keeps BYOK configuration centralized and provider-agnostic.
+
+## BYOK Configuration
+
+Users configure their LLM provider in **Settings → AI Provider**:
+
+| Setting | Description | Example |
+|---|---|---|
+| `llm_provider` | Provider type | `openai`, `ollama`, or `custom` |
+| `llm_api_key` | API key (not needed for local Ollama) | `sk-...` |
+| `llm_api_base` | Custom API base URL (empty = provider default) | `https://api.openai.com/v1` |
+| `llm_model` | Model name | `gpt-4o-mini` |
+
+Environment variable overrides: `LLM_API_KEY`, `LLM_MODEL`, `LLM_API_BASE`, `LLM_PROVIDER`.
+
+### Supported Providers
+
+- **OpenAI**: Uses `https://api.openai.com/v1` by default
+- **Ollama** (local): Uses `http://localhost:11434/v1`, no API key required
+- **Custom**: Any OpenAI-compatible endpoint (vLLM, LM Studio, etc.) — set `llm_api_base` explicitly
+
+## Available Skills
+
+### enrich_hf_metadata
+
+Enriches HuggingFace-downloaded models with metadata extracted by an LLM from the HF model card.
+
+**Entry point**: Right-click context menu → "Enrich Metadata (Agent)"
+
+**What it does**:
+1. Reads the model's `.metadata.json` to get the `hf_url`
+2. Fetches the README.md from the HuggingFace repository
+3. Sends the README + local metadata to the LLM for structured extraction
+4. Writes extracted fields to `.metadata.json`:
+   - `base_model` — only if current value is empty
+   - `trainedWords` — trigger words (LoRA only, if none exist)
+   - `modelDescription` — concise summary (if none exists)
+   - `tags` — merged with existing tags, deduplicated
+   - `metadata_source` — audit trail: `agent:enrich_hf_metadata`
+   - `llm_enriched_at` — ISO timestamp
+5. Downloads and optimizes preview image (if LLM found one in the README)
+6. Updates the scanner cache
+7. Broadcasts WebSocket progress events
+
+**Model types**: LoRA, Checkpoint, Embedding
+
+## Adding a New Skill
+
+### 1. Create the skill directory
+
+```
+py/services/agent/skills/<skill_name>/
+├── skill.yaml      # Skill metadata and schemas
+├── prompt.md       # LLM prompt template
+└── handler.py      # Pre-processing and post-processing
+```
+
+### 2. Write skill.yaml
+
+```yaml
+name: my_skill
+title: "My Skill"
+description: "What this skill does"
+llm_required: true
+model_type_filter: ["lora"]  # or null for all types
+input_schema:
+  type: object
+  properties:
+    model_paths:
+      type: array
+      items:
+        type: string
+  required:
+    - model_paths
+output_schema:
+  type: object
+  properties:
+    # ... JSON schema for LLM output
+permissions:
+  write_metadata: true
+  write_previews: false
+  network_domains:
+    - "example.com"
+```
+
+### 3. Write prompt.md
+
+Use `{{variable}}` placeholders that will be replaced with data from the `prepare` function:
+
+```markdown
+You are an expert assistant...
+
+Model URL: {{hf_url}}
+README content:
+{{readme_content}}
+
+Current metadata:
+{{current_metadata}}
+```
+
+### 4. Write handler.py
+
+```python
+async def prepare(model_path: str, input_data: dict) -> dict:
+    """Gather context for the LLM prompt. Returns variables for template rendering."""
+    return {
+        "model_path": model_path,
+        # ... other variables used in prompt.md
+    }
+
+async def post_process(context) -> dict:
+    """Apply the LLM-extracted data to the model."""
+    llm_response = context.llm_response
+    # ... write metadata, download previews, update cache
+    return {
+        "success": True,
+        "updated_fields": ["base_model", "tags"],
+        "errors": [],
+    }
+```
+
+**Important**: Use absolute imports (`from py.utils.metadata_manager import MetadataManager`) because skills are loaded via `importlib.util.spec_from_file_location`, which doesn't support relative imports.
+
+### 5. Test
+
+The skill is automatically discovered by `SkillRegistry` on startup. Test with:
+
+```python
+pytest tests/services/test_agent_service.py
+```
+
+## API Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/api/lm/agent/skills` | List available skills |
+| POST | `/api/lm/agent/execute/{skill_name}` | Execute a skill (body: `{"model_paths": [...]}`) |
+| POST | `/api/lm/agent/cancel` | Cancel running skill (stub) |
+
+## WebSocket Events
+
+| Type | When | Key fields |
+|---|---|---|
+| `agent_progress` | Skill started/processing | `skill`, `status`, `total`, `processed`, `success`, `current_path` |
+| `agent_progress` | Skill completed | `skill`, `status`, `updated_models`, `errors`, `summary` |
+| `agent_progress` | Skill error | `skill`, `status`, `error` |
+
+## Security Model
+
+Skills declare permissions in `skill.yaml`:
+- `write_metadata` — can write `.metadata.json` files
+- `write_previews` — can download/replace preview images
+- `network_domains` — allowed domains for HTTP requests
+
+These are declarative constraints checked by `AgentService`. They are defense-in-depth, not a sandbox — the Python process can technically do anything, but the contract is clear and auditable.
+
+## File Locations
+
+| Component | Path |
+|---|---|
+| LLMService | `py/services/llm_service.py` |
+| AgentService | `py/services/agent/agent_service.py` |
+| SkillRegistry | `py/services/agent/skill_registry.py` |
+| SkillDefinition | `py/services/agent/skill_definition.py` |
+| Skills directory | `py/services/agent/skills/` |
+| Route handlers | `py/routes/handlers/agent_handlers.py` |
+| Frontend manager | `static/js/managers/AgentManager.js` |
+| Settings UI | `templates/components/modals/settings_modal.html` |
+| Context menu | `templates/components/context_menu.html` |
--- a/locales/de.json
+++ b/locales/de.json
@@ -105,6 +105,7 @@
            "removeFromFavorites": "Aus Favoriten entfernen",
            "viewOnCivitai": "Auf Civitai anzeigen",
            "notAvailableFromCivitai": "Nicht auf Civitai verfügbar",
+            "viewOnHuggingFace": "Auf Hugging Face ansehen",
            "sendToWorkflow": "An ComfyUI senden (Klick: Anhängen, Shift+Klick: Ersetzen)",
            "copyLoRASyntax": "LoRA-Syntax kopieren",
            "checkpointNameCopied": "Checkpoint-Name kopiert",
@@ -656,6 +657,32 @@
            "proxyPassword": "Passwort (optional)",
            "proxyPasswordPlaceholder": "passwort",
            "proxyPasswordHelp": "Passwort für die Proxy-Authentifizierung (falls erforderlich)"
+        },
+        "aiProvider": {
+            "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.",
+            "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",
+            "apiKey": "API-Schlüssel",
+            "apiKeyHelp": "Ihr LLM-API-Schlüssel. Wird lokal gespeichert und niemals an einen anderen Server außer Ihrem gewählten LLM-Anbieter gesendet.",
+            "apiKeyPlaceholder": "sk-...",
+            "apiKeyNotSet": "Nicht festgelegt",
+            "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.",
+            "modelPlaceholder": "Modell auswählen..."
        }
    },
    "loras": {
@@ -753,7 +780,8 @@
                "completed": "Abgeschlossen: {success} verschoben, {skipped} übersprungen, {failures} fehlgeschlagen",
                "complete": "Automatische Organisation abgeschlossen",
                "error": "Fehler: {error}"
-            }
+            },
+            "enrichHfAgent": "HF-Metadaten mit KI anreichern"
        },
        "contextMenu": {
            "refreshMetadata": "Civitai-Daten aktualisieren",
@@ -777,7 +805,8 @@
            "shareRecipe": "Rezept teilen",
            "viewAllLoras": "Alle LoRAs anzeigen",
            "downloadMissingLoras": "Fehlende LoRAs herunterladen",
-            "deleteRecipe": "Rezept löschen"
+            "deleteRecipe": "Rezept löschen",
+            "enrichHfAgent": "HF-Metadaten mit KI anreichern"
        }
    },
    "recipes": {
@@ -1134,7 +1163,10 @@
            "titleWithType": "{type} von URL herunterladen",
            "civitaiUrl": "Civitai URL:",
            "placeholder": "https://civitai.com/models/...",
-            "urlHint": "Geben Sie eine CivitAI- oder CivArchive-URL pro Zeile ein. Unterstützt mehrere URLs für den Batch-Download.",
+            "urlHint": "Geben Sie eine CivitAI-, CivArchive- oder Hugging Face-URL pro Zeile ein. Unterstützt mehrere URLs für den Batch-Download.",
+            "selectHfFiles": "Datei(en) zum Herunterladen aus diesem Repository auswählen:",
+            "selectAll": "Alle auswählen",
+            "fetchingRepoFiles": "Repository-Dateien werden abgerufen...",
            "locationPreview": "Download-Speicherort Vorschau",
            "useDefaultPath": "Standardpfad verwenden",
            "useDefaultPathTooltip": "Wenn aktiviert, werden Dateien automatisch mit konfigurierten Pfadvorlagen organisiert",
@@ -1163,7 +1195,9 @@
            },
            "errors": {
                "invalidUrl": "Ungültiges Civitai URL-Format",
-                "noVersions": "Keine Versionen für dieses Modell verfügbar"
+                "noVersions": "Keine Versionen für dieses Modell verfügbar",
+                "mixedSources": "CivitAI- und Hugging Face-URLs können nicht in derselben Charge gemischt werden.",
+                "noModelFiles": "In diesem Repository wurden keine Modelldateien gefunden."
            },
            "status": {
                "preparing": "Download wird vorbereitet...",
@@ -1314,6 +1348,8 @@
                "editVersionName": "Versionsname bearbeiten",
                "viewOnCivitai": "Auf Civitai anzeigen",
                "viewOnCivitaiText": "Auf Civitai anzeigen",
+                "viewOnHuggingFace": "Auf Hugging Face ansehen",
+                "viewOnHuggingFaceText": "Auf Hugging Face ansehen",
                "viewCreatorProfile": "Ersteller-Profil anzeigen",
                "openFileLocation": "Dateispeicherort öffnen",
                "sendToWorkflow": "An ComfyUI senden",
@@ -1339,7 +1375,10 @@
                "additionalNotes": "Zusätzliche Notizen",
                "notesHint": "Enter zum Speichern, Shift+Enter für neue Zeile",
                "addNotesPlaceholder": "Fügen Sie hier Ihre Notizen hinzu...",
-                "aboutThisVersion": "Über diese Version"
+                "aboutThisVersion": "Über diese Version",
+                "baseModelSearchPlaceholder": "Basismodell suchen…",
+                "baseModelSuggested": "Vorschlag",
+                "baseModelNoMatch": "Keine passenden Basismodelle"
            },
            "notes": {
                "saved": "Notizen erfolgreich gespeichert",
@@ -2070,6 +2109,12 @@
            "moveFailed": "Failed to move item: {message}",
            "copiedToClipboard": "In die Zwischenablage kopiert",
            "downloadStarted": "Download gestartet"
+        },
+        "agent": {
+            "llmNotConfigured": "KI-Anbieter nicht konfiguriert. Aktivieren Sie ihn unter Einstellungen → KI-Anbieter.",
+            "enrichStarted": "Metadaten werden mit KI angereichert...",
+            "enrichComplete": "Metadatenanreicherung abgeschlossen: {{summary}}",
+            "enrichFailed": "Metadatenanreicherung fehlgeschlagen: {{error}}"
        }
    },
    "doctor": {
--- a/locales/en.json
+++ b/locales/en.json
--- a/locales/es.json
+++ b/locales/es.json
@@ -105,6 +105,7 @@
            "removeFromFavorites": "Eliminar de favoritos",
            "viewOnCivitai": "Ver en Civitai",
            "notAvailableFromCivitai": "No disponible en Civitai",
+            "viewOnHuggingFace": "Ver en Hugging Face",
            "sendToWorkflow": "Enviar a ComfyUI (Clic: Añadir, Shift+Clic: Reemplazar)",
            "copyLoRASyntax": "Copiar sintaxis de LoRA",
            "checkpointNameCopied": "Nombre del checkpoint copiado",
@@ -656,6 +657,32 @@
            "proxyPassword": "Contraseña (opcional)",
            "proxyPasswordPlaceholder": "contraseña",
            "proxyPasswordHelp": "Contraseña para autenticación de proxy (si es necesario)"
+        },
+        "aiProvider": {
+            "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.",
+            "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",
+            "apiKey": "Clave de API",
+            "apiKeyHelp": "Su clave de API del proveedor LLM. Se almacena localmente y nunca se envía a ningún servidor excepto a su proveedor LLM elegido.",
+            "apiKeyPlaceholder": "sk-...",
+            "apiKeyNotSet": "No configurada",
+            "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.",
+            "modelPlaceholder": "Seleccionar un modelo..."
        }
    },
    "loras": {
@@ -753,7 +780,8 @@
                "completed": "Completado: {success} movidos, {skipped} omitidos, {failures} fallidos",
                "complete": "Auto-organización completada",
                "error": "Error: {error}"
-            }
+            },
+            "enrichHfAgent": "Enriquecer metadatos HF (IA)"
        },
        "contextMenu": {
            "refreshMetadata": "Actualizar datos de Civitai",
@@ -777,7 +805,8 @@
            "shareRecipe": "Compartir receta",
            "viewAllLoras": "Ver todos los LoRAs",
            "downloadMissingLoras": "Descargar LoRAs faltantes",
-            "deleteRecipe": "Eliminar receta"
+            "deleteRecipe": "Eliminar receta",
+            "enrichHfAgent": "Enriquecer metadatos HF (IA)"
        }
    },
    "recipes": {
@@ -1134,7 +1163,10 @@
            "titleWithType": "Descargar {type} desde URL",
            "civitaiUrl": "URL de Civitai:",
            "placeholder": "https://civitai.com/models/...",
-            "urlHint": "Ingrese una URL de CivitAI o CivArchive por línea. Admite múltiples URLs para descarga por lotes.",
+            "urlHint": "Ingrese una URL de CivitAI, CivArchive o Hugging Face por línea. Admite múltiples URLs para descarga por lotes.",
+            "selectHfFiles": "Seleccione el/los archivo(s) para descargar de este repositorio:",
+            "selectAll": "Seleccionar todo",
+            "fetchingRepoFiles": "Obteniendo archivos del repositorio...",
            "locationPreview": "Vista previa de ubicación de descarga",
            "useDefaultPath": "Usar ruta predeterminada",
            "useDefaultPathTooltip": "Cuando está habilitado, los archivos se organizan automáticamente usando plantillas de rutas configuradas",
@@ -1163,7 +1195,9 @@
            },
            "errors": {
                "invalidUrl": "Formato de URL de Civitai inválido",
-                "noVersions": "No hay versiones disponibles para este modelo"
+                "noVersions": "No hay versiones disponibles para este modelo",
+                "mixedSources": "No se pueden mezclar URL de CivitAI y Hugging Face en el mismo lote.",
+                "noModelFiles": "No se encontraron archivos de modelo en este repositorio."
            },
            "status": {
                "preparing": "Preparando descarga...",
@@ -1314,6 +1348,8 @@
                "editVersionName": "Editar nombre de versión",
                "viewOnCivitai": "Ver en Civitai",
                "viewOnCivitaiText": "Ver en Civitai",
+                "viewOnHuggingFace": "Ver en Hugging Face",
+                "viewOnHuggingFaceText": "Ver en Hugging Face",
                "viewCreatorProfile": "Ver perfil del creador",
                "openFileLocation": "Abrir ubicación del archivo",
                "sendToWorkflow": "Enviar a ComfyUI",
@@ -1339,7 +1375,10 @@
                "additionalNotes": "Notas adicionales",
                "notesHint": "Presiona Enter para guardar, Shift+Enter para nueva línea",
                "addNotesPlaceholder": "Añade tus notas aquí...",
-                "aboutThisVersion": "Acerca de esta versión"
+                "aboutThisVersion": "Acerca de esta versión",
+                "baseModelSearchPlaceholder": "Buscar modelo base…",
+                "baseModelSuggested": "Sugerido",
+                "baseModelNoMatch": "No hay modelos base que coincidan"
            },
            "notes": {
                "saved": "Notas guardadas exitosamente",
@@ -2070,6 +2109,12 @@
            "moveFailed": "Failed to move item: {message}",
            "copiedToClipboard": "Copiado al portapapeles",
            "downloadStarted": "Descarga iniciada"
+        },
+        "agent": {
+            "llmNotConfigured": "Proveedor de IA no configurado. Actívelo en Configuración → Proveedor de IA.",
+            "enrichStarted": "Enriqueciendo metadatos con IA...",
+            "enrichComplete": "Enriquecimiento de metadatos completado: {{summary}}",
+            "enrichFailed": "Enriquecimiento de metadatos fallido: {{error}}"
        }
    },
    "doctor": {
--- a/locales/fr.json
+++ b/locales/fr.json
@@ -105,6 +105,7 @@
            "removeFromFavorites": "Retirer des favoris",
            "viewOnCivitai": "Voir sur Civitai",
            "notAvailableFromCivitai": "Non disponible sur Civitai",
+            "viewOnHuggingFace": "Voir sur Hugging Face",
            "sendToWorkflow": "Envoyer vers ComfyUI (Clic: Ajouter, Maj+Clic: Remplacer)",
            "copyLoRASyntax": "Copier la syntaxe LoRA",
            "checkpointNameCopied": "Nom du checkpoint copié",
@@ -656,6 +657,32 @@
            "proxyPassword": "Mot de passe (optionnel)",
            "proxyPasswordPlaceholder": "mot_de_passe",
            "proxyPasswordHelp": "Mot de passe pour l'authentification proxy (si nécessaire)"
+        },
+        "aiProvider": {
+            "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.",
+            "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",
+            "apiKey": "Clé API",
+            "apiKeyHelp": "Votre clé API du fournisseur LLM. Stockée localement, jamais envoyée à un serveur autre que votre fournisseur LLM choisi.",
+            "apiKeyPlaceholder": "sk-...",
+            "apiKeyNotSet": "Non définie",
+            "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.",
+            "modelPlaceholder": "Sélectionner un modèle..."
        }
    },
    "loras": {
@@ -753,7 +780,8 @@
                "completed": "Terminé : {success} déplacés, {skipped} ignorés, {failures} échecs",
                "complete": "Auto-organisation terminée",
                "error": "Erreur : {error}"
-            }
+            },
+            "enrichHfAgent": "Enrichir les métadonnées HF (IA)"
        },
        "contextMenu": {
            "refreshMetadata": "Actualiser les données Civitai",
@@ -777,7 +805,8 @@
            "shareRecipe": "Partager la recipe",
            "viewAllLoras": "Voir tous les LoRAs",
            "downloadMissingLoras": "Télécharger les LoRAs manquants",
-            "deleteRecipe": "Supprimer la recipe"
+            "deleteRecipe": "Supprimer la recipe",
+            "enrichHfAgent": "Enrichir les métadonnées HF (IA)"
        }
    },
    "recipes": {
@@ -1134,7 +1163,10 @@
            "titleWithType": "Télécharger {type} depuis une URL",
            "civitaiUrl": "URL Civitai :",
            "placeholder": "https://civitai.com/models/...",
-            "urlHint": "Entrez une URL CivitAI ou CivArchive par ligne. Prend en charge plusieurs URLs pour le téléchargement par lot.",
+            "urlHint": "Entrez une URL CivitAI, CivArchive ou Hugging Face par ligne. Prend en charge plusieurs URL pour le téléchargement par lot.",
+            "selectHfFiles": "Sélectionnez le(s) fichier(s) à télécharger depuis ce dépôt :",
+            "selectAll": "Tout sélectionner",
+            "fetchingRepoFiles": "Récupération des fichiers du dépôt...",
            "locationPreview": "Aperçu de l'emplacement de téléchargement",
            "useDefaultPath": "Utiliser le chemin par défaut",
            "useDefaultPathTooltip": "Lorsque activé, les fichiers sont automatiquement organisés selon les modèles de chemin configurés",
@@ -1163,7 +1195,9 @@
            },
            "errors": {
                "invalidUrl": "Format d'URL Civitai invalide",
-                "noVersions": "Aucune version disponible pour ce modèle"
+                "noVersions": "Aucune version disponible pour ce modèle",
+                "mixedSources": "Impossible de mélanger les URL CivitAI et Hugging Face dans le même lot.",
+                "noModelFiles": "Aucun fichier de modèle trouvé dans ce dépôt."
            },
            "status": {
                "preparing": "Préparation du téléchargement...",
@@ -1314,6 +1348,8 @@
                "editVersionName": "Modifier le nom de la version",
                "viewOnCivitai": "Voir sur Civitai",
                "viewOnCivitaiText": "Voir sur Civitai",
+                "viewOnHuggingFace": "Voir sur Hugging Face",
+                "viewOnHuggingFaceText": "Voir sur Hugging Face",
                "viewCreatorProfile": "Voir le profil du créateur",
                "openFileLocation": "Ouvrir l'emplacement du fichier",
                "sendToWorkflow": "Envoyer vers ComfyUI",
@@ -1339,7 +1375,10 @@
                "additionalNotes": "Notes supplémentaires",
                "notesHint": "Appuyez sur Entrée pour sauvegarder, Maj+Entrée pour nouvelle ligne",
                "addNotesPlaceholder": "Ajoutez vos notes ici...",
-                "aboutThisVersion": "À propos de cette version"
+                "aboutThisVersion": "À propos de cette version",
+                "baseModelSearchPlaceholder": "Rechercher un modèle de base…",
+                "baseModelSuggested": "Suggéré",
+                "baseModelNoMatch": "Aucun modèle de base correspondant"
            },
            "notes": {
                "saved": "Notes sauvegardées avec succès",
@@ -2070,6 +2109,12 @@
            "moveFailed": "Failed to move item: {message}",
            "copiedToClipboard": "Copié dans le presse-papiers",
            "downloadStarted": "Téléchargement démarré"
+        },
+        "agent": {
+            "llmNotConfigured": "Fournisseur d'IA non configuré. Activez-le dans Paramètres → Fournisseur d'IA.",
+            "enrichStarted": "Enrichissement des métadonnées par IA...",
+            "enrichComplete": "Enrichissement des métadonnées terminé : {{summary}}",
+            "enrichFailed": "Échec de l'enrichissement des métadonnées : {{error}}"
        }
    },
    "doctor": {
--- a/locales/he.json
+++ b/locales/he.json
@@ -105,6 +105,7 @@
            "removeFromFavorites": "הסר מהמועדפים",
            "viewOnCivitai": "הצג ב-Civitai",
            "notAvailableFromCivitai": "לא זמין מ-Civitai",
+            "viewOnHuggingFace": "צפייה ב-Hugging Face",
            "sendToWorkflow": "שלח ל-ComfyUI (לחיצה: הוסף, Shift+לחיצה: החלף)",
            "copyLoRASyntax": "העתק תחביר LoRA",
            "checkpointNameCopied": "שם Checkpoint הועתק",
@@ -656,6 +657,32 @@
            "proxyPassword": "סיסמה (אופציונלי)",
            "proxyPasswordPlaceholder": "password",
            "proxyPasswordHelp": "סיסמה לאימות מול הפרוקסי (אם נדרש)"
+        },
+        "aiProvider": {
+            "title": "ספק AI",
+            "provider": "ספק",
+            "providerHelp": "בחר את ספק ה-LLM שלך. OpenAI ו-Ollama משתמשים בנקודות קצה מוגדרות מראש. מותאם אישית מאפשר לך לציין כל נקודת קצה תואמת 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",
+            "apiKey": "מפתח API",
+            "apiKeyHelp": "מפתח ה-API של ספק ה-LLM שלך. נשמר מקומית, לעולם לא נשלח לשרת כלשהו מלבד ספק ה-LLM שבחרת.",
+            "apiKeyPlaceholder": "sk-...",
+            "apiKeyNotSet": "לא הוגדר",
+            "apiKeyConfigured": "הוגדר",
+            "apiKeySet": "הגדר",
+            "model": "מודל",
+            "modelHelp": "שם המודל לשימוש (לדוגמה deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). בדוק אצל הספק שלך אילו מודלים זמינים.",
+            "modelPlaceholder": "בחר מודל..."
        }
    },
    "loras": {
@@ -753,7 +780,8 @@
                "completed": "הושלם: {success} הועברו, {skipped} דולגו, {failures} נכשלו",
                "complete": "ארגון אוטומטי הושלם",
                "error": "שגיאה: {error}"
-            }
+            },
+            "enrichHfAgent": "העשרת HF מטא-דאטה (AI)"
        },
        "contextMenu": {
            "refreshMetadata": "רענן נתוני Civitai",
@@ -777,7 +805,8 @@
            "shareRecipe": "שתף מתכון",
            "viewAllLoras": "הצג את כל ה-LoRAs",
            "downloadMissingLoras": "הורד LoRAs חסרים",
-            "deleteRecipe": "מחק מתכון"
+            "deleteRecipe": "מחק מתכון",
+            "enrichHfAgent": "העשרת HF מטא-דאטה (AI)"
        }
    },
    "recipes": {
@@ -1134,7 +1163,10 @@
            "titleWithType": "הורד {type} מכתובת URL",
            "civitaiUrl": "כתובת URL של Civitai:",
            "placeholder": "https://civitai.com/models/...",
-            "urlHint": "יש להזין כתובת URL אחת של CivitAI או CivArchive בכל שורה. תומך במספר כתובות URL להורדה בבת אחת.",
+            "urlHint": "יש להזין כתובת URL אחת של CivitAI, CivArchive או Hugging Face בכל שורה. תומך במספר כתובות URL להורדה בקבוצה.",
+            "selectHfFiles": "בחר קבצים להורדה ממאגר זה:",
+            "selectAll": "בחר הכל",
+            "fetchingRepoFiles": "מביא קבצים מהמאגר...",
            "locationPreview": "תצוגה מקדימה של מיקום ההורדה",
            "useDefaultPath": "השתמש בנתיב ברירת מחדל",
            "useDefaultPathTooltip": "כאשר מופעל, קבצים מאורגנים אוטומטית באמצעות תבניות נתיב מוגדרות",
@@ -1163,7 +1195,9 @@
            },
            "errors": {
                "invalidUrl": "פורמט URL של Civitai לא חוקי",
-                "noVersions": "אין גרסאות זמינות למודל זה"
+                "noVersions": "אין גרסאות זמינות למודל זה",
+                "mixedSources": "לא ניתן לערבב כתובות URL של CivitAI ו-Hugging Face באותה קבוצה.",
+                "noModelFiles": "לא נמצאו קבצי מודל במאגר זה."
            },
            "status": {
                "preparing": "מכין הורדה...",
@@ -1314,6 +1348,8 @@
                "editVersionName": "ערוך שם גרסה",
                "viewOnCivitai": "הצג ב-Civitai",
                "viewOnCivitaiText": "הצג ב-Civitai",
+                "viewOnHuggingFace": "צפייה ב-Hugging Face",
+                "viewOnHuggingFaceText": "צפייה ב-Hugging Face",
                "viewCreatorProfile": "הצג פרופיל יוצר",
                "openFileLocation": "פתח מיקום קובץ",
                "sendToWorkflow": "שלח ל-ComfyUI",
@@ -1339,7 +1375,10 @@
                "additionalNotes": "הערות נוספות",
                "notesHint": "לחץ Enter לשמירה, Shift+Enter לשורה חדשה",
                "addNotesPlaceholder": "הוסף את ההערות שלך כאן...",
-                "aboutThisVersion": "אודות גרסה זו"
+                "aboutThisVersion": "אודות גרסה זו",
+                "baseModelSearchPlaceholder": "חפש מודל בסיס…",
+                "baseModelSuggested": "מוצע",
+                "baseModelNoMatch": "אין מודלי בסיס תואמים"
            },
            "notes": {
                "saved": "הערות נשמרו בהצלחה",
@@ -2070,6 +2109,12 @@
            "moveFailed": "Failed to move item: {message}",
            "copiedToClipboard": "הועתק ללוח",
            "downloadStarted": "ההורדה החלה"
+        },
+        "agent": {
+            "llmNotConfigured": "ספק AI לא הוגדר. הפעל אותו בהגדרות → ספק AI.",
+            "enrichStarted": "מעשיר מטא-דאטה באמצעות AI...",
+            "enrichComplete": "העשרת מטא-דאטה הושלמה: {{summary}}",
+            "enrichFailed": "העשרת מטא-דאטה נכשלה: {{error}}"
        }
    },
    "doctor": {
--- a/locales/ja.json
+++ b/locales/ja.json
@@ -105,6 +105,7 @@
            "removeFromFavorites": "お気に入りから削除",
            "viewOnCivitai": "Civitaiで表示",
            "notAvailableFromCivitai": "Civitaiでは利用できません",
+            "viewOnHuggingFace": "Hugging Face で見る",
            "sendToWorkflow": "ComfyUIに送信（クリック：追加、Shift+クリック：置換）",
            "copyLoRASyntax": "LoRA構文をコピー",
            "checkpointNameCopied": "checkpointの名前をコピーしました",
@@ -656,6 +657,32 @@
            "proxyPassword": "パスワード（任意）",
            "proxyPasswordPlaceholder": "パスワード",
            "proxyPasswordHelp": "プロキシ認証用のパスワード（必要な場合）"
+        },
+        "aiProvider": {
+            "title": "AIプロバイダー",
+            "provider": "プロバイダー",
+            "providerHelp": "LLMプロバイダーを選択してください。OpenAIとOllamaはプリセットのAPIエンドポイントを使用します。カスタムでは任意の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",
+            "apiKey": "APIキー",
+            "apiKeyHelp": "LLMプロバイダーのAPIキー。ローカルに保存され、選択したLLMプロバイダー以外のサーバーに送信されることはありません。",
+            "apiKeyPlaceholder": "sk-...",
+            "apiKeyNotSet": "未設定",
+            "apiKeyConfigured": "設定済み",
+            "apiKeySet": "設定",
+            "model": "モデル",
+            "modelHelp": "使用するモデル名（例：deepseek-v4-flash, gemini-2.5-flash, gemma4:12b）。プロバイダーで利用可能なモデルをご確認ください。",
+            "modelPlaceholder": "モデルを選択..."
        }
    },
    "loras": {
@@ -753,7 +780,8 @@
                "completed": "完了：{success} 移動、{skipped} スキップ、{failures} 失敗",
                "complete": "自動整理が完了しました",
                "error": "エラー：{error}"
-            }
+            },
+            "enrichHfAgent": "HF メタデータをAIで補完"
        },
        "contextMenu": {
            "refreshMetadata": "Civitaiデータを更新",
@@ -777,7 +805,8 @@
            "shareRecipe": "レシピを共有",
            "viewAllLoras": "すべてのLoRAを表示",
            "downloadMissingLoras": "不足しているLoRAをダウンロード",
-            "deleteRecipe": "レシピを削除"
+            "deleteRecipe": "レシピを削除",
+            "enrichHfAgent": "HF メタデータをAIで補完"
        }
    },
    "recipes": {
@@ -1134,7 +1163,10 @@
            "titleWithType": "URLから{type}をダウンロード",
            "civitaiUrl": "Civitai URL：",
            "placeholder": "https://civitai.com/models/...",
-            "urlHint": "1行に1つのCivitAIまたはCivArchive URLを入力してください。複数のURLを一括ダウンロードできます。",
+            "urlHint": "1行に1つのCivitAI、CivArchive、またはHugging Face URLを入力してください。複数のURLを一括ダウンロードできます。",
+            "selectHfFiles": "このリポジトリからダウンロードするファイルを選択してください：",
+            "selectAll": "すべて選択",
+            "fetchingRepoFiles": "リポジトリのファイルを取得中...",
            "locationPreview": "ダウンロード場所プレビュー",
            "useDefaultPath": "デフォルトパスを使用",
            "useDefaultPathTooltip": "有効にすると、設定されたパステンプレートを使用してファイルが自動的に整理されます",
@@ -1163,7 +1195,9 @@
            },
            "errors": {
                "invalidUrl": "無効なCivitai URL形式",
-                "noVersions": "このモデルの利用可能なバージョンがありません"
+                "noVersions": "このモデルの利用可能なバージョンがありません",
+                "mixedSources": "同じバッチ内でCivitAIとHugging FaceのURLを混在させることはできません。",
+                "noModelFiles": "このリポジトリにモデルファイルが見つかりませんでした。"
            },
            "status": {
                "preparing": "ダウンロードを準備中...",
@@ -1314,6 +1348,8 @@
                "editVersionName": "バージョン名を編集",
                "viewOnCivitai": "Civitaiで表示",
                "viewOnCivitaiText": "Civitaiで表示",
+                "viewOnHuggingFace": "Hugging Face で見る",
+                "viewOnHuggingFaceText": "Hugging Face で見る",
                "viewCreatorProfile": "作成者プロフィールを表示",
                "openFileLocation": "ファイルの場所を開く",
                "sendToWorkflow": "ComfyUI に送信",
@@ -1339,7 +1375,10 @@
                "additionalNotes": "追加メモ",
                "notesHint": "Enterで保存、Shift+Enterで改行",
                "addNotesPlaceholder": "メモをここに追加...",
-                "aboutThisVersion": "このバージョンについて"
+                "aboutThisVersion": "このバージョンについて",
+                "baseModelSearchPlaceholder": "ベースモデルを検索…",
+                "baseModelSuggested": "おすすめ",
+                "baseModelNoMatch": "該当するベースモデルがありません"
            },
            "notes": {
                "saved": "メモが正常に保存されました",
@@ -2070,6 +2109,12 @@
            "moveFailed": "Failed to move item: {message}",
            "copiedToClipboard": "クリップボードにコピーしました",
            "downloadStarted": "ダウンロードを開始しました"
+        },
+        "agent": {
+            "llmNotConfigured": "AIプロバイダーが設定されていません。設定 → AIプロバイダーで有効にしてください。",
+            "enrichStarted": "AIでメタデータを補完中...",
+            "enrichComplete": "メタデータの補完が完了しました：{{summary}}",
+            "enrichFailed": "メタデータの補完に失敗しました：{{error}}"
        }
    },
    "doctor": {
--- a/locales/ko.json
+++ b/locales/ko.json
@@ -105,6 +105,7 @@
            "removeFromFavorites": "즐겨찾기에서 제거",
            "viewOnCivitai": "Civitai에서 보기",
            "notAvailableFromCivitai": "Civitai에서 사용할 수 없음",
+            "viewOnHuggingFace": "Hugging Face에서 보기",
            "sendToWorkflow": "ComfyUI로 전송 (클릭: 추가, Shift+클릭: 교체)",
            "copyLoRASyntax": "LoRA 문법 복사",
            "checkpointNameCopied": "Checkpoint 이름 복사됨",
@@ -656,6 +657,32 @@
            "proxyPassword": "비밀번호 (선택사항)",
            "proxyPasswordPlaceholder": "password",
            "proxyPasswordHelp": "프록시 인증에 필요한 비밀번호 (필요한 경우)"
+        },
+        "aiProvider": {
+            "title": "AI 제공자",
+            "provider": "제공자",
+            "providerHelp": "LLM 제공자를 선택하세요. OpenAI와 Ollama는 사전 설정된 API 엔드포인트를 사용합니다. 사용자 정의를 선택하면 모든 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",
+            "apiKey": "API 키",
+            "apiKeyHelp": "LLM 제공자의 API 키입니다. 로컬에 저장되며 선택한 LLM 제공자 외의 서버로 전송되지 않습니다.",
+            "apiKeyPlaceholder": "sk-...",
+            "apiKeyNotSet": "설정되지 않음",
+            "apiKeyConfigured": "설정됨",
+            "apiKeySet": "설정",
+            "model": "모델",
+            "modelHelp": "사용할 모델 이름 (예: deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). 제공자에서 사용 가능한 모델을 확인하세요.",
+            "modelPlaceholder": "모델 선택..."
        }
    },
    "loras": {
@@ -753,7 +780,8 @@
                "completed": "완료: {success}개 이동, {skipped}개 건너뜀, {failures}개 실패",
                "complete": "자동 정리 완료",
                "error": "오류: {error}"
-            }
+            },
+            "enrichHfAgent": "HF AI로 메타데이터 보강"
        },
        "contextMenu": {
            "refreshMetadata": "Civitai 데이터 새로고침",
@@ -777,7 +805,8 @@
            "shareRecipe": "레시피 공유",
            "viewAllLoras": "모든 LoRA 보기",
            "downloadMissingLoras": "누락된 LoRA 다운로드",
-            "deleteRecipe": "레시피 삭제"
+            "deleteRecipe": "레시피 삭제",
+            "enrichHfAgent": "HF AI로 메타데이터 보강"
        }
    },
    "recipes": {
@@ -1134,7 +1163,10 @@
            "titleWithType": "URL에서 {type} 다운로드",
            "civitaiUrl": "Civitai URL:",
            "placeholder": "https://civitai.com/models/...",
-            "urlHint": "한 줄에 하나의 CivitAI 또는 CivArchive URL을 입력하세요. 여러 URL을 일괄 다운로드할 수 있습니다.",
+            "urlHint": "한 줄에 하나의 CivitAI, CivArchive 또는 Hugging Face URL을 입력하세요. 여러 URL을 일괄 다운로드할 수 있습니다.",
+            "selectHfFiles": "이 저장소에서 다운로드할 파일을 선택하세요：",
+            "selectAll": "모두 선택",
+            "fetchingRepoFiles": "저장소 파일을 가져오는 중...",
            "locationPreview": "다운로드 위치 미리보기",
            "useDefaultPath": "기본 경로 사용",
            "useDefaultPathTooltip": "활성화하면 구성된 경로 템플릿을 사용하여 파일이 자동으로 정리됩니다",
@@ -1163,7 +1195,9 @@
            },
            "errors": {
                "invalidUrl": "잘못된 Civitai URL 형식",
-                "noVersions": "이 모델에 사용 가능한 버전이 없습니다"
+                "noVersions": "이 모델에 사용 가능한 버전이 없습니다",
+                "mixedSources": "동일한 배치에서 CivitAI와 Hugging Face URL을 혼합할 수 없습니다.",
+                "noModelFiles": "이 저장소에서 모델 파일을 찾을 수 없습니다."
            },
            "status": {
                "preparing": "다운로드 준비 중...",
@@ -1314,6 +1348,8 @@
                "editVersionName": "버전명 편집",
                "viewOnCivitai": "Civitai에서 보기",
                "viewOnCivitaiText": "Civitai에서 보기",
+                "viewOnHuggingFace": "Hugging Face에서 보기",
+                "viewOnHuggingFaceText": "Hugging Face에서 보기",
                "viewCreatorProfile": "제작자 프로필 보기",
                "openFileLocation": "파일 위치 열기",
                "sendToWorkflow": "ComfyUI로 보내기",
@@ -1339,7 +1375,10 @@
                "additionalNotes": "추가 메모",
                "notesHint": "Enter로 저장, Shift+Enter로 줄바꿈",
                "addNotesPlaceholder": "메모를 여기에 추가하세요...",
-                "aboutThisVersion": "이 버전에 대해"
+                "aboutThisVersion": "이 버전에 대해",
+                "baseModelSearchPlaceholder": "베이스 모델 검색…",
+                "baseModelSuggested": "추천",
+                "baseModelNoMatch": "일치하는 베이스 모델 없음"
            },
            "notes": {
                "saved": "메모가 성공적으로 저장됨",
@@ -2070,6 +2109,12 @@
            "moveFailed": "Failed to move item: {message}",
            "copiedToClipboard": "클립보드에 복사됨",
            "downloadStarted": "다운로드 시작됨"
+        },
+        "agent": {
+            "llmNotConfigured": "AI 제공자가 설정되지 않았습니다. 설정 → AI 제공자에서 활성화하세요.",
+            "enrichStarted": "AI로 메타데이터 보강 중...",
+            "enrichComplete": "메타데이터 보강 완료: {{summary}}",
+            "enrichFailed": "메타데이터 보강 실패: {{error}}"
        }
    },
    "doctor": {
--- a/locales/ru.json
+++ b/locales/ru.json
@@ -105,6 +105,7 @@
            "removeFromFavorites": "Удалить из избранного",
            "viewOnCivitai": "Посмотреть на Civitai",
            "notAvailableFromCivitai": "Недоступно на Civitai",
+            "viewOnHuggingFace": "Открыть Hugging Face",
            "sendToWorkflow": "Отправить в ComfyUI (Клик: Добавить, Shift+Клик: Заменить)",
            "copyLoRASyntax": "Копировать синтаксис LoRA",
            "checkpointNameCopied": "Имя checkpoint скопировано",
@@ -656,6 +657,32 @@
            "proxyPassword": "Пароль (необязательно)",
            "proxyPasswordPlaceholder": "пароль",
            "proxyPasswordHelp": "Пароль для аутентификации на прокси (если требуется)"
+        },
+        "aiProvider": {
+            "title": "Поставщик ИИ",
+            "provider": "Поставщик",
+            "providerHelp": "Выберите поставщика LLM. OpenAI и Ollama используют предустановленные API-эндпоинты. Пользовательский позволяет указать любой совместимый с 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",
+            "apiKey": "API-ключ",
+            "apiKeyHelp": "Ваш API-ключ поставщика LLM. Хранится локально и никогда не отправляется на другие серверы, кроме выбранного поставщика LLM.",
+            "apiKeyPlaceholder": "sk-...",
+            "apiKeyNotSet": "Не задан",
+            "apiKeyConfigured": "Настроен",
+            "apiKeySet": "Настроить",
+            "model": "Модель",
+            "modelHelp": "Имя модели для использования (например, deepseek-v4-flash, gemini-2.5-flash, gemma4:12b). Проверьте доступные модели у вашего поставщика.",
+            "modelPlaceholder": "Выберите модель..."
        }
    },
    "loras": {
@@ -753,7 +780,8 @@
                "completed": "Завершено: {success} перемещено, {skipped} пропущено, {failures} не удалось",
                "complete": "Автоматическая организация завершена",
                "error": "Ошибка: {error}"
-            }
+            },
+            "enrichHfAgent": "Обогатить HF метаданные (ИИ)"
        },
        "contextMenu": {
            "refreshMetadata": "Обновить данные Civitai",
@@ -777,7 +805,8 @@
            "shareRecipe": "Поделиться рецептом",
            "viewAllLoras": "Посмотреть все LoRAs",
            "downloadMissingLoras": "Загрузить отсутствующие LoRAs",
-            "deleteRecipe": "Удалить рецепт"
+            "deleteRecipe": "Удалить рецепт",
+            "enrichHfAgent": "Обогатить HF метаданные (ИИ)"
        }
    },
    "recipes": {
@@ -1134,7 +1163,10 @@
            "titleWithType": "Скачать {type} по URL",
            "civitaiUrl": "Civitai URL:",
            "placeholder": "https://civitai.com/models/...",
-            "urlHint": "Введите один URL CivitAI или CivArchive в каждой строке. Поддерживается пакетная загрузка нескольких URL.",
+            "urlHint": "Введите один URL CivitAI, CivArchive или Hugging Face в каждой строке. Поддерживает несколько URL для пакетной загрузки.",
+            "selectHfFiles": "Выберите файл(ы) для загрузки из этого репозитория：",
+            "selectAll": "Выбрать все",
+            "fetchingRepoFiles": "Получение файлов репозитория...",
            "locationPreview": "Предпросмотр места загрузки",
            "useDefaultPath": "Использовать путь по умолчанию",
            "useDefaultPathTooltip": "При включении файлы автоматически организуются с использованием настроенных шаблонов путей",
@@ -1163,7 +1195,9 @@
            },
            "errors": {
                "invalidUrl": "Неверный формат URL Civitai",
-                "noVersions": "Нет доступных версий для этой модели"
+                "noVersions": "Нет доступных версий для этой модели",
+                "mixedSources": "Нельзя смешивать URL-адреса CivitAI и Hugging Face в одном пакете.",
+                "noModelFiles": "В этом репозитории не найдено файлов моделей."
            },
            "status": {
                "preparing": "Подготовка загрузки...",
@@ -1314,6 +1348,8 @@
                "editVersionName": "Редактировать название версии",
                "viewOnCivitai": "Посмотреть на Civitai",
                "viewOnCivitaiText": "Посмотреть на Civitai",
+                "viewOnHuggingFace": "Открыть Hugging Face",
+                "viewOnHuggingFaceText": "Открыть Hugging Face",
                "viewCreatorProfile": "Посмотреть профиль создателя",
                "openFileLocation": "Открыть расположение файла",
                "sendToWorkflow": "Отправить в ComfyUI",
@@ -1339,7 +1375,10 @@
                "additionalNotes": "Дополнительные заметки",
                "notesHint": "Нажмите Enter для сохранения, Shift+Enter для новой строки",
                "addNotesPlaceholder": "Добавьте ваши заметки здесь...",
-                "aboutThisVersion": "Об этой версии"
+                "aboutThisVersion": "Об этой версии",
+                "baseModelSearchPlaceholder": "Поиск базовой модели…",
+                "baseModelSuggested": "Предполагаемые",
+                "baseModelNoMatch": "Нет подходящих базовых моделей"
            },
            "notes": {
                "saved": "Заметки успешно сохранены",
@@ -2070,6 +2109,12 @@
            "moveFailed": "Failed to move item: {message}",
            "copiedToClipboard": "Скопировано в буфер обмена",
            "downloadStarted": "Загрузка начата"
+        },
+        "agent": {
+            "llmNotConfigured": "Поставщик ИИ не настроен. Включите его в Настройки → Поставщик ИИ.",
+            "enrichStarted": "Обогащение метаданных с помощью ИИ...",
+            "enrichComplete": "Обогащение метаданных завершено: {{summary}}",
+            "enrichFailed": "Ошибка обогащения метаданных: {{error}}"
        }
    },
    "doctor": {
--- a/locales/zh-CN.json
+++ b/locales/zh-CN.json
@@ -105,6 +105,7 @@
            "removeFromFavorites": "从收藏移除",
            "viewOnCivitai": "在 Civitai 查看",
            "notAvailableFromCivitai": "Civitai 上不可用",
+            "viewOnHuggingFace": "在 Hugging Face 查看",
            "sendToWorkflow": "发送到 ComfyUI（点击：追加，Shift+点击：替换）",
            "copyLoRASyntax": "复制 LoRA 语法",
            "checkpointNameCopied": "检查点名称已复制",
@@ -656,6 +657,32 @@
            "proxyPassword": "密码 (可选)",
            "proxyPasswordPlaceholder": "密码",
            "proxyPasswordHelp": "代理认证的密码 (如果需要)"
+        },
+        "aiProvider": {
+            "title": "AI 提供商",
+            "provider": "提供商",
+            "providerHelp": "选择您的 LLM 提供商。OpenAI 和 Ollama 使用预设的 API 端点。自定义允许您指定任何兼容 OpenAI 的端点。",
+            "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-...",
+            "apiKeyNotSet": "未设置",
+            "apiKeyConfigured": "已配置",
+            "apiKeySet": "设置",
+            "model": "模型",
+            "modelHelp": "要使用的模型。从下拉框选择（从提供商获取）或输入自定义模型名称。",
+            "modelPlaceholder": "选择一个模型..."
        }
    },
    "loras": {
@@ -753,7 +780,8 @@
                "completed": "完成：已移动 {success} 个，跳过 {skipped} 个，失败 {failures} 个",
                "complete": "自动整理已完成",
                "error": "错误：{error}"
-            }
+            },
+            "enrichHfAgent": "AI HF 元数据增强"
        },
        "contextMenu": {
            "refreshMetadata": "刷新 Civitai 数据",
@@ -777,7 +805,8 @@
            "shareRecipe": "分享配方",
            "viewAllLoras": "查看所有 LoRA",
            "downloadMissingLoras": "下载缺失的 LoRA",
-            "deleteRecipe": "删除配方"
+            "deleteRecipe": "删除配方",
+            "enrichHfAgent": "AI HF 元数据增强"
        }
    },
    "recipes": {
@@ -1134,7 +1163,10 @@
            "titleWithType": "从 URL 下载 {type}",
            "civitaiUrl": "Civitai URL:",
            "placeholder": "https://civitai.com/models/...",
-            "urlHint": "每行输入一个 CivitAI 或 CivArchive URL。支持批量下载多个 URL。",
+            "urlHint": "每行输入一个 CivitAI、CivArchive 或 Hugging Face URL。支持批量下载多个 URL。",
+            "selectHfFiles": "选择从此仓库下载的文件：",
+            "selectAll": "全选",
+            "fetchingRepoFiles": "正在获取仓库文件...",
            "locationPreview": "下载位置预览",
            "useDefaultPath": "使用默认路径",
            "useDefaultPathTooltip": "启用后，文件将自动按配置的路径模板进行整理",
@@ -1163,7 +1195,9 @@
            },
            "errors": {
                "invalidUrl": "无效的 Civitai URL 格式",
-                "noVersions": "此模型没有可用版本"
+                "noVersions": "此模型没有可用版本",
+                "mixedSources": "无法在同一批次中混合使用 CivitAI 和 Hugging Face URL。",
+                "noModelFiles": "在此仓库中未找到模型文件。"
            },
            "status": {
                "preparing": "正在准备下载...",
@@ -1314,6 +1348,8 @@
                "editVersionName": "编辑版本名称",
                "viewOnCivitai": "在 Civitai 查看",
                "viewOnCivitaiText": "在 Civitai 查看",
+                "viewOnHuggingFace": "在 Hugging Face 查看",
+                "viewOnHuggingFaceText": "在 Hugging Face 查看",
                "viewCreatorProfile": "查看创作者主页",
                "openFileLocation": "打开文件位置",
                "sendToWorkflow": "发送到 ComfyUI",
@@ -1339,7 +1375,10 @@
                "additionalNotes": "附加备注",
                "notesHint": "回车保存，Shift+回车换行",
                "addNotesPlaceholder": "在此添加你的备注...",
-                "aboutThisVersion": "关于此版本"
+                "aboutThisVersion": "关于此版本",
+                "baseModelSearchPlaceholder": "搜索基础模型…",
+                "baseModelSuggested": "推荐",
+                "baseModelNoMatch": "没有匹配的基础模型"
            },
            "notes": {
                "saved": "备注保存成功",
@@ -2070,6 +2109,12 @@
            "moveFailed": "Failed to move item: {message}",
            "copiedToClipboard": "已复制到剪贴板",
            "downloadStarted": "下载已开始"
+        },
+        "agent": {
+            "llmNotConfigured": "AI 提供商未配置。请在 设置 → AI 提供商 中进行配置。",
+            "enrichStarted": "正在使用 AI 增强元数据...",
+            "enrichComplete": "元数据增强完成：{{summary}}",
+            "enrichFailed": "元数据增强失败：{{error}}"
        }
    },
    "doctor": {
--- a/locales/zh-TW.json
+++ b/locales/zh-TW.json
@@ -105,6 +105,7 @@
            "removeFromFavorites": "移除收藏",
            "viewOnCivitai": "在 Civitai 查看",
            "notAvailableFromCivitai": "Civitai 不提供",
+            "viewOnHuggingFace": "在 Hugging Face 查看",
            "sendToWorkflow": "傳送到 ComfyUI（點擊：附加，Shift+點擊：取代）",
            "copyLoRASyntax": "複製 LoRA 語法",
            "checkpointNameCopied": "Checkpoint 名稱已複製",
@@ -656,6 +657,32 @@
            "proxyPassword": "密碼（選填）",
            "proxyPasswordPlaceholder": "password",
            "proxyPasswordHelp": "代理驗證所需的密碼（如有需要）"
+        },
+        "aiProvider": {
+            "title": "AI 提供者",
+            "provider": "提供者",
+            "providerHelp": "選擇您的 LLM 提供者。OpenAI 和 Ollama 使用預設 API 端點。自訂允許您指定任何相容 OpenAI 的端點。",
+            "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": "[TODO: Translate] sk-...",
+            "apiKeyNotSet": "未設定",
+            "apiKeyConfigured": "已設定",
+            "apiKeySet": "設定",
+            "model": "模型",
+            "modelHelp": "要使用的模型。從下拉選單選擇（從提供者取得）或輸入自訂模型名稱。",
+            "modelPlaceholder": "選擇一個模型..."
        }
    },
    "loras": {
@@ -753,7 +780,8 @@
                "completed": "完成：已移動 {success}，已略過 {skipped}，失敗 {failures}",
                "complete": "自動整理完成",
                "error": "錯誤：{error}"
-            }
+            },
+            "enrichHfAgent": "AI HF 中繼資料增強"
        },
        "contextMenu": {
            "refreshMetadata": "刷新 Civitai 資料",
@@ -777,7 +805,8 @@
            "shareRecipe": "分享配方",
            "viewAllLoras": "檢視全部 LoRA",
            "downloadMissingLoras": "下載缺少的 LoRA",
-            "deleteRecipe": "刪除配方"
+            "deleteRecipe": "刪除配方",
+            "enrichHfAgent": "AI HF 中繼資料增強"
        }
    },
    "recipes": {
@@ -1134,7 +1163,10 @@
            "titleWithType": "從網址下載 {type}",
            "civitaiUrl": "Civitai 網址：",
            "placeholder": "https://civitai.com/models/...",
-            "urlHint": "每行輸入一個 CivitAI 或 CivArchive URL。支援批量下載多個 URL。",
+            "urlHint": "每行輸入一個 CivitAI、CivArchive 或 Hugging Face URL。支援批量下載多個 URL。",
+            "selectHfFiles": "選擇從此倉庫下載的檔案：",
+            "selectAll": "全選",
+            "fetchingRepoFiles": "正在獲取倉庫檔案...",
            "locationPreview": "下載位置預覽",
            "useDefaultPath": "使用預設路徑",
            "useDefaultPathTooltip": "啟用後，檔案將依照設定的路徑範本自動整理",
@@ -1163,7 +1195,9 @@
            },
            "errors": {
                "invalidUrl": "Civitai 網址格式無效",
-                "noVersions": "此模型無可用版本"
+                "noVersions": "此模型無可用版本",
+                "mixedSources": "無法在同一批次中混合使用 CivitAI 和 Hugging Face URL。",
+                "noModelFiles": "在此倉庫中未找到模型檔案。"
            },
            "status": {
                "preparing": "準備下載中...",
@@ -1314,6 +1348,8 @@
                "editVersionName": "編輯版本名稱",
                "viewOnCivitai": "在 Civitai 查看",
                "viewOnCivitaiText": "在 Civitai 查看",
+                "viewOnHuggingFace": "在 Hugging Face 查看",
+                "viewOnHuggingFaceText": "在 Hugging Face 查看",
                "viewCreatorProfile": "查看創作者個人檔案",
                "openFileLocation": "開啟檔案位置",
                "sendToWorkflow": "傳送到 ComfyUI",
@@ -1339,7 +1375,10 @@
                "additionalNotes": "附加備註",
                "notesHint": "按 Enter 儲存，Shift+Enter 換行",
                "addNotesPlaceholder": "在此新增備註...",
-                "aboutThisVersion": "關於此版本"
+                "aboutThisVersion": "關於此版本",
+                "baseModelSearchPlaceholder": "搜尋基礎模型…",
+                "baseModelSuggested": "推薦",
+                "baseModelNoMatch": "沒有符合的基礎模型"
            },
            "notes": {
                "saved": "備註已儲存",
@@ -2070,6 +2109,12 @@
            "moveFailed": "Failed to move item: {message}",
            "copiedToClipboard": "已複製到剪貼簿",
            "downloadStarted": "下載已開始"
+        },
+        "agent": {
+            "llmNotConfigured": "AI 提供者尚未設定。請在 設定 → AI 提供者 中進行設定。",
+            "enrichStarted": "正在使用 AI 增強中繼資料...",
+            "enrichComplete": "中繼資料增強完成：{{summary}}",
+            "enrichFailed": "中繼資料增強失敗：{{error}}"
        }
    },
    "doctor": {
--- a/py/config.py
+++ b/py/config.py
@@ -8,6 +8,8 @@ from typing import Any, Dict, Iterable, List, Mapping, Optional, Set, Tuple
 import logging
 import json
 import urllib.parse
+import sys as _sys
+import types as _types
 import time

 from .utils.cache_paths import CacheType, get_cache_file_path, get_legacy_cache_paths
@@ -175,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()
@@ -191,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
@@ -1380,4 +1381,20 @@ class Config:


 # Global config instance
-config = Config()
+# NOTE: Guard against re-import.  When ServiceRegistry.get_lora_scanner() triggers
+# a fresh import of lora_scanner → config, we must NOT re-execute Config.__init__()
+# (which re-scans all roots, re-registers libraries, etc.).
+#
+# Strategy: store the config instance in a dedicated sentinel module
+# ('_lm_config_cache') that is NEVER removed from sys.modules (its key does
+# NOT start with 'py.'), so it survives re-imports of py.* modules.
+_CONFIG_SENTINEL = "_lm_config_cache"
+if _CONFIG_SENTINEL in _sys.modules:
+    # Re-import: reuse the existing singleton from the sentinel.
+    config: Config = _sys.modules[_CONFIG_SENTINEL].config  # type: ignore[valid-type]
+else:
+    config: Config = Config()
+    # Register the sentinel so re-imports of py.config find us.
+    _sentinel_mod = _types.ModuleType(_CONFIG_SENTINEL)
+    _sentinel_mod.config = config
+    _sys.modules[_CONFIG_SENTINEL] = _sentinel_mod
--- 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()
@@ -445,5 +449,12 @@ class LoraManager:
                    scanner.cancel_task()
                    logger.debug("LoRA Manager: Cancelled %s", name)

+            # Close shared aiohttp sessions to avoid "Unclosed client session" warnings
+            try:
+                from py.routes.handlers.hf_handlers import close_hf_api_session
+                await close_hf_api_session()
+            except Exception as exc:
+                logger.debug("Error closing HF API session: %s", exc)
+
        except Exception as e:
            logger.error(f"Error during cleanup: {e}", exc_info=True)
--- a/py/metadata_ops/init.py
+++ b/py/metadata_ops/init.py
@@ -0,0 +1,233 @@
+"""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
+``py`` package, so ``sys.modules`` caching works normally and there is no
+risk of double import or circular dependencies.
+
+Usage (in-process, primary)::
+
+    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.metadata_ops base-models list
+    python -m py.metadata_ops metadata read /path/to/model.safetensors
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+SCANNER_TYPE_MAP: dict[str, str] = {
+    "get_lora_scanner": "lora",
+    "get_checkpoint_scanner": "checkpoint",
+    "get_embedding_scanner": "embedding",
+}
+
+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 SCANNER_GETTER_NAMES:
+        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:
+                if os.path.normpath(entry.get("file_path", "")) == normalized:
+                    return scanner, entry, getter_name
+        except Exception as exc:
+            logger.debug(
+                "Scanner %s check failed for %s: %s",
+                getter_name, model_path, exc,
+            )
+    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"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+async def list_base_models(limit: int = 0) -> List[str]:
+    """Return all valid CivitAI base model names.
+
+    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.civitai_base_model_service import (
+        CivitaiBaseModelService,
+    )
+
+    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 names[:limit]
+    return names
+
+
+async def read_metadata(model_path: str) -> Dict[str, Any]:
+    """Load the full metadata payload for *model_path* from disk.
+
+    Returns an empty dict when the metadata file does not exist or cannot
+    be parsed — never raises.
+    """
+    from ..utils.metadata_manager import MetadataManager
+
+    try:
+        return await MetadataManager.load_metadata_payload(model_path) or {}
+    except Exception as exc:
+        logger.warning("read_metadata failed for %s: %s", model_path, exc)
+        return {}
+
+
+async def apply_metadata_updates(
+    model_path: str,
+    updates: Dict[str, Any],
+) -> List[str]:
+    """Merge *updates* into the model's on-disk metadata and persist.
+
+    Returns the list of field names that actually changed.
+    """
+    from ..utils.metadata_manager import MetadataManager
+
+    metadata = await read_metadata(model_path)
+    updated_fields: List[str] = []
+    for key, value in updates.items():
+        old = metadata.get(key)
+        if old != value:
+            metadata[key] = value
+            updated_fields.append(key)
+    if updated_fields:
+        await MetadataManager.save_metadata(model_path, metadata)
+    return updated_fields
+
+
+async def download_preview(
+    model_path: str,
+    url: str,
+    *,
+    target_width: int = 480,
+    quality: int = 85,
+) -> 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 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 None
+
+    base_name = os.path.splitext(os.path.basename(model_path))[0]
+    preview_dir = os.path.dirname(model_path)
+    output_path = os.path.join(preview_dir, base_name + ".webp")
+
+    downloader = await get_downloader()
+
+    # Try in-memory download + optimise first
+    success, content, _headers = await downloader.download_to_memory(
+        url, use_auth=False,
+    )
+    if success and content:
+        try:
+            optimized_data, _ = ExifUtils.optimize_image(
+                image_data=content,
+                target_width=target_width,
+                format="webp",
+                quality=quality,
+                preserve_metadata=False,
+            )
+            with open(output_path, "wb") as f:
+                f.write(optimized_data)
+            return output_path
+        except Exception as exc:
+            logger.warning("Preview optimisation failed, saving raw: %s", exc)
+            # Fall through to raw save
+
+    # Fallback: download directly to file
+    try:
+        ok, _ = await downloader.download_file(url, output_path, use_auth=False)
+        if ok:
+            return output_path
+    except Exception as exc:
+        logger.warning("Preview fallback download failed for %s: %s", model_path, exc)
+
+    return None
+
+
+async def refresh_cache(model_path: str) -> bool:
+    """Invalidate and reload the scanner cache entry for *model_path*.
+
+    Returns ``True`` when the model was found and the cache was refreshed.
+    """
+    scanner, entry = await _find_scanner_for_model(model_path)
+    if scanner is None:
+        logger.warning("refresh_cache: no scanner found for %s", model_path)
+        return False
+    try:
+        metadata = await read_metadata(model_path)
+        if not metadata:
+            logger.warning("refresh_cache: no metadata for %s", model_path)
+            return False
+        await scanner.update_single_model_cache(model_path, model_path, metadata)
+        return True
+    except Exception as exc:
+        logger.warning("refresh_cache failed for %s: %s", model_path, exc)
+        return False
--- a/py/metadata_ops/main.py
+++ b/py/metadata_ops/main.py
@@ -0,0 +1,113 @@
+"""Subprocess entry point for ``metadata_ops`` (debugging / external use).
+
+Usage::
+
+    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
+
+import argparse
+import asyncio
+import json
+import sys
+from typing import Any, Dict, List
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="lmcli", description="LoRA Manager Agent CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # base-models list
+    base_models = sub.add_parser("base-models", aliases=["bm"])
+    base_models_cmds = base_models.add_subparsers(dest="subcommand", required=True)
+    base_models_list = base_models_cmds.add_parser("list")
+    base_models_list.add_argument(
+        "--limit", type=int, default=0, help="Max number of models (0 = all)"
+    )
+
+    # metadata read
+    meta = sub.add_parser("metadata", aliases=["md"])
+    meta_cmds = meta.add_subparsers(dest="subcommand", required=True)
+    meta_read = meta_cmds.add_parser("read")
+    meta_read.add_argument("path", type=str, help="Model file path")
+
+    # metadata update
+    meta_update = meta_cmds.add_parser("update")
+    meta_update.add_argument("path", type=str, help="Model file path")
+    meta_update.add_argument(
+        "--json",
+        type=str,
+        required=True,
+        help='JSON object of fields to update, e.g. \'{"base_model": "SDXL 1.0"}\'',
+    )
+
+    # preview download
+    prev = sub.add_parser("preview", aliases=["pv"])
+    prev_cmds = prev.add_subparsers(dest="subcommand", required=True)
+    prev_dl = prev_cmds.add_parser("download")
+    prev_dl.add_argument("path", type=str, help="Model file path")
+    prev_dl.add_argument("--url", type=str, required=True, help="Preview image URL")
+
+    # cache refresh
+    cache = sub.add_parser("cache")
+    cache_cmds = cache.add_subparsers(dest="subcommand", required=True)
+    cache_refresh = cache_cmds.add_parser("refresh")
+    cache_refresh.add_argument("path", type=str, help="Model file path")
+
+    return parser
+
+
+async def _run(args: argparse.Namespace) -> Any:
+    from . import (  # lazy import so startup is fast
+        list_base_models,
+        read_metadata,
+        apply_metadata_updates,
+        download_preview,
+        refresh_cache,
+    )
+
+    cmd = args.command
+    sub = args.subcommand
+
+    if cmd in ("base-models", "bm") and sub == "list":
+        return await list_base_models(limit=args.limit)
+
+    if cmd in ("metadata", "md") and sub == "read":
+        return await read_metadata(args.path)
+
+    if cmd in ("metadata", "md") and sub == "update":
+        updates: Dict[str, Any] = json.loads(args.json)
+        return await apply_metadata_updates(args.path, updates)
+
+    if cmd in ("preview", "pv") and sub == "download":
+        return await download_preview(args.path, args.url)
+
+    if cmd == "cache" and sub == "refresh":
+        return await refresh_cache(args.path)
+
+    raise ValueError(f"Unknown command: {cmd} {sub}")
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    result = asyncio.run(_run(args))
+    # Always print as JSON so callers can parse reliably
+    if isinstance(result, list):
+        for item in result:
+            print(item)
+    elif isinstance(result, dict):
+        json.dump(result, sys.stdout, ensure_ascii=False, indent=2)
+        print()
+    else:
+        print(json.dumps(result))
+
+
+if __name__ == "__main__":
+    main()
--- a/py/routes/handlers/agent_handlers.py
+++ b/py/routes/handlers/agent_handlers.py
@@ -0,0 +1,165 @@
+"""HTTP route handlers for agent skill endpoints.
+
+These handlers expose the :class:`AgentService` via HTTP, allowing the
+frontend to list available skills and execute them on selected models.
+Progress is reported via WebSocket broadcast.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict
+
+from aiohttp import web
+
+from ...services.agent import AgentService, AgentProgressReporter
+from ...services.llm_service import LLMNotConfiguredError
+
+logger = logging.getLogger(__name__)
+
+
+class AgentHandler:
+    """HTTP handler for agent skill operations."""
+
+    def __init__(self, agent_service: AgentService | None = None) -> None:
+        self._agent_service = agent_service
+
+    async def _ensure_service(self) -> AgentService:
+        if self._agent_service is None:
+            self._agent_service = await AgentService.get_instance()
+        return self._agent_service
+
+    # ------------------------------------------------------------------
+    # GET /api/lm/agent/skills
+    # ------------------------------------------------------------------
+
+    async def get_agent_skills(self, request: web.Request) -> web.Response:
+        """Return a list of available agent skills."""
+
+        service = await self._ensure_service()
+        skills = await service.list_skills()
+        return web.json_response({"skills": skills})
+
+    # ------------------------------------------------------------------
+    # POST /api/lm/agent/execute/{skill_name}
+    # ------------------------------------------------------------------
+
+    async def execute_agent_skill(self, request: web.Request) -> web.Response:
+        """Execute an agent skill on the provided model paths.
+
+        Request body::
+
+            {"model_paths": ["/path/to/model1.safetensors", ...], "options": {}}
+
+        Returns immediately with a task ID.  Execution runs in the
+        background; progress and completion are pushed via WebSocket
+        events of type ``agent_progress``.
+        """
+
+        skill_name = request.match_info.get("skill_name", "")
+        if not skill_name:
+            return web.json_response(
+                {"error": "Skill name is required"}, status=400
+            )
+
+        try:
+            body = await request.json()
+        except Exception:
+            return web.json_response(
+                {"error": "Invalid JSON body"}, status=400
+            )
+
+        model_paths = body.get("model_paths", [])
+        if not model_paths or not isinstance(model_paths, list):
+            return web.json_response(
+                {"error": "model_paths must be a non-empty array"},
+                status=400,
+            )
+
+        service = await self._ensure_service()
+
+        # Validate LLM configuration early for skills that need it
+        # (fail fast rather than after starting background work)
+        try:
+            from ...services.llm_service import LLMService
+
+            llm = await LLMService.get_instance()
+            if not llm.is_configured():
+                return web.json_response(
+                    {
+                        "error": "LLM provider is not configured. "
+                        "Enable it in Settings → AI Provider.",
+                    },
+                    status=400,
+                )
+        except Exception as exc:
+            logger.error("Failed to check LLM configuration: %s", exc)
+
+        # Launch execution in the background
+        progress_reporter = AgentProgressReporter()
+        logger.info(
+            "LLM enrichment '%s' starting for %d model(s)",
+            skill_name, len(model_paths),
+        )
+
+        async def _run() -> None:
+            try:
+                result = await service.execute_skill(
+                    skill_name=skill_name,
+                    input_data={"model_paths": model_paths},
+                    progress_callback=progress_reporter,
+                )
+                logger.info(
+                    "LLM enrichment '%s' finished: success=%s, summary='%s', errors=%s",
+                    skill_name, result.success, result.summary, result.errors,
+                )
+            except LLMNotConfiguredError as exc:
+                logger.warning("LLM enrichment '%s' not configured: %s", skill_name, exc)
+                await progress_reporter.on_progress(
+                    {
+                        "type": "agent_progress",
+                        "skill": skill_name,
+                        "status": "error",
+                        "error": str(exc),
+                    }
+                )
+            except Exception as exc:
+                logger.error("LLM enrichment '%s' failed: %s", skill_name, exc, exc_info=True)
+                await progress_reporter.on_progress(
+                    {
+                        "type": "agent_progress",
+                        "skill": skill_name,
+                        "status": "error",
+                        "error": str(exc),
+                    }
+                )
+
+        # Fire and forget — progress comes via WebSocket
+        asyncio.create_task(_run())
+
+        return web.json_response(
+            {
+                "status": "started",
+                "skill": skill_name,
+                "model_count": len(model_paths),
+            }
+        )
+
+    # ------------------------------------------------------------------
+    # POST /api/lm/agent/cancel
+    # ------------------------------------------------------------------
+
+    async def cancel_agent_skill(self, request: web.Request) -> web.Response:
+        """Cancel a running agent skill.
+
+        NOTE: Cancellation is a stub for now — the AgentService processes
+        models sequentially and does not yet support mid-execution
+        cancellation.  This endpoint exists for API completeness.
+        """
+
+        # TODO: implement cooperative cancellation in AgentService
+        return web.json_response(
+            {"status": "acknowledged", "note": "Cancellation not yet implemented"},
+            status=200,
+        )
--- a/py/routes/handlers/hf_handlers.py
+++ b/py/routes/handlers/hf_handlers.py
@@ -0,0 +1,417 @@
+"""Handlers for Hugging Face model listing and download.
+
+Minimal MVP implementation — uses direct HTTP to the HF API for file
+listing and the project's existing aiohttp-based Downloader for
+downloading.  No huggingface_hub dependency required.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from typing import Any
+
+import aiohttp
+from aiohttp import web
+
+from ...config import config
+from ...services.downloader import (
+    DownloadProgress,
+    get_downloader,
+)
+from ...services.aria2_downloader import Aria2Downloader
+from ...services.settings_manager import get_settings_manager
+from ...services.service_registry import ServiceRegistry
+from ...services.websocket_manager import ws_manager
+from ...utils.constants import MODEL_FILE_EXTENSIONS
+from ...utils.metadata_manager import MetadataManager
+from ...utils.models import LoraMetadata, CheckpointMetadata, EmbeddingMetadata
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_MODEL_CLASS = LoraMetadata
+_DEFAULT_SCANNER_GETTER = "get_lora_scanner"
+
+# Shared aiohttp session for HF API calls (created on first use)
+_hf_api_session: aiohttp.ClientSession | None = None
+
+
+async def _get_hf_api_session() -> aiohttp.ClientSession:
+    """Get or create the shared aiohttp session for HF API calls."""
+    global _hf_api_session  # needed because we reassign the module-level name
+    if _hf_api_session is None or _hf_api_session.closed:
+        _hf_api_session = aiohttp.ClientSession(
+            headers={"User-Agent": "ComfyUI-LoRA-Manager/1.0"},
+            timeout=aiohttp.ClientTimeout(total=30),
+        )
+    return _hf_api_session
+
+
+async def close_hf_api_session() -> None:
+    """Close the shared HF API session, if it was ever created."""
+    global _hf_api_session
+    if _hf_api_session is not None and not _hf_api_session.closed:
+        await _hf_api_session.close()
+        _hf_api_session = None
+
+
+def _infer_model_type(model_root: str) -> tuple[Any, str]:
+    """Determine model class and scanner by matching ``model_root`` against the
+    configured root paths for each model type (from ``Config``).
+
+    The ``model_root`` value comes from the frontend's model-root dropdown,
+    which is populated from the current page's scanner roots.  By checking
+    which scanner's root list it belongs to, we avoid fragile heuristics
+    like substring-matching path names.
+    """
+    norm = os.path.normpath(model_root).replace(os.sep, "/")
+
+    # LoRA roots
+    for p in (config.loras_roots or []) + (config.extra_loras_roots or []):
+        if os.path.normpath(p).replace(os.sep, "/") == norm:
+            return LoraMetadata, "get_lora_scanner"
+
+    # Checkpoint / UNet roots
+    for p in (
+        (config.checkpoints_roots or [])
+        + (config.extra_checkpoints_roots or [])
+        + (config.unet_roots or [])
+        + (config.extra_unet_roots or [])
+    ):
+        if os.path.normpath(p).replace(os.sep, "/") == norm:
+            return CheckpointMetadata, "get_checkpoint_scanner"
+
+    # Embedding roots
+    for p in (config.embeddings_roots or []) + (config.extra_embeddings_roots or []):
+        if os.path.normpath(p).replace(os.sep, "/") == norm:
+            return EmbeddingMetadata, "get_embedding_scanner"
+
+    # Fallback — should not happen in normal use
+    logger.warning(
+        "Could not determine model type for root '%s'; defaulting to LoRA",
+        model_root,
+    )
+    return _DEFAULT_MODEL_CLASS, _DEFAULT_SCANNER_GETTER
+
+
+async def _save_hf_metadata(dest_path: str, repo: str, model_root: str) -> None:
+    """Create a proper .metadata.json and add the model to the scanner cache.
+
+    Uses ``MetadataManager.create_default_metadata()`` which computes the
+    SHA256 hash, extracts safetensors header metadata (base_model), and
+    produces a fully-populated ``LoraMetadata`` (or ``CheckpointMetadata`` /
+    ``EmbeddingMetadata``) object.  We then overlay HF-specific fields and
+    register the model in the in-memory scanner cache so it appears
+    immediately without a full filesystem walk.
+    """
+    try:
+        hf_url = f"https://huggingface.co/{repo}"
+        model_class, scanner_getter_name = _infer_model_type(model_root)
+
+        # 1. Create proper metadata (computes SHA256, reads safetensors headers)
+        metadata = await MetadataManager.create_default_metadata(
+            dest_path, model_class=model_class
+        )
+        if metadata is None:
+            logger.warning("create_default_metadata returned None for %s", dest_path)
+            return
+
+        # 2. Overlay HF-specific fields
+        metadata._unknown_fields["hf_url"] = hf_url
+        metadata.from_civitai = False  # HF models are not from CivitAI
+
+        # 3. Save metadata atomically
+        await MetadataManager.save_metadata(dest_path, metadata)
+        logger.info("Saved HF metadata (with hf_url) for %s", dest_path)
+
+        # 4. Determine relative folder path for cache
+        #    model_root is an absolute path; dest_path is under it
+        folder = ""
+        if os.path.isabs(model_root) and dest_path.startswith(model_root):
+            rel = os.path.relpath(os.path.dirname(dest_path), model_root)
+            folder = rel.replace(os.sep, "/") if rel != "." else ""
+
+        # 5. Add to scanner cache (same as CivitAI's _execute_download does)
+        scanner_getter = getattr(ServiceRegistry, scanner_getter_name, None)
+        if scanner_getter is not None:
+            scanner = await scanner_getter()
+            if scanner is not None:
+                metadata_dict = metadata.to_dict()
+                metadata_dict["hf_url"] = hf_url
+                await scanner.add_model_to_cache(metadata_dict, folder)
+                logger.info("Added %s to scanner cache (folder=%s)", dest_path, folder)
+
+    except Exception as exc:
+        logger.warning("Failed to save HF metadata for %s: %s", dest_path, exc)
+
+
+class HfHandler:
+    """Handle Hugging Face model browsing and download."""
+
+    async def get_hf_repo_files(self, request: web.Request) -> web.Response:
+        """List model-weight files from a HF repo with real file sizes.
+
+        Uses the HF tree API endpoint which returns accurate file sizes
+        (including LFS-tracked files), unlike the model info endpoint.
+        """
+        repo = request.query.get("repo", "").strip()
+        if not repo or "/" not in repo:
+            return web.json_response(
+                {"error": "Missing or invalid 'repo' parameter (expected user/repo)"},
+                status=400,
+            )
+
+        url = f"https://huggingface.co/api/models/{repo}/tree/main"
+
+        try:
+            session = await _get_hf_api_session()
+            async with session.get(url) as resp:
+                if resp.status == 404:
+                    return web.json_response(
+                        {"error": f"Repo '{repo}' not found"}, status=404
+                    )
+                if resp.status != 200:
+                    text = await resp.text()
+                    return web.json_response(
+                        {"error": f"HF API error {resp.status}: {text[:200]}"},
+                        status=resp.status,
+                    )
+                tree: list[dict[str, Any]] = await resp.json()
+        except Exception as exc:
+            logger.error("Failed to fetch HF repo files: %s", exc)
+            return web.json_response({"error": str(exc)}, status=502)
+
+        files: list[dict[str, Any]] = []
+        for entry in tree:
+            path: str = entry.get("path", "")
+            ext = os.path.splitext(path)[1].lower()
+            if ext not in MODEL_FILE_EXTENSIONS:
+                continue
+            size = entry.get("size", 0) or 0
+            if size == 0 and "lfs" in entry:
+                size = entry["lfs"].get("size", 0) or 0
+            files.append({
+                "filename": path,
+                "size": size,
+            })
+
+        files.sort(key=lambda f: f["size"], reverse=True)
+        return web.json_response(files)
+
+    async def download_hf_model(self, request: web.Request) -> web.Response:
+        """Download a single file from Hugging Face into the model directory.
+
+        POST JSON body::
+
+            {
+              "repo": "dx8152/Flux2-Klein-9B-Consistency",
+              "filename": "Flux2-Klein-9B-consistency-V2.safetensors",
+              "revision": "main",
+              "model_root": "loras",
+              "relative_path": "",
+              "use_default_paths": false,
+              "download_id": "optional-batch-id"
+            }
+
+        If ``download_id`` is provided, real-time progress (bytes, speed,
+        percentage) is broadcast via the WebSocket progress system, matching
+        the CivitAI download experience.
+
+        Respects the ``download_backend`` setting (``aria2`` or ``default``).
+        """
+        try:
+            payload: dict[str, Any] = await request.json()
+        except json.JSONDecodeError:
+            return web.json_response({"error": "Invalid JSON"}, status=400)
+
+        repo = (payload.get("repo") or "").strip()
+        filename = (payload.get("filename") or "").strip()
+        revision = (payload.get("revision") or "main").strip()
+        model_root = (payload.get("model_root") or "").strip()
+        relative_path = (payload.get("relative_path") or "").strip()
+        use_default_paths = bool(payload.get("use_default_paths", False))
+        download_id: str | None = payload.get("download_id")
+
+        logger.info(
+            "download_hf_model: repo=%s file=%s root=%s download_id=%s",
+            repo, filename, model_root, download_id,
+        )
+
+        if not repo or not filename:
+            return web.json_response(
+                {"error": "Missing required fields: 'repo' and 'filename'"}, status=400
+            )
+
+        # Validate repo format — must be user/repo_name
+        if repo.count("/") != 1 or not re.match(r"^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$", repo):
+            return web.json_response({"error": f"Invalid repo format: {repo}"}, status=400)
+        author, repo_name = repo.split("/", 1)
+        if ".." in (author, repo_name) or "." in (author, repo_name):
+            return web.json_response({"error": f"Invalid repo format: {repo}"}, status=400)
+
+        # Validate filename — must not contain path separators or ..
+        if "/" in filename or "\\" in filename or ".." in filename:
+            return web.json_response({"error": "Invalid filename"}, status=400)
+
+        # Validate relative_path — must not be absolute or escape base directory
+        if relative_path:
+            if os.path.isabs(relative_path):
+                return web.json_response({"error": "relative_path must not be absolute"}, status=400)
+            if ".." in relative_path.split("/") or "\\" in relative_path:
+                return web.json_response({"error": "Invalid relative_path"}, status=400)
+
+        # Validate model_root — must not contain path traversal
+        if not os.path.isabs(model_root):
+            # For relative model_root, check it doesn't escape
+            resolved_model_root = os.path.realpath(
+                os.path.join(os.getcwd(), "models", model_root)
+            )
+        else:
+            resolved_model_root = os.path.realpath(model_root)
+
+        # Verify model_root is within a configured scanner root
+        allowed_roots = set()
+        for root_list in (
+            config.loras_roots or [],
+            config.extra_loras_roots or [],
+            config.checkpoints_roots or [],
+            config.extra_checkpoints_roots or [],
+            config.unet_roots or [],
+            config.extra_unet_roots or [],
+            config.embeddings_roots or [],
+            config.extra_embeddings_roots or [],
+        ):
+            for r in root_list:
+                allowed_roots.add(os.path.realpath(r))
+
+        if not any(resolved_model_root == root or resolved_model_root.startswith(root + os.sep) for root in allowed_roots):
+            logger.warning("Invalid model_root rejected: %s", model_root)
+            return web.json_response({"error": f"Invalid model_root: {model_root}"}, status=400)
+
+        base_dir = resolved_model_root
+
+        if use_default_paths:
+            target_dir = os.path.join(base_dir, "huggingface", author, repo_name)
+        elif relative_path:
+            target_dir = os.path.join(base_dir, relative_path)
+        else:
+            target_dir = base_dir
+
+        os.makedirs(target_dir, exist_ok=True)
+        dest_path = os.path.join(target_dir, filename)
+
+        # Resolve symlinks and check for path traversal escape
+        real_dest = os.path.realpath(dest_path)
+        real_base = os.path.realpath(target_dir)
+        if not real_dest.startswith(real_base + os.sep):
+            logger.warning("Path traversal blocked: %s -> %s", dest_path, real_dest)
+            return web.json_response({"error": "Path traversal detected"}, status=400)
+
+        # Check if already exists (simple skip)
+        if os.path.exists(dest_path) and os.path.getsize(dest_path) > 0:
+            logger.info("download_hf_model: file already exists, skipping — %s", dest_path)
+            return web.json_response({
+                "success": True,
+                "message": f"File already exists: {dest_path}",
+                "path": dest_path,
+            })
+
+        # Build HF resolve URL
+        resolve_url = (
+            f"https://huggingface.co/{repo}/resolve/{revision}/{filename}"
+        )
+
+        # Set up progress callback if download_id is provided
+        progress_callback = None
+        if download_id:
+
+            async def _progress_callback(
+                progress: float | DownloadProgress,
+                snapshot: DownloadProgress | None = None,
+            ) -> None:
+                percent = 0.0
+                metrics = snapshot if isinstance(snapshot, DownloadProgress) else None
+
+                if isinstance(progress, DownloadProgress):
+                    percent = progress.percent_complete
+                    metrics = progress
+                elif isinstance(snapshot, DownloadProgress):
+                    percent = snapshot.percent_complete
+                else:
+                    percent = float(progress)
+
+                broadcast: dict[str, Any] = {
+                    "status": "progress",
+                    "progress": round(percent),
+                }
+                if metrics:
+                    broadcast["bytes_downloaded"] = metrics.bytes_downloaded
+                    broadcast["total_bytes"] = metrics.total_bytes
+                    broadcast["bytes_per_second"] = metrics.bytes_per_second
+
+                await ws_manager.broadcast_download_progress(download_id, broadcast)
+
+            progress_callback = _progress_callback
+
+        # Respect download backend setting (aria2 vs default)
+        download_backend = (
+            get_settings_manager().get("download_backend", "default")
+        )
+
+        if download_backend == "aria2":
+            aria2 = await Aria2Downloader.get_instance()
+            aid = download_id or f"hf_{repo}_{filename}"
+            try:
+                hf_success, hf_result = await aria2.download_file(
+                    url=resolve_url,
+                    save_path=dest_path,
+                    download_id=aid,
+                    progress_callback=progress_callback,
+                )
+                if hf_success:
+                    await _save_hf_metadata(dest_path, repo, model_root)
+                    return web.json_response({
+                        "success": True,
+                        "message": f"Downloaded to {dest_path}",
+                        "path": dest_path,
+                    })
+                else:
+                    return web.json_response(
+                        {"success": False, "error": hf_result or "aria2 download failed"},
+                        status=500,
+                    )
+            except Exception as exc:
+                logger.error("HF download (aria2) failed: %s", exc)
+                return web.json_response(
+                    {"success": False, "error": str(exc)}, status=500
+                )
+
+        # Default: use built-in aiohttp Downloader
+        downloader = await get_downloader()
+        try:
+            success, result = await downloader.download_file(
+                url=resolve_url,
+                save_path=dest_path,
+                use_auth=False,
+                allow_resume=True,
+                progress_callback=progress_callback,
+            )
+            if success:
+                await _save_hf_metadata(dest_path, repo, model_root)
+                return web.json_response({
+                    "success": True,
+                    "message": f"Downloaded to {result}",
+                    "path": result,
+                })
+            else:
+                return web.json_response(
+                    {"success": False, "error": result or "Download failed"},
+                    status=500,
+                )
+        except Exception as exc:
+            logger.error("HF download failed: %s", exc)
+            return web.json_response(
+                {"success": False, "error": str(exc)}, status=500
+            )
--- a/py/routes/handlers/misc_handlers.py
+++ b/py/routes/handlers/misc_handlers.py
@@ -38,6 +38,12 @@ 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 (
+    PROVIDER_PRESETS,
+    fetch_ollama_models,
+    get_all_provider_models,
+    get_provider_model_ids,
+)
 from ...services.cache_health_monitor import CacheHealthMonitor, CacheHealthStatus
 from ...utils.models import BaseModelMetadata
 from ...utils.constants import (
@@ -48,6 +54,8 @@ from ...utils.constants import (
    SUPPORTED_MEDIA_EXTENSIONS,
    VALID_LORA_TYPES,
 )
+from .hf_handlers import HfHandler
+from .agent_handlers import AgentHandler
 from ...utils.civitai_utils import rewrite_preview_url
 from ...utils.example_images_paths import (
    find_non_compliant_items_in_example_images_root,
@@ -1398,8 +1406,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",
        }
    )

@@ -1457,6 +1466,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
@@ -1561,6 +1572,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}"
@@ -1583,6 +1630,20 @@ class SettingsHandler:
    def _is_dedicated_example_images_folder(self, folder_path: str) -> bool:
        return is_valid_example_images_root(folder_path)

+    async def get_provider_models(self, request: web.Request) -> web.Response:
+        """Return the model catalog for all preset providers.
+
+        This endpoint is called asynchronously by the settings UI so that
+        page rendering never blocks on the remote model catalog fetch.
+        """
+        catalog_provider_ids = [p for p in PROVIDER_PRESETS if p != "custom"]
+        try:
+            provider_models = await get_all_provider_models(catalog_provider_ids)
+            return web.json_response({"success": True, "models": provider_models})
+        except Exception as exc:
+            logger.warning("Failed to fetch provider models: %s", exc)
+            return web.json_response({"success": False, "models": {}, "error": str(exc)})
+

 class UsageStatsHandler:
    def __init__(self, usage_stats_factory: UsageStatsFactory = UsageStats) -> None:
@@ -3315,6 +3376,8 @@ class MiscHandlerSet:
        doctor: DoctorHandler,
        example_workflows: ExampleWorkflowsHandler,
        base_model: BaseModelHandlerSet,
+        hf_handler: HfHandler | None = None,
+        agent_handler: AgentHandler | None = None,
    ) -> None:
        self.health = health
        self.settings = settings
@@ -3333,6 +3396,8 @@ class MiscHandlerSet:
        self.doctor = doctor
        self.example_workflows = example_workflows
        self.base_model = base_model
+        self.hf_handler = hf_handler
+        self.agent_handler = agent_handler

    def to_route_mapping(
        self,
@@ -3348,6 +3413,8 @@ 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,
+            "get_provider_models": self.settings.get_provider_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,
@@ -3378,6 +3445,13 @@ class MiscHandlerSet:
            "get_supporters": self.supporters.get_supporters,
            "get_example_workflows": self.example_workflows.get_example_workflows,
            "get_example_workflow": self.example_workflows.get_example_workflow,
+            # Hugging Face handlers
+            "get_hf_repo_files": self.hf_handler.get_hf_repo_files,
+            "download_hf_model": self.hf_handler.download_hf_model,
+            # Agent skill handlers
+            "get_agent_skills": self.agent_handler.get_agent_skills,
+            "execute_agent_skill": self.agent_handler.execute_agent_skill,
+            "cancel_agent_skill": self.agent_handler.cancel_agent_skill,
            # Base model handlers
            "get_base_models": self.base_model.get_base_models,
            "refresh_base_models": self.base_model.refresh_base_models,
--- a/py/routes/handlers/model_handlers.py
+++ b/py/routes/handlers/model_handlers.py
@@ -154,6 +154,14 @@ class ModelPageView:
                )
                self._template_env._i18n_filter_added = True  # type: ignore[attr-defined]

+            from ...services.llm_service import PROVIDER_PRESETS
+
+            # Provider presets are embedded directly (local, no await needed).
+            # Provider model catalogs are fetched asynchronously by the
+            # frontend via GET /api/lm/llm/provider-models so page rendering
+            # never blocks on the remote model catalog (which can take up to
+            # 30s on cold cache).
+
            template_context = {
                "is_initializing": is_initializing,
                "settings": self._settings,
@@ -161,6 +169,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": "{}",
            }

            if not is_initializing:
@@ -203,11 +213,17 @@ class ModelListingHandler:
            result = await self._service.get_paginated_data(**params)

            format_start = time.perf_counter()
+            formatted_raw = [
+                await self._service.format_response(entry)
+                for entry in result["items"]
+            ]
+            # Filter out None entries returned for corrupted cache rows (issue #730).
+            # Note: "total" intentionally remains the pre-filter count to reflect
+            # the true number of models in the cache; corrupted entries are rare
+            # and adjusting total would cause pagination drift on every page.
+            formatted_items = [item for item in formatted_raw if item is not None]
            formatted_result = {
-                "items": [
-                    await self._service.format_response(item)
-                    for item in result["items"]
-                ],
+                "items": formatted_items,
                "total": result["total"],
                "page": result["page"],
                "page_size": result["page_size"],
@@ -238,11 +254,15 @@ class ModelListingHandler:
            result = await self._service.get_excluded_paginated_data(**params)

            format_start = time.perf_counter()
+            formatted_raw = [
+                await self._service.format_response(entry)
+                for entry in result["items"]
+            ]
+            # Filter out None entries returned for corrupted cache rows (issue #730).
+            # "total" stays at the pre-filter count; see get_models for rationale.
+            formatted_items = [item for item in formatted_raw if item is not None]
            formatted_result = {
-                "items": [
-                    await self._service.format_response(item)
-                    for item in result["items"]
-                ],
+                "items": formatted_items,
                "total": result["total"],
                "page": result["page"],
                "page_size": result["page_size"],
@@ -533,8 +553,13 @@ class ModelManagementHandler:
            if not success:
                return web.json_response({"success": False, "error": error})

-            formatted_metadata = await self._service.format_response(model_data)
-            return web.json_response({"success": True, "metadata": formatted_metadata})
+            formatted = await self._service.format_response(model_data)
+            if formatted is None:
+                return web.json_response(
+                    {"success": False, "error": "Model entry is corrupted (missing file_path)"},
+                    status=500,
+                )
+            return web.json_response({"success": True, "metadata": formatted})
        except Exception as exc:
            if is_expected_offline_error(str(exc)):
                return web.json_response(
@@ -1091,10 +1116,12 @@ class ModelQueryHandler:
                # Sort: originals first, copies last
                sorted_models = self._sort_duplicate_group(filtered)

-                # Format response
+                # Format response, filtering out corrupted entries (issue #730)
                group = {"hash": sha256, "models": []}
                for model in sorted_models:
-                    group["models"].append(await self._service.format_response(model))
+                    formatted = await self._service.format_response(model)
+                    if formatted is not None:
+                        group["models"].append(formatted)

                # Only include groups with 2+ models after filtering
                if len(group["models"]) > 1:
@@ -1211,9 +1238,9 @@ class ModelQueryHandler:
                        (m for m in cache.raw_data if m["file_path"] == path), None
                    )
                    if model:
-                        group["models"].append(
-                            await self._service.format_response(model)
-                        )
+                        formatted = await self._service.format_response(model)
+                        if formatted is not None:
+                            group["models"].append(formatted)
                hash_val = self._service.scanner.get_hash_by_filename(filename)
                if hash_val:
                    main_path = self._service.get_path_by_hash(hash_val)
@@ -1223,9 +1250,9 @@ class ModelQueryHandler:
                            None,
                        )
                        if main_model:
-                            group["models"].insert(
-                                0, await self._service.format_response(main_model)
-                            )
+                            formatted = await self._service.format_response(main_model)
+                            if formatted is not None:
+                                group["models"].insert(0, formatted)
                if group["models"]:
                    result.append(group)
            return web.json_response(
--- a/py/routes/misc_route_registrar.py
+++ b/py/routes/misc_route_registrar.py
@@ -22,6 +22,8 @@ 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/llm/provider-models", "get_provider_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"),
@@ -94,6 +96,23 @@ MISC_ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
    RouteDefinition(
        "GET", "/api/lm/delete-model-version", "delete_model_version"
    ),
+    # Hugging Face model endpoints
+    RouteDefinition(
+        "GET", "/api/lm/hf-repo-files", "get_hf_repo_files"
+    ),
+    RouteDefinition(
+        "POST", "/api/lm/download-hf-model", "download_hf_model"
+    ),
+    # Agent skill endpoints
+    RouteDefinition(
+        "GET", "/api/lm/agent/skills", "get_agent_skills"
+    ),
+    RouteDefinition(
+        "POST", "/api/lm/agent/execute/{skill_name}", "execute_agent_skill"
+    ),
+    RouteDefinition(
+        "POST", "/api/lm/agent/cancel", "cancel_agent_skill"
+    ),
 )


--- a/py/routes/misc_routes.py
+++ b/py/routes/misc_routes.py
@@ -39,6 +39,8 @@ from .handlers.misc_handlers import (
    build_service_registry_adapter,
 )
 from .handlers.base_model_handlers import BaseModelHandlerSet
+from .handlers.hf_handlers import HfHandler
+from .handlers.agent_handlers import AgentHandler
 from .misc_route_registrar import MiscRouteRegistrar

 logger = logging.getLogger(__name__)
@@ -136,6 +138,8 @@ class MiscRoutes:
        doctor = DoctorHandler(settings_service=self._settings)
        example_workflows = ExampleWorkflowsHandler()
        base_model = BaseModelHandlerSet()
+        hf_handler = HfHandler()
+        agent_handler = AgentHandler()

        return self._handler_set_factory(
            health=health,
@@ -155,6 +159,8 @@ class MiscRoutes:
            doctor=doctor,
            example_workflows=example_workflows,
            base_model=base_model,
+            hf_handler=hf_handler,
+            agent_handler=agent_handler,
        )


--- a/py/routes/update_routes.py
+++ b/py/routes/update_routes.py
@@ -16,6 +16,27 @@ logger = logging.getLogger(__name__)

 NETWORK_EXCEPTIONS = (ClientError, OSError, asyncio.TimeoutError)

+# User-managed directories that live inside the plugin folder (portable
+# mode) and must survive a Git-based update. ``git clean -fd`` would
+# otherwise delete them because they are untracked and, in released tags,
+# not listed in ``.gitignore``. ``-e`` excludes a path from cleaning
+# regardless of whether it is ignored.
+_PRESERVE_DIRS = ('settings.json', 'civitai', 'wildcards', 'backups', 'stats', 'logs', 'cache', 'model_cache')
+
+
+def _clean_excludes() -> List[str]:
+    """Build the ``-e`` arguments for ``git clean`` from :data:`_PRESERVE_DIRS`."""
+    excludes: List[str] = []
+    for name in _PRESERVE_DIRS:
+        excludes.append('-e')
+        excludes.append(name)
+        # For directories, also exclude nested matches explicitly
+        # (``-e dir`` alone matches the dir entry; ``-e dir/**`` guards
+        # contents under all git versions as defense-in-depth).
+        excludes.append('-e')
+        excludes.append(f'{name}/**')
+    return excludes
+

 class UpdateRoutes:
    """Routes for handling plugin update checks"""
@@ -365,6 +386,8 @@ class UpdateRoutes:
            )
            return False, ""

+        clean_excludes = _clean_excludes()
+
        try:
            # Open the Git repository
            repo = git.Repo(plugin_root)
@@ -376,8 +399,9 @@ class UpdateRoutes:
            if nightly:
                # Reset to discard any local changes
                repo.git.reset('--hard')
-                # Clean untracked files
-                repo.git.clean('-fd')
+                # Clean untracked files, but preserve user-managed directories
+                # (wildcards, backups, stats, civitai, caches, settings.json).
+                repo.git.clean('-fd', *clean_excludes)
                
                # Switch to main branch and pull latest
                main_branch = 'main'
@@ -394,8 +418,9 @@ class UpdateRoutes:
            else:
                # Reset to discard any local changes
                repo.git.reset('--hard')
-                # Clean untracked files
-                repo.git.clean('-fd')
+                # Clean untracked files, but preserve user-managed directories
+                # (wildcards, backups, stats, civitai, caches, settings.json).
+                repo.git.clean('-fd', *clean_excludes)
                
                # Get latest release tag
                tags = sorted(repo.tags, key=lambda t: t.commit.committed_datetime, reverse=True)
--- a/py/services/agent/init.py
+++ b/py/services/agent/init.py
@@ -0,0 +1,27 @@
+"""LLM-powered metadata enrichment pipeline infrastructure.
+
+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
+
+from .skill_definition import SkillDefinition, SkillPermissions
+from .skill_registry import SkillRegistry
+from .agent_service import AgentService, AgentProgressReporter, SkillResult
+from .post_processor import PostProcessor
+
+__all__ = [
+    "AgentProgressReporter",
+    "AgentService",
+    "PostProcessor",
+    "SkillDefinition",
+    "SkillPermissions",
+    "SkillRegistry",
+    "SkillResult",
+]
--- a/py/services/agent/agent_service.py
+++ b/py/services/agent/agent_service.py
@@ -0,0 +1,489 @@
+"""Pipeline orchestration service.
+
+The :class:`AgentService` coordinates LLM-powered pipeline execution:
+
+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.metadata_ops`)
+6. Broadcast progress and completion via :class:`WebSocketManager`
+
+Pipeline definitions (*skills*) describe *what* to do (prompt template).
+The AgentService handles *how* (LLM calls, context gathering, validation,
+progress).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from dataclasses import dataclass, field
+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__)
+
+
+class AgentProgressReporter:
+    """Protocol-compatible progress reporter backed by WebSocket broadcast."""
+
+    async def on_progress(self, payload: Dict[str, Any]) -> None:
+        await ws_manager.broadcast(payload)
+
+
+@dataclass
+class SkillResult:
+    """Outcome of a skill execution."""
+
+    success: bool
+    updated_models: List[Dict[str, Any]] = field(default_factory=list)
+    errors: List[str] = field(default_factory=list)
+    summary: str = ""
+
+
+def _validate_schema(data: Any, schema: Dict[str, Any], path: str = "") -> List[str]:
+    """Minimal JSON schema validator.
+
+    Supports a subset of JSON Schema: ``type``, ``properties``, ``required``,
+    ``items``, ``enum``.  Returns a list of error messages (empty = valid).
+    """
+
+    errors: List[str] = []
+    if not schema:
+        return errors
+
+    expected_type = schema.get("type")
+    if expected_type:
+        type_map = {
+            "string": str,
+            "number": (int, float),
+            "integer": int,
+            "boolean": bool,
+            "array": list,
+            "object": dict,
+            "null": type(None),
+        }
+        expected_py = type_map.get(expected_type)
+        if expected_py is not None and not isinstance(data, expected_py):
+            errors.append(f"{path or 'root'}: expected {expected_type}, got {type(data).__name__}")
+            return errors
+
+    if expected_type == "object" and isinstance(data, dict):
+        properties = schema.get("properties", {})
+        required = schema.get("required", [])
+        for req_key in required:
+            if req_key not in data:
+                errors.append(f"{path or 'root'}: missing required property '{req_key}'")
+        for key, value in data.items():
+            if key in properties:
+                errors.extend(_validate_schema(value, properties[key], f"{path}.{key}"))
+
+    if expected_type == "array" and isinstance(data, list):
+        items_schema = schema.get("items")
+        if items_schema:
+            for i, item in enumerate(data):
+                errors.extend(_validate_schema(item, items_schema, f"{path}[{i}]"))
+
+    if "enum" in schema and data not in schema["enum"]:
+        errors.append(f"{path or 'root'}: value '{data}' not in enum {schema['enum']}")
+
+    return errors
+
+
+# ------------------------------------------------------------------
+# Prompt template rendering
+# ------------------------------------------------------------------
+
+
+def _render_prompt(template: str, variables: Dict[str, Any]) -> str:
+    """Render a prompt template with ``{{variable}}`` placeholders.
+
+    Uses simple regex substitution — no Jinja2 dependency needed.
+    """
+
+    def replace(match: re.Match) -> str:
+        key = match.group(1).strip()
+        value = variables.get(key, "")
+        if isinstance(value, (dict, list)):
+            return json.dumps(value, ensure_ascii=False, indent=2)
+        return str(value)
+
+    return re.sub(r"\{\{(\w+)\}\}", replace, template)
+
+
+class AgentService:
+    """Orchestrate agent skill execution.
+
+    Usage::
+
+        service = await AgentService.get_instance()
+        result = await service.execute_skill(
+            skill_name="enrich_hf_metadata",
+            input_data={"model_paths": ["/path/to/model.safetensors"]},
+            progress_callback=AgentProgressReporter(),
+        )
+    """
+
+    _instance: Optional["AgentService"] = None
+    _lock: asyncio.Lock = asyncio.Lock()
+
+    def __init__(
+        self,
+        *,
+        skill_registry: Optional[SkillRegistry] = None,
+        llm_service: Optional[LLMService] = None,
+    ) -> None:
+        self._registry = skill_registry
+        self._llm_service = llm_service
+
+    @classmethod
+    async def get_instance(cls) -> "AgentService":
+        """Return the lazily-initialised global ``AgentService``."""
+
+        if cls._instance is None:
+            async with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls(
+                        skill_registry=await SkillRegistry.get_instance(),
+                        llm_service=await LLMService.get_instance(),
+                    )
+        return cls._instance
+
+    @classmethod
+    def reset_instance(cls) -> None:
+        """Reset the cached singleton — primarily for tests."""
+
+        cls._instance = None
+
+    async def _ensure_registry(self) -> SkillRegistry:
+        if self._registry is None:
+            self._registry = await SkillRegistry.get_instance()
+        return self._registry
+
+    async def _ensure_llm(self) -> LLMService:
+        if self._llm_service is None:
+            self._llm_service = await LLMService.get_instance()
+        return self._llm_service
+
+    async def list_skills(self) -> List[Dict[str, Any]]:
+        """Return a JSON-serialisable list of available skills."""
+
+        registry = await self._ensure_registry()
+        return [
+            {
+                "name": s.name,
+                "title": s.title,
+                "description": s.description,
+                "llm_required": s.llm_required,
+                "model_type_filter": s.model_type_filter,
+            }
+            for s in registry.list_skills()
+        ]
+
+    async def execute_skill(
+        self,
+        *,
+        skill_name: str,
+        input_data: Dict[str, Any],
+        progress_callback: Optional[AgentProgressReporter] = None,
+    ) -> SkillResult:
+        """Execute a pipeline (skill) on the given models.
+
+        Args:
+            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:
+            :class:`SkillResult` with success status and updated model info
+        """
+
+        registry = await self._ensure_registry()
+        skill = registry.get_skill(skill_name)
+        if skill is None:
+            return SkillResult(
+                success=False,
+                errors=[f"Skill not found: {skill_name}"],
+                summary=f"Skill '{skill_name}' does not exist",
+            )
+
+        input_errors = _validate_schema(input_data, skill.input_schema)
+        if input_errors:
+            return SkillResult(
+                success=False,
+                errors=input_errors,
+                summary=f"Invalid input: {'; '.join(input_errors)}",
+            )
+
+        model_paths = input_data.get("model_paths", [])
+        if not model_paths:
+            return SkillResult(
+                success=False,
+                errors=["No model_paths provided"],
+                summary="No models to process",
+            )
+
+        total = len(model_paths)
+        processed = 0
+        success_count = 0
+        skipped_count = 0
+        updated_models: List[Dict[str, Any]] = []
+        errors: List[str] = []
+        post_processor = PostProcessor()
+
+        await self._emit_progress(
+            progress_callback, skill_name, status="started",
+            total=total, processed=0, success=0,
+        )
+
+        llm = await self._ensure_llm()
+        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(
+                "[%s] [%d/%d] %s",
+                skill_name, processed + 1, total, model_filename,
+            )
+            updated_data: Dict[str, Any] = {}
+            skip_model = False
+            try:
+                from ...metadata_ops import read_metadata
+                metadata = await read_metadata(model_path)
+
+                # 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(
+                        "[%s] SKIP %s — no hf_url in metadata",
+                        skill_name, model_filename,
+                    )
+                    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", ""),
+                    )
+
+                    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)
+                errors.append(f"{model_path}: {exc}")
+
+            processed += 1
+            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, {skipped_count} skipped",
+        )
+
+        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,
+        model_path: str,
+        metadata: Dict[str, Any],
+        registry: SkillRegistry,
+        llm: Any,
+    ) -> Dict[str, Any]:
+        """Gather variables for the skill's prompt template.
+
+        Reads metadata, fetches the HF README (if applicable), lists available
+        base models, loads user priority tags, and returns a dict that maps to
+        ``{{variable}}`` placeholders in ``prompt.md``.
+        """
+        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", ""),
+            "tags": metadata.get("tags", []),
+            "modelDescription": metadata.get("modelDescription", ""),
+            "trainedWords": metadata.get("trainedWords", []),
+            "sha256": (metadata.get("sha256") or "")[:16] + "..." if metadata.get("sha256") else "",
+            "size": metadata.get("size", 0),
+        }
+
+        hf_url = metadata.get("hf_url", "")
+        context["hf_url"] = hf_url
+        repo = self._extract_repo_from_url(hf_url) if hf_url else ""
+        context["repo"] = repo or ""
+        if repo:
+            readme = await self._fetch_readme(repo)
+            # 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:
+            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
+
+    @staticmethod
+    def _extract_repo_from_url(hf_url: str) -> Optional[str]:
+        """Extract ``user/repo`` from a HuggingFace URL."""
+        if not hf_url:
+            return None
+        m = re.match(r"https?://huggingface\.co/([^/]+/[^/]+)", hf_url)
+        return m.group(1) if m else None
+
+    @staticmethod
+    async def _fetch_readme(repo: str) -> str:
+        """Fetch README.md from HuggingFace (tries ``main``, then ``master``)."""
+        async with aiohttp.ClientSession(
+            headers={"User-Agent": "ComfyUI-LoRA-Manager/1.0"},
+            timeout=aiohttp.ClientTimeout(total=30),
+        ) as session:
+            for branch in ("main", "master"):
+                url = f"https://huggingface.co/{repo}/raw/{branch}/README.md"
+                try:
+                    async with session.get(url) as resp:
+                        if resp.status == 200:
+                            return await resp.text()
+                except Exception as exc:
+                    logger.debug("Failed to fetch README from %s: %s", url, exc)
+        return ""
+
+    async def _emit_progress(
+        self,
+        callback: Optional[AgentProgressReporter],
+        skill_name: str,
+        *,
+        status: str,
+        **extra: Any,
+    ) -> None:
+        """Send a progress update via WebSocket (if callback is set)."""
+        payload: Dict[str, Any] = {"type": "agent_progress", "skill": skill_name, "status": status}
+        payload.update(extra)
+        if callback is not None:
+            await callback.on_progress(payload)
--- a/py/services/agent/post_processor.py
+++ b/py/services/agent/post_processor.py
@@ -0,0 +1,336 @@
+"""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.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.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
+
+logger = logging.getLogger(__name__)
+
+
+class PostProcessor:
+    """Deterministic post-processor for skill pipeline outputs.
+
+    Usage (called by :class:`~py.services.agent.agent_service.AgentService`)::
+
+        processor = PostProcessor()
+        result = await processor.process(
+            skill_name="enrich_hf_metadata",
+            model_path="/path/to/model.safetensors",
+            llm_output={...},
+            metadata={...},    # from metadata_ops.read_metadata()
+        )
+    """
+
+    async def process(
+        self,
+        *,
+        skill_name: str,
+        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, readme_content,
+            )
+        return {
+            "success": False,
+            "updated_fields": [],
+            "errors": [f"No post-processor registered for skill: {skill_name}"],
+        }
+
+    # ------------------------------------------------------------------
+    # enrich_hf_metadata
+    # ------------------------------------------------------------------
+
+    async def _process_enrich_hf_metadata(
+        self,
+        model_path: str,
+        llm_output: Dict[str, Any],
+        metadata: Dict[str, Any],
+        readme_content: str = "",
+    ) -> Dict[str, Any]:
+        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
+
+        # -- Determine whether this is an HF-sourced model -----------------
+        is_hf_model = not metadata.get("from_civitai", True)
+
+        # -- Collect updates -----------------------------------------------
+        updates: Dict[str, Any] = {}
+
+        # base_model
+        new_base = (llm_output.get("base_model") or "").strip()
+        current_base = metadata.get("base_model", "") or ""
+        if new_base and self._should_overwrite(current_base, is_hf_model):
+            updates["base_model"] = new_base
+
+        # 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()]
+            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 — 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
+
+        # 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 []
+            merged = self._merge_tags(existing_tags, new_tags)
+            if len(merged) > len(existing_tags) or is_hf_model:
+                updates["tags"] = merged
+
+        # metadata_source & llm_enriched_at (always set)
+        updates["metadata_source"] = "agent:enrich_hf_metadata"
+        updates["llm_enriched_at"] = datetime.now(timezone.utc).isoformat()
+
+        # 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)
+
+        # -- Refresh scanner cache ------------------------------------------
+        if updated_fields or preview_downloaded:
+            await refresh_cache(model_path)
+
+        return {
+            "success": True,
+            "updated_fields": updated_fields,
+            "preview_downloaded": preview_downloaded,
+            "updates": updates,
+            "errors": [],
+        }
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _should_overwrite(current_value: str, is_hf_model: bool) -> bool:
+        """Return ``True`` when a scalar field should be overwritten."""
+        return is_hf_model or not current_value or current_value.lower() in (
+            "", "unknown",
+        )
+
+    @staticmethod
+    def _should_overwrite_list(current_list: List[str], is_hf_model: bool) -> bool:
+        """Return ``True`` when a list field should be overwritten."""
+        return is_hf_model or not current_list
+
+    @staticmethod
+    def _merge_tags(existing: List[str], new: List[str]) -> List[str]:
+        """Merge *new* tags into *existing*, all lowercased.
+
+        This matches the behaviour of :class:`TagUpdateService` which
+        normalises every tag to lowercase for case-insensitive dedup.
+        """
+        merged: List[str] = []
+        seen: set = set()
+        for tag in list(existing) + list(new):
+            t = tag.strip().lower()
+            if t and t not in seen:
+                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_definition.py
+++ b/py/services/agent/skill_definition.py
@@ -0,0 +1,45 @@
+"""Skill definition data structures.
+
+Each skill is described by a :class:`SkillDefinition` that declares its
+input/output schemas, whether it needs an LLM call, and what permissions
+its post-processor has.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+
+@dataclass(frozen=True)
+class SkillPermissions:
+    """Declarative permission scope for a skill's post-processor.
+
+    These are auditable constraints — the :class:`AgentService` checks them
+    before invoking the handler.  They are defense-in-depth, not a sandbox.
+    """
+
+    write_metadata: bool = True
+    write_previews: bool = True
+    network_domains: Tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class SkillDefinition:
+    """Immutable description of an agent skill."""
+
+    name: str
+    title: str
+    description: str
+    llm_required: bool
+    input_schema: Dict[str, Any] = field(default_factory=dict)
+    output_schema: Dict[str, Any] = field(default_factory=dict)
+    model_type_filter: Optional[List[str]] = None
+    permissions: SkillPermissions = field(default_factory=SkillPermissions)
+
+    def applies_to_model_type(self, model_type: str) -> bool:
+        """Return ``True`` if this skill can run on the given model type."""
+
+        if self.model_type_filter is None:
+            return True
+        return model_type in self.model_type_filter
--- a/py/services/agent/skill_registry.py
+++ b/py/services/agent/skill_registry.py
@@ -0,0 +1,210 @@
+"""Discovery and loading of prompt-based skills.
+
+Skills live in ``py/services/agent/skills/<name>/`` directories.  Each
+directory must contain a ``prompt.md`` file with YAML frontmatter::
+
+    ---
+    name: my_skill
+    title: "My Skill"
+    description: "What this skill does"
+    llm_required: true
+    ---
+
+    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.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+from .skill_definition import SkillDefinition, SkillPermissions
+
+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
+# ---------------------------------------------------------------------------
+
+_FRONTMATTER_RE = re.compile(
+    r"^---\s*\n(.*?\n)---\s*\n?(.*)", re.DOTALL
+)
+
+
+def _parse_skill_file(path: Path) -> tuple[dict, str]:
+    """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.
+    """
+    text = path.read_text(encoding="utf-8")
+    m = _FRONTMATTER_RE.match(text)
+    if not m:
+        raise ValueError(f"Missing or invalid YAML frontmatter in {path}")
+    frontmatter = yaml.safe_load(m.group(1))
+    if not isinstance(frontmatter, dict):
+        raise ValueError(f"Frontmatter in {path} is not a mapping")
+    body = m.group(2).strip()
+    return frontmatter, body
+
+
+class SkillRegistry:
+    """Discover and load agent skills from the filesystem."""
+
+    _instance: Optional["SkillRegistry"] = None
+    _lock: asyncio.Lock = asyncio.Lock()
+
+    def __init__(self, skills_dir: Path = _SKILLS_DIR) -> None:
+        self._skills_dir = skills_dir
+        self._skills: Dict[str, SkillDefinition] = {}
+        self._loaded: bool = False
+
+    # ------------------------------------------------------------------
+    # Singleton access
+    # ------------------------------------------------------------------
+
+    @classmethod
+    async def get_instance(cls) -> "SkillRegistry":
+        """Return the lazily-initialised global ``SkillRegistry``."""
+
+        if cls._instance is None:
+            async with cls._lock:
+                if cls._instance is None:
+                    registry = cls()
+                    registry._discover()
+                    cls._instance = registry
+        return cls._instance
+
+    @classmethod
+    def reset_instance(cls) -> None:
+        """Reset the cached singleton — primarily for tests."""
+
+        cls._instance = None
+
+    # ------------------------------------------------------------------
+    # 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."""
+
+        self._skills.clear()
+        if not self._skills_dir.is_dir():
+            logger.warning("Skills directory does not exist: %s", self._skills_dir)
+            self._loaded = True
+            return
+
+        for entry in sorted(self._skills_dir.iterdir()):
+            if not entry.is_dir():
+                continue
+            prompt_file = self._find_prompt_file(entry)
+            if prompt_file is None:
+                continue
+            try:
+                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", prompt_file, exc)
+
+        self._loaded = True
+        logger.info("Discovered %d prompt-based skills", len(self._skills))
+
+    def _load_skill_definition(self, path: Path) -> Optional[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 prompt file %s: %s", path, exc)
+            return None
+
+        if "name" not in data:
+            logger.warning("Prompt file %s missing required 'name' field", path)
+            return None
+
+        perm_data = data.get("permissions", {})
+        permissions = SkillPermissions(
+            write_metadata=perm_data.get("write_metadata", True),
+            write_previews=perm_data.get("write_previews", True),
+            network_domains=tuple(perm_data.get("network_domains", [])),
+        )
+
+        return SkillDefinition(
+            name=data["name"],
+            title=data.get("title", data["name"]),
+            description=data.get("description", ""),
+            llm_required=data.get("llm_required", False),
+            input_schema=data.get("input_schema", {}),
+            output_schema=data.get("output_schema", {}),
+            model_type_filter=data.get("model_type_filter"),
+            permissions=permissions,
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def list_skills(self) -> List[SkillDefinition]:
+        """Return all discovered skill definitions."""
+
+        if not self._loaded:
+            self._discover()
+        return list(self._skills.values())
+
+    def get_skill(self, name: str) -> Optional[SkillDefinition]:
+        """Return the skill definition for ``name``, or ``None`` if not found."""
+
+        if not self._loaded:
+            self._discover()
+        return self._skills.get(name)
+
+    def load_prompt(self, name: str) -> str:
+        """Load and return the prompt template body for the named skill."""
+
+        skill_dir = self._skills_dir / name
+        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
+        except (ValueError, yaml.YAMLError) as exc:
+            raise ValueError(f"Failed to parse prompt from {skill_path}: {exc}") from exc
--- 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/base_model_service.py
+++ b/py/services/base_model_service.py
@@ -791,8 +791,12 @@ class BaseModelService(ABC):
        }

    @abstractmethod
-    async def format_response(self, model_data: Dict) -> Dict:
-        """Format model data for API response - must be implemented by subclasses"""
+    async def format_response(self, model_data: Dict) -> Optional[Dict]:
+        """Format model data for API response - must be implemented by subclasses.
+
+        Subclasses should return None for corrupted entries so the handler
+        layer can filter them out. See issue #730.
+        """
        pass

    # Common service methods that delegate to scanner
--- a/py/services/checkpoint_service.py
+++ b/py/services/checkpoint_service.py
@@ -1,6 +1,6 @@
 import os
 import logging
-from typing import Dict
+from typing import Dict, Optional

 from .base_model_service import BaseModelService
 from .auto_tag_service import extract_auto_tags
@@ -21,20 +21,37 @@ class CheckpointService(BaseModelService):
        """
        super().__init__("checkpoint", scanner, CheckpointMetadata, update_service=update_service)
    
-    async def format_response(self, checkpoint_data: Dict) -> Dict:
-        """Format Checkpoint data for API response"""
+    async def format_response(self, checkpoint_data: Dict) -> Optional[Dict]:
+        """Format Checkpoint data for API response.
+
+        Returns None when the entry is missing critical fields (corrupted cache
+        row), so the handler layer can filter it out. See issue #730.
+        """
+        # Guard against corrupted cache entries missing critical fields
+        file_path = checkpoint_data.get("file_path")
+        if not file_path or not isinstance(file_path, str):
+            logger.warning(
+                "Skipping corrupted checkpoint entry (missing file_path): %s",
+                checkpoint_data.get("file_name", "<unknown>"),
+            )
+            return None
+
        # Get sub_type from cache entry (new canonical field)
        sub_type = checkpoint_data.get("sub_type", "checkpoint")
-        
+
+        file_name = checkpoint_data.get("file_name") or ""
+        model_name = checkpoint_data.get("model_name") or file_name
+        folder = checkpoint_data.get("folder") or ""
+
        return {
-            "model_name": checkpoint_data["model_name"],
-            "file_name": checkpoint_data["file_name"],
+            "model_name": model_name,
+            "file_name": file_name,
            "preview_url": config.get_preview_static_url(checkpoint_data.get("preview_url", "")),
            "preview_nsfw_level": checkpoint_data.get("preview_nsfw_level", 0),
            "base_model": checkpoint_data.get("base_model", ""),
-            "folder": checkpoint_data["folder"],
+            "folder": folder,
            "sha256": checkpoint_data.get("sha256", ""),
-            "file_path": checkpoint_data["file_path"].replace(os.sep, "/"),
+            "file_path": file_path.replace(os.sep, "/"),
            "file_size": checkpoint_data.get("size", 0),
            "modified": checkpoint_data.get("modified", ""),
            "tags": checkpoint_data.get("tags", []),
@@ -49,6 +66,7 @@ class CheckpointService(BaseModelService):
            "civitai": self.filter_civitai_data(checkpoint_data.get("civitai", {}), minimal=True),
            "auto_tags": checkpoint_data.get("auto_tags") or extract_auto_tags(checkpoint_data),
            "version_count": checkpoint_data.get("version_count"),
+            "hf_url": checkpoint_data.get("hf_url", ""),
        }
    
    def find_duplicate_hashes(self) -> Dict:
--- a/py/services/civarchive_client.py
+++ b/py/services/civarchive_client.py
@@ -327,7 +327,7 @@ class CivArchiveClient:
            if resolved:
                return resolved, None

-            logger.error("Error fetching version of CivArchive model by hash %s", model_hash[:10])
+            logger.debug("Error fetching version of CivArchive model by hash %s", model_hash[:10])
            return None, "No version data found"

        except RateLimitError:
--- a/py/services/civitai_base_model_service.py
+++ b/py/services/civitai_base_model_service.py
@@ -196,6 +196,7 @@ class CivitaiBaseModelService:
            "ernie": "ERNI",
            "ernie turbo": "ETRB",
            "nucleus": "NUCL",
+            "krea 2": "KR2",
            "svd": "SVD",
            "ltxv": "LTXV",
            "ltxv2": "LTV2",
@@ -212,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:
@@ -391,6 +404,7 @@ class CivitaiBaseModelService:
                "LTXV2",
                "LTXV 2.3",
                "CogVideoX",
+                "HappyHorse",
                "Mochi",
                "Hunyuan Video",
                "Wan Video",
@@ -403,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",
@@ -424,6 +448,8 @@ class CivitaiBaseModelService:
                "Ernie",
                "Ernie Turbo",
                "Nucleus",
+                "Krea 2",
+                "Upscaler",
            ],
        }

--- a/py/services/embedding_service.py
+++ b/py/services/embedding_service.py
@@ -1,6 +1,6 @@
 import os
 import logging
-from typing import Dict
+from typing import Dict, Optional

 from .base_model_service import BaseModelService
 from .auto_tag_service import extract_auto_tags
@@ -21,20 +21,37 @@ class EmbeddingService(BaseModelService):
        """
        super().__init__("embedding", scanner, EmbeddingMetadata, update_service=update_service)
    
-    async def format_response(self, embedding_data: Dict) -> Dict:
-        """Format Embedding data for API response"""
+    async def format_response(self, embedding_data: Dict) -> Optional[Dict]:
+        """Format Embedding data for API response.
+
+        Returns None when the entry is missing critical fields (corrupted cache
+        row), so the handler layer can filter it out. See issue #730.
+        """
+        # Guard against corrupted cache entries missing critical fields
+        file_path = embedding_data.get("file_path")
+        if not file_path or not isinstance(file_path, str):
+            logger.warning(
+                "Skipping corrupted embedding entry (missing file_path): %s",
+                embedding_data.get("file_name", "<unknown>"),
+            )
+            return None
+
        # Get sub_type from cache entry (new canonical field)
        sub_type = embedding_data.get("sub_type", "embedding")
-        
+
+        file_name = embedding_data.get("file_name") or ""
+        model_name = embedding_data.get("model_name") or file_name
+        folder = embedding_data.get("folder") or ""
+
        return {
-            "model_name": embedding_data["model_name"],
-            "file_name": embedding_data["file_name"],
+            "model_name": model_name,
+            "file_name": file_name,
            "preview_url": config.get_preview_static_url(embedding_data.get("preview_url", "")),
            "preview_nsfw_level": embedding_data.get("preview_nsfw_level", 0),
            "base_model": embedding_data.get("base_model", ""),
-            "folder": embedding_data["folder"],
+            "folder": folder,
            "sha256": embedding_data.get("sha256", ""),
-            "file_path": embedding_data["file_path"].replace(os.sep, "/"),
+            "file_path": file_path.replace(os.sep, "/"),
            "file_size": embedding_data.get("size", 0),
            "modified": embedding_data.get("modified", ""),
            "tags": embedding_data.get("tags", []),
@@ -49,6 +66,7 @@ class EmbeddingService(BaseModelService):
            "civitai": self.filter_civitai_data(embedding_data.get("civitai", {}), minimal=True),
            "auto_tags": embedding_data.get("auto_tags") or extract_auto_tags(embedding_data),
            "version_count": embedding_data.get("version_count"),
+            "hf_url": embedding_data.get("hf_url", ""),
        }
    
    def find_duplicate_hashes(self) -> Dict:
--- a/py/services/errors.py
+++ b/py/services/errors.py
@@ -25,3 +25,21 @@ class ResourceNotFoundError(RuntimeError):

    pass

+
+class LLMNotConfiguredError(RuntimeError):
+    """Raised when an LLM-dependent operation is attempted but no provider is configured."""
+
+    pass
+
+
+class LLMRateLimitError(RateLimitError):
+    """Raised when the LLM provider rejects a request due to rate limiting."""
+
+    pass
+
+
+class LLMResponseError(RuntimeError):
+    """Raised when the LLM returns an unparseable or schema-invalid response."""
+
+    pass
+
--- a/py/services/llm_service.py
+++ b/py/services/llm_service.py
@@ -0,0 +1,695 @@
+"""Centralized LLM API client with BYOK (bring-your-own-key) provider support.
+
+Reads provider configuration from :class:`SettingsManager` and makes
+OpenAI-compatible ``/chat/completions`` calls.  Supports any provider that
+implements the OpenAI Chat Completions API surface area (OpenAI, Ollama,
+vLLM, LM Studio, etc.).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+import aiohttp
+
+from .errors import LLMNotConfiguredError, LLMRateLimitError, LLMResponseError
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# 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
+
+# Per-model max output token limits parsed from the catalog.
+# ``{provider_id: {model_id: max_output_tokens}}``.
+_model_output_limits: Dict[str, Dict[str, int]] = {}
+
+_CATALOG_TIMEOUT = aiohttp.ClientTimeout(total=30)
+
+
+async def _load_model_catalog() -> Dict[str, List[str]]:
+    """Fetch and parse the model catalog.
+
+    Returns ``{provider_id: [model_id, ...]}`` and also populates
+    :data:`_model_output_limits` with per-model ``limit.output`` values
+    for use by :func:`_get_model_max_output`.
+
+    The JSON at ``_MODEL_CATALOG_URL`` is a dict keyed by provider slug; each
+    value has a ``models`` sub-dict keyed by model ID.  The result is cached
+    in memory after the first successful fetch.
+    Subsequent calls return the cached data immediately.
+    """
+    global _catalog_cache, _model_output_limits
+    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]] = {}
+    output_limits: Dict[str, Dict[str, int]] = {}
+    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: List[str] = []
+        provider_limits: Dict[str, int] = {}
+        for mid, model_info in models_dict.items():
+            if not isinstance(mid, str):
+                continue
+            model_ids.append(mid)
+            if isinstance(model_info, dict):
+                limit = model_info.get("limit")
+                if isinstance(limit, dict):
+                    output = limit.get("output")
+                    if isinstance(output, (int, float)) and output > 0:
+                        provider_limits[mid] = int(output)
+        if model_ids:
+            result[provider_id] = model_ids
+        if provider_limits:
+            output_limits[provider_id] = provider_limits
+
+    _catalog_cache = result
+    _model_output_limits = output_limits
+    logger.debug(
+        "Loaded model catalog: %d providers, %d total models "
+        "(%d providers have output limits)",
+        len(result),
+        sum(len(m) for m in result.values()),
+        len(output_limits),
+    )
+    return result
+
+
+def _get_model_max_output(provider: str, model: str) -> Optional[int]:
+    """Return the model's max output token limit from the catalog, or ``None``.
+
+    Returns ``None`` when the provider or model is not found in the catalog
+    (e.g. local Ollama models, custom models, or user-typed model names).
+    Callers should fall back to a safe default.
+    """
+    return _model_output_limits.get(provider, {}).get(model)
+
+
+# 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] = {
+    pid: info["api_base"]
+    for pid, info in PROVIDER_PRESETS.items()
+    if info.get("api_base")
+}
+
+# Request timeout for LLM calls (seconds)
+_LLM_TIMEOUT = aiohttp.ClientTimeout(total=120)
+
+
+class LLMService:
+    """Centralized LLM API client.
+
+    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
+    _lock: asyncio.Lock = asyncio.Lock()
+
+    def __init__(self, settings_service) -> None:
+        self._settings = settings_service
+
+    # ------------------------------------------------------------------
+    # Singleton access
+    # ------------------------------------------------------------------
+
+    @classmethod
+    async def get_instance(cls) -> "LLMService":
+        """Return the lazily-initialised global ``LLMService`` instance."""
+
+        if cls._instance is None:
+            async with cls._lock:
+                if cls._instance is None:
+                    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
+    def reset_instance(cls) -> None:
+        """Reset the cached singleton — primarily for tests."""
+
+        cls._instance = None
+
+    # ------------------------------------------------------------------
+    # Configuration helpers
+    # ------------------------------------------------------------------
+
+    def _get_config(self) -> Dict[str, Any]:
+        """Read the current LLM configuration from settings."""
+
+        return {
+            "provider": self._settings.get("llm_provider", "openai"),
+            "api_key": self._settings.get("llm_api_key", ""),
+            "api_base": self._settings.get("llm_api_base", ""),
+            "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,
+        an API key is configured for providers that require one (e.g.
+        Ollama does not), and an API base URL is set for providers that
+        have no preset default (e.g. ``custom``).
+        """
+
+        cfg = self._get_config()
+        has_model = bool(cfg["model"])
+        has_key = bool(cfg["api_key"]) or not self._provider_requires_key(cfg["provider"])
+        has_base = bool(cfg["api_base"]) or bool(_PROVIDER_DEFAULTS.get(cfg["provider"]))
+        return has_model and has_key and has_base
+
+    def _resolve_api_base(self, provider: str, api_base: str) -> str:
+        """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("/")
+        return _PROVIDER_DEFAULTS.get(provider, "").rstrip("/")
+
+    def _build_headers(self, api_key: str) -> Dict[str, str]:
+        """Build HTTP headers for the LLM API request."""
+
+        headers = {"Content-Type": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        return headers
+
+    def _ensure_configured(self) -> Dict[str, Any]:
+        """Validate configuration and return it, or raise.
+
+        A provider is considered configured when ``llm_model`` is set,
+        an API key is configured for providers that require one, and
+        an API base URL is set for providers without a preset default.
+        """
+
+        cfg = self._get_config()
+        has_model = bool(cfg["model"])
+        needs_key = self._provider_requires_key(cfg["provider"])
+        has_key = bool(cfg["api_key"]) or not needs_key
+        has_base = bool(cfg["api_base"]) or bool(_PROVIDER_DEFAULTS.get(cfg["provider"]))
+        if not (has_model and has_key and has_base):
+            parts = []
+            if not has_model:
+                parts.append("No LLM model specified")
+            if not has_key and needs_key:
+                parts.append("No LLM API key configured")
+            if not has_base:
+                parts.append(
+                    f"No API base URL for provider '{cfg['provider']}'"
+                )
+            detail = "; ".join(parts) if parts else "LLM provider is not configured"
+            raise LLMNotConfiguredError(
+                f"{detail}. Configure it in Settings → AI Provider."
+            )
+        return cfg
+
+    # ------------------------------------------------------------------
+    # Core API call
+    # ------------------------------------------------------------------
+
+    async def chat_completion(
+        self,
+        *,
+        messages: List[Dict[str, str]],
+        model: Optional[str] = None,
+        temperature: float = 0.3,
+        response_format: Optional[Dict[str, Any]] = None,
+        max_tokens: Optional[int] = None,
+        retry_on_rate_limit: bool = True,
+    ) -> Dict[str, Any]:
+        """Call the configured LLM provider's ``/chat/completions`` endpoint.
+
+        Args:
+            messages: OpenAI-format message list
+            model: Override the configured model name
+            temperature: Sampling temperature
+            response_format: Optional ``{"type": "json_object"}`` for structured output
+            max_tokens: Optional max output tokens
+            retry_on_rate_limit: Retry once after a 429 with backoff
+
+        Returns:
+            Dict with ``content`` (str), ``usage`` (dict), ``model`` (str)
+
+        Raises:
+            LLMNotConfiguredError: Provider not enabled / missing config
+            LLMRateLimitError: Rate limited and retry exhausted
+            LLMResponseError: Non-200 response or parse failure
+        """
+
+        cfg = self._ensure_configured()
+        api_base = self._resolve_api_base(cfg["provider"], cfg["api_base"])
+        model_name = model or cfg["model"]
+
+        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,
+                    # 8K context is sufficient for metadata enrichment
+                    # (prompt ~2-5K, output ~0.2-1K tokens).  The old 32K
+                    # value was excessive for this use case and increased
+                    # Ollama VRAM usage unnecessarily.
+                    "num_ctx": 8192,
+                },
+            }
+            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"])
+
+        attempt = 0
+        max_attempts = 2 if retry_on_rate_limit else 1
+        while attempt < max_attempts:
+            attempt += 1
+            try:
+                async with aiohttp.ClientSession(timeout=_LLM_TIMEOUT) as session:
+                    async with session.post(
+                        url, json=payload, headers=headers
+                    ) as resp:
+                        if resp.status == 429:
+                            if attempt < max_attempts:
+                                retry_after = float(
+                                    resp.headers.get("Retry-After", "5")
+                                )
+                                logger.warning(
+                                    "LLM rate limited, retrying after %.1fs",
+                                    retry_after,
+                                )
+                                await asyncio.sleep(retry_after)
+                                continue
+                            raise LLMRateLimitError(
+                                f"LLM provider rate limited (HTTP 429)",
+                                provider=cfg["provider"],
+                            )
+
+                        if resp.status != 200:
+                            body = await resp.text()
+                            raise LLMResponseError(
+                                f"LLM API returned HTTP {resp.status}: "
+                                f"{body[:500]}"
+                            )
+
+                        data = await resp.json()
+
+            except aiohttp.ClientError as exc:
+                raise LLMResponseError(f"Network error calling LLM API: {exc}") from exc
+
+            # Parse response
+            try:
+                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,
+                    "model": data.get("model", model_name),
+                }
+            except (KeyError, IndexError) as exc:
+                raise LLMResponseError(
+                    f"Unexpected LLM response structure: {json.dumps(data)[:500]}"
+                ) from exc
+
+        # Should not reach here, but satisfy type checker
+        raise LLMRateLimitError("Rate limit retry exhausted", provider=cfg["provider"])
+
+    # ------------------------------------------------------------------
+    # Structured output convenience
+    # ------------------------------------------------------------------
+
+    async def chat_completion_json(
+        self,
+        *,
+        system_prompt: str,
+        user_prompt: str,
+        model: Optional[str] = None,
+        temperature: float = 0.3,
+        max_tokens: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Call the LLM with ``response_format=json_object`` and return parsed JSON.
+
+        ``max_tokens`` is resolved in this order:
+        1. Explicit caller-supplied ``max_tokens``
+        2. Per-model ``limit.output`` from the model catalog
+        3. A safe default of 4096 (sufficient for metadata enrichment)
+
+        If the response content is empty or not valid JSON, attempts
+        :func:`_try_salvage_json` before raising.
+
+        Args:
+            system_prompt: System-level instructions
+            user_prompt: User-level query
+            model: Override the configured model name
+            temperature: Sampling temperature
+            max_tokens: Optional max output tokens
+
+        Returns:
+            Parsed JSON dict from the LLM response
+
+        Raises:
+            LLMNotConfiguredError: Provider not configured
+            LLMRateLimitError: Rate limited
+            LLMResponseError: Empty response or JSON parse failure
+        """
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ]
+
+        # Resolve max_tokens: caller override → catalog lookup → safe default
+        if max_tokens is None:
+            cfg = self._get_config()
+            effective_max = _get_model_max_output(cfg["provider"], cfg["model"])
+        else:
+            effective_max = max_tokens
+        if effective_max is None:
+            effective_max = 4096
+
+        result = await self.chat_completion(
+            messages=messages,
+            model=model,
+            temperature=temperature,
+            response_format={"type": "json_object"},
+            max_tokens=effective_max,
+        )
+
+        content = result.get("content", "") or ""
+        if not content:
+            raise LLMResponseError(
+                "LLM returned empty content in json_object mode. "
+                f"Raw response: {json.dumps(result)[:500]}"
+            )
+
+        try:
+            parsed = json.loads(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",
+                content[:800],
+            )
+
+        # Last resort: attempt to salvage partial/truncated JSON
+        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: {content[:200]}"
+        )
+
+
+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/services/lora_service.py
+++ b/py/services/lora_service.py
@@ -24,23 +24,41 @@ class LoraService(BaseModelService):
        """
        super().__init__("lora", scanner, LoraMetadata, update_service=update_service)

-    async def format_response(self, lora_data: Dict) -> Dict:
-        """Format LoRA data for API response"""
+    async def format_response(self, lora_data: Dict) -> Optional[Dict]:
+        """Format LoRA data for API response.
+
+        Returns None when the entry is missing critical fields (corrupted cache
+        row), so the handler layer can filter it out instead of crashing the
+        whole listing request. See issue #730.
+        """
+        # Guard against corrupted cache entries missing critical fields
+        file_path = lora_data.get("file_path")
+        if not file_path or not isinstance(file_path, str):
+            logger.warning(
+                "Skipping corrupted LoRA entry (missing file_path): %s",
+                lora_data.get("file_name", "<unknown>"),
+            )
+            return None
+
        # Resolve sub_type using priority: sub_type > model_type > civitai.model.type > default
        # Normalize to lowercase for consistent API responses
        sub_type = resolve_sub_type(lora_data).lower()

+        file_name = lora_data.get("file_name") or ""
+        model_name = lora_data.get("model_name") or file_name
+        folder = lora_data.get("folder") or ""
+
        return {
-            "model_name": lora_data["model_name"],
-            "file_name": lora_data["file_name"],
+            "model_name": model_name,
+            "file_name": file_name,
            "preview_url": config.get_preview_static_url(
                lora_data.get("preview_url", "")
            ),
            "preview_nsfw_level": lora_data.get("preview_nsfw_level", 0),
            "base_model": lora_data.get("base_model", ""),
-            "folder": lora_data["folder"],
+            "folder": folder,
            "sha256": lora_data.get("sha256", ""),
-            "file_path": lora_data["file_path"].replace(os.sep, "/"),
+            "file_path": file_path.replace(os.sep, "/"),
            "file_size": lora_data.get("size", 0),
            "modified": lora_data.get("modified", ""),
            "tags": lora_data.get("tags", []),
@@ -60,6 +78,7 @@ class LoraService(BaseModelService):
            ),
            "auto_tags": lora_data.get("auto_tags") or extract_auto_tags(lora_data),
            "version_count": lora_data.get("version_count"),
+            "hf_url": lora_data.get("hf_url", ""),
        }

    async def _apply_specific_filters(self, data: List[Dict], **kwargs) -> List[Dict]:
--- a/py/services/model_scanner.py
+++ b/py/services/model_scanner.py
@@ -248,6 +248,7 @@ class ModelScanner:
            'civitai': civitai_slim,
            'civitai_deleted': bool(get_value('civitai_deleted', False)),
            'skip_metadata_refresh': bool(get_value('skip_metadata_refresh', False)),
+            'hf_url': get_value('hf_url', '') or '',
        }

        license_source: Dict[str, Any] = {}
@@ -476,11 +477,20 @@ class ModelScanner:
            for tag in adjusted_item.get('tags') or []:
                tags_count[tag] = tags_count.get(tag, 0) + 1

-        # Validate cache entries and check health
+        # Validate cache entries and check health.
+        # Always use the validated/repaired entries — even when there are no
+        # invalid entries, auto_repair may have filled in missing optional
+        # fields (model_name, file_name, folder) with safe defaults on a copied
+        # working_entry.  Without this unconditional replacement the repaired
+        # copies are discarded and None values propagate to format_response.
+        # See issue #730.
        valid_entries, invalid_entries = CacheEntryValidator.validate_batch(
            adjusted_raw_data, auto_repair=True
        )

+        # Always use the validated entries (repaired copies)
+        adjusted_raw_data = valid_entries
+
        if invalid_entries:
            monitor = CacheHealthMonitor()
            report = monitor.check_health(adjusted_raw_data, auto_repair=True)
--- a/py/services/persistent_model_cache.py
+++ b/py/services/persistent_model_cache.py
@@ -57,6 +57,7 @@ class PersistentModelCache:
        "db_checked",
        "last_checked_at",
        "hash_status",
+        "hf_url",
    )
    _MODEL_UPDATE_COLUMNS: Tuple[str, ...] = _MODEL_COLUMNS[2:]
    _instances: Dict[str, "PersistentModelCache"] = {}
@@ -165,8 +166,8 @@ class PersistentModelCache:

            item = {
                "file_path": file_path,
-                "file_name": row["file_name"],
-                "model_name": row["model_name"],
+                "file_name": row["file_name"] or "",
+                "model_name": row["model_name"] or "",
                "folder": row["folder"] or "",
                "size": row["size"] or 0,
                "modified": row["modified"] or 0.0,
@@ -188,6 +189,7 @@ class PersistentModelCache:
                "skip_metadata_refresh": bool(row["skip_metadata_refresh"]),
                "license_flags": int(license_value),
                "hash_status": row["hash_status"] or "completed",
+                "hf_url": row["hf_url"] or "",
            }
            raw_data.append(item)

@@ -452,6 +454,7 @@ class PersistentModelCache:
                            db_checked INTEGER,
                            last_checked_at REAL,
                            hash_status TEXT,
+                            hf_url TEXT DEFAULT '',
                            PRIMARY KEY (model_type, file_path)
                        );

@@ -500,6 +503,7 @@ class PersistentModelCache:
            # Persisting without explicit flags should assume CivitAI's documented defaults (0b111001 == 57).
            "license_flags": f"INTEGER DEFAULT {DEFAULT_LICENSE_FLAGS}",
            "hash_status": "TEXT DEFAULT 'completed'",
+            "hf_url": "TEXT DEFAULT ''",
        }

        for column, definition in required_columns.items():
@@ -548,19 +552,19 @@ class PersistentModelCache:
        return (
            model_type,
            item.get("file_path"),
-            item.get("file_name"),
-            item.get("model_name"),
-            item.get("folder"),
+            item.get("file_name") or "",
+            item.get("model_name") or "",
+            item.get("folder") or "",
            int(item.get("size") or 0),
            float(item.get("modified") or 0.0),
            (item.get("sha256") or "").lower() or None,
-            item.get("base_model"),
-            item.get("preview_url"),
+            item.get("base_model") or "",
+            item.get("preview_url") or "",
            int(item.get("preview_nsfw_level") or 0),
            1 if item.get("from_civitai", True) else 0,
            1 if item.get("favorite") else 0,
-            item.get("notes"),
-            item.get("usage_tips"),
+            item.get("notes") or "",
+            item.get("usage_tips") or "",
            metadata_source,
            civitai.get("id"),
            civitai.get("modelId"),
@@ -575,6 +579,7 @@ class PersistentModelCache:
            1 if item.get("db_checked") else 0,
            float(item.get("last_checked_at") or 0.0),
            item.get("hash_status", "completed"),
+            item.get("hf_url") or "",
        )

    def _insert_model_sql(self) -> str:
--- a/py/services/settings_manager.py
+++ b/py/services/settings_manager.py
@@ -107,6 +107,11 @@ DEFAULT_SETTINGS: Dict[str, Any] = {
    "backup_retention_count": 5,
    "use_new_license_icons": True,
    "group_by_model": False,
+    # AI / LLM provider configuration (BYOK)
+    "llm_provider": "openai",  # "openai" | "ollama" | "custom"
+    "llm_api_key": "",
+    "llm_api_base": "",  # empty = provider default
+    "llm_model": "",  # e.g. "gpt-4o-mini"
 }


@@ -873,6 +878,23 @@ class SettingsManager:
            self.settings["civitai_api_key"] = env_api_key
            self._save_settings()

+        # LLM provider overrides
+        llm_env_map = {
+            "LLM_API_KEY": "llm_api_key",
+            "LLM_MODEL": "llm_model",
+            "LLM_API_BASE": "llm_api_base",
+            "LLM_PROVIDER": "llm_provider",
+        }
+        llm_changed = False
+        for env_var, settings_key in llm_env_map.items():
+            env_val = os.environ.get(env_var)
+            if env_val:
+                logger.info("Found %s environment variable", env_var)
+                self.settings[settings_key] = env_val
+                llm_changed = True
+        if llm_changed:
+            self._save_settings()
+
    def _default_settings_actions(self) -> List[Dict[str, Any]]:
        return [
            {
@@ -1568,7 +1590,7 @@ class SettingsManager:
        previous_dir = os.path.dirname(previous_path) or target_dir

        if os.path.abspath(previous_path) != os.path.abspath(target_path):
-            self._copy_model_cache_directory(previous_dir, target_dir)
+            self._migrate_settings_directory_content(previous_dir, target_dir)
            logger.info("Switching settings file to: %s", target_path)

        self._pending_portable_switch = {"other_path": other_path}
@@ -1603,46 +1625,52 @@ class SettingsManager:
        finally:
            self._pending_portable_switch = None

-    def _copy_model_cache_directory(self, source_dir: str, target_dir: str) -> None:
-        """Copy model_cache artifacts when switching storage locations."""
+    def _migrate_settings_directory_content(
+        self, source_dir: str, target_dir: str
+    ) -> None:
+        """Migrate settings directory subdirectories when switching storage locations.
+
+        Copies the canonical subdirectories (cache, backups, logs, stats, wildcards)
+        from the old settings directory to the new one. Legacy cache artifacts
+        (model_cache, recipe_cache, etc.) are migrated lazily by
+        ``resolve_cache_path_with_migration`` on first access.
+
+        Args:
+            source_dir: The previous settings directory path.
+            target_dir: The new settings directory path.
+        """

        if not source_dir or not target_dir:
            return

-        source_cache_dir = os.path.join(source_dir, "model_cache")
-        target_cache_dir = os.path.join(target_dir, "model_cache")
-        if os.path.isdir(source_cache_dir) and os.path.abspath(
-            source_cache_dir
-        ) != os.path.abspath(target_cache_dir):
-            try:
-                shutil.copytree(
-                    source_cache_dir,
-                    target_cache_dir,
-                    dirs_exist_ok=True,
-                    ignore=shutil.ignore_patterns("*.sqlite-shm", "*.sqlite-wal"),
-                )
-            except Exception as exc:
-                logger.warning(
-                    "Failed to copy model_cache directory from %s to %s: %s",
-                    source_cache_dir,
-                    target_cache_dir,
-                    exc,
-                )
+        def _copy_dir(name: str) -> None:
+            source = os.path.join(source_dir, name)
+            target = os.path.join(target_dir, name)
+            if os.path.isdir(source) and os.path.abspath(source) != os.path.abspath(
+                target
+            ):
+                try:
+                    shutil.copytree(
+                        source,
+                        target,
+                        dirs_exist_ok=True,
+                        ignore=shutil.ignore_patterns("*.sqlite-shm", "*.sqlite-wal"),
+                    )
+                except Exception as exc:
+                    logger.warning(
+                        "Failed to copy directory %s from %s to %s: %s",
+                        name,
+                        source,
+                        target,
+                        exc,
+                    )

-        source_cache_file = os.path.join(source_dir, "model_cache.sqlite")
-        target_cache_file = os.path.join(target_dir, "model_cache.sqlite")
-        if os.path.isfile(source_cache_file) and os.path.abspath(
-            source_cache_file
-        ) != os.path.abspath(target_cache_file):
-            try:
-                shutil.copy2(source_cache_file, target_cache_file)
-            except Exception as exc:
-                logger.warning(
-                    "Failed to copy model_cache.sqlite from %s to %s: %s",
-                    source_cache_file,
-                    target_cache_file,
-                    exc,
-                )
+        # Managed subdirectories under settings_dir
+        _copy_dir("cache")
+        _copy_dir("backups")
+        _copy_dir("logs")
+        _copy_dir("stats")
+        _copy_dir("wildcards")

    def _get_user_config_directory(self) -> str:
        """Return the user configuration directory, falling back to ~/.config."""
--- a/py/utils/constants.py
+++ b/py/utils/constants.py
@@ -47,6 +47,20 @@ SUPPORTED_MEDIA_EXTENSIONS = {
    "videos": [".mp4", ".webm"],
 }

+# Model weight file extensions recognised by scanners.
+# This is the union of all scanner extensions (lora, checkpoint, embedding).
+MODEL_FILE_EXTENSIONS = {
+    ".safetensors",
+    ".ckpt",
+    ".pt",
+    ".pt2",
+    ".bin",
+    ".pth",
+    ".pkl",
+    ".sft",
+    ".gguf",
+}
+
 # Valid sub-types for each scanner type
 VALID_LORA_SUB_TYPES = ["lora", "locon", "dora"]
 VALID_CHECKPOINT_SUB_TYPES = ["checkpoint", "diffusion_model"]
@@ -212,8 +226,21 @@ SUPPORTED_DOWNLOAD_SKIP_BASE_MODELS = frozenset(
        "Wan Video 2.5 I2V",
        "Hunyuan Video",
        "Anima",
+        "ACE Audio",
+        "Boogu",
        "Ernie",
        "Ernie Turbo",
+        "Grok",
+        "HappyHorse",
+        "HiDream-O1",
+        "Ideogram 4.0",
+        "Krea 2",
+        "Lens",
+        "MAI",
        "Nucleus",
+        "Qwen 2",
+        "Upscaler",
+        "Wan Image 2.7",
+        "Wan Video 2.7",
    ]
 )
--- a/py/utils/models.py
+++ b/py/utils/models.py
@@ -35,6 +35,9 @@ class BaseModelMetadata:
    metadata_source: Optional[str] = None  # Last provider that supplied metadata
    last_checked_at: float = 0  # Last checked timestamp
    hash_status: str = "completed"  # Hash calculation status: pending | calculating | completed | failed
+    trainedWords: List[str] = field(
+        default_factory=list
+    )  # Trigger words / activation prompts (source-agnostic)
    _unknown_fields: Dict[str, Any] = field(
        default_factory=dict, repr=False, compare=False
    )  # Store unknown fields
@@ -47,6 +50,9 @@ class BaseModelMetadata:
        if self.tags is None:
            self.tags = []

+        if self.trainedWords is None:
+            self.trainedWords = []
+
    @classmethod
    def from_dict(cls, data: Dict) -> "BaseModelMetadata":
        """Create instance from dictionary"""
--- a/static/css/components/lora-modal/lora-modal.css
+++ b/static/css/components/lora-modal/lora-modal.css
@@ -444,16 +444,161 @@
    flex: 1;
 }

-.base-model-selector {
-    width: 100%;
-    padding: 3px 5px;
+/* ── Base Model Search Dropdown ─────────────────────────────────────────── */
+
+.base-model-search-wrapper {
+    position: relative;
+    flex: 1;
+    min-width: 0;
+    z-index: 100;
+}
+
+.base-model-search-input-wrapper {
+    display: flex;
+    align-items: center;
    background: var(--bg-color);
    border: 1px solid var(--lora-accent);
    border-radius: var(--border-radius-xs);
+    padding: 0 6px;
+    gap: 4px;
+}
+
+.base-model-search-input-wrapper .search-icon {
+    color: var(--text-color);
+    opacity: 0.45;
+    font-size: 12px;
+    flex-shrink: 0;
+    pointer-events: none;
+    /* Reset global .search-icon rules from search-filter.css */
+    position: static;
+    right: auto;
+    top: auto;
+    transform: none;
+}
+
+.base-model-search-input {
+    flex: 1;
+    background: transparent;
+    border: none;
+    outline: none;
    color: var(--text-color);
    font-size: 0.9em;
-    outline: none;
-    margin-right: var(--space-1);
+    padding: 3px 0;
+    width: 100%;
+    min-width: 0;
+}
+
+.base-model-search-input::placeholder {
+    color: var(--text-color);
+    opacity: 0.35;
+}
+
+.base-model-dropdown {
+    position: absolute;
+    top: 100%;
+    left: -1px;
+    right: -1px;
+    max-height: 270px;
+    overflow-y: auto;
+    background: var(--bg-color);
+    border: 1px solid var(--lora-border);
+    border-top: none;
+    border-radius: 0 0 var(--border-radius-xs) var(--border-radius-xs);
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.22);
+    z-index: 101;
+}
+
+[data-theme="dark"] .base-model-dropdown {
+    box-shadow: 0 8px 28px rgba(0, 0, 0, 0.5);
+}
+
+/* Dropdown scrollbar styling */
+.base-model-dropdown::-webkit-scrollbar {
+    width: 6px;
+}
+
+.base-model-dropdown::-webkit-scrollbar-thumb {
+    background: var(--lora-border);
+    border-radius: 3px;
+}
+
+.base-model-dropdown::-webkit-scrollbar-track {
+    background: transparent;
+}
+
+/* Section */
+.base-model-dropdown-section {
+    border-bottom: 1px solid var(--lora-border);
+}
+
+.base-model-dropdown-section:last-child {
+    border-bottom: none;
+}
+
+/* Section header */
+.base-model-dropdown-header {
+    padding: 5px 10px;
+    font-size: 0.72em;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--text-color);
+    opacity: 0.5;
+    background: var(--surface-subtle);
+    position: sticky;
+    top: 0;
+    z-index: 1;
+}
+
+.base-model-dropdown-header.suggested-header {
+    color: var(--lora-accent);
+    opacity: 1;
+    background: oklch(from var(--lora-accent) l c h / 0.08);
+}
+
+.base-model-dropdown-header.suggested-header i {
+    margin-right: 4px;
+    font-size: 0.85em;
+}
+
+/* Dropdown items */
+.base-model-dropdown-item {
+    padding: 5px 12px;
+    cursor: pointer;
+    font-size: 0.9em;
+    color: var(--text-color);
+    transition: background 0.1s;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.base-model-dropdown-item:hover {
+    background: oklch(from var(--lora-accent) l c h / 0.1);
+}
+
+.base-model-dropdown-item.active {
+    background: oklch(from var(--lora-accent) l c h / 0.16);
+}
+
+.base-model-dropdown-item.selected {
+    font-weight: 600;
+}
+
+.base-model-dropdown-item.selected::after {
+    content: '✓';
+    float: right;
+    color: var(--lora-accent);
+    margin-left: 8px;
+}
+
+/* Empty state */
+.base-model-dropdown-empty {
+    padding: 18px 12px;
+    text-align: center;
+    color: var(--text-color);
+    opacity: 0.4;
+    font-size: 0.88em;
 }

 .size-wrapper {
--- 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/download-modal.css
+++ b/static/css/components/modal/download-modal.css
@@ -821,4 +821,66 @@

 [data-theme="dark"] .batch-preview-item {
    background: var(--lora-surface);
-}
+}
+
+.hf-badge {
+    display: inline-block;
+    padding: 1px 6px;
+    border-radius: 8px;
+    background: oklch(0.55 0.12 250 / 0.15);
+    color: oklch(0.7 0.12 250);
+    font-size: 0.75em;
+    font-weight: 600;
+    margin-left: 4px;
+}
+
+
+/* Checkbox inside HF batch preview items */
+.batch-preview-checkbox {
+    width: 18px;
+    height: 18px;
+    cursor: pointer;
+    accent-color: var(--lora-accent);
+    flex-shrink: 0;
+    padding: 0;
+    border: none;
+    margin: 0;
+}
+
+/* Select All toolbar in batch preview */
+.batch-preview-select-all {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 8px 12px;
+    border-bottom: 1px solid var(--border-color);
+    background: var(--lora-surface);
+    cursor: pointer;
+    position: sticky;
+    top: 0;
+    z-index: 1;
+}
+
+.batch-preview-select-all input[type="checkbox"] {
+    width: 18px;
+    height: 18px;
+    cursor: pointer;
+    accent-color: var(--lora-accent);
+    flex-shrink: 0;
+    padding: 0;
+    border: none;
+    margin: 0;
+}
+
+.batch-preview-select-all label {
+    cursor: pointer;
+    font-size: 0.9em;
+    color: var(--text-color);
+    font-weight: 500;
+    margin: 0;
+    user-select: none;
+}
+
+[data-theme="dark"] .batch-preview-select-all {
+    background: var(--lora-surface);
+}
--- 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/api/apiConfig.js
+++ b/static/js/api/apiConfig.js
@@ -190,6 +190,12 @@ export const DOWNLOAD_ENDPOINTS = {
    exampleImages: '/api/lm/force-download-example-images' // New endpoint for downloading example images
 };

+// Hugging Face API endpoints
+export const HF_ENDPOINTS = {
+    repoFiles: '/api/lm/hf-repo-files',
+    download: '/api/lm/download-hf-model',
+};
+
 // WebSocket endpoints
 export const WS_ENDPOINTS = {
    fetchProgress: '/ws/fetch-progress'
--- a/static/js/api/baseModelApi.js
+++ b/static/js/api/baseModelApi.js
@@ -7,6 +7,7 @@ import {
    getCurrentModelType,
    isValidModelType,
    DOWNLOAD_ENDPOINTS,
+    HF_ENDPOINTS,
    WS_ENDPOINTS
 } from './apiConfig.js';
 import { resetAndReload } from './modelApiFactory.js';
@@ -1243,6 +1244,48 @@ export class BaseModelApiClient {
        }
    }

+    async fetchHfRepoFiles(repo, revision = 'main') {
+        try {
+            const params = new URLSearchParams({ repo, revision });
+            const response = await fetch(`${HF_ENDPOINTS.repoFiles}?${params}`);
+            if (!response.ok) {
+                const err = await response.json().catch(() => ({}));
+                throw new Error(err.error || 'Failed to fetch HF repo files');
+            }
+            return await response.json();
+        } catch (error) {
+            console.error('Error fetching HF repo files:', error);
+            throw error;
+        }
+    }
+
+    async downloadHfModel({ repo, filename, revision, modelRoot, relativePath, useDefaultPaths, download_id }) {
+        try {
+            const response = await fetch(HF_ENDPOINTS.download, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    repo,
+                    filename,
+                    revision: revision || 'main',
+                    model_root: modelRoot,
+                    relative_path: relativePath || '',
+                    use_default_paths: useDefaultPaths || false,
+                    ...(download_id ? { download_id } : {}),
+                })
+            });
+
+            if (!response.ok) {
+                throw new Error(await response.text());
+            }
+
+            return await response.json();
+        } catch (error) {
+            console.error('Error downloading HF model:', error);
+            throw error;
+        }
+    }
+
    _buildQueryParams(baseParams, pageState) {
        const params = new URLSearchParams(baseParams);
        const isExcludedView = pageState.viewMode === 'excluded';
--- 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,6 +274,9 @@ export class BulkContextMenu extends BaseContextMenu {
            case 'resume-metadata-refresh':
                bulkManager.setSkipMetadataRefresh(false);
                break;
+            case 'enrich-hf-llm-bulk':
+                this.enrichBulkWithAgent();
+                break;
            case 'delete-all':
                bulkManager.showBulkDeleteModal();
                break;
@@ -363,4 +366,80 @@ export class BulkContextMenu extends BaseContextMenu {
            console.error('Bulk download example images failed:', error);
        }
    }
+
+    /**
+     * Enrich metadata for selected models via LLM agent skill.
+     */
+    async enrichBulkWithAgent() {
+        if (state.selectedModels.size === 0) {
+            return;
+        }
+
+        const { agentManager } = await import('../../managers/AgentManager.js');
+
+        const configured = await agentManager.isLlmConfigured();
+        if (!configured) {
+            showToast('toast.agent.llmNotConfigured', {}, 'warning');
+            return;
+        }
+
+        const modelPaths = [...state.selectedModels];
+
+        agentManager.connect();
+
+        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 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'
+                );
+            } else if (data.status === 'error') {
+                state.loadingManager.hide();
+                showToast(
+                    'toast.agent.enrichFailed',
+                    { error: data.error || 'Unknown error' },
+                    'error'
+                );
+            }
+        };
+        agentManager.onComplete(onComplete);
+
+        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 },
+                'error'
+            );
+        }
+    }
 }
--- a/static/js/components/ContextMenu/LoraContextMenu.js
+++ b/static/js/components/ContextMenu/LoraContextMenu.js
@@ -1,7 +1,8 @@
 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 } from '../../utils/uiHelpers.js';
+import { copyLoraSyntax, sendLoraToWorkflow, buildLoraSyntax, showToast } from '../../utils/uiHelpers.js';
 import { showExcludeModal, showDeleteModal } from '../../utils/modalUtils.js';
 import { moveManager } from '../../managers/MoveManager.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,6 +72,9 @@ export class LoraContextMenu extends BaseContextMenu {
            case 'refresh-metadata':
                getModelApiClient().refreshSingleModelMetadata(this.currentCard.dataset.filepath);
                break;
+            case 'enrich-hf-llm':
+                this.enrichWithAgent(this.currentCard.dataset.filepath);
+                break;
            case 'exclude':
                showExcludeModal(this.currentCard.dataset.filepath);
                break;
@@ -72,6 +84,61 @@ export class LoraContextMenu extends BaseContextMenu {
        }
    }

+    async enrichWithAgent(filePath) {
+        const { agentManager } = await import('../../managers/AgentManager.js');
+
+        const configured = await agentManager.isLlmConfigured();
+        if (!configured) {
+            showToast('toast.agent.llmNotConfigured', {}, 'warning');
+            return;
+        }
+
+        agentManager.connect();
+
+        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 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');
+            } else if (data.status === 'error') {
+                state.loadingManager.hide();
+                showToast('toast.agent.enrichFailed', { error: data.error || 'Unknown error' }, 'error');
+            }
+        };
+        agentManager.onComplete(onComplete);
+
+        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');
+        }
+    }
+
    sendLoraToWorkflow(replaceMode) {
        const card = this.currentCard;
        const usageTips = JSON.parse(card.dataset.usage_tips || '{}');
--- a/static/js/components/shared/ModelCard.js
+++ b/static/js/components/shared/ModelCard.js
@@ -1,4 +1,4 @@
-import { showToast, openCivitai, copyToClipboard, copyLoraSyntax, sendLoraToWorkflow, sendEmbeddingToWorkflow, openExampleImagesFolder, buildLoraSyntax, sendModelPathToWorkflow } from '../../utils/uiHelpers.js';
+import { showToast, openCivitai, openHuggingFace, copyToClipboard, copyLoraSyntax, sendLoraToWorkflow, sendEmbeddingToWorkflow, openExampleImagesFolder, buildLoraSyntax, sendModelPathToWorkflow } from '../../utils/uiHelpers.js';
 import { state, getCurrentPageState } from '../../state/index.js';
 import { showModelModal } from './ModelModal.js';
 import { toggleShowcase } from './showcase/ShowcaseView.js';
@@ -66,6 +66,8 @@ function handleModelCardEvent_internal(event, modelType) {
        event.stopPropagation();
        if (card.dataset.from_civitai === 'true') {
            openCivitai(card.dataset.filepath);
+        } else if (card.dataset.hf_url) {
+            openHuggingFace(card.dataset.hf_url);
        }
        return true; // Stop propagation
    }
@@ -313,6 +315,7 @@ async function showModelModalFromCard(card, modelType) {
        modified: card.dataset.modified,
        file_size: parseInt(card.dataset.file_size || '0'),
        from_civitai: card.dataset.from_civitai === 'true',
+        hf_url: card.dataset.hf_url || '',
        base_model: card.dataset.base_model,
        notes: card.dataset.notes || '',
        favorite: card.dataset.favorite === 'true',
@@ -401,6 +404,7 @@ function showExampleAccessModal(card, modelType) {
                modified: card.dataset.modified,
                file_size: card.dataset.file_size,
                from_civitai: card.dataset.from_civitai === 'true',
+                hf_url: card.dataset.hf_url || '',
                base_model: card.dataset.base_model,
                notes: card.dataset.notes,
                favorite: card.dataset.favorite === 'true',
@@ -467,6 +471,7 @@ export function createModelCard(model, modelType) {
    card.dataset.base_model = model.base_model || 'Unknown';
    card.dataset.favorite = model.favorite ? 'true' : 'false';
    card.dataset.exclude = model.exclude ? 'true' : 'false';
+    card.dataset.hf_url = model.hf_url || '';
    const hasUpdateAvailable = Boolean(model.update_available);
    card.dataset.update_available = hasUpdateAvailable ? 'true' : 'false';
    card.dataset.skip_metadata_refresh = model.skip_metadata_refresh ? 'true' : 'false';
@@ -578,7 +583,10 @@ export function createModelCard(model, modelType) {
        translate('modelCard.actions.addToFavorites', {}, 'Add to favorites');
    const globeTitle = model.from_civitai ?
        translate('modelCard.actions.viewOnCivitai', {}, 'View on Civitai') :
-        translate('modelCard.actions.notAvailableFromCivitai', {}, 'Not available from Civitai');
+        model.hf_url ?
+            translate('modelCard.actions.viewOnHuggingFace', {}, 'View on Hugging Face') :
+            translate('modelCard.actions.notAvailableFromCivitai', {}, 'Not available from Civitai');
+    const globeEnabled = model.from_civitai || !!model.hf_url;
    let sendTitle;
    let copyTitle;
    if (modelType === MODEL_TYPES.LORA) {
@@ -603,7 +611,7 @@ export function createModelCard(model, modelType) {
        </i>
        <i class="fas fa-globe" 
           title="${globeTitle}"
-           ${!model.from_civitai ? 'style="opacity: 0.5; cursor: not-allowed"' : ''}>
+           ${!globeEnabled ? 'style="opacity: 0.5; cursor: not-allowed"' : ''}>
        </i>
        <i class="fas fa-paper-plane" 
           title="${sendTitle}">
--- a/static/js/components/shared/ModelMetadata.js
+++ b/static/js/components/shared/ModelMetadata.js
@@ -3,9 +3,75 @@
 * Handles model metadata editing functionality - General version
 */

-import { BASE_MODEL_CATEGORIES } from '../../utils/constants.js';
+import { BASE_MODEL_CATEGORIES, getMergedBaseModels } from '../../utils/constants.js';
 import { showToast } from '../../utils/uiHelpers.js';
 import { getModelApiClient } from '../../api/modelApiFactory.js';
+import { translate } from '../../utils/i18nHelpers.js';
+
+// ── Filename-based base model inference ──────────────────────────────────────
+// Rules are ordered by specificity — first match wins for dedup.
+// Each rule checks the filename (lowercased) for a regex pattern and suggests
+// the associated base model values.
+
+const BASE_MODEL_FILENAME_RULES = [
+    { pattern: /flux\.?\s*2\s*klein/i, models: ['Flux.2 Klein 9B', 'Flux.2 Klein 9B-base', 'Flux.2 Klein 4B', 'Flux.2 Klein 4B-base'] },
+    { pattern: /flux\.?\s*2/i, models: ['Flux.2 D', 'Flux.2 Klein 9B', 'Flux.2 Klein 4B'] },
+    { pattern: /flux\.?\s*1\s*(dev|d)\b/i, models: ['Flux.1 D'] },
+    { pattern: /flux\.?\s*1\s*(schnell|s)\b/i, models: ['Flux.1 S'] },
+    { pattern: /flux/i, models: ['Flux.1 D', 'Flux.1 S', 'Flux.2 D'] },
+    { pattern: /sdxl/i, models: ['SDXL 1.0', 'SDXL Lightning', 'SDXL Hyper'] },
+    { pattern: /sd\s*1[._-\s]?5/i, models: ['SD 1.5'] },
+    { pattern: /sd\s*1[._-\s]?4/i, models: ['SD 1.4'] },
+    { pattern: /sd\s*1/i, models: ['SD 1.5', 'SD 1.4', 'SD 1.5 LCM', 'SD 1.5 Hyper'] },
+    { pattern: /sd\s*3[._-\s]?5/i, models: ['SD 3.5', 'SD 3.5 Medium', 'SD 3.5 Large', 'SD 3.5 Large Turbo'] },
+    { pattern: /sd\s*3/i, models: ['SD 3', 'SD 3.5'] },
+    { pattern: /wan\s*\.?\s*video/i, models: ['Wan Video', 'Wan Video 1.3B t2v', 'Wan Video 14B t2v', 'Wan Video 14B i2v 480p', 'Wan Video 14B i2v 720p'] },
+    { pattern: /hunyuan\s*\.?\s*video/i, models: ['Hunyuan Video'] },
+    { pattern: /ltxv/i, models: ['LTXV', 'LTXV2', 'LTXV 2.3'] },
+    { pattern: /cogvideo/i, models: ['CogVideoX'] },
+    { pattern: /pony/i, models: ['Pony', 'Pony V7'] },
+    { pattern: /illustrious/i, models: ['Illustrious'] },
+    { pattern: /noobai/i, models: ['NoobAI'] },
+    { pattern: /pixart/i, models: ['PixArt a', 'PixArt E'] },
+    { pattern: /aura\s*\.?\s*flow/i, models: ['AuraFlow'] },
+    { pattern: /kolors/i, models: ['Kolors'] },
+    { pattern: /hunyuan\s*1/i, models: ['Hunyuan 1'] },
+    { pattern: /lumina/i, models: ['Lumina'] },
+    { pattern: /hidream/i, models: ['HiDream'] },
+    { pattern: /qwen/i, models: ['Qwen'] },
+    { pattern: /chroma/i, models: ['Chroma'] },
+    { pattern: /anima/i, models: ['Anima'] },
+    { pattern: /sd\s*2[._-\s]?[01]/i, models: ['SD 2.0', 'SD 2.1'] },
+    { pattern: /mochi/i, models: ['Mochi'] },
+    { pattern: /svd/i, models: ['SVD'] },
+    { pattern: /zimage/i, models: ['ZImageTurbo', 'ZImageBase'] },
+    { pattern: /nucleus/i, models: ['Nucleus'] },
+    { pattern: /krea/i, models: ['Flux.1 Krea', 'Krea 2'] },
+    { pattern: /ernie/i, models: ['Ernie', 'Ernie Turbo'] },
+];
+
+/**
+ * Infer likely base model(s) from a filename + model name string.
+ * Returns a deduplicated array in match-priority order.
+ * @param {string} filename
+ * @returns {string[]}
+ */
+function inferBaseModelsFromFilename(filename) {
+    if (!filename || typeof filename !== 'string') return [];
+    const seen = new Set();
+    const results = [];
+    for (const rule of BASE_MODEL_FILENAME_RULES) {
+        if (rule.pattern.test(filename)) {
+            for (const model of rule.models) {
+                if (!seen.has(model)) {
+                    seen.add(model);
+                    results.push(model);
+                }
+            }
+        }
+    }
+    return results;
+}

 /**
 * Resolve the active file path for the currently open model modal.
@@ -226,7 +292,9 @@ export function setupModelNameEditing(filePath) {
 }

 /**
- * Set up base model editing functionality
+ * Set up base model editing functionality with searchable dropdown
+ * Shows filename-inferred suggestions at the top, supports keyboard navigation,
+ * and allows typing custom values.
 * @param {string} filePath - File path
 */
 export function setupBaseModelEditing(filePath) {
@@ -257,98 +325,251 @@ export function setupBaseModelEditing(filePath) {
        // Store the original value to check for changes later
        const originalValue = baseModelContent.textContent.trim();
        
-        // Create dropdown selector to replace the base model content
-        const currentValue = originalValue;
-        const dropdown = document.createElement('select');
-        dropdown.className = 'base-model-selector';
+        // ── Build the full option list ────────────────────────────────────────
+        const allModels = []; // { value, label, category }
+        const categorizedModels = new Set();
        
-        // Flag to track if a change was made
-        let valueChanged = false;
-        
-        // Add options from BASE_MODEL_CATEGORIES constants
-        const baseModelCategories = BASE_MODEL_CATEGORIES;
-        
-        // Create option groups for better organization
-        Object.entries(baseModelCategories).forEach(([category, models]) => {
-            const group = document.createElement('optgroup');
-            group.label = category;
-            
+        Object.entries(BASE_MODEL_CATEGORIES).forEach(([category, models]) => {
            models.forEach(model => {
-                const option = document.createElement('option');
-                option.value = model;
-                option.textContent = model;
-                option.selected = model === currentValue;
-                group.appendChild(option);
+                allModels.push({ value: model, label: model, category });
+                categorizedModels.add(model);
+            });
+        });
+        
+        const mergedModels = getMergedBaseModels();
+        const uncategorizedModels = mergedModels.filter(model => !categorizedModels.has(model));
+        if (uncategorizedModels.length > 0) {
+            uncategorizedModels.forEach(model => {
+                allModels.push({ value: model, label: model, category: 'Other (API)' });
+            });
+        }
+        
+        // ── Filename-based inference ──────────────────────────────────────────
+        const fileName = (document.querySelector('.file-name-content')?.textContent || '') + ' ' +
+                         (document.querySelector('.model-name-content')?.textContent || '');
+        const inferredModels = inferBaseModelsFromFilename(fileName);
+        const inferredSet = new Set(inferredModels);
+        
+        // ── Build search widget DOM ───────────────────────────────────────────
+        const wrapper = document.createElement('div');
+        wrapper.className = 'base-model-search-wrapper';
+        
+        // Search input row
+        const inputWrapper = document.createElement('div');
+        inputWrapper.className = 'base-model-search-input-wrapper';
+        const searchIcon = document.createElement('i');
+        searchIcon.className = 'fas fa-search search-icon';
+        searchIcon.setAttribute('aria-hidden', 'true');
+        inputWrapper.appendChild(searchIcon);
+        const searchInput = document.createElement('input');
+        searchInput.type = 'text';
+        searchInput.className = 'base-model-search-input';
+        searchInput.placeholder = translate('modals.model.metadata.baseModelSearchPlaceholder', {}, 'Search base model…');
+        searchInput.autocomplete = 'off';
+        searchInput.spellcheck = false;
+        inputWrapper.appendChild(searchInput);
+        wrapper.appendChild(inputWrapper);
+        
+        // Dropdown list
+        const dropdown = document.createElement('div');
+        dropdown.className = 'base-model-dropdown';
+        wrapper.appendChild(dropdown);
+        
+        // ── Render ────────────────────────────────────────────────────────────
+        function renderDropdown(filterText) {
+            const lowerFilter = (filterText || '').toLowerCase().trim();
+            dropdown.innerHTML = '';
+            let hasVisibleItems = false;
+            const fragment = document.createDocumentFragment();
+            
+            // 1. Suggested section (filename-inferred, filtered by search)
+            let suggestedToShow = inferredModels;
+            if (lowerFilter) {
+                suggestedToShow = inferredModels.filter(m =>
+                    m.toLowerCase().includes(lowerFilter)
+                );
+            }
+            
+            if (suggestedToShow.length > 0) {
+                const section = document.createElement('div');
+                section.className = 'base-model-dropdown-section';
+                
+                const header = document.createElement('div');
+                header.className = 'base-model-dropdown-header suggested-header';
+                header.innerHTML = '<i class="fas fa-star" aria-hidden="true"></i> ' +
+                    translate('modals.model.metadata.baseModelSuggested', {}, 'Suggested');
+                section.appendChild(header);
+                
+                suggestedToShow.forEach(model => {
+                    const item = document.createElement('div');
+                    item.className = 'base-model-dropdown-item';
+                    if (model === originalValue) item.classList.add('selected');
+                    item.dataset.value = model;
+                    item.textContent = model;
+                    section.appendChild(item);
+                    hasVisibleItems = true;
+                });
+                
+                fragment.appendChild(section);
+            }
+            
+            // 2. Categorized options (deduplicated against suggestions)
+            const categoryMap = {};
+            allModels.forEach(m => {
+                if (inferredSet.has(m.value)) return; // already shown in Suggested
+                if (lowerFilter && !m.label.toLowerCase().includes(lowerFilter)) return;
+                if (!categoryMap[m.category]) categoryMap[m.category] = [];
+                categoryMap[m.category].push(m);
            });
            
-            dropdown.appendChild(group);
+            Object.entries(categoryMap).forEach(([category, items]) => {
+                if (items.length === 0) return;
+                const section = document.createElement('div');
+                section.className = 'base-model-dropdown-section';
+                
+                const header = document.createElement('div');
+                header.className = 'base-model-dropdown-header';
+                header.textContent = category;
+                section.appendChild(header);
+                
+                items.forEach(m => {
+                    const item = document.createElement('div');
+                    item.className = 'base-model-dropdown-item';
+                    if (m.value === originalValue) item.classList.add('selected');
+                    item.dataset.value = m.value;
+                    item.textContent = m.label;
+                    section.appendChild(item);
+                    hasVisibleItems = true;
+                });
+                
+                fragment.appendChild(section);
+            });
+            
+            // 3. Empty state
+            if (!hasVisibleItems) {
+                const empty = document.createElement('div');
+                empty.className = 'base-model-dropdown-empty';
+                empty.textContent = translate('modals.model.metadata.baseModelNoMatch', {}, 'No matching base models');
+                fragment.appendChild(empty);
+            }
+            
+            dropdown.appendChild(fragment);
+            
+            // Scroll the selected item into view
+            const selected = dropdown.querySelector('.base-model-dropdown-item.selected');
+            if (selected) {
+                selected.scrollIntoView({ block: 'nearest' });
+            }
+        }
+        
+        // Initial render — show everything
+        renderDropdown('');
+        
+        // ── Events ────────────────────────────────────────────────────────────
+        let filterTimeout;
+        searchInput.addEventListener('input', () => {
+            clearTimeout(filterTimeout);
+            filterTimeout = setTimeout(() => renderDropdown(searchInput.value), 50);
        });
        
-        // Replace content with dropdown
+        // Click to select
+        dropdown.addEventListener('click', (e) => {
+            const item = e.target.closest('.base-model-dropdown-item');
+            if (!item) return;
+            baseModelContent.textContent = item.dataset.value;
+            cleanup();
+            const finalValue = baseModelContent.textContent.trim();
+            if (finalValue !== originalValue) {
+                saveBaseModel(
+                    getActiveModalFilePath(baseModelContent.dataset.filePath),
+                    originalValue
+                );
+            }
+        });
+        
+        // Replace content with search widget
        baseModelContent.style.display = 'none';
-        baseModelDisplay.insertBefore(dropdown, editBtn);
-        
-        // Hide edit button during editing
        editBtn.style.display = 'none';
+        baseModelDisplay.insertBefore(wrapper, editBtn);
+        searchInput.focus();
        
-        // Focus the dropdown
-        dropdown.focus();
-        
-        // Handle dropdown change
-        dropdown.addEventListener('change', function() {
-            const selectedModel = this.value;
-            baseModelContent.textContent = selectedModel;
-            
-            // Mark that a change was made if the value differs from original
-            if (selectedModel !== originalValue) {
-                valueChanged = true;
-            } else {
-                valueChanged = false;
+        // ── Cleanup ───────────────────────────────────────────────────────────
+        function cleanup() {
+            if (wrapper.parentNode === baseModelDisplay) {
+                baseModelDisplay.removeChild(wrapper);
            }
-        });
-        
-        // Function to save changes and exit edit mode
-        const saveAndExit = function() {
-            // Check if dropdown still exists and remove it
-            if (dropdown && dropdown.parentNode === baseModelDisplay) {
-                baseModelDisplay.removeChild(dropdown);
-            }
-            
-            // Show the content and edit button
            baseModelContent.style.display = '';
            editBtn.style.display = '';
-            
-            // Remove editing class
            baseModelDisplay.classList.remove('editing');
-            
-            // Only save if the value has actually changed
-            if (valueChanged || baseModelContent.textContent.trim() !== originalValue) {
-                const resolvedPath = getActiveModalFilePath(baseModelContent.dataset.filePath);
-                saveBaseModel(resolvedPath, originalValue);
-            }
-            
-            // Remove this event listener
            document.removeEventListener('click', outsideClickHandler);
-        };
+        }
        
-        // Handle outside clicks to save and exit
+        // Outside click → save typed/custom value if any
        const outsideClickHandler = function(e) {
-            // If click is outside the dropdown and base model display
-            if (!baseModelDisplay.contains(e.target)) {
-                saveAndExit();
+            if (wrapper.contains(e.target)) return;
+            
+            // If user typed a custom value (not just empty), apply it
+            const typedValue = searchInput.value.trim();
+            if (typedValue) {
+                baseModelContent.textContent = typedValue;
+            }
+            cleanup();
+            const finalValue = baseModelContent.textContent.trim();
+            if (finalValue !== originalValue) {
+                saveBaseModel(
+                    getActiveModalFilePath(baseModelContent.dataset.filePath),
+                    originalValue
+                );
            }
        };
        
-        // Add delayed event listener for outside clicks
+        // Defer listener to avoid the opening click itself
        setTimeout(() => {
            document.addEventListener('click', outsideClickHandler);
        }, 0);
        
-        // Also handle dropdown blur event
-        dropdown.addEventListener('blur', function(e) {
-            // Only save if the related target is not the edit button or inside the baseModelDisplay
-            if (!baseModelDisplay.contains(e.relatedTarget)) {
-                saveAndExit();
+        // Keyboard navigation
+        searchInput.addEventListener('keydown', function onKeydown(e) {
+            const items = Array.from(dropdown.querySelectorAll('.base-model-dropdown-item'));
+            const activeIdx = items.findIndex(el => el.classList.contains('active'));
+            
+            if (e.key === 'ArrowDown') {
+                e.preventDefault();
+                items.forEach(el => el.classList.remove('active'));
+                const next = Math.min(activeIdx + 1, items.length - 1);
+                if (items[next]) {
+                    items[next].classList.add('active');
+                    items[next].scrollIntoView({ block: 'nearest' });
+                }
+            } else if (e.key === 'ArrowUp') {
+                e.preventDefault();
+                items.forEach(el => el.classList.remove('active'));
+                const prev = Math.max(activeIdx - 1, 0);
+                if (items[prev]) {
+                    items[prev].classList.add('active');
+                    items[prev].scrollIntoView({ block: 'nearest' });
+                }
+            } else if (e.key === 'Enter') {
+                e.preventDefault();
+                const activeItem = items.find(el => el.classList.contains('active'));
+                if (activeItem) {
+                    activeItem.click();
+                } else if (searchInput.value.trim()) {
+                    // Custom value typed
+                    baseModelContent.textContent = searchInput.value.trim();
+                    cleanup();
+                    const finalValue = baseModelContent.textContent.trim();
+                    if (finalValue !== originalValue) {
+                        saveBaseModel(
+                            getActiveModalFilePath(baseModelContent.dataset.filePath),
+                            originalValue
+                        );
+                    }
+                }
+            } else if (e.key === 'Escape') {
+                e.preventDefault();
+                baseModelContent.textContent = originalValue;
+                cleanup();
            }
        });
    });
--- a/static/js/components/shared/ModelModal.js
+++ b/static/js/components/shared/ModelModal.js
@@ -360,6 +360,11 @@ export async function showModelModal(model, modelType) {
    const viewOnCivitaiAction = modelWithFullData.from_civitai ? `
 <div class="civitai-view" title="${translate('modals.model.actions.viewOnCivitai', {}, 'View on Civitai')}" data-action="view-civitai" data-filepath="${escapedFilePathAttr}">
    <i class="fas fa-globe"></i> ${translate('modals.model.actions.viewOnCivitaiText', {}, 'View on Civitai')}
+</div>`.trim() : '';
+    const escapedHfUrl = modelWithFullData.hf_url ? escapeAttribute(modelWithFullData.hf_url) : '';
+    const viewOnHuggingFaceAction = escapedHfUrl ? `
+<div class="civitai-view" title="${translate('modals.model.actions.viewOnHuggingFace', {}, 'View on Hugging Face')}" data-action="view-huggingface" data-hf-url="${escapedHfUrl}">
+    <i class="fas fa-globe"></i> ${translate('modals.model.actions.viewOnHuggingFaceText', {}, 'View on Hugging Face')}
 </div>`.trim() : '';
    const creatorInfoAction = modelWithFullData.civitai?.creator ? `
 <div class="creator-info" data-username="${modelWithFullData.civitai.creator.username}" data-action="view-creator" title="${translate('modals.model.actions.viewCreatorProfile', {}, 'View Creator Profile')}">
@@ -377,6 +382,9 @@ export async function showModelModal(model, modelType) {
    if (viewOnCivitaiAction) {
        creatorActionItems.push(indentMarkup(viewOnCivitaiAction, 24));
    }
+    if (viewOnHuggingFaceAction) {
+        creatorActionItems.push(indentMarkup(viewOnHuggingFaceAction, 24));
+    }
    if (creatorInfoAction) {
        creatorActionItems.push(indentMarkup(creatorInfoAction, 24));
    }
@@ -869,6 +877,11 @@ function setupEventHandlers(filePath, modelType) {
            case 'view-civitai':
                openCivitai(target.dataset.filepath);
                break;
+            case 'view-huggingface':
+                if (target.dataset.hfUrl) {
+                    window.open(target.dataset.hfUrl, '_blank', 'noopener,noreferrer');
+                }
+                break;
            case 'view-creator':
                const username = target.dataset.username;
                if (username) {
--- 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
@@ -0,0 +1,209 @@
+/**
+ * AgentManager — WebSocket listener for agent skill progress events.
+ *
+ * Connects to the generic WebSocket endpoint and filters for
+ * `type: "agent_progress"` messages.  Dispatches progress and completion
+ * events to registered callbacks.
+ */
+class AgentManager {
+    constructor() {
+        this.websocket = null;
+        this.progressCallbacks = [];
+        this.completeCallbacks = [];
+        this.errorCallbacks = [];
+        this.connected = false;
+    }
+
+    /**
+     * Connect to the WebSocket endpoint for agent progress events.
+     * Safe to call multiple times — won't reconnect if already connected.
+     */
+    connect() {
+        if (this.connected && this.websocket?.readyState === WebSocket.OPEN) {
+            return;
+        }
+
+        const wsProtocol = window.location.protocol === 'https:' ? 'wss://' : 'ws://';
+        try {
+            this.websocket = new WebSocket(
+                `${wsProtocol}${window.location.host}/ws/fetch-progress`
+            );
+        } catch (e) {
+            console.error('AgentManager: Failed to create WebSocket:', e);
+            return;
+        }
+
+        this.websocket.onopen = () => {
+            this.connected = true;
+            console.debug('AgentManager: WebSocket connected');
+        };
+
+        this.websocket.onmessage = (event) => {
+            try {
+                const data = JSON.parse(event.data);
+                if (data.type !== 'agent_progress') return;
+                this._dispatch(data);
+            } catch (e) {
+                // Not JSON or wrong format — ignore
+            }
+        };
+
+        this.websocket.onerror = (error) => {
+            console.error('AgentManager: WebSocket error:', error);
+            this.connected = false;
+        };
+
+        this.websocket.onclose = () => {
+            this.connected = false;
+            console.debug('AgentManager: WebSocket closed');
+        };
+    }
+
+    /**
+     * Dispatch a parsed agent event to the appropriate callbacks.
+     * @param {Object} data - The parsed WebSocket message
+     */
+    _dispatch(data) {
+        const { status, skill } = data;
+
+        if (status === 'error') {
+            this.errorCallbacks.forEach((cb) => {
+                try {
+                    cb(data);
+                } catch (e) {
+                    console.error('AgentManager error callback failed:', e);
+                }
+            });
+            return;
+        }
+
+        if (status === 'completed') {
+            this.completeCallbacks.forEach((cb) => {
+                try {
+                    cb(data);
+                } catch (e) {
+                    console.error('AgentManager complete callback failed:', e);
+                }
+            });
+            return;
+        }
+
+        // started, processing — general progress
+        this.progressCallbacks.forEach((cb) => {
+            try {
+                cb(data);
+            } catch (e) {
+                console.error('AgentManager progress callback failed:', e);
+            }
+        });
+    }
+
+    /**
+     * Register a callback for progress events (started, processing).
+     * @param {Function} callback - Receives the event data
+     */
+    onProgress(callback) {
+        this.progressCallbacks.push(callback);
+    }
+
+    /**
+     * Register a callback for completion events.
+     * @param {Function} callback - Receives the event data
+     */
+    onComplete(callback) {
+        this.completeCallbacks.push(callback);
+    }
+
+    /**
+     * Register a callback for error events.
+     * @param {Function} callback - Receives the event data
+     */
+    onError(callback) {
+        this.errorCallbacks.push(callback);
+    }
+
+    /**
+     * Clear all registered callbacks.
+     */
+    clearCallbacks() {
+        this.progressCallbacks = [];
+        this.completeCallbacks = [];
+        this.errorCallbacks = [];
+    }
+
+    /**
+     * Execute an agent skill on the provided model paths.
+     *
+     * @param {string} skillName - The skill to execute
+     * @param {string[]} modelPaths - Model file paths to process
+     * @returns {Promise<Object>} The response JSON
+     */
+    async executeSkill(skillName, modelPaths) {
+        const response = await fetch(
+            `/api/lm/agent/execute/${encodeURIComponent(skillName)}`,
+            {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ model_paths: modelPaths }),
+            }
+        );
+
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            throw new Error(
+                errorData.error || `HTTP ${response.status}: ${response.statusText}`
+            );
+        }
+
+        return response.json();
+    }
+
+    /**
+     * Check if the LLM provider is configured.
+     *
+     * Returns true when both an API key and a model name are set.
+     *
+     * @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');
+            if (!response.ok) return false;
+            const data = await response.json();
+            const provider = data.settings?.llm_provider;
+            const hasModel = !!data.settings?.llm_model;
+            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;
+        }
+    }
+
+    /**
+     * Get the list of available agent skills.
+     *
+     * @returns {Promise<Array>}
+     */
+    async listSkills() {
+        const response = await fetch('/api/lm/agent/skills');
+        if (!response.ok) return [];
+        const data = await response.json();
+        return data.skills || [];
+    }
+}
+
+// Export as singleton
+export const agentManager = new AgentManager();
--- a/static/js/managers/DownloadManager.js
+++ b/static/js/managers/DownloadManager.js
@@ -7,6 +7,7 @@ import { getStorageItem, setStorageItem } from '../utils/storageHelpers.js';
 import { FolderTreeManager } from '../components/FolderTreeManager.js';
 import { translate } from '../utils/i18nHelpers.js';
 import { extractCivitaiModelUrlParts } from '../utils/civitaiUtils.js';
+import { formatFileSize } from '../utils/formatters.js';

 export class DownloadManager {
    constructor() {
@@ -27,6 +28,10 @@ export class DownloadManager {
        this.isBatchMode = false;
        this.editingBatchIndex = -1;

+        // HF download state
+        this.hfRepoId = null;
+        this.hfSelectedFiles = [];
+
        this.loadingManager = new LoadingManager();
        this.folderTreeManager = new FolderTreeManager();
        this.folderClickHandler = null;
@@ -44,6 +49,8 @@ export class DownloadManager {
        this.handleToggleDefaultPath = this.toggleDefaultPath.bind(this);
        this.handleBackToUrlFromBatch = this.backToUrlFromBatch.bind(this);
        this.handleNextFromBatch = this.nextFromBatch.bind(this);
+
+
    }

    showDownloadModal() {
@@ -99,6 +106,8 @@ export class DownloadManager {

        // Default path toggle handler
        document.getElementById('useDefaultPath').addEventListener('change', this.handleToggleDefaultPath);
+
+
    }

    updateModalLabels() {
@@ -160,6 +169,10 @@ export class DownloadManager {

        // Reset default path toggle
        this.loadDefaultPathSetting();
+
+        // Reset HF state
+        this.hfRepoId = null;
+        this.hfSelectedFiles = [];
    }

    async retrieveVersionsForModel(modelId, source = null) {
@@ -180,6 +193,29 @@ export class DownloadManager {
            return;
        }

+        // Detect URL types — all URLs must share the same source type
+        const urlTypes = urls.map(u => DownloadManager.detectUrlType(u));
+        const isHf = urlTypes.every(t => t && (t.type === 'hf-resolve' || t.type === 'hf-repo'));
+        const isCivitai = urlTypes.every(t => t && t.type === 'civitai');
+
+        if (!isHf && !isCivitai) {
+            const allValid = urlTypes.every(t => t !== null);
+            if (!allValid) {
+                errorElement.textContent = translate('modals.download.errors.invalidUrl');
+                return;
+            }
+            // Mixed sources not supported in one batch
+            if (urls.length > 1) {
+                errorElement.textContent = translate('modals.download.errors.mixedSources');
+                return;
+            }
+        }
+
+        if (isHf) {
+            return this._validateAndFetchHf(urls, errorElement);
+        }
+
+        // --- Original CivitAI flow below ---
        if (urls.length === 1) {
            this.isBatchMode = false;
            try {
@@ -271,6 +307,112 @@ export class DownloadManager {
        this.showBatchPreviewStep();
    }

+    // ---- Hugging Face download flow ----
+
+    async _validateAndFetchHf(urls, errorElement) {
+        if (urls.length === 1) {
+            const info = DownloadManager.detectUrlType(urls[0]);
+            // Direct file resolve URL → skip file selection, go to location
+            if (info.type === 'hf-resolve') {
+                this.isBatchMode = false;
+                this.hfRepoId = info.repo;
+                this.hfSelectedFiles = [info.filename];
+                this.source = 'huggingface';
+                this.proceedToLocation();
+                return;
+            }
+            // Repo URL → fetch file list and convert to batch items
+            try {
+                this.loadingManager.showSimpleLoading(translate('modals.download.fetchingRepoFiles'));
+                const files = await this.apiClient.fetchHfRepoFiles(info.repo);
+                if (!files || files.length === 0) {
+                    throw new Error(translate('modals.download.errors.noModelFiles'));
+                }
+                this.isBatchMode = true;
+                this.batchModels = [];
+                this.source = 'huggingface';
+                for (const file of files) {
+                    this.batchModels.push({
+                        url: urls[0],
+                        source: 'huggingface',
+                        repo: info.repo,
+                        filename: file.filename,
+                        revision: 'main',
+                        displayName: file.filename,
+                        fileSizeBytes: file.size,
+                        selectedVersion: true,
+                        versions: [],
+                        checked: false,
+                        error: null,
+                    });
+                }
+                this.showBatchPreviewStep();
+            } catch (err) {
+                errorElement.textContent = err.message;
+            } finally {
+                this.loadingManager.hide();
+            }
+            return;
+        }
+
+        // Multiple HF URLs → batch mode: flatten all files from all repos
+        this.isBatchMode = true;
+        this.batchModels = [];
+        this.source = 'huggingface';
+        this.loadingManager.showSimpleLoading(translate('modals.download.fetchingRepoFiles'));
+
+        for (const url of urls) {
+            const info = DownloadManager.detectUrlType(url);
+            if (!info) {
+                this.batchModels.push({ url, error: 'Invalid URL', versions: [], selectedVersion: null });
+                continue;
+            }
+            if (info.type === 'hf-resolve') {
+                this.batchModels.push({
+                    url,
+                    source: 'huggingface',
+                    repo: info.repo,
+                    filename: info.filename,
+                    revision: info.revision || 'main',
+                    displayName: info.filename,
+                    selectedVersion: true,
+                    versions: [],
+                    checked: false,
+                    error: null,
+                });
+            } else if (info.type === 'hf-repo') {
+                try {
+                    const files = await this.apiClient.fetchHfRepoFiles(info.repo);
+                    if (!files || files.length === 0) {
+                        this.batchModels.push({ url, error: 'No model files found', versions: [], selectedVersion: null });
+                        continue;
+                    }
+                    // Flatten: create one batch item per file, all checked by default
+                    for (const file of files) {
+                        this.batchModels.push({
+                            url,
+                            source: 'huggingface',
+                            repo: info.repo,
+                            filename: file.filename,
+                            revision: 'main',
+                            displayName: file.filename,
+                            fileSizeBytes: file.size,
+                            selectedVersion: true,
+                            versions: [],
+                            checked: false,
+                            error: null,
+                        });
+                    }
+                } catch (err) {
+                    this.batchModels.push({ url, error: err.message, versions: [], selectedVersion: null });
+                }
+            }
+        }
+
+        this.loadingManager.hide();
+        this.showBatchPreviewStep();
+    }
+
    async fetchVersionsForCurrentModel() {
        const errorElement = document.getElementById('urlError');
        if (errorElement) {
@@ -311,6 +453,60 @@ export class DownloadManager {
        return { modelId: null, modelVersionId: null, source: null };
    }

+    /**
+     * Detect the source type of a download URL.
+     * @param {string} url
+     * @returns {{ type: string, repo?: string, filename?: string, revision?: string } | null}
+     *   type: 'civitai' | 'civarchive' | 'hf-resolve' | 'hf-repo' | 'direct-http'
+     */
+    static detectUrlType(url) {
+        const trimmed = url.trim();
+        if (!trimmed) return null;
+
+        // CivitAI
+        if (/civitai\.com\/models\//i.test(trimmed) || /civitaiarchive|civarchive/i.test(trimmed)) {
+            // Will be parsed by existing CivitAI logic
+            return { type: 'civitai' };
+        }
+
+        // Hugging Face resolve URL → direct file
+        const hfResolveMatch = trimmed.match(/huggingface\.co\/([^/\s]+\/[^/\s]+)\/resolve\/([^/\s]+)\/(.+)/i);
+        if (hfResolveMatch) {
+            return {
+                type: 'hf-resolve',
+                repo: hfResolveMatch[1],
+                revision: hfResolveMatch[2],
+                filename: hfResolveMatch[3],
+            };
+        }
+
+        // Hugging Face repo URL (huggingface.co/user/repo or bare user/repo path)
+        // Require huggingface.co prefix for full URLs; bare user/repo only without ://
+        const hfRepoMatch = trimmed.match(
+            trimmed.includes('://')
+                ? /^https?:\/\/huggingface\.co\/([a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+)(?:\/?$|$)/
+                : /^([a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+)$/
+        );
+        if (hfRepoMatch) {
+            // Reject path-traversal patterns like "../.." or "user/.."
+            const parts = hfRepoMatch[1].split('/');
+            if (parts.some(p => p === '.' || p === '..')) {
+                return null;
+            }
+            return {
+                type: 'hf-repo',
+                repo: hfRepoMatch[1],
+            };
+        }
+
+        // Direct HTTP(S) URL (non-HF)
+        if (/^https?:\/\//i.test(trimmed)) {
+            return { type: 'direct-http' };
+        }
+
+        return null;
+    }
+
    extractModelId(url) {
        const result = DownloadManager.parseModelUrl(url);
        this.modelVersionId = result.modelVersionId;
@@ -559,8 +755,8 @@ export class DownloadManager {
            return;
        }

-        // In single-URL mode, validate version selection
-        if (!this.isBatchMode) {
+        // In single-URL mode, validate version selection (skip for HF)
+        if (!this.isBatchMode && this.source !== 'huggingface') {
            if (!this.currentVersion) {
                showToast('toast.loras.pleaseSelectVersion', {}, 'error');
                return;
@@ -784,6 +980,77 @@ export class DownloadManager {
        }
    }

+    async _downloadHfSingle({ modelRoot, targetFolder, useDefaultPaths }) {
+        modalManager.closeModal('downloadModal');
+        this.loadingManager.restoreProgressBar();
+        const totalFiles = this.hfSelectedFiles.length;
+        const updateProgress = this.loadingManager.showDownloadProgress(totalFiles);
+
+        try {
+            let completedDownloads = 0;
+            for (let i = 0; i < totalFiles; i++) {
+                const filename = this.hfSelectedFiles[i];
+                updateProgress(0, completedDownloads, filename);
+                this.loadingManager.setStatus(`Downloading ${filename}...`);
+
+                const downloadId = Date.now().toString() + '_' + i;
+                const wsProtocol = window.location.protocol === 'https:' ? 'wss://' : 'ws://';
+                const ws = new WebSocket(`${wsProtocol}${window.location.host}/ws/download-progress?id=${downloadId}`);
+
+                try {
+                    await new Promise((resolve, reject) => {
+                        ws.onopen = resolve;
+                        ws.onerror = reject;
+                    });
+
+                    // Capture completed count at WS creation time so progress
+                    // updates arriving after completedDownloads increments still
+                    // show the correct "N / total" position.
+                    const snapshotCompleted = completedDownloads;
+                    ws.onmessage = (event) => {
+                        const data = JSON.parse(event.data);
+                        if (data.status === 'progress') {
+                            const metrics = {
+                                bytesDownloaded: data.bytes_downloaded,
+                                totalBytes: data.total_bytes,
+                                bytesPerSecond: data.bytes_per_second,
+                            };
+                            updateProgress(data.progress, snapshotCompleted, filename, metrics);
+                        }
+                    };
+
+                    const response = await this.apiClient.downloadHfModel({
+                        repo: this.hfRepoId,
+                        filename,
+                        revision: 'main',
+                        modelRoot,
+                        relativePath: targetFolder,
+                        useDefaultPaths,
+                        download_id: downloadId,
+                    });
+
+                    if (response?.success) {
+                        completedDownloads++;
+                        updateProgress(100, completedDownloads, filename);
+                    }
+                } finally {
+                    ws.close();
+                }
+            }
+
+            showToast('toast.loras.downloadCompleted', {}, 'success');
+            // Reload page data — model is already in scanner cache via backend
+            await resetAndReload(true);
+            return true;
+        } catch (error) {
+            console.error('Failed to download HF model:', error);
+            showToast('toast.downloads.downloadError', { message: error?.message }, 'error');
+            return false;
+        } finally {
+            this.loadingManager.hide();
+        }
+    }
+
    updatePathSelectionUI() {
        const manualSelection = document.getElementById('manualPathSelection');

@@ -812,13 +1079,19 @@ export class DownloadManager {
        document.querySelectorAll('.download-step').forEach(step => step.style.display = 'none');
        document.getElementById('batchPreviewStep').style.display = 'block';

-        const validCount = this.batchModels.filter(m => !m.error && m.selectedVersion).length;
+        const validCount = this.batchModels.filter(m => {
+            if (m.error) return false;
+            if (m.source === 'huggingface') return m.checked !== false;
+            return m.selectedVersion;
+        }).length;
        document.getElementById('downloadModalTitle').textContent =
            translate('modals.download.titleWithType', { type: this.apiClient.apiConfig.config.displayName }) +
            ` (${validCount})`;

        const list = document.getElementById('batchPreviewList');
-        list.innerHTML = this.batchModels.map((item, index) => {
+        const hasHfItems = this.batchModels.some(m => m.source === 'huggingface' && !m.error);
+
+        let itemsHtml = this.batchModels.map((item, index) => {
            if (item.error) {
                return `
                    <div class="batch-preview-item batch-preview-error" data-index="${index}">
@@ -837,6 +1110,30 @@ export class DownloadManager {
            }

            const ver = item.selectedVersion;
+
+            // HF batch item rendering with checkbox
+            if (item.source === 'huggingface') {
+                const hfSize = item.fileSizeBytes
+                    ? formatFileSize(item.fileSizeBytes)
+                    : '?';
+                return `
+                    <div class="batch-preview-item" data-index="${index}">
+                        <input type="checkbox" class="batch-preview-checkbox"
+                               data-index="${index}" ${item.checked !== false ? 'checked' : ''} />
+                        <div class="batch-preview-info">
+                            <div class="batch-preview-name">${item.displayName || item.filename || `HF #${index}`} <span class="hf-badge">HF</span></div>
+                            <div class="batch-preview-meta">
+                                <span>${hfSize}</span>
+                                <span>${item.repo || ''}</span>
+                            </div>
+                        </div>
+                        <button class="batch-preview-remove" data-index="${index}" title="${translate('common.actions.remove', {}, 'Remove')}">
+                            <i class="fas fa-times"></i>
+                        </button>
+                    </div>
+                `;
+            }
+
            const firstImage = ver?.images?.find(img => !img.url.endsWith('.mp4'));
            const thumbnailUrl = firstImage ? firstImage.url : '/loras_static/images/no-preview.png';
            const fileSize = ver?.modelSizeKB
@@ -866,6 +1163,21 @@ export class DownloadManager {
            `;
        }).join('');

+        // Prepend select-all toolbar if there are HF items with checkboxes
+        if (hasHfItems) {
+            const allChecked = this.batchModels
+                .filter(m => m.source === 'huggingface' && !m.error)
+                .every(m => m.checked !== false);
+            itemsHtml = `
+                <div class="batch-preview-select-all">
+                    <input type="checkbox" id="batchSelectAll" ${allChecked ? 'checked' : ''} />
+                    <label for="batchSelectAll">${translate('modals.download.selectAll', {}, 'Select All')}</label>
+                </div>
+            ` + itemsHtml;
+        }
+
+        list.innerHTML = itemsHtml;
+
        list.onclick = (e) => {
            const removeBtn = e.target.closest('.batch-preview-remove');
            if (removeBtn) {
@@ -881,6 +1193,59 @@ export class DownloadManager {
            }
        };

+        // Checkbox handler for HF batch items
+        const checkboxes = list.querySelectorAll('.batch-preview-checkbox');
+        checkboxes.forEach(cb => {
+            cb.addEventListener('change', (e) => {
+                const idx = parseInt(e.target.dataset.index);
+                if (this.batchModels[idx]) {
+                    this.batchModels[idx].checked = e.target.checked;
+                }
+                // Update valid count in title and Next button
+                const checkedCount = this.batchModels.filter(
+                    m => !m.error && m.checked !== false
+                ).length;
+                document.getElementById('downloadModalTitle').textContent =
+                    translate('modals.download.titleWithType', { type: this.apiClient.apiConfig.config.displayName }) +
+                    ` (${checkedCount})`;
+                const nextBtn = document.getElementById('nextFromBatchBtn');
+                nextBtn.disabled = checkedCount === 0;
+                nextBtn.classList.toggle('disabled', checkedCount === 0);
+                // Update select-all checkbox state
+                const selectAll = document.getElementById('batchSelectAll');
+                if (selectAll) {
+                    const hfItems = this.batchModels.filter(m => m.source === 'huggingface' && !m.error);
+                    selectAll.checked = hfItems.length > 0 && hfItems.every(m => m.checked !== false);
+                }
+            });
+        });
+
+        // Select-all handler
+        const selectAll = document.getElementById('batchSelectAll');
+        if (selectAll) {
+            selectAll.addEventListener('change', (e) => {
+                const checked = e.target.checked;
+                const hfCheckboxes = list.querySelectorAll('.batch-preview-checkbox');
+                hfCheckboxes.forEach(cb => {
+                    cb.checked = checked;
+                    const idx = parseInt(cb.dataset.index);
+                    if (this.batchModels[idx]) {
+                        this.batchModels[idx].checked = checked;
+                    }
+                });
+                // Update valid count in title and Next button
+                const checkedCount = this.batchModels.filter(
+                    m => !m.error && m.checked !== false
+                ).length;
+                document.getElementById('downloadModalTitle').textContent =
+                    translate('modals.download.titleWithType', { type: this.apiClient.apiConfig.config.displayName }) +
+                    ` (${checkedCount})`;
+                const nextBtn = document.getElementById('nextFromBatchBtn');
+                nextBtn.disabled = checkedCount === 0;
+                nextBtn.classList.toggle('disabled', checkedCount === 0);
+            });
+        }
+
        const nextBtn = document.getElementById('nextFromBatchBtn');
        nextBtn.disabled = validCount === 0;
        nextBtn.classList.toggle('disabled', validCount === 0);
@@ -903,7 +1268,12 @@ export class DownloadManager {
    }

    nextFromBatch() {
-        const validModels = this.batchModels.filter(m => !m.error && m.selectedVersion);
+        // For HF items, respect the checked flag; for CivitAI items, use selectedVersion
+        const validModels = this.batchModels.filter(m => {
+            if (m.error) return false;
+            if (m.source === 'huggingface') return m.checked !== false;
+            return m.selectedVersion;
+        });
        if (validModels.length === 0) return;
        this.proceedToLocation();
    }
@@ -953,6 +1323,15 @@ export class DownloadManager {
            targetFolder = this.folderTreeManager.getSelectedPath();
        }
        if (!this.isBatchMode) {
+            // Single-item download
+            if (this.source === 'huggingface') {
+                return this._downloadHfSingle({
+                    modelRoot,
+                    targetFolder,
+                    useDefaultPaths,
+                });
+            }
+
            const fileParams = this.selectedFile ? {
                type: this.selectedFile.type || 'Model',
                format: this.selectedFile.metadata?.format || 'SafeTensor',
@@ -974,7 +1353,13 @@ export class DownloadManager {
        }

        // Batch download mode
-        const downloadItems = this.batchModels.filter(m => !m.error && m.selectedVersion && !m.selectedVersion.existsLocally);
+        const downloadItems = this.batchModels.filter(m => {
+            if (m.error) return false;
+            if (!m.selectedVersion) return false;
+            // HF items have selectedVersion as a boolean marker + checked flag
+            if (m.source === 'huggingface') return m.checked !== false;
+            return !m.selectedVersion.existsLocally;
+        });
        if (downloadItems.length === 0) {
            showToast('toast.loras.downloadCompleted', {}, 'info');
            modalManager.closeModal('downloadModal');
@@ -999,7 +1384,7 @@ export class DownloadManager {

            if (data.status === 'progress' && data.download_id?.startsWith(batchDownloadId)) {
                const current = downloadItems[completedDownloads + failedDownloads];
-                const name = current?.selectedVersion?.name || `#${completedDownloads + failedDownloads + 1}`;
+                const name = current?.selectedVersion?.name || current?.displayName || current?.filename || `#${completedDownloads + failedDownloads + 1}`;
                const metrics = {
                    bytesDownloaded: data.bytes_downloaded,
                    totalBytes: data.total_bytes,
@@ -1016,22 +1401,59 @@ export class DownloadManager {

        for (let i = 0; i < downloadItems.length; i++) {
            const item = downloadItems[i];
-            const ver = item.selectedVersion;
-            const name = ver?.name || `Model #${item.modelId}`;
+            const name = item.displayName || item.filename || (item.selectedVersion?.name || `Model #${item.modelId}`);
+            const isHf = item.source === 'huggingface';

            updateProgress(0, completedDownloads, name);
            loadingManager.setStatus(`${i + 1}/${downloadItems.length}: ${name}`);

            try {
-                const response = await this.apiClient.downloadModel(
-                    item.modelId,
-                    ver.id,
-                    modelRoot,
-                    targetFolder,
-                    useDefaultPaths,
-                    batchDownloadId,
-                    item.source
-                );
+                let response;
+                if (isHf) {
+                    // Per-file WebSocket for real-time progress
+                    const downloadId = Date.now().toString() + '_hf_' + i;
+                    const wsHf = new WebSocket(`${wsProtocol}${window.location.host}/ws/download-progress?id=${downloadId}`);
+                    try {
+                        await new Promise((resolve, reject) => {
+                            wsHf.onopen = resolve;
+                            wsHf.onerror = reject;
+                        });
+                        const snapshotCompleted = completedDownloads;
+                        wsHf.onmessage = (event) => {
+                            const data = JSON.parse(event.data);
+                            if (data.status === 'progress') {
+                                const metrics = {
+                                    bytesDownloaded: data.bytes_downloaded,
+                                    totalBytes: data.total_bytes,
+                                    bytesPerSecond: data.bytes_per_second,
+                                };
+                                updateProgress(data.progress, snapshotCompleted, name, metrics);
+                            }
+                        };
+
+                        response = await this.apiClient.downloadHfModel({
+                            repo: item.repo,
+                            filename: item.filename,
+                            revision: item.revision || 'main',
+                            modelRoot,
+                            relativePath: targetFolder,
+                            useDefaultPaths,
+                            download_id: downloadId,
+                        });
+                    } finally {
+                        wsHf.close();
+                    }
+                } else {
+                    response = await this.apiClient.downloadModel(
+                        item.modelId,
+                        item.selectedVersion.id,
+                        modelRoot,
+                        targetFolder,
+                        useDefaultPaths,
+                        batchDownloadId,
+                        item.source
+                    );
+                }

                if (!response.success) {
                    failedDownloads++;
--- a/static/js/managers/SettingsManager.js
+++ b/static/js/managers/SettingsManager.js
@@ -789,6 +789,27 @@ export class SettingsManager {
        }
    }

+    async _fetchProviderModelsAsync() {
+        try {
+            const resp = await fetch('/api/lm/llm/provider-models');
+            if (!resp.ok) return;
+            const data = await resp.json();
+            if (data.success && data.models) {
+                this._providerModels = data.models;
+                // Refresh model combobox if the settings modal is still open.
+                // Skip when provider is Ollama — it fetches its own live list
+                // from the local Ollama API and we must not overwrite it.
+                const llmProviderSelect = document.getElementById('llmProvider');
+                const provider = llmProviderSelect ? llmProviderSelect.value : 'openai';
+                if (this._llmModelCombobox && provider !== 'ollama') {
+                    this._llmModelCombobox.updatePresets(this._providerModels[provider] || []);
+                }
+            }
+        } catch (_) {
+            // Silently ignore — models stay empty until next modal open
+        }
+    }
+
    async loadSettingsToUI() {
        // Set frontend settings from state
        const blurMatureContentCheckbox = document.getElementById('blurMatureContent');
@@ -827,6 +848,115 @@ export class SettingsManager {

        // Update API key status display (do NOT pre-fill the input)
        this.updateApiKeyStatus();
+        this.updateLlmApiKeyStatus();
+
+        // ── 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 = {};
+            }
+        }
+
+        // If the embedded provider models is empty (server did not block on
+        // the remote catalog during page render), fetch asynchronously.
+        if (!this._providerModels || Object.keys(this._providerModels).length === 0) {
+            this._fetchProviderModelsAsync();
+        }
+
+        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');
+        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');
        if (civitaiHostSelect) {
@@ -2931,42 +3061,70 @@ export class SettingsManager {
        }
    }

-    editApiKey() {
-        const statusEl = document.getElementById('civitaiApiKeyStatus');
+    updateLlmApiKeyStatus() {
+        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;
+
+        if (hasKey) {
+            statusText.classList.remove('api-key-status--unconfigured');
+            statusText.classList.add('api-key-status--configured');
+            statusText.innerHTML = '<i class="fas fa-check-circle text-success"></i> '
+                + translate('settings.aiProvider.apiKeyConfigured', {}, 'Configured');
+            actionBtn.textContent = translate('common.actions.change', {}, 'Change');
+        } else {
+            statusText.classList.remove('api-key-status--configured');
+            statusText.classList.add('api-key-status--unconfigured');
+            statusText.innerHTML = '<i class="fas fa-times-circle text-error"></i> '
+                + translate('settings.aiProvider.apiKeyNotSet', {}, 'Not set');
+            actionBtn.textContent = translate('settings.aiProvider.apiKeySet', {}, 'Set up');
+        }
+    }
+
+    editApiKey(settingsKey = 'civitai_api_key', inputId = 'civitaiApiKey') {
+        const statusId = inputId + 'Status';
+        const editId = inputId + 'Edit';
+        const statusEl = document.getElementById(statusId);
        if (statusEl) statusEl.classList.add('is-hidden');
-        const editContainer = document.getElementById('civitaiApiKeyEdit');
+        const editContainer = document.getElementById(editId);
        if (editContainer) editContainer.classList.remove('is-hidden');
        // Focus the input
-        const input = document.getElementById('civitaiApiKey');
+        const input = document.getElementById(inputId);
        if (input) {
            input.value = '';  // Never pre-fill the secret
            setTimeout(() => input.focus(), 50);
        }
    }

-    cancelEditApiKey(silent) {
-        const editContainer = document.getElementById('civitaiApiKeyEdit');
+    cancelEditApiKey(silent, inputId = 'civitaiApiKey') {
+        const editId = inputId + 'Edit';
+        const statusId = inputId + 'Status';
+        const editContainer = document.getElementById(editId);
        if (editContainer) editContainer.classList.add('is-hidden');
-        const statusContainer = document.getElementById('civitaiApiKeyStatus');
+        const statusContainer = document.getElementById(statusId);
        if (statusContainer) statusContainer.classList.remove('is-hidden');
        // Clear any typed value
-        const input = document.getElementById('civitaiApiKey');
+        const input = document.getElementById(inputId);
        if (input) input.value = '';
        if (!silent) {
-            this.updateApiKeyStatus();
+            if (inputId === 'civitaiApiKey') {
+                this.updateApiKeyStatus();
+            }
        }
    }

-    async saveApiKey() {
-        const input = document.getElementById('civitaiApiKey');
+    async saveApiKey(settingsKey = 'civitai_api_key', inputId = 'civitaiApiKey') {
+        const input = document.getElementById(inputId);
        if (!input) return;

        const value = input.value.trim();

        try {
-            await this.saveSetting('civitai_api_key', value);
+            await this.saveSetting(settingsKey, value);
+            const labelName = settingsKey === 'civitai_api_key' ? 'CivitAI API Key' : 'LLM API Key';
            showToast('toast.settings.settingsUpdated',
-                { setting: 'CivitAI API Key' }, 'success');
+                { setting: labelName }, 'success');
        } catch (error) {
            showToast('toast.settings.settingSaveFailed',
                { message: error.message }, 'error');
@@ -2974,9 +3132,13 @@ export class SettingsManager {
        }

        // Update the in-memory flag so the UI reflects the change
-        state.global.settings.civitai_api_key_set = !!value;
-        this.cancelEditApiKey(true);
-        this.updateApiKeyStatus();
+        if (settingsKey === 'civitai_api_key') {
+            state.global.settings.civitai_api_key_set = !!value;
+        }
+        this.cancelEditApiKey(true, inputId);
+        if (inputId === 'civitaiApiKey') {
+            this.updateApiKeyStatus();
+        }
    }

    toggleInputVisibility(button) {
--- a/static/js/state/index.js
+++ b/static/js/state/index.js
@@ -55,6 +55,10 @@ const DEFAULT_SETTINGS_BASE = Object.freeze({
    strip_lora_on_copy: false,
    use_new_license_icons: true,
    group_by_model: false,
+    llm_provider: 'openai',
+    llm_api_key: '',
+    llm_api_base: '',
+    llm_model: '',
 });

 export function createDefaultSettings() {
--- a/static/js/utils/constants.js
+++ b/static/js/utils/constants.js
@@ -66,10 +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",
+    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"
 };
@@ -142,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',
@@ -194,9 +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.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'
@@ -392,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': [
@@ -400,7 +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.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/static/js/utils/uiHelpers.js
+++ b/static/js/utils/uiHelpers.js
@@ -319,6 +319,15 @@ export function openCivitai(filePath) {
  openCivitaiByMetadata(civitaiId, versionId, modelName);
 }

+/**
+ * Open a Hugging Face model page in a new tab
+ * @param {string} hfUrl - The Hugging Face URL
+ */
+export function openHuggingFace(hfUrl) {
+  if (!hfUrl) return;
+  window.open(hfUrl, '_blank', 'noopener,noreferrer');
+}
+
 /**
 * Dynamically positions the search options panel and filter panel
 * based on the current layout and folder tags container height
--- a/templates/components/context_menu.html
+++ b/templates/components/context_menu.html
@@ -15,6 +15,9 @@
    <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">
@@ -83,6 +86,9 @@
        <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-llm-bulk">
+            <i class="fas fa-wand-magic-sparkles"></i> <span>{{ t('loras.bulkOperations.enrichHfAgent') }}</span>
+        </div>
    </div>
    <div class="context-menu-section" data-section="workflow">
        <div class="context-menu-section-header">{{ t('loras.bulkOperations.sections.workflow') }}</div>
--- a/templates/components/modals/download_modal.html
+++ b/templates/components/modals/download_modal.html
@@ -14,7 +14,7 @@
                <div class="error-message" id="urlError"></div>
                <div class="input-hint">
                    <i class="fas fa-info-circle"></i>
-                    <span>{{ t('modals.download.urlHint') }}</span>
+                    <span id="urlHint">{{ t('modals.download.urlHint') }}</span>
                </div>
            </div>
            <div class="modal-actions">
--- a/templates/components/modals/settings_modal.html
+++ b/templates/components/modals/settings_modal.html
@@ -144,6 +144,112 @@
                            </div>
                        </div>

+                        <!-- AI Provider Configuration (BYOK) -->
+                        <div class="settings-subsection">
+                            <div class="settings-subsection-header">
+                                <h4>{{ t('settings.aiProvider.title') }}</h4>
+                            </div>
+                            <div class="setting-item">
+                                <div class="setting-row">
+                                    <div class="setting-info">
+                                        <label for="llmProvider">{{ t('settings.aiProvider.provider') }}</label>
+                                        <i class="fas fa-info-circle info-icon" data-tooltip="{{ t('settings.aiProvider.providerHelp') }}"></i>
+                                    </div>
+                                    <div class="setting-control select-control">
+                                        <select id="llmProvider" onchange="settingsManager.saveSelectSetting('llmProvider', 'llm_provider')">
+                                            <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>
+                            </div>
+                            <div class="setting-item">
+                                <div class="setting-row">
+                                    <div class="setting-info">
+                                        <label for="llmApiBase">{{ t('settings.aiProvider.apiBase') }}</label>
+                                        <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 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>
+                                    </div>
+                                </div>
+                            </div>
+                            <div class="setting-item api-key-item">
+                                <div class="setting-row">
+                                    <div class="setting-info">
+                                        <label>{{ t('settings.aiProvider.apiKey') }}</label>
+                                        <i class="fas fa-info-circle info-icon" data-tooltip="{{ t('settings.aiProvider.apiKeyHelp') }}"></i>
+                                    </div>
+                                    <div class="setting-control">
+                                        <div id="llmApiKeyStatus" class="api-key-status">
+                                            <span id="llmApiKeyStatusText" class="api-key-status-text api-key-status--unconfigured">
+                                                <i class="fas fa-times-circle text-error"></i>
+                                                {{ t('settings.aiProvider.apiKeyNotSet') }}
+                                            </span>
+                                            <button type="button" class="secondary-btn" id="llmApiKeyActionBtn" onclick="settingsManager.editApiKey('llm_api_key', 'llmApiKey')">
+                                                {{ t('settings.aiProvider.apiKeySet') }}
+                                            </button>
+                                        </div>
+                                        <div id="llmApiKeyEdit" class="api-key-edit is-hidden">
+                                            <div class="api-key-input">
+                                                <input type="text"
+                                                    id="llmApiKey"
+                                                    class="api-key-masked"
+                                                    placeholder="{{ t('settings.aiProvider.apiKeyPlaceholder') }}"
+                                                    autocomplete="off"
+                                                    data-mask="css" />
+                                                <button type="button" class="toggle-visibility">
+                                                    <i class="fas fa-eye"></i>
+                                                </button>
+                                            </div>
+                                            <button type="button" class="primary-btn" onclick="settingsManager.saveApiKey('llm_api_key', 'llmApiKey')">{{ t('common.actions.save') }}</button>
+                                            <button type="button" class="secondary-btn" onclick="settingsManager.cancelEditApiKey(true, 'llmApiKey')">{{ t('common.actions.cancel') }}</button>
+                                        </div>
+                                    </div>
+                                </div>
+                            </div>
+                            <div class="setting-item">
+                                <div class="setting-row">
+                                    <div class="setting-info">
+                                        <label for="llmModel">{{ t('settings.aiProvider.model') }}</label>
+                                        <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 lm-combobox-container">
+                                            <input type="text" id="llmModel"
+                                                   class="lm-combobox-input"
+                                                   value="{{ settings.get('llm_model', '') }}"
+                                                   placeholder="{{ t('settings.aiProvider.modelPlaceholder') }}"
+                                                   autocomplete="off"
+                                                   onblur="settingsManager.saveInputSetting('llmModel', 'llm_model')"
+                                                   onkeydown="if(event.key === 'Enter') { this.blur(); }" />
+                                        </div>
+                                    </div>
+                                </div>
+                            </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/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/frontend/utils/hfUrlDetection.test.js
+++ b/tests/frontend/utils/hfUrlDetection.test.js
@@ -0,0 +1,103 @@
+import { describe, it, expect } from 'vitest';
+import { DownloadManager } from '../../../static/js/managers/DownloadManager.js';
+
+describe('DownloadManager.detectUrlType — HF URL detection', () => {
+
+    it('detects HF resolve URL with file', () => {
+        const result = DownloadManager.detectUrlType(
+            'https://huggingface.co/dx8152/Flux2-Klein-9B-Consistency/resolve/main/Flux2-Klein-9B-consistency-V2.safetensors'
+        );
+        expect(result).toEqual({
+            type: 'hf-resolve',
+            repo: 'dx8152/Flux2-Klein-9B-Consistency',
+            revision: 'main',
+            filename: 'Flux2-Klein-9B-consistency-V2.safetensors',
+        });
+    });
+
+    it('detects HF resolve URL with subdirectory file', () => {
+        const result = DownloadManager.detectUrlType(
+            'https://huggingface.co/user/repo/resolve/main/subdir/model.safetensors'
+        );
+        expect(result).toEqual({
+            type: 'hf-resolve',
+            repo: 'user/repo',
+            revision: 'main',
+            filename: 'subdir/model.safetensors',
+        });
+    });
+
+    it('detects HF repo URL (full URL)', () => {
+        const result = DownloadManager.detectUrlType(
+            'https://huggingface.co/dx8152/Flux2-Klein-9B-Consistency'
+        );
+        expect(result).toEqual({
+            type: 'hf-repo',
+            repo: 'dx8152/Flux2-Klein-9B-Consistency',
+        });
+    });
+
+    it('detects HF repo URL (bare user/repo)', () => {
+        const result = DownloadManager.detectUrlType('dx8152/Flux2-Klein-9B-Consistency');
+        expect(result).toEqual({
+            type: 'hf-repo',
+            repo: 'dx8152/Flux2-Klein-9B-Consistency',
+        });
+    });
+
+    it('detects HF repo URL with trailing slash', () => {
+        const result = DownloadManager.detectUrlType(
+            'https://huggingface.co/user/repo/'
+        );
+        expect(result).toEqual({
+            type: 'hf-repo',
+            repo: 'user/repo',
+        });
+    });
+
+    it('detects CivitAI URL', () => {
+        const result = DownloadManager.detectUrlType(
+            'https://civitai.com/models/123/some-model'
+        );
+        expect(result).toEqual({ type: 'civitai' });
+    });
+
+    it('detects CivArchive URL', () => {
+        const result = DownloadManager.detectUrlType(
+            'https://civarchive.com/models/456'
+        );
+        expect(result).toEqual({ type: 'civitai' });
+    });
+
+    it('detects direct HTTP URL', () => {
+        const result = DownloadManager.detectUrlType(
+            'https://example.com/file.zip'
+        );
+        expect(result).toEqual({ type: 'direct-http' });
+    });
+
+    it('returns null for invalid input', () => {
+        expect(DownloadManager.detectUrlType('')).toBeNull();
+        expect(DownloadManager.detectUrlType('   ')).toBeNull();
+    });
+
+    it('returns null for unrecognized path', () => {
+        expect(DownloadManager.detectUrlType('justrandomtext')).toBeNull();
+    });
+
+    it('prefers HF resolve over repo when both match', () => {
+        const result = DownloadManager.detectUrlType(
+            'https://huggingface.co/user/repo/resolve/main/file.safetensors'
+        );
+        expect(result?.type).toBe('hf-resolve');
+    });
+
+    it('prefers CivitAI over HF when both match', () => {
+        // CivitAI check comes first in detectUrlType
+        // This URL should be detected as CivitAI, not HF
+        const result = DownloadManager.detectUrlType(
+            'https://civitai.com/models/123?huggingface.co/test/repo'
+        );
+        expect(result?.type).toBe('civitai');
+    });
+});
--- 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/routes/test_base_model_routes_smoke.py
+++ b/tests/routes/test_base_model_routes_smoke.py
@@ -201,6 +201,45 @@ def test_list_models_returns_formatted_items(mock_service, mock_scanner):
    asyncio.run(scenario())


+def test_list_models_filters_out_corrupted_entries(mock_service, mock_scanner):
+    """Corrupted cache entries (format_response returns None) must not appear
+    in the response items nor cause a 500. See issue #730.
+    """
+    mock_service.paginated_items = [
+        {"file_path": "/tmp/good.safetensors", "name": "Good"},
+        {"file_path": None, "name": "Corrupted"},  # triggers None from format_response
+        {"file_path": "/tmp/also_good.safetensors", "name": "AlsoGood"},
+    ]
+
+    # Override format_response to return None for corrupted entries
+    original_format = mock_service.format_response
+
+    async def conditional_format(item):
+        if item.get("file_path") is None:
+            return None
+        return await original_format(item)
+
+    mock_service.format_response = conditional_format
+
+    async def scenario():
+        client = await create_test_client(mock_service)
+        try:
+            response = await client.get("/api/lm/test-models/list")
+            payload = await response.json()
+
+            assert response.status == 200
+            # Only the 2 non-corrupted entries should appear
+            assert len(payload["items"]) == 2
+            assert payload["items"][0]["name"] == "Good"
+            assert payload["items"][1]["name"] == "AlsoGood"
+            # None should never appear in the items list
+            assert None not in payload["items"]
+        finally:
+            await client.close()
+
+    asyncio.run(scenario())
+
+
 def test_model_types_endpoint_returns_counts(mock_service, mock_scanner):
    mock_service.model_types = [
        {"type": "LoRa", "count": 3},
--- a/tests/routes/test_update_routes.py
+++ b/tests/routes/test_update_routes.py
@@ -59,3 +59,180 @@ async def test_get_nightly_version_network_error_logs_warning(monkeypatch, caplo
    assert changelog == []
    assert "Unable to reach GitHub for nightly version" in caplog.text
    assert "Traceback" not in caplog.text
+
+
+def test_clean_excludes_covers_user_data_dirs():
+    """git clean must receive -e excludes for every user-managed dir."""
+    excludes = update_routes._clean_excludes()
+    assert "-e" in excludes  # at least one exclude flag present
+    for name in update_routes._PRESERVE_DIRS:
+        assert name in excludes
+        assert f"{name}/**" in excludes
+
+
+@pytest.mark.asyncio
+async def test_perform_git_update_preserves_user_dirs(monkeypatch, tmp_path):
+    """``git clean`` must be called with -e excludes for user data dirs.
+
+    Regression test for portable-mode updates wiping wildcards/, stats/,
+    backups/, etc. because ``git clean -fd`` removed untracked, non-ignored
+    directories.
+    """
+    calls = []
+
+    class FakeGit:
+        def reset(self, *args, **kwargs):
+            calls.append(("reset", args))
+
+        def clean(self, *args, **kwargs):
+            calls.append(("clean", args))
+
+        def checkout(self, *args, **kwargs):
+            calls.append(("checkout", args))
+
+    class FakeRemote:
+        def fetch(self):
+            calls.append(("fetch", ()))
+
+        def pull(self, *args, **kwargs):
+            calls.append(("pull", args))
+
+    class FakeRemotes:
+        origin = FakeRemote()
+
+    class FakeCommit:
+        hexsha = "abcdef123456"
+
+    class FakeHeads:
+        def __getitem__(self, name):
+            class Head:
+                def checkout(self_inner):
+                    calls.append(("head-checkout", (name,)))
+            return Head()
+
+    class FakeBranches:
+        names = ["main"]
+
+        def __iter__(self):
+            class B:
+                name = "main"
+            return iter([B()])
+
+    class FakeRepo:
+        def __init__(self, path):
+            calls.append(("repo", (path,)))
+
+        git = FakeGit()
+        remotes = FakeRemotes()
+        head = type("H", (), {"commit": FakeCommit()})()
+        branches = FakeBranches()
+        heads = FakeHeads()
+
+        def create_head(self, name, ref):
+            calls.append(("create_head", (name, ref)))
+
+    class FakeGitModule:
+        class Repo:
+            def __new__(cls, path):
+                return FakeRepo(path)
+
+        class exc:
+            class GitError(Exception):
+                pass
+
+    import builtins
+
+    real_import = builtins.__import__
+
+    def fake_import(name, *args, **kwargs):
+        if name == "git":
+            return FakeGitModule
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+
+    success, version = await update_routes.UpdateRoutes._perform_git_update(
+        str(tmp_path), nightly=True
+    )
+
+    assert success is True
+    clean_calls = [c for c in calls if c[0] == "clean"]
+    assert len(clean_calls) == 1
+    clean_args = clean_calls[0][1]
+    # Every preserved dir must be excluded via -e
+    for name in update_routes._PRESERVE_DIRS:
+        assert name in clean_args, f"{name} missing from git clean excludes"
+        assert f"{name}/**" in clean_args, f"{name}/** missing from git clean excludes"
+        # Ensure there's an -e before each name occurrence
+        idx = clean_args.index(name)
+        assert clean_args[idx - 1] == "-e"
+
+
+@pytest.mark.asyncio
+async def test_perform_git_update_stable_preserves_user_dirs(monkeypatch, tmp_path):
+    """Stable (tag) update path must also pass -e excludes to git clean."""
+    calls = []
+
+    class FakeGit:
+        def reset(self, *args, **kwargs):
+            calls.append(("reset", args))
+
+        def clean(self, *args, **kwargs):
+            calls.append(("clean", args))
+
+        def checkout(self, *args, **kwargs):
+            calls.append(("checkout", args))
+
+    class FakeRemote:
+        def fetch(self):
+            calls.append(("fetch", ()))
+
+    class FakeRemotes:
+        origin = FakeRemote()
+
+    class FakeCommit:
+        committed_datetime = "2026-01-01"
+
+    class FakeTag:
+        name = "v9.9.9"
+        commit = FakeCommit()
+
+    class FakeRepo:
+        def __init__(self, path):
+            calls.append(("repo", (path,)))
+
+        git = FakeGit()
+        remotes = FakeRemotes()
+        tags = [FakeTag()]
+
+    class FakeGitModule:
+        class Repo:
+            def __new__(cls, path):
+                return FakeRepo(path)
+
+        class exc:
+            class GitError(Exception):
+                pass
+
+    import builtins
+
+    real_import = builtins.__import__
+
+    def fake_import(name, *args, **kwargs):
+        if name == "git":
+            return FakeGitModule
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+
+    success, version = await update_routes.UpdateRoutes._perform_git_update(
+        str(tmp_path), nightly=False
+    )
+
+    assert success is True
+    assert version == "v9.9.9"
+    clean_calls = [c for c in calls if c[0] == "clean"]
+    assert len(clean_calls) == 1
+    clean_args = clean_calls[0][1]
+    for name in update_routes._PRESERVE_DIRS:
+        assert name in clean_args, f"{name} missing from git clean excludes (stable)"
--- a/tests/services/test_llm_service.py
+++ b/tests/services/test_llm_service.py
@@ -0,0 +1,263 @@
+"""Tests for the LLMService."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from unittest import mock
+
+import pytest
+
+from py.services.llm_service import LLMService
+from py.services.errors import LLMNotConfiguredError, LLMRateLimitError, LLMResponseError
+
+
+class MockSettings:
+    """Minimal settings mock for LLMService tests."""
+
+    def __init__(self, **kwargs):
+        self._data = {
+            "llm_enabled": False,
+            "llm_provider": "openai",
+            "llm_api_key": "",
+            "llm_api_base": "",
+            "llm_model": "",
+        }
+        self._data.update(kwargs)
+
+    def get(self, key, default=None):
+        return self._data.get(key, default)
+
+
+class MockResponse:
+    """Mock aiohttp response."""
+
+    def __init__(self, status, json_data=None, text_data="", headers=None):
+        self.status = status
+        self._json_data = json_data
+        self._text_data = text_data
+        self.headers = headers or {}
+
+    async def json(self):
+        return self._json_data
+
+    async def text(self):
+        return self._text_data
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        pass
+
+
+class MockSession:
+    """Mock aiohttp ClientSession."""
+
+    def __init__(self, response):
+        self._response = response
+        self.closed = False
+
+    def post(self, url, json=None, headers=None):
+        self.last_url = url
+        self.last_json = json
+        self.last_headers = headers
+        return self._response
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        pass
+
+
+@pytest.fixture
+def llm_service():
+    """Create an LLMService with mock settings."""
+    LLMService.reset_instance()
+    settings = MockSettings(
+        llm_enabled=True,
+        llm_provider="openai",
+        llm_api_key="sk-test-key",
+        llm_api_base="",
+        llm_model="gpt-4o-mini",
+    )
+    return LLMService(settings)
+
+
+class TestLLMServiceConfiguration:
+    def test_is_configured_when_enabled_with_key_and_model(self, llm_service):
+        assert llm_service.is_configured() is True
+
+    def test_not_configured_when_disabled(self):
+        settings = MockSettings(
+            llm_enabled=False, llm_api_key="sk-test", llm_model="gpt-4o"
+        )
+        service = LLMService(settings)
+        # Lenient: model + API key is treated as configured even without
+        # the toggle, because the user clearly intends to use the feature.
+        assert service.is_configured() is True
+
+    def test_not_configured_without_model(self):
+        settings = MockSettings(llm_enabled=True, llm_api_key="sk-test", llm_model="")
+        service = LLMService(settings)
+        assert service.is_configured() is False
+
+    def test_not_configured_without_api_key_for_openai(self):
+        settings = MockSettings(llm_enabled=True, llm_api_key="", llm_model="gpt-4o")
+        service = LLMService(settings)
+        assert service.is_configured() is False
+
+    def test_ollama_configured_without_api_key(self):
+        settings = MockSettings(
+            llm_enabled=True, llm_provider="ollama", llm_api_key="", llm_model="llama3"
+        )
+        service = LLMService(settings)
+        assert service.is_configured() is True
+
+    def test_resolve_api_base_openai_default(self, llm_service):
+        assert llm_service._resolve_api_base("openai", "") == "https://api.openai.com/v1"
+
+    def test_resolve_api_base_ollama_default(self, llm_service):
+        assert llm_service._resolve_api_base("ollama", "") == "http://localhost:11434/v1"
+
+    def test_resolve_api_base_custom_override(self, llm_service):
+        assert llm_service._resolve_api_base("custom", "https://my.api.com/v1/") == "https://my.api.com/v1"
+
+    def test_ensure_configured_raises_when_disabled(self):
+        settings = MockSettings(llm_enabled=False)
+        service = LLMService(settings)
+        with pytest.raises(LLMNotConfiguredError):
+            service._ensure_configured()
+
+    def test_ensure_configured_raises_without_model(self):
+        settings = MockSettings(llm_enabled=True, llm_api_key="sk-test", llm_model="")
+        service = LLMService(settings)
+        with pytest.raises(LLMNotConfiguredError):
+            service._ensure_configured()
+
+    def test_not_configured_custom_without_api_base(self):
+        settings = MockSettings(
+            llm_enabled=True, llm_provider="custom",
+            llm_api_key="sk-test", llm_api_base="", llm_model="gpt-4o",
+        )
+        service = LLMService(settings)
+        assert service.is_configured() is False
+
+    def test_custom_configured_with_api_base(self):
+        settings = MockSettings(
+            llm_enabled=True, llm_provider="custom",
+            llm_api_key="sk-test",
+            llm_api_base="https://my.api.com/v1", llm_model="gpt-4o",
+        )
+        service = LLMService(settings)
+        assert service.is_configured() is True
+
+    def test_ensure_configured_raises_custom_without_api_base(self):
+        settings = MockSettings(
+            llm_enabled=True, llm_provider="custom",
+            llm_api_key="sk-test", llm_api_base="", llm_model="gpt-4o",
+        )
+        service = LLMService(settings)
+        with pytest.raises(LLMNotConfiguredError, match="API base URL"):
+            service._ensure_configured()
+
+
+class TestLLMServiceChatCompletion:
+    @pytest.mark.asyncio
+    async def test_chat_completion_success(self, llm_service):
+        mock_response = MockResponse(
+            200,
+            json_data={
+                "choices": [{"message": {"content": "Hello!"}}],
+                "usage": {"total_tokens": 10},
+                "model": "gpt-4o-mini",
+            },
+        )
+        mock_session = MockSession(mock_response)
+
+        with mock.patch("aiohttp.ClientSession", return_value=mock_session):
+            result = await llm_service.chat_completion(
+                messages=[{"role": "user", "content": "Hi"}],
+            )
+
+        assert result["content"] == "Hello!"
+        assert result["usage"]["total_tokens"] == 10
+        assert result["model"] == "gpt-4o-mini"
+
+    @pytest.mark.asyncio
+    async def test_chat_completion_raises_on_not_configured(self):
+        settings = MockSettings(llm_enabled=False)
+        service = LLMService(settings)
+        with pytest.raises(LLMNotConfiguredError):
+            await service.chat_completion(messages=[])
+
+    @pytest.mark.asyncio
+    async def test_chat_completion_raises_on_http_error(self, llm_service):
+        mock_response = MockResponse(500, text_data="Internal Server Error")
+        mock_session = MockSession(mock_response)
+
+        with mock.patch("aiohttp.ClientSession", return_value=mock_session):
+            with pytest.raises(LLMResponseError, match="HTTP 500"):
+                await llm_service.chat_completion(messages=[])
+
+    @pytest.mark.asyncio
+    async def test_chat_completion_raises_on_rate_limit(self, llm_service):
+        mock_response = MockResponse(429, text_data="Rate limited", headers={"Retry-After": "0"})
+        mock_session = MockSession(mock_response)
+
+        with mock.patch("aiohttp.ClientSession", return_value=mock_session):
+            with pytest.raises(LLMRateLimitError):
+                await llm_service.chat_completion(
+                    messages=[], retry_on_rate_limit=False
+                )
+
+    @pytest.mark.asyncio
+    async def test_chat_completion_raises_on_bad_response_structure(self, llm_service):
+        mock_response = MockResponse(200, json_data={"unexpected": "data"})
+        mock_session = MockSession(mock_response)
+
+        with mock.patch("aiohttp.ClientSession", return_value=mock_session):
+            with pytest.raises(LLMResponseError, match="Unexpected LLM response"):
+                await llm_service.chat_completion(messages=[])
+
+
+class TestLLMServiceChatCompletionJson:
+    @pytest.mark.asyncio
+    async def test_chat_completion_json_parses_json(self, llm_service):
+        mock_response = MockResponse(
+            200,
+            json_data={
+                "choices": [{"message": {"content": '{"key": "value"}'}}],
+                "usage": {},
+                "model": "gpt-4o-mini",
+            },
+        )
+        mock_session = MockSession(mock_response)
+
+        with mock.patch("aiohttp.ClientSession", return_value=mock_session):
+            result = await llm_service.chat_completion_json(
+                system_prompt="You are helpful.",
+                user_prompt="Return JSON.",
+            )
+
+        assert result == {"key": "value"}
+
+    @pytest.mark.asyncio
+    async def test_chat_completion_json_raises_on_non_json(self, llm_service):
+        # Non-JSON content raises LLMResponseError (salvage also fails)
+        mock_response = MockResponse(
+            200,
+            json_data={
+                "choices": [{"message": {"content": "not json at all"}}],
+                "usage": {},
+            },
+        )
+        mock_session = MockSession(mock_response)
+
+        with mock.patch("aiohttp.ClientSession", return_value=mock_session):
+            with pytest.raises(LLMResponseError, match="could not be parsed as JSON"):
+                await llm_service.chat_completion_json(
+                    system_prompt="test",
+                    user_prompt="test",
+                )
--- a/tests/services/test_post_processor.py
+++ b/tests/services/test_post_processor.py
@@ -0,0 +1,434 @@
+"""Tests for the PostProcessor (py/services/agent/post_processor.py).
+
+PostProcessor delegates all I/O to AgentCLI — these tests mock AgentCLI
+functions and verify the business logic (conditions, merges, dispatch).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from unittest import mock
+
+import pytest
+
+from py.services.agent.post_processor import PostProcessor
+
+
+@pytest.fixture
+def processor():
+    return PostProcessor()
+
+
+# ======================================================================
+# process() — routing
+# ======================================================================
+
+
+class TestProcessDispatch:
+    @pytest.mark.asyncio
+    async def test_unknown_skill_returns_error(self, processor):
+        result = await processor.process(
+            skill_name="nonexistent",
+            model_path="/p.safetensors",
+            llm_output={},
+            metadata={},
+        )
+        assert result["success"] is False
+        assert "nonexistent" in result["errors"][0]
+
+    @pytest.mark.asyncio
+    async def test_enrich_hf_metadata_routes_correctly(self, processor):
+        with (
+            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 = None
+
+            result = await processor.process(
+                skill_name="enrich_hf_metadata",
+                model_path="/p.safetensors",
+                llm_output={},
+                metadata={"from_civitai": True},
+            )
+
+        assert result["success"] is True
+
+
+# ======================================================================
+# enrich_hf_metadata — field-level logic
+# ======================================================================
+
+
+class TestEnrichHfMetadata:
+    """Business logic tests for the enrich_hf_metadata post-processor."""
+
+    MIN_LLM_OUTPUT = {
+        "base_model": "",
+        "trigger_words": [],
+        "short_description": "",
+        "tags": [],
+        "recommended_width": 0,
+        "recommended_height": 0,
+        "preview_url": "",
+        "confidence": "low",
+    }
+
+    # -- base_model ------------------------------------------------------
+
+    @pytest.mark.asyncio
+    async def test_base_model_overwrites_empty(self, processor):
+        """Empty current base_model → new value is applied."""
+        llm = {**self.MIN_LLM_OUTPUT, "base_model": "Flux.1 D"}
+        with (
+            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",
+                model_path="/p.safetensors",
+                llm_output=llm,
+                metadata={"base_model": ""},
+            )
+        applied = mock_apply.call_args[0][1]
+        assert applied["base_model"] == "Flux.1 D"
+
+    @pytest.mark.asyncio
+    async def test_base_model_does_not_overwrite_existing_civitai(self, processor):
+        """Existing base_model from CivitAI → not overwritten."""
+        llm = {**self.MIN_LLM_OUTPUT, "base_model": "Flux.1 D"}
+        with (
+            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",
+                model_path="/p.safetensors",
+                llm_output=llm,
+                metadata={"base_model": "SDXL 1.0", "from_civitai": True},
+            )
+        # apply IS called (metadata_source, llm_enriched_at) but base_model not in it
+        applied = mock_apply.call_args[0][1]
+        assert "base_model" not in applied
+
+    @pytest.mark.asyncio
+    async def test_base_model_overwrites_existing_hf_model(self, processor):
+        """Existing base_model from HF → overwritten (LLM is more reliable)."""
+        llm = {**self.MIN_LLM_OUTPUT, "base_model": "Flux.1 D"}
+        with (
+            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",
+                model_path="/p.safetensors",
+                llm_output=llm,
+                metadata={"base_model": "SD 1.5", "from_civitai": False},
+            )
+        applied = mock_apply.call_args[0][1]
+        assert applied["base_model"] == "Flux.1 D"
+
+    @pytest.mark.asyncio
+    async def test_base_model_skipped_when_llm_empty(self, processor):
+        """LLM returns empty base_model → nothing written."""
+        with (
+            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",
+                model_path="/p.safetensors",
+                llm_output=self.MIN_LLM_OUTPUT,
+                metadata={"base_model": ""},
+            )
+        applied = mock_apply.call_args[0][1]
+        assert "base_model" not in applied
+
+    # -- trigger_words ---------------------------------------------------
+
+    @pytest.mark.asyncio
+    async def test_trigger_words_merged(self, processor):
+        """New trigger words written when current list is empty."""
+        llm = {**self.MIN_LLM_OUTPUT, "trigger_words": ["trigger1", "trigger2"]}
+        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={"trainedWords": []},
+            )
+        applied = mock_apply.call_args[0][1]
+        assert applied["civitai"]["trainedWords"] == ["trigger1", "trigger2"]
+
+    # -- short_description → civitai.description -------------------------
+
+    @pytest.mark.asyncio
+    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.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": False},
+            )
+        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 ------------------------------------------------------------
+
+    @pytest.mark.asyncio
+    async def test_tags_merged_and_deduplicated(self, processor):
+        llm = {**self.MIN_LLM_OUTPUT, "tags": ["flux", "lora", "STYLE"]}
+        with (
+            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",
+                model_path="/p.safetensors",
+                llm_output=llm,
+                metadata={"tags": ["anime"], "from_civitai": False},
+            )
+        merged = mock_apply.call_args[0][1]["tags"]
+        assert "anime" in merged
+        assert "flux" in merged
+        assert "style" in merged  # lowercased
+        # "lora" and "STYLE" → "lora" and "style"
+        assert len(merged) == 4  # anime, flux, lora, style
+
+    # -- metadata_source & llm_enriched_at --------------------------------
+
+    @pytest.mark.asyncio
+    async def test_audit_fields_always_set(self, processor):
+        with (
+            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",
+                model_path="/p.safetensors",
+                llm_output=self.MIN_LLM_OUTPUT,
+                metadata={},
+            )
+        applied = mock_apply.call_args[0][1]
+        assert applied["metadata_source"] == "agent:enrich_hf_metadata"
+        assert "llm_enriched_at" in applied
+
+    # -- preview download ------------------------------------------------
+
+    @pytest.mark.asyncio
+    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.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 = "/p.webp"
+            result = await processor.process(
+                skill_name="enrich_hf_metadata",
+                model_path="/p.safetensors",
+                llm_output=llm,
+                metadata={},
+            )
+        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.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(
+                skill_name="enrich_hf_metadata",
+                model_path="/p.safetensors",
+                llm_output=llm,
+                metadata={"preview_url": "/existing/preview.webp"},
+            )
+        mock_dl.assert_not_called()
+
+    # -- cache refresh ---------------------------------------------------
+
+    @pytest.mark.asyncio
+    async def test_cache_refreshed_when_updates_applied(self, processor):
+        llm = {**self.MIN_LLM_OUTPUT, "base_model": "Flux.1 D"}
+        with (
+            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",
+                model_path="/p.safetensors",
+                llm_output=llm,
+                metadata={"base_model": ""},
+            )
+        mock_ref.assert_awaited_once_with("/p.safetensors")
+
+    @pytest.mark.asyncio
+    async def test_cache_not_refreshed_when_nothing_changed(self, processor):
+        with (
+            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",
+                model_path="/p.safetensors",
+                llm_output=self.MIN_LLM_OUTPUT,
+                metadata={"base_model": ""},
+            )
+        mock_ref.assert_not_called()
+
+
+# ======================================================================
+# Unit: _merge_tags
+# ======================================================================
+
+
+class TestMergeTags:
+    def test_deduplicates_case_insensitive(self):
+        existing = ["anime", "Flux"]
+        new = ["flux", "LORA", "anime"]
+        result = PostProcessor._merge_tags(existing, new)
+        # All tags are lowercased (matching TagUpdateService behaviour)
+        assert result == ["anime", "flux", "lora"]
--- a/tests/services/test_service_format_response_sub_type.py
+++ b/tests/services/test_service_format_response_sub_type.py
@@ -199,8 +199,107 @@ class TestEmbeddingServiceFormatResponse:
            "from_civitai": True,
            "civitai": {},
        }
-        
+
        result = await embedding_service.format_response(embedding_data)
-        
+
        assert result["sub_type"] == "embedding"
        assert "model_type" not in result  # Removed in refactoring
+
+
+class TestFormatResponseCorruptedEntries:
+    """Test format_response handles corrupted cache entries gracefully (issue #730).
+
+    When cache rows have None/missing critical fields (e.g. from a partially
+    written or legacy DB), format_response must NOT raise KeyError/AttributeError.
+    Instead it returns None so the handler layer can filter the bad entry out
+    instead of failing the entire listing request.
+    """
+
+    @pytest.fixture
+    def mock_scanner(self):
+        scanner = MagicMock()
+        scanner._hash_index = MagicMock()
+        return scanner
+
+    @pytest.fixture
+    def lora_service(self, mock_scanner):
+        return LoraService(mock_scanner)
+
+    @pytest.fixture
+    def checkpoint_service(self, mock_scanner):
+        return CheckpointService(mock_scanner)
+
+    @pytest.fixture
+    def embedding_service(self, mock_scanner):
+        return EmbeddingService(mock_scanner)
+
+    @pytest.mark.asyncio
+    async def test_lora_returns_none_on_missing_file_path(self, lora_service):
+        """format_response returns None when file_path is missing (corrupted row)."""
+        lora_data = {
+            "model_name": "Test LoRA",
+            "file_name": "test_lora",
+            "file_path": None,  # corrupted: missing file_path
+            "folder": "",
+            "sha256": "abc123",
+            "tags": [],
+            "from_civitai": True,
+            "civitai": {},
+        }
+        result = await lora_service.format_response(lora_data)
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_lora_handles_none_model_name_gracefully(self, lora_service):
+        """format_response should not crash when model_name is None (legacy DB row)."""
+        lora_data = {
+            "model_name": None,          # NULL from old DB row
+            "file_name": "test_lora",
+            "file_path": "/models/test_lora.safetensors",
+            "folder": "",
+            "sha256": "abc123",
+            "tags": [],
+            "from_civitai": True,
+            "civitai": {},
+        }
+        result = await lora_service.format_response(lora_data)
+        # Should not raise; model_name falls back to file_name
+        assert result is not None
+        assert result["model_name"] == "test_lora"
+
+    @pytest.mark.asyncio
+    async def test_checkpoint_returns_none_on_missing_file_path(self, checkpoint_service):
+        """format_response returns None when file_path is missing (corrupted row)."""
+        checkpoint_data = {
+            "model_name": "Test",
+            "file_name": "test",
+            "file_path": "",  # empty string == corrupted
+            "folder": "",
+            "sha256": "abc",
+            "tags": [],
+            "from_civitai": True,
+            "civitai": {},
+            "sub_type": "checkpoint",
+        }
+        result = await checkpoint_service.format_response(checkpoint_data)
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_embedding_handles_none_fields_gracefully(self, embedding_service):
+        """format_response should not crash when optional fields are None."""
+        embedding_data = {
+            "model_name": None,
+            "file_name": None,
+            "file_path": "/models/test.pt",
+            "folder": None,
+            "sha256": "abc",
+            "tags": [],
+            "from_civitai": True,
+            "civitai": {},
+            "sub_type": "embedding",
+        }
+        result = await embedding_service.format_response(embedding_data)
+        assert result is not None
+        assert result["file_path"] == "/models/test.pt"
+        # model_name falls back to file_name which falls back to ""
+        assert result["model_name"] == ""
--- a/tests/services/test_settings_manager.py
+++ b/tests/services/test_settings_manager.py
@@ -200,52 +200,97 @@ def _setup_storage_paths(tmp_path, monkeypatch):
    return project_root, user_dir, user_settings_path


-def _populate_cache(root_dir, marker_name, db_text):
-    cache_dir = root_dir / "model_cache"
-    cache_dir.mkdir(exist_ok=True)
-    marker_file = cache_dir / marker_name
-    marker_file.write_text(marker_name, encoding="utf-8")
-    (root_dir / "model_cache.sqlite").write_text(db_text, encoding="utf-8")
+def _populate_settings_dir(root_dir):
+    """Create test data for all managed subdirectories under a settings directory."""
+    (root_dir / "cache" / "symlink").mkdir(parents=True, exist_ok=True)
+    (root_dir / "cache" / "symlink" / "symlink_map.json").write_text(
+        '{"migrated": true}', encoding="utf-8"
+    )
+    (root_dir / "backups").mkdir(parents=True, exist_ok=True)
+    (root_dir / "backups" / "backup_test.zip").write_text(
+        "backup", encoding="utf-8"
+    )
+    (root_dir / "logs").mkdir(parents=True, exist_ok=True)
+    (root_dir / "logs" / "session.log").write_text("log", encoding="utf-8")
+    (root_dir / "stats").mkdir(parents=True, exist_ok=True)
+    (root_dir / "stats" / "stats.json").write_text(
+        '{"stats": true}', encoding="utf-8"
+    )
+    (root_dir / "wildcards").mkdir(parents=True, exist_ok=True)
+    (root_dir / "wildcards" / "test.txt").write_text("wildcard", encoding="utf-8")


-def test_switch_to_portable_mode_copies_cache(tmp_path, monkeypatch):
+def test_switch_to_portable_mode_copies_subdirectories(tmp_path, monkeypatch):
    project_root, user_dir, user_settings = _setup_storage_paths(tmp_path, monkeypatch)
-    _populate_cache(user_dir, "user_marker.txt", "user_db")
+    _populate_settings_dir(user_dir)

    manager = SettingsManager()

    manager.set("use_portable_settings", True)

    assert manager.settings_file == str(project_root / "settings.json")
-    marker_copy = project_root / "model_cache" / "user_marker.txt"
-    assert marker_copy.read_text(encoding="utf-8") == "user_marker.txt"
-    assert (project_root / "model_cache.sqlite").read_text(
+    # Managed subdirectories should all be migrated
+    assert (
+        project_root / "cache" / "symlink" / "symlink_map.json"
+    ).read_text(encoding="utf-8") == '{"migrated": true}'
+    assert (
+        project_root / "backups" / "backup_test.zip"
+    ).read_text(encoding="utf-8") == "backup"
+    assert (project_root / "logs" / "session.log").read_text(
        encoding="utf-8"
-    ) == "user_db"
+    ) == "log"
+    assert (project_root / "stats" / "stats.json").read_text(
+        encoding="utf-8"
+    ) == '{"stats": true}'
+    assert (project_root / "wildcards" / "test.txt").read_text(
+        encoding="utf-8"
+    ) == "wildcard"
    assert user_settings.exists()


-def test_switching_back_to_user_config_moves_cache(tmp_path, monkeypatch):
+def test_switching_back_to_user_config_moves_subdirectories(tmp_path, monkeypatch):
    project_root, user_dir, user_settings = _setup_storage_paths(tmp_path, monkeypatch)
-    _populate_cache(user_dir, "user_marker.txt", "user_db")
+    _populate_settings_dir(user_dir)

    manager = SettingsManager()
    manager.set("use_portable_settings", True)

-    project_cache_dir = project_root / "model_cache"
-    project_cache_dir.mkdir(exist_ok=True)
-    (project_cache_dir / "project_marker.txt").write_text(
-        "project_marker", encoding="utf-8"
+    # Populate project-root managed subdirectories
+    (project_root / "cache" / "model").mkdir(parents=True, exist_ok=True)
+    (project_root / "cache" / "model" / "default.sqlite").write_text(
+        "project_db", encoding="utf-8"
+    )
+    (project_root / "backups" / "project_backup.zip").write_text(
+        "project_backup", encoding="utf-8"
+    )
+    (project_root / "logs" / "project.log").write_text(
+        "project_log", encoding="utf-8"
+    )
+    (project_root / "stats" / "project_stats.json").write_text(
+        '{"project": true}', encoding="utf-8"
+    )
+    (project_root / "wildcards" / "project.txt").write_text(
+        "project_wildcard", encoding="utf-8"
    )
-    (project_root / "model_cache.sqlite").write_text("project_db", encoding="utf-8")

    manager.set("use_portable_settings", False)

    assert manager.settings_file == str(user_settings)
-    assert (user_dir / "model_cache" / "project_marker.txt").read_text(
+    assert (user_dir / "cache" / "model" / "default.sqlite").read_text(
        encoding="utf-8"
-    ) == "project_marker"
-    assert (user_dir / "model_cache.sqlite").read_text(encoding="utf-8") == "project_db"
+    ) == "project_db"
+    assert (user_dir / "backups" / "project_backup.zip").read_text(
+        encoding="utf-8"
+    ) == "project_backup"
+    assert (user_dir / "logs" / "project.log").read_text(
+        encoding="utf-8"
+    ) == "project_log"
+    assert (user_dir / "stats" / "project_stats.json").read_text(
+        encoding="utf-8"
+    ) == '{"project": true}'
+    assert (user_dir / "wildcards" / "project.txt").read_text(
+        encoding="utf-8"
+    ) == "project_wildcard"


 def test_download_path_template_parses_json_string(manager):
--- a/tests/services/test_skill_registry.py
+++ b/tests/services/test_skill_registry.py
@@ -0,0 +1,88 @@
+"""Tests for the SkillRegistry (``prompt.md`` discovery + prompt loading)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from py.services.agent.skill_registry import SkillRegistry
+from py.services.agent.skill_definition import SkillDefinition, SkillPermissions
+
+
+@pytest.fixture
+def registry():
+    """Create a SkillRegistry with the real skills directory."""
+    SkillRegistry.reset_instance()
+    reg = SkillRegistry()
+    reg._discover()
+    return reg
+
+
+class TestSkillRegistryDiscovery:
+    def test_discovers_enrich_hf_metadata_skill(self, registry):
+        skills = registry.list_skills()
+        assert len(skills) >= 1
+        skill = registry.get_skill("enrich_hf_metadata")
+        assert skill is not None
+        assert skill.name == "enrich_hf_metadata"
+        assert skill.llm_required is True
+
+    def test_skill_has_correct_model_type_filter(self, registry):
+        skill = registry.get_skill("enrich_hf_metadata")
+        # 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):
+        skill = registry.get_skill("enrich_hf_metadata")
+        assert skill.permissions.write_metadata is True
+        assert skill.permissions.write_previews is True
+        # network_domains defaults to () since permissions block was removed
+
+    def test_get_skill_returns_none_for_unknown(self, registry):
+        assert registry.get_skill("nonexistent_skill") is None
+
+
+class TestSkillRegistryLoading:
+    def test_load_prompt_returns_content(self, registry):
+        prompt = registry.load_prompt("enrich_hf_metadata")
+        assert isinstance(prompt, str)
+        assert len(prompt) > 100
+        assert "base_model" in prompt
+        assert "trigger_words" in prompt
+
+    def test_load_prompt_raises_for_unknown_skill(self, registry):
+        with pytest.raises((FileNotFoundError, ValueError)):
+            registry.load_prompt("nonexistent")
+
+
+class TestSkillDefinition:
+    def test_applies_to_model_type_with_filter(self):
+        sd = SkillDefinition(
+            name="test",
+            title="Test",
+            description="",
+            llm_required=False,
+            model_type_filter=["lora"],
+        )
+        assert sd.applies_to_model_type("lora") is True
+        assert sd.applies_to_model_type("checkpoint") is False
+
+    def test_applies_to_model_type_without_filter(self):
+        sd = SkillDefinition(
+            name="test",
+            title="Test",
+            description="",
+            llm_required=False,
+            model_type_filter=None,
+        )
+        assert sd.applies_to_model_type("lora") is True
+        assert sd.applies_to_model_type("checkpoint") is True
+
+
+class TestSkillPermissions:
+    def test_defaults(self):
+        sp = SkillPermissions()
+        assert sp.write_metadata is True
+        assert sp.write_previews is True
+        assert sp.network_domains == ()