chore(release): bump version to v1.2.1

feat(recipes): add toolbar toggle and settings preview for masonry layout
feat(metadata): collect generation params from Krea two/three stage samplers
2026-08-16 18:53:21 -03:00 · 2026-08-16 19:47:15 +08:00 · 2026-08-16 15:23:30 +08:00 · 2026-08-16 09:53:08 +08:00 · 2026-08-16 09:17:59 +08:00 · 2026-08-15 22:03:54 +08:00
573 changed files with 99900 additions and 12036 deletions
@@ -1,47 +1,145 @@
 ---
 name: lora-manager-e2e
-description: End-to-end testing and validation for LoRa Manager features. Use when performing automated E2E validation of LoRa Manager standalone mode, including starting/restarting the server, using Chrome DevTools MCP to interact with the web UI at http://127.0.0.1:8188/loras, and verifying frontend-to-backend functionality. Covers workflow validation, UI interaction testing, and integration testing between the standalone Python backend and the browser frontend.
+description: End-to-end testing and validation for LoRa Manager features. Use when performing automated E2E validation of LoRa Manager standalone mode in a SANDBOXED, disposable configuration: check the port, start/restart the standalone server on a free port, use Chrome DevTools MCP to interact with the web UI (http://127.0.0.1:{PORT}/loras), and verify frontend-to-backend functionality. Covers workflow validation, UI interaction testing, and integration testing between the standalone Python backend and the browser frontend. Trigger keywords: E2E, standalone, Chrome DevTools MCP, lora-manager-e2e, sandbox.
 ---

 # LoRa Manager E2E Testing

 This skill provides workflows and utilities for end-to-end testing of LoRa Manager using Chrome DevTools MCP.

+## Conventions Used in This Document
+
+- **`{PORT}`**: The server port. The default candidate is `8188`, but **`8188` is commonly occupied by a live ComfyUI process** and MUST NOT be assumed to be free. Always check availability first (see [Port Selection](#port-selection)) and use a free port (e.g. `8199`) for the E2E run. Substitute the actual port for every `{PORT}` in the commands below.
+- **`<repo-root>`**: The repository/worktree root. Always run commands from the repo or worktree root; never assume a specific absolute path (paths such as `/home/<user>/...` differ per machine). The E2E scripts resolve the project root themselves, but fixture/settings paths are relative to `<repo-root>`.
+
+## SANDBOX (MANDATORY)
+
+> **Read this section before running anything.** Every E2E run MUST target a throwaway sandbox, never the real user data. A fresh subagent that skips this section WILL permanently mutate real user recipes.
+
+1. **Portable settings**: create `<repo-root>/settings.json` (gitignored) with `"use_portable_settings": true` plus sandboxed `folder_paths` (lora/checkpoint roots) and `recipes_path`. This keeps the configuration inside the repo instead of the real user config dir (`~/.config/ComfyUI-LoRA-Manager/settings.json`).
+2. **Sandboxed paths**: point `folder_paths` / `recipes_path` / `example_images_path` at disposable dirs — e.g. under `/tmp/opencode/<plan-name>-e2e/` (or worktree-local dirs). NEVER point the E2E at the real library (`~/models/...`), real recipe dir, or real settings.
+3. **Never touch the real config**: the real user config at `~/.config/ComfyUI-LoRA-Manager/settings.json` and the real recipe dir must remain byte-identical before and after the run.
+4. **Record real-data protection proof** before starting and after finishing:
+   ```bash
+   # BEFORE: snapshot real config + recipe library state
+   sha256sum ~/.config/ComfyUI-LoRA-Manager/settings.json > /tmp/opencode/<plan>-e2e/settings.before.sha256
+   ls ~/models/recipes/*.recipe.json 2>/dev/null | wc -l > /tmp/opencode/<plan>-e2e/recipes-count.before.txt
+   find ~/models/recipes -name '*.recipe.json' -newermt "$(date -Iseconds)" | head   # expect empty after run
+   # AFTER: record again, then diff the two snapshots. Any change = the run leaked into real data.
+   ```
+   Also confirm `<repo-root>/git status` stays clean for `settings.json`/`cache/` (both are gitignored).
+
+### Portable Settings Example
+
+```json
+{
+  "use_portable_settings": true,
+  "folder_paths": {
+    "loras": ["/tmp/opencode/<plan>-e2e/models/loras"],
+    "checkpoints": ["/tmp/opencode/<plan>-e2e/models/checkpoints"],
+    "unet": ["/tmp/opencode/<plan>-e2e/models/checkpoints"],
+    "diffusers": []
+  },
+  "recipes_path": "/tmp/opencode/<plan>-e2e/recipes",
+  "example_images_path": "/tmp/opencode/<plan>-e2e/example_images"
+}
+```
+
+The scanner computes and persists model hashes during the library scan, so the sandbox model dirs just need the model files + `.metadata.json` sidecars (see [Fixture + Fresh-State Guidance](#fixture--fresh-state-guidance)).
+
+## Time Budgets & Abort Guidance
+
+A fresh subagent should complete a sandboxed standalone E2E **in well under 30 minutes**. Budget each phase:
+
+| Phase | Expected duration | Abort if |
+| --- | --- | --- |
+| Port check + sandbox setup | < 2 min | — |
+| Server start (detached) + readiness | < 30 s | > 60 s (2x) → stop |
+| Chrome DevTools MCP connect | < 1 min | > 2 min → stop |
+| Per entry-point run (after fixtures ready) | < 5 min | > 10 min (2x) → stop |
+| Fixture reset + cache clear between runs | < 1 min | > 2 min → stop |
+
+**Abort rule**: if a phase exceeds ~2x its budget, OR any single tool call fails/retries 3+ times in a row, **STOP**. Do not loop or retry blindly. Report `BLOCKED` with: the phase, the last observed state (server PID + `ss -tlnp` output, page snapshot, last API response), and the suspected cause. Record the partial state as evidence; a clean BLOCKED report is more valuable than an hour of retries.
+
 ## Prerequisites

- LoRa Manager project cloned and dependencies installed (`pip install -r requirements.txt`)
+- LoRa Manager project cloned and dependencies installed (`pip install -r requirements.txt`) — run everything from `<repo-root>`
 - Chrome browser available for debugging
 - Chrome DevTools MCP connected
+- `ss` (or `lsof`/`netstat`) available for port checks: `ss -tlnp`

-## Quick Start Workflow
+## Port Selection

-### 1. Start LoRa Manager Standalone
-
-```python
-# Use the provided script to start the server
-python .agents/skills/lora-manager-e2e/scripts/start_server.py --port 8188
-```
-
-Or manually:
-```bash
-cd /home/miao/workspace/ComfyUI/custom_nodes/ComfyUI-Lora-Manager
-python standalone.py --port 8188
-```
-
-Wait for server ready message before proceeding.
-
-### 2. Open Chrome Debug Mode
+`8188` is only the *default candidate*. Verify it is actually free before every run:

 ```bash
-# Chrome with remote debugging on port 9222
-google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-lora-manager http://127.0.0.1:8188/loras
+# Is anything listening on 8188?
+ss -tlnp | grep ':8188' || echo "8188 is free"
 ```

-### 3. Connect Chrome DevTools MCP
+- If a process holds `8188` (e.g. a live ComfyUI — pid 6575 on this machine), pick a different free port, e.g. `8199`:
+  ```bash
+  ss -tlnp | grep ':8199' || echo "8199 is free"
+  ```
+- **Never** kill a process you did not start for this E2E. The live ComfyUI is off-limits. Pick a free port instead.
+- Use your chosen port for **all** subsequent commands (server, Chrome launch, browser URLs).

-Ensure the MCP server is connected to Chrome at `http://localhost:9222`.
+## Quick Start Workflow (sandboxed)

-### 4. Navigate and Interact
+### 1. Prepare the sandbox
+
+```bash
+cd <repo-root>                       # ALWAYS run from the repo/worktree root
+mkdir -p /tmp/opencode/<plan>-e2e/models/{loras,checkpoints}
+mkdir -p /tmp/opencode/<plan>-e2e/{recipes,example_images,recipes-before}
+# write <repo-root>/settings.json per the portable-settings example above
+# record real-data protection proof (see SANDBOX section)
+```
+
+### 2. Check port availability
+
+```bash
+ss -tlnp | grep ':{PORT}' || echo "port {PORT} is free"
+```
+
+If `{PORT}` is occupied by an unrelated process, pick a free one and use it everywhere below. When in doubt use `8199`.
+
+### 3. Start LoRa Manager Standalone (detached)
+
+The standalone server **dies with the shell unless launched fully detached** — a plain background `&` from the bash tool is killed when the tool call returns. Launch via the helper script:
+
+```bash
+python .agents/skills/lora-manager-e2e/scripts/start_server.py --port {PORT} --wait --timeout 30 --detach
+```
+
+Or manually (equivalent detached form):
+
+```bash
+setsid nohup python standalone.py --port {PORT} --host 127.0.0.1 < /dev/null \
+  >> /tmp/opencode/<plan>-e2e/server.log 2>&1 &
+echo "started"   # record the printed/pidfile PID for cleanup
+```
+
+Verify it is listening **before** proceeding (readiness poll is not a substitute for this):
+
+```bash
+ss -tlnp | grep ':{PORT}'
+```
+
+Record the server PID for cleanup: the helper script writes it to `/tmp/lora-manager-e2e-server-{PORT}.pid`; a manual `setsid` launch has no pidfile, so capture it explicitly (e.g. from `ss -tlnp`).
+
+### 4. Open Chrome Debug Mode
+
+```bash
+# Chrome with remote debugging on port 9222 (note the {PORT} URL)
+google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-lora-manager http://127.0.0.1:{PORT}/loras
+```
+
+### 5. Connect Chrome DevTools MCP
+
+Ensure the MCP server is connected to Chrome at `http://localhost:9222`. Verify with `list_pages` — if it fails with "browser is already running", see [Chrome DevTools MCP Troubleshooting](#chrome-devtools-mcp-troubleshooting).
+
+### 6. Navigate and Interact

 Use Chrome DevTools MCP tools to:
 - Take snapshots: `take_snapshot`
@@ -56,7 +154,7 @@ Use Chrome DevTools MCP tools to:

 ```python
 # Navigate to LoRA list page
-navigate_page(type="url", url="http://127.0.0.1:8188/loras")
+navigate_page(type="url", url="http://127.0.0.1:{PORT}/loras")

 # Wait for page to load
 wait_for(text="LoRAs", timeout=10000)
@@ -68,9 +166,10 @@ snapshot = take_snapshot()
 ### Pattern: Restart Server for Configuration Changes

 ```python
-# Stop current server (if running)
-# Start with new configuration
-python .agents/skills/lora-manager-e2e/scripts/start_server.py --port 8188 --restart
+# Stop current server (if running), start with new configuration.
+# --restart only kills the E2E server this script started before (via its pidfile);
+# it refuses to blindly kill unrelated processes on the port.
+python .agents/skills/lora-manager-e2e/scripts/start_server.py --port {PORT} --restart --wait --detach

 # Wait and refresh browser
 navigate_page(type="reload", ignoreCache=True)
@@ -130,24 +229,96 @@ click(uid="modal-submit-button")
 wait_for(text="Success", timeout=5000)
 ```

+## Fixture + Fresh-State Guidance
+
+For rematch/repair E2E runs, seed the **sandboxed** `recipes_path` with hand-written fixture recipes. Rules (validated by the task-8 E2E):
+
+1. **Filename constraint**: each file MUST be named `f"{id}.recipe.json"` **and** the in-JSON `id` field MUST equal the filename. Discovery accepts any `*.recipe.json`, but persistence resolves the path via `get_recipe_json_path` and `_save_recipe_persistently` returns `False` on a mismatch → the fixture would be counted as an error.
+   - `recipe-a.recipe.json` → in-JSON `"id": "recipe-a"`
+2. **File format**: mirror an existing recipe JSON — top-level `id`, `file_path`, `title`, `loras`, `fingerprint`, `gen_params`; lora entries per the persistence conventions (`hash`, `file_name`, `modelVersionId`, `isDeleted`, ...).
+3. **Companion image**: each recipe needs an image (e.g. a `.webp` generated with PIL) referenced by `file_path`, used for EXIF verification (`ExifUtils.append_recipe_metadata` writes a `"Recipe metadata: ..."` marker; a freshly generated `.webp` with no marker is the clean "untouched" control).
+4. **autov3 three-state contract**: for L3 (autov3-only, renamed-file) fixtures the local model's `.metadata.json` sidecar MUST have the `autov3` key **ABSENT** (the "unchecked" state), NOT `""` — `""` is the TERMINAL "checked but unavailable" state that L3 deliberately skips. The scanner computes + persists `autov3` from the file header during the normal library scan (`model_scanner.py` `_process_model_file`), so the live L3 match resolves through the local autov3/hash cache; the computed-autov3 branch for unchecked items is covered by the unit suite.
+5. **Fixture design for a rematch run** (mirrors the task-8 E2E):
+   - `recipe-a`: lora entry `isDeleted=True`, `hash` = 12-char autov3 computed from the local model (`calculate_autov3`, `py/utils/file_utils.py`), whose local model file was RENAMED after the recipe was written so `file_name` differs (proves L3 match without filename).
+   - `recipe-b`: parser-convention checkpoint entry (uses `id`, no `modelVersionId`) matching a local checkpoint via L2 — the local checkpoint's `.metadata.json` MUST carry civitai version data with that `id` so `version_index` contains it (L2 cannot match otherwise).
+   - `recipe-c`: healthy recipe (no deleted entries) → must remain untouched.
+
+### Fresh state between entry-point runs
+
+Each entry point (global / per-recipe / selection-bulk) must start from the same deleted state. Between runs:
+
+```bash
+# 1. Reset fixtures to the before-state snapshot (copy back from recipes-before/)
+cp /tmp/opencode/<plan>-e2e/recipes-before/*.recipe.json /tmp/opencode/<plan>-e2e/recipes/
+# 2. Clear the recipe/FTS caches so the stale in-memory/library state is gone
+rm -f <repo-root>/cache/recipe/*.sqlite
+rm -rf <repo-root>/cache/fts/*
+# 3. Restart the server (fresh process, fresh scan)
+python .agents/skills/lora-manager-e2e/scripts/start_server.py --port {PORT} --restart --wait --timeout 30 --detach
+# 4. Re-verify server listening + reload the browser page
+```
+
+## Server Lifecycle
+
+- **Detached launch is mandatory**: the standalone server dies with the shell unless launched via `setsid` (or the helper script's `--detach`). Use `setsid nohup python standalone.py --port {PORT} --host 127.0.0.1 ... < /dev/null &`.
+- **Verify with `ss -tlnp`** after every (re)start; do not proceed on a blind "server starting" message.
+- **Never kill pre-existing processes** — only kill the E2E server PID you started (`start_server.py --restart` kills only PIDs it manages via its pidfile). The live ComfyUI or a stale QA Chrome must never be killed as part of cleanup unless explicitly identified as such (see Chrome troubleshooting).
+- **Record your PID for cleanup**: note the PID printed/pidfile, and stop exactly that PID at the end (`kill <PID>`, then confirm with `ss -tlnp` that `{PORT}` is released).
+
+## Chrome DevTools MCP Troubleshooting
+
+### Stale profile lock ("browser is already running" / `list_pages` fails)
+
+A Chrome profile can be held by a stale Chrome from a prior MCP session, which makes `list_pages` fail with "browser is already running":
+
+1. Identify the stale Chrome — it owns the profile dir in `--user-data-dir` (e.g. `~/.config/chrome-dev-profile`). Find its process:
+   ```bash
+   ps -ef | grep -i '[c]hrome.*user-data-dir'
+   ```
+2. Confirm it is a QA Chrome from a completed task (its parent is an old MCP/browser process, it is NOT the live ComfyUI server, and it is NOT your current MCP instance).
+3. Kill ONLY that stale Chrome:
+   ```bash
+   kill <stale-chrome-pid>
+   ```
+   Never kill the live server or unrelated processes.
+4. Retry `list_pages`. The current MCP will spawn a fresh browser.
+
+### Screenshot-write restrictions
+
+The chrome-devtools MCP may refuse to write into paths outside its configured workspace roots (e.g. the worktree `.omo/evidence/...` canonicalizing to an unmapped path). Workaround:
+
+```bash
+# 1. Save the screenshot to /tmp via the MCP
+#    take_screenshot(filePath="/tmp/<plan>-e2e/recipe-b-after.png", format="png")
+# 2. Copy it into the evidence dir from the shell
+mkdir -p <repo-root>/.omo/evidence/screenshots
+cp /tmp/<plan>-e2e/recipe-b-after.png <repo-root>/.omo/evidence/screenshots/
+```
+
+## Cancellation Testing (KNOWN GAP)
+
+Testing the rematch-cancel path E2E requires a run long enough to cancel mid-flight. A tiny 3-recipe fixture set completes in **seconds** — too fast to reliably cancel. The cancel path is currently **unit-covered only** (`rematch_all_recipes` cancellation tests); do not block an E2E run on cancel-path verification. If you must attempt it, you would need an artificially large/deferred fixture set to create a cancellable window — treat this as a research task, not part of the standard E2E.
+
 ## Available Scripts

 ### scripts/start_server.py

-Starts or restarts the LoRa Manager standalone server.
+Starts or restarts the LoRa Manager standalone server for E2E testing.

 ```bash
-python scripts/start_server.py [--port PORT] [--restart] [--wait]
+python scripts/start_server.py [--port PORT] [--restart] [--wait] [--timeout SECONDS] [--detach]
 ```

 Options:
- `--port`: Server port (default: 8188)
- `--restart`: Kill existing server before starting
- `--wait`: Wait for server to be ready before exiting
+- `--port`: Server port (default: 8188). The script exits early with a clear message if the port is already in use by an unrelated process.
+- `--restart`: Kill the E2E server this script previously managed (tracked via `/tmp/lora-manager-e2e-server-{PORT}.pid`) before starting. If unrelated processes still hold the port after that, the script reports them and aborts instead of killing them.
+- `--wait`: Wait for the server to be ready before exiting.
+- `--timeout`: Readiness wait timeout in seconds (default: 30).
+- `--detach`: Launch the server fully detached (`setsid`-style, survives shell death — REQUIRED for E2E). Default off: a normal background process that dies with the shell.

 ### scripts/wait_for_server.py

-Polls server until ready or timeout.
+Polls the server until ready or timeout.

 ```bash
 python scripts/wait_for_server.py [--port PORT] [--timeout SECONDS]
@@ -196,6 +367,7 @@ results = performance_stop_trace()
 ## Cleanup

 Always ensure proper cleanup after tests:
-1. Stop the standalone server
-2. Close browser pages (keep at least one open)
-3. Clear temporary data if needed
+1. Stop the standalone server: `kill <recorded-pid>` (only the PID you started), then confirm `ss -tlnp | grep ':{PORT}'` is empty.
+2. Close browser pages (keep at least one open).
+3. Remove the sandbox: `rm -rf /tmp/opencode/<plan>-e2e` and `<repo-root>/settings.json` + `<repo-root>/cache` (both gitignored).
+4. Re-run the real-data protection check from the SANDBOX section and record the result in your evidence.
@@ -2,11 +2,13 @@

 Quick reference for common MCP commands used in LoRa Manager E2E testing.

+> **Port convention**: `{PORT}` is the port chosen for the E2E run (default candidate `8188`, but only if actually free — see the SKILL.md Port Selection section; use e.g. `8199` when `8188` is occupied by a live ComfyUI). Always run against the **sandboxed** standalone server, never a live instance.
+
 ## Navigation

 ```python
 # Navigate to LoRA list page
-navigate_page(type="url", url="http://127.0.0.1:8188/loras")
+navigate_page(type="url", url="http://127.0.0.1:{PORT}/loras")

 # Reload page with cache clear
 navigate_page(type="reload", ignoreCache=True)
@@ -179,7 +181,7 @@ pages = list_pages()
 select_page(pageId=0, bringToFront=True)

 # Create new page
-new_page(url="http://127.0.0.1:8188/loras")
+new_page(url="http://127.0.0.1:{PORT}/loras")

 # Close page (keep at least one open!)
 close_page(pageId=1)
@@ -261,7 +263,7 @@ drag(from_uid="draggable-item", to_uid="drop-zone")
 ### Verify LoRA Cards Loaded

 ```python
-navigate_page(type="url", url="http://127.0.0.1:8188/loras")
+navigate_page(type="url", url="http://127.0.0.1:{PORT}/loras")
 wait_for(text="LoRAs", timeout=10000)

 # Check if cards loaded
@@ -322,3 +324,37 @@ navigate_page(type="reload")
 errors = list_console_messages(types=["error"])
 assert len(errors) == 0, f"Console errors: {errors}"
 ```
+
+## Troubleshooting
+
+### Stale profile lock ("browser is already running" / `list_pages` fails)
+
+A Chrome profile held by a stale Chrome from a prior MCP session makes `list_pages`
+fail with "browser is already running". Fix:
+
+1. Find the stale Chrome that owns the profile dir (e.g. `~/.config/chrome-dev-profile`):
+   ```bash
+   ps -ef | grep -i '[c]hrome.*user-data-dir'
+   ```
+2. Confirm it is a QA Chrome from a completed task (NOT the live ComfyUI server, NOT
+   your current MCP instance).
+3. Kill ONLY that stale Chrome (`kill <stale-pid>`), then retry `list_pages`.
+
+### Screenshot-write restrictions
+
+The MCP may refuse to write into paths outside its configured workspace roots
+(e.g. `.omo/evidence/screenshots/` under a worktree that canonicalizes to an unmapped
+path). Save the screenshot to `/tmp` via the MCP, then copy it into the evidence dir:
+
+```bash
+# MCP:  take_screenshot(filePath="/tmp/<plan>-e2e/recipe-b-after.png", format="png")
+# Shell:
+mkdir -p <repo-root>/.omo/evidence/screenshots
+cp /tmp/<plan>-e2e/recipe-b-after.png <repo-root>/.omo/evidence/screenshots/
+```
+
+### Time budgets & abort rule
+
+See SKILL.md "Time Budgets & Abort Guidance": if a phase exceeds ~2x its budget or a
+tool call retries 3+ times in a row, STOP and report BLOCKED with the last observed
+state (server PID + `ss -tlnp`, page snapshot, last API response). Do not loop.
@@ -2,6 +2,14 @@

 This document provides detailed test scenarios for end-to-end validation of LoRa Manager features.

+> **Run preconditions (from SKILL.md)**: every run uses the **sandboxed** standalone
+> server on a free port `{PORT}` (default candidate `8188`, only if actually free — pick
+> e.g. `8199` when `8188` is occupied by a live ComfyUI). Fixtures live in the sandboxed
+> `recipes_path` as `f"{id}.recipe.json"` files with matching in-JSON `id`; the real user
+> config and real library are never touched (record protection proof before/after).
+> Abort if a phase exceeds ~2x its budget or a tool call retries 3+ times (SKILL.md
+> "Time Budgets & Abort Guidance").
+
 ## Table of Contents

 1. [LoRA List Page](#lora-list-page)
@@ -19,7 +27,7 @@ This document provides detailed test scenarios for end-to-end validation of LoRa
 **Objective**: Verify the LoRA list page loads correctly and displays models.

 **Steps**:
-1. Navigate to `http://127.0.0.1:8188/loras`
+1. Navigate to `http://127.0.0.1:{PORT}/loras`
 2. Wait for page title "LoRAs" to appear
 3. Take snapshot to verify:
   - Header with "LoRAs" title is visible
@@ -134,7 +142,7 @@ evaluate_script(function="""
 **Objective**: Verify recipes page loads and displays recipes.

 **Steps**:
-1. Navigate to `http://127.0.0.1:8188/recipes`
+1. Navigate to `http://127.0.0.1:{PORT}/recipes`
 2. Wait for "Recipes" title
 3. Take snapshot

@@ -176,7 +184,7 @@ evaluate_script(function="""
 **Objective**: Verify settings page displays correctly.

 **Steps**:
-1. Navigate to `http://127.0.0.1:8188/settings`
+1. Navigate to `http://127.0.0.1:{PORT}/settings`
 2. Wait for "Settings" title
 3. Take snapshot

@@ -190,7 +198,7 @@ evaluate_script(function="""
 1. Navigate to settings page
 2. Change a setting (e.g., default view mode)
 3. Save settings
-4. Restart server: `python scripts/start_server.py --restart --wait`
+4. Restart server: `python scripts/start_server.py --port {PORT} --restart --wait --timeout 30 --detach`
 5. Refresh browser page
 6. Navigate to settings

@@ -8,186 +8,208 @@ This script shows how to:
 3. Verify functionality end-to-end

 Note: This is a template. Actual execution requires Chrome DevTools MCP.
+
+Port: pick a FREE port for the run — 8188 is commonly occupied by a live
+ComfyUI (see the skill's Port Selection section). Set PORT below to e.g. 8199
+when 8188 is taken. Always run against a SANDBOXED standalone server.
 """

 import subprocess
 import sys
-import time
+
+# Choose the E2E port. 8188 is only the default candidate; use 8199 (or any
+# free port checked with `ss -tlnp`) when 8188 is occupied by a live ComfyUI.
+PORT = "8188"


 def run_test():
    """Run example E2E test flow."""
-    
+
    print("=" * 60)
    print("LoRa Manager E2E Test Example")
    print("=" * 60)
-    
-    # Step 1: Start server
+
+    # Step 1: Start server (detached so it survives the shell)
    print("\n[1/5] Starting LoRa Manager standalone server...")
    result = subprocess.run(
-        [sys.executable, "start_server.py", "--port", "8188", "--wait", "--timeout", "30"],
+        [sys.executable, "start_server.py", "--port", PORT, "--wait", "--timeout", "30", "--detach"],
        capture_output=True,
-        text=True
+        text=True,
    )
    if result.returncode != 0:
        print(f"Failed to start server: {result.stderr}")
        return 1
    print("Server ready!")
-    
+
    # Step 2: Open Chrome (manual step - show command)
    print("\n[2/5] Open Chrome with debug mode:")
-    print("google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-lora-manager http://127.0.0.1:8188/loras")
+    print(
+        f"google-chrome --remote-debugging-port=9222 "
+        f"--user-data-dir=/tmp/chrome-lora-manager http://127.0.0.1:{PORT}/loras"
+    )
    print("(In actual test, this would be automated via MCP)")
-    
+
    # Step 3: Navigate and verify page load
    print("\n[3/5] Page Load Verification:")
-    print("""
+    print(
+        f"""
    MCP Commands to execute:
-    1. navigate_page(type="url", url="http://127.0.0.1:8188/loras")
+    1. navigate_page(type="url", url="http://127.0.0.1:{PORT}/loras")
    2. wait_for(text="LoRAs", timeout=10000)
    3. snapshot = take_snapshot()
-    """)
-    
+    """
+    )
+
    # Step 4: Test search functionality
    print("\n[4/5] Search Functionality Test:")
-    print("""
+    print(
+        """
    MCP Commands to execute:
    1. fill(uid="search-input", value="test")
    2. press_key(key="Enter")
    3. wait_for(text="Results", timeout=5000)
-    4. result = evaluate_script(function="""
+    4. result = evaluate_script(function=`
        () => {
            const cards = document.querySelectorAll('.lora-card');
            return { count: cards.length };
        }
-        """)
-    """)
-    
+        `)
+    """
+    )
+
    # Step 5: Verify API
    print("\n[5/5] API Verification:")
-    print("""
+    print(
+        """
    MCP Commands to execute:
-    1. api_result = evaluate_script(function="""
+    1. api_result = evaluate_script(function=`
        async () => {
            const response = await fetch('/loras/api/list');
            const data = await response.json();
            return { count: data.length, status: response.status };
        }
-        """)
+        `)
    2. Verify api_result['status'] == 200
-    """)
-    
+    """
+    )
+
    print("\n" + "=" * 60)
    print("Test flow completed!")
    print("=" * 60)
-    
+
    return 0


 def example_restart_flow():
    """Example: Testing configuration change that requires restart."""
-    
+
    print("\n" + "=" * 60)
    print("Example: Server Restart Flow")
    print("=" * 60)
-    
-    print("""
+
+    print(
+        f"""
    Scenario: Change setting and verify after restart
-    
+
    Steps:
    1. Navigate to settings page
-       - navigate_page(type="url", url="http://127.0.0.1:8188/settings")
-    
+       - navigate_page(type="url", url="http://127.0.0.1:{PORT}/settings")
+
    2. Change a setting (e.g., theme)
       - fill(uid="theme-select", value="dark")
       - click(uid="save-settings-button")
-    
+
    3. Restart server
-       - subprocess.run([python, "start_server.py", "--restart", "--wait"])
-    
+       - subprocess.run([python, "start_server.py", "--port", "{PORT}", "--restart", "--wait", "--detach"])
+
    4. Refresh browser
       - navigate_page(type="reload", ignoreCache=True)
       - wait_for(text="LoRAs", timeout=15000)
-    
+
    5. Verify setting persisted
-       - navigate_page(type="url", url="http://127.0.0.1:8188/settings")
+       - navigate_page(type="url", url="http://127.0.0.1:{PORT}/settings")
       - theme = evaluate_script(function="() => document.querySelector('#theme-select').value")
       - assert theme == "dark"
-    """)
+    """
+    )


 def example_modal_interaction():
    """Example: Testing modal dialog interaction."""
-    
+
    print("\n" + "=" * 60)
    print("Example: Modal Dialog Interaction")
    print("=" * 60)
-    
-    print("""
+
+    print(
+        """
    Scenario: Add new LoRA via modal
-    
+
    Steps:
    1. Open modal
       - click(uid="add-lora-button")
       - wait_for(text="Add LoRA", timeout=3000)
-    
+
    2. Fill form
       - fill_form(elements=[
           {"uid": "lora-name", "value": "Test Character"},
           {"uid": "lora-path", "value": "/models/test.safetensors"},
       ])
-    
+
    3. Submit
       - click(uid="modal-submit-button")
-    
+
    4. Verify success
       - wait_for(text="Successfully added", timeout=5000)
       - snapshot = take_snapshot()
-    """)
+    """
+    )


 def example_network_monitoring():
    """Example: Network request monitoring."""
-    
+
    print("\n" + "=" * 60)
    print("Example: Network Request Monitoring")
    print("=" * 60)
-    
-    print("""
+
+    print(
+        f"""
    Scenario: Verify API calls during user interaction
-    
+
    Steps:
    1. Clear network log (implicit on navigation)
-       - navigate_page(type="url", url="http://127.0.0.1:8188/loras")
-    
+       - navigate_page(type="url", url="http://127.0.0.1:{PORT}/loras")
+
    2. Perform action that triggers API call
       - fill(uid="search-input", value="character")
       - press_key(key="Enter")
-    
+
    3. List network requests
       - requests = list_network_requests(resourceTypes=["xhr", "fetch"])
-    
+
    4. Find search API call
       - search_requests = [r for r in requests if "/api/search" in r.get("url", "")]
       - assert len(search_requests) > 0, "Search API was not called"
-    
+
    5. Get request details
       - if search_requests:
           details = get_network_request(reqid=search_requests[0]["reqid"])
           - Verify request method, response status, etc.
-    """)
+    """
+    )


 if __name__ == "__main__":
    print("LoRa Manager E2E Test Examples\n")
    print("This script demonstrates E2E testing patterns.\n")
    print("Note: Actual execution requires Chrome DevTools MCP connection.\n")
-    
+
    run_test()
    example_restart_flow()
    example_modal_interaction()
    example_network_monitoring()
-    
+
    print("\n" + "=" * 60)
    print("All examples shown!")
    print("=" * 60)
@@ -1,15 +1,78 @@
 #!/usr/bin/env python3
 """
 Start or restart LoRa Manager standalone server for E2E testing.
+
+Backward-compatible CLI: --port, --restart, --wait, --timeout all work as before.
+New options: --detach (setsid-style fully detached launch, survives shell death).
+
+Safety rules implemented here:
+- Never kill processes the script did not start. The script tracks the PIDs it
+  manages in a pidfile (/tmp/lora-manager-e2e-server-{PORT}.pid).
+- If the port is held by an unrelated process (e.g. a live ComfyUI) the script
+  reports the conflict and exits early instead of killing it.
+- --restart only kills managed PIDs; if unrelated processes still hold the port
+  afterwards, the script reports them and aborts.
 """

+from __future__ import annotations
+
 import argparse
+import os
+import signal
+import socket
 import subprocess
 import sys
 import time
-import socket
-import signal
-import os
+
+PIDFILE_PREFIX = "/tmp/lora-manager-e2e-server"
+
+
+def pidfile_path(port: int) -> str:
+    """Path of the pidfile that records PIDs this script started for a port."""
+    return f"{PIDFILE_PREFIX}-{port}.pid"
+
+
+def read_managed_pids(port: int) -> list[int]:
+    """Read PIDs this script previously managed for the port (may be stale)."""
+    path = pidfile_path(port)
+    if not os.path.exists(path):
+        return []
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            return [int(line.strip()) for line in fh if line.strip().isdigit()]
+    except (OSError, ValueError):
+        return []
+
+
+def write_managed_pids(port: int, pids: list[int]) -> None:
+    """Record PIDs this script manages for the port."""
+    try:
+        with open(pidfile_path(port), "w", encoding="utf-8") as fh:
+            for pid in pids:
+                fh.write(f"{pid}\n")
+    except OSError as exc:
+        print(f"Warning: could not write pidfile for port {port}: {exc}")
+
+
+def clear_managed_pids(port: int) -> None:
+    """Remove the pidfile for the port (no longer managed)."""
+    path = pidfile_path(port)
+    try:
+        if os.path.exists(path):
+            os.remove(path)
+    except OSError as exc:
+        print(f"Warning: could not remove pidfile {path}: {exc}")
+
+
+def process_alive(pid: int) -> bool:
+    """Return True if a process with the given pid exists."""
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # exists but owned by someone else


 def find_server_process(port: int) -> list[int]:
@@ -19,7 +82,7 @@ def find_server_process(port: int) -> list[int]:
            ["lsof", "-ti", f":{port}"],
            capture_output=True,
            text=True,
-            check=False
+            check=False,
        )
        if result.returncode == 0 and result.stdout.strip():
            return [int(pid) for pid in result.stdout.strip().split("\n") if pid]
@@ -30,7 +93,7 @@ def find_server_process(port: int) -> list[int]:
                ["netstat", "-tlnp"],
                capture_output=True,
                text=True,
-                check=False
+                check=False,
            )
            pids = []
            for line in result.stdout.split("\n"):
@@ -49,30 +112,48 @@ def find_server_process(port: int) -> list[int]:
    return []


-def kill_server(port: int) -> None:
-    """Kill processes using the specified port."""
-    pids = find_server_process(port)
+def describe_processes(pids: list[int]) -> str:
+    """Human-readable description of a pid list (pid + command line)."""
+    descriptions = []
    for pid in pids:
+        cmdline = ""
+        try:
+            with open(f"/proc/{pid}/cmdline", "rb") as fh:
+                raw = fh.read().replace(b"\x00", b" ").decode("utf-8", "replace")
+                cmdline = raw.strip()
+        except OSError:
+            pass
+        descriptions.append(f"pid {pid}{' (' + cmdline + ')' if cmdline else ''}")
+    return ", ".join(descriptions) if descriptions else "none"
+
+
+def kill_pids(pids: list[int], what: str) -> None:
+    """Send SIGTERM (then SIGKILL) to the given PIDs, only after reporting."""
+    for pid in pids:
+        print(f"Sent SIGTERM to {what} pid {pid}")
        try:
            os.kill(pid, signal.SIGTERM)
-            print(f"Sent SIGTERM to process {pid}")
        except ProcessLookupError:
            pass
-    
+
    # Wait for processes to terminate
-    time.sleep(1)
-    
+    deadline = time.time() + 5
+    while time.time() < deadline:
+        if not any(process_alive(pid) for pid in pids):
+            break
+        time.sleep(0.2)
+
    # Force kill if still running
-    pids = find_server_process(port)
    for pid in pids:
-        try:
-            os.kill(pid, signal.SIGKILL)
-            print(f"Sent SIGKILL to process {pid}")
-        except ProcessLookupError:
-            pass
+        if process_alive(pid):
+            try:
+                os.kill(pid, signal.SIGKILL)
+                print(f"Sent SIGKILL to {what} pid {pid}")
+            except ProcessLookupError:
+                pass


-def is_server_ready(port: int, timeout: float = 0.5) -> bool:
+def is_server_ready(port: int, timeout: float = 2.0) -> bool:
    """Check if server is accepting connections."""
    try:
        with socket.create_connection(("127.0.0.1", port), timeout=timeout):
@@ -84,9 +165,15 @@ def is_server_ready(port: int, timeout: float = 0.5) -> bool:
 def wait_for_server(port: int, timeout: int = 30) -> bool:
    """Wait for server to become ready."""
    start = time.time()
+    last_report = 0.0
    while time.time() - start < timeout:
        if is_server_ready(port):
            return True
+        # Report progress every ~5s so a slow boot is visible, not silent.
+        elapsed = time.time() - start
+        if elapsed - last_report >= 5:
+            print(f"  ...still waiting ({int(elapsed)}s/{timeout}s)")
+            last_report = elapsed
        time.sleep(0.5)
    return False

@@ -99,68 +186,148 @@ def main() -> int:
        "--port",
        type=int,
        default=8188,
-        help="Server port (default: 8188)"
+        help="Server port (default: 8188)",
    )
    parser.add_argument(
        "--restart",
        action="store_true",
-        help="Kill existing server before starting"
+        help="Kill the E2E server previously managed by this script for the port "
+        "(tracked via pidfile) before starting; refuse to kill unrelated processes",
    )
    parser.add_argument(
        "--wait",
        action="store_true",
-        help="Wait for server to be ready before exiting"
+        help="Wait for server to be ready before exiting",
    )
    parser.add_argument(
        "--timeout",
        type=int,
        default=30,
-        help="Timeout for waiting (default: 30)"
+        help="Timeout for waiting (default: 30)",
    )
-    
+    parser.add_argument(
+        "--detach",
+        action="store_true",
+        help="Launch the server fully detached (setsid-style) so it survives shell "
+        "death. REQUIRED for E2E: a plain background process dies with the shell",
+    )
+
    args = parser.parse_args()
-    
+
    # Get project root (parent of .agents directory)
    script_dir = os.path.dirname(os.path.abspath(__file__))
    skill_dir = os.path.dirname(script_dir)
    project_root = os.path.dirname(os.path.dirname(os.path.dirname(skill_dir)))
-    
-    # Restart if requested
+
+    managed_pids = read_managed_pids(args.port)
+
+    # Restart if requested: kill ONLY managed PIDs.
    if args.restart:
-        print(f"Killing existing server on port {args.port}...")
-        kill_server(args.port)
+        alive_managed = [pid for pid in managed_pids if process_alive(pid)]
+        if alive_managed:
+            print(
+                f"Killing E2E server previously started by this script on port "
+                f"{args.port} ({describe_processes(alive_managed)})..."
+            )
+            kill_pids(alive_managed, "managed E2E server")
+        else:
+            print(
+                f"No live managed E2E server for port {args.port} "
+                f"(pidfile: {pidfile_path(args.port)})"
+            )
        time.sleep(1)
-    
-    # Check if already running
-    if is_server_ready(args.port):
-        print(f"Server already running on port {args.port}")
-        return 0
-    
+        # Refuse to kill anything the script did not manage.
+        remaining = find_server_process(args.port)
+        if remaining:
+            print(
+                f"ERROR: port {args.port} is still held by process(es) this script "
+                f"did not start: {describe_processes(remaining)}."
+            )
+            print(
+                "These may be unrelated (e.g. a live ComfyUI). The script will NOT "
+                "kill them. Pick a different --port, or stop them manually if you "
+                "are certain they are stale E2E servers."
+            )
+            return 2
+        clear_managed_pids(args.port)
+
+    # Port conflict check before starting: never blind-kill.
+    port_pids = find_server_process(args.port)
+    if port_pids:
+        alive_managed = [pid for pid in port_pids if pid in managed_pids]
+        unmanaged = [pid for pid in port_pids if pid not in managed_pids]
+        if alive_managed and not unmanaged:
+            print(
+                f"Server already running on port {args.port} "
+                f"({describe_processes(alive_managed)}, started by this script). "
+                f"Use --restart to recycle it."
+            )
+            return 0
+        print(
+            f"ERROR: port {args.port} is already in use by process(es): "
+            f"{describe_processes(port_pids)}."
+        )
+        print(
+            "This is likely an unrelated process (e.g. a live ComfyUI holding 8188). "
+            "The script will NOT kill it. Pick a free port with --port, e.g. 8199."
+        )
+        return 2
+
    # Start server
    print(f"Starting LoRa Manager standalone server on port {args.port}...")
-    cmd = [sys.executable, "standalone.py", "--port", str(args.port)]
-    
-    # Start in background
-    process = subprocess.Popen(
-        cmd,
-        cwd=project_root,
-        stdout=subprocess.PIPE,
-        stderr=subprocess.PIPE,
-        start_new_session=True
-    )
-    
-    print(f"Server process started with PID {process.pid}")
-    
+    cmd = [
+        sys.executable,
+        "standalone.py",
+        "--host",
+        "127.0.0.1",
+        "--port",
+        str(args.port),
+    ]
+
+    if args.detach:
+        # Fully detached launch: new session (setsid), no controlling terminal,
+        # stdin from /dev/null, stdout/stderr to a log file. Survives the shell.
+        log_dir = os.path.join(script_dir, "logs")
+        os.makedirs(log_dir, exist_ok=True)
+        log_path = os.path.join(log_dir, f"server-{args.port}.log")
+        with open(log_path, "ab") as log_fh:
+            process = subprocess.Popen(
+                cmd,
+                cwd=project_root,
+                stdin=subprocess.DEVNULL,
+                stdout=log_fh,
+                stderr=subprocess.STDOUT,
+                start_new_session=True,
+                close_fds=True,
+            )
+        print(f"Detached server process started with PID {process.pid} (setsid)")
+        print(f"Log: {log_path}")
+    else:
+        # Plain background process (legacy behavior): dies with the shell.
+        process = subprocess.Popen(
+            cmd,
+            cwd=project_root,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            start_new_session=True,
+        )
+        print(f"Server process started with PID {process.pid}")
+        print(
+            "NOTE: not detached — this process dies when the launching shell exits. "
+            "For E2E use --detach."
+        )
+
+    write_managed_pids(args.port, [process.pid])
+
    # Wait for ready if requested
    if args.wait:
        print(f"Waiting for server to be ready (timeout: {args.timeout}s)...")
        if wait_for_server(args.port, args.timeout):
            print(f"Server ready at http://127.0.0.1:{args.port}/loras")
            return 0
-        else:
-            print(f"Timeout waiting for server")
-            return 1
-    
+        print(f"Timeout waiting for server on port {args.port}")
+        return 1
+
    print(f"Server starting at http://127.0.0.1:{args.port}/loras")
    return 0

@@ -1,15 +1,20 @@
 #!/usr/bin/env python3
 """
 Wait for LoRa Manager server to become ready.
+
+Timeout is configurable via --timeout (default 30s); the script polls the port
+until the server accepts connections or the timeout expires.
 """

+from __future__ import annotations
+
 import argparse
 import socket
 import sys
 import time


-def is_server_ready(port: int, timeout: float = 0.5) -> bool:
+def is_server_ready(port: int, timeout: float = 2.0) -> bool:
    """Check if server is accepting connections."""
    try:
        with socket.create_connection(("127.0.0.1", port), timeout=timeout):
@@ -21,9 +26,15 @@ def is_server_ready(port: int, timeout: float = 0.5) -> bool:
 def wait_for_server(port: int, timeout: int = 30) -> bool:
    """Wait for server to become ready."""
    start = time.time()
+    last_report = 0.0
    while time.time() - start < timeout:
        if is_server_ready(port):
            return True
+        # Report progress every ~5s so a slow boot is visible, not silent.
+        elapsed = time.time() - start
+        if elapsed - last_report >= 5:
+            print(f"  ...still waiting ({int(elapsed)}s/{timeout}s)")
+            last_report = elapsed
        time.sleep(0.5)
    return False

@@ -36,25 +47,24 @@ def main() -> int:
        "--port",
        type=int,
        default=8188,
-        help="Server port (default: 8188)"
+        help="Server port (default: 8188)",
    )
    parser.add_argument(
        "--timeout",
        type=int,
        default=30,
-        help="Timeout in seconds (default: 30)"
+        help="Timeout in seconds (default: 30)",
    )
-    
+
    args = parser.parse_args()
-    
+
    print(f"Waiting for server on port {args.port} (timeout: {args.timeout}s)...")
-    
+
    if wait_for_server(args.port, args.timeout):
        print(f"Server ready at http://127.0.0.1:{args.port}/loras")
        return 0
-    else:
-        print(f"Timeout: Server not ready after {args.timeout}s")
-        return 1
+    print(f"Timeout: Server not ready after {args.timeout}s")
+    return 1


 if __name__ == "__main__":
@@ -0,0 +1,69 @@
+---
+name: lora-manager-runtime-context
+description: Inspect ComfyUI LoRA Manager runtime configuration and local diagnostic state. Use when debugging LoRA Manager issues that require locating or reading settings.json, active library paths, model metadata JSON sidecars, recipe metadata JSON files, example image folders, SQLite caches, symlink maps, download history, aria2 state, or other cache files under the LoRA Manager user config directory.
+---
+
+# LoRA Manager Runtime Context
+
+## Core Rules
+
+- Treat runtime state as local user data. Prefer read-only inspection unless the user explicitly asks for mutation.
+- Never print secret-like settings values. Redact keys containing `key`, `token`, `secret`, `password`, `auth`, or `credential`, including `civitai_api_key`.
+- Resolve paths from the runtime configuration before guessing. In this environment the settings file is normally `/home/miao/.config/ComfyUI-LoRA-Manager/settings.json`, but portable settings can override this through the repository `settings.json`.
+- Use the active library when selecting per-library caches and paths. Read `active_library` from settings; fall back to `default` if missing.
+- Normalize and expand `~` before comparing paths. Symlinks are common in this repo.
+
+## Quick Start
+
+Use the bundled helper for a safe first pass:
+
+```bash
+python .agents/skills/lora-manager-runtime-context/scripts/inspect_runtime_context.py summary
+python .agents/skills/lora-manager-runtime-context/scripts/inspect_runtime_context.py caches
+```
+
+The script redacts sensitive settings, opens SQLite databases read-only, and reports inaccessible or locked databases as warnings.
+
+For focused checks:
+
+```bash
+python .agents/skills/lora-manager-runtime-context/scripts/inspect_runtime_context.py recipes
+python .agents/skills/lora-manager-runtime-context/scripts/inspect_runtime_context.py model --path /path/to/model.safetensors
+python .agents/skills/lora-manager-runtime-context/scripts/inspect_runtime_context.py sqlite --db /path/to/cache.sqlite --limit 3
+```
+
+## Runtime Path Rules
+
+- Settings directory: use `py/utils/settings_paths.py`. Default platform path is `platformdirs.user_config_dir("ComfyUI-LoRA-Manager", appauthor=False)`.
+- Settings file: `<settings_dir>/settings.json`.
+- Cache root: `<settings_dir>/cache`.
+- Canonical cache files:
+  - Model cache: `cache/model/<active_library>.sqlite`.
+  - Recipe cache: `cache/recipe/<active_library>.sqlite`.
+  - Model update cache: `cache/model_update/<active_library>.sqlite`.
+  - Recipe FTS: `cache/fts/recipe_fts.sqlite`.
+  - Tag FTS: `cache/fts/tag_fts.sqlite`.
+  - Symlink map: `cache/symlink/symlink_map.json`.
+  - Download history: `cache/download_history/downloaded_versions.sqlite`.
+  - aria2 state: `cache/aria2/downloads.json`.
+- Legacy cache locations may exist; prefer canonical paths unless diagnosing migrations.
+
+## Data Location Rules
+
+- Model roots come from `settings.folder_paths` and the active library payload under `settings.libraries[active_library]`.
+- Model metadata JSON sidecars live next to the model file as `<model basename>.metadata.json`.
+- Recipes root is `settings.recipes_path` when it is a non-empty string. If empty, use the first configured LoRA root plus `/recipes`.
+- Recipe JSON files are named `*.recipe.json` under the recipes root and may be nested in folders.
+- Example image root is `settings.example_images_path`.
+- If multiple libraries are configured, example images are stored under `<example_images_path>/<sanitized_library>/<sha256>/`; otherwise they are under `<example_images_path>/<sha256>/`.
+
+## Useful Cache Tables
+
+- Model cache: `models`, `model_tags`, `hash_index`, `excluded_models`.
+- Recipe cache: `recipes`, `cache_metadata`.
+- Model update cache: `model_update_status`, `model_update_versions`.
+- Tag FTS cache: `tags`, `fts_metadata`, plus FTS internal tables.
+- Recipe FTS cache: `recipe_rowid`, `fts_metadata`, plus FTS internal tables.
+- Download history: `downloaded_model_versions`.
+
+Prefer querying only counts, schema, and a few sample rows unless the user asks for full output.
@@ -0,0 +1,4 @@
+interface:
+  display_name: "LoRA Manager Runtime Context"
+  short_description: "Inspect LoRA Manager runtime state"
+  default_prompt: "Use $lora-manager-runtime-context to inspect LoRA Manager settings, metadata paths, and caches for debugging."
@@ -0,0 +1,381 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import sqlite3
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+SECRET_PATTERN = re.compile(r"(key|token|secret|password|auth|credential)", re.IGNORECASE)
+APP_NAME = "ComfyUI-LoRA-Manager"
+CACHE_SQLITE = {
+    "model": ("model", "{library}.sqlite"),
+    "recipe": ("recipe", "{library}.sqlite"),
+    "model_update": ("model_update", "{library}.sqlite"),
+    "recipe_fts": ("fts", "recipe_fts.sqlite"),
+    "tag_fts": ("fts", "tag_fts.sqlite"),
+    "download_history": ("download_history", "downloaded_versions.sqlite"),
+}
+CACHE_JSON = {
+    "symlink": ("symlink", "symlink_map.json"),
+    "aria2": ("aria2", "downloads.json"),
+}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Inspect LoRA Manager runtime state read-only.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser("summary", help="Print redacted settings and resolved paths.")
+    subparsers.add_parser("caches", help="Print cache paths and SQLite table summaries.")
+    subparsers.add_parser("recipes", help="Print resolved recipes root and recipe JSON count.")
+
+    model_parser = subparsers.add_parser("model", help="Inspect a model metadata sidecar path.")
+    model_parser.add_argument("--path", required=True, help="Path to a model file or metadata JSON file.")
+
+    sqlite_parser = subparsers.add_parser("sqlite", help="Inspect a SQLite database read-only.")
+    sqlite_parser.add_argument("--db", required=True, help="Path to the SQLite database.")
+    sqlite_parser.add_argument("--limit", type=int, default=3, help="Rows to sample from each user table.")
+
+    args = parser.parse_args()
+    context = build_context()
+
+    if args.command == "summary":
+        print_json(summary_payload(context))
+    elif args.command == "caches":
+        print_json(caches_payload(context))
+    elif args.command == "recipes":
+        print_json(recipes_payload(context))
+    elif args.command == "model":
+        print_json(model_payload(args.path))
+    elif args.command == "sqlite":
+        print_json(sqlite_payload(Path(args.db).expanduser(), args.limit))
+    return 0
+
+
+def build_context() -> dict[str, Any]:
+    settings_path = resolve_settings_path()
+    settings = load_json(settings_path)
+    settings_dir = settings_path.parent
+    active_library = settings.get("active_library") or "default"
+    safe_library = sanitize_library_name(str(active_library))
+    cache_root = settings_dir / "cache"
+    return {
+        "settings_path": str(settings_path),
+        "settings_dir": str(settings_dir),
+        "settings": settings,
+        "active_library": active_library,
+        "safe_library": safe_library,
+        "cache_root": str(cache_root),
+        "cache_paths": resolve_cache_paths(cache_root, safe_library),
+    }
+
+
+def resolve_settings_path() -> Path:
+    repo_root = find_repo_root()
+    portable = repo_root / "settings.json"
+    if portable.exists():
+        payload = load_json(portable)
+        if isinstance(payload, dict) and payload.get("use_portable_settings") is True:
+            return portable
+
+    config_home = os.environ.get("XDG_CONFIG_HOME")
+    if config_home:
+        return Path(config_home).expanduser() / APP_NAME / "settings.json"
+    return Path.home() / ".config" / APP_NAME / "settings.json"
+
+
+def find_repo_root() -> Path:
+    current = Path(__file__).resolve()
+    for parent in current.parents:
+        if (parent / "py").is_dir() and (parent / "standalone.py").exists():
+            return parent
+    return Path.cwd()
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            payload = json.load(handle)
+    except FileNotFoundError:
+        return {}
+    except json.JSONDecodeError as exc:
+        return {"_error": f"invalid JSON: {exc}"}
+    except OSError as exc:
+        return {"_error": f"unreadable: {exc}"}
+    return payload if isinstance(payload, dict) else {"_error": "JSON root is not an object"}
+
+
+def resolve_cache_paths(cache_root: Path, library: str) -> dict[str, str]:
+    paths: dict[str, str] = {}
+    for name, (subdir, filename) in CACHE_SQLITE.items():
+        paths[name] = str(cache_root / subdir / filename.format(library=library))
+    for name, (subdir, filename) in CACHE_JSON.items():
+        paths[name] = str(cache_root / subdir / filename)
+    return paths
+
+
+def summary_payload(context: dict[str, Any]) -> dict[str, Any]:
+    settings = context["settings"]
+    return {
+        "settings_path": context["settings_path"],
+        "settings_dir": context["settings_dir"],
+        "active_library": context["active_library"],
+        "settings": redact(settings),
+        "model_roots": model_roots(settings, context["active_library"]),
+        "recipes_root": str(resolve_recipes_root(settings, context["active_library"]) or ""),
+        "example_images": example_images_payload(settings, context["active_library"]),
+        "cache_root": context["cache_root"],
+        "cache_paths": context["cache_paths"],
+    }
+
+
+def caches_payload(context: dict[str, Any]) -> dict[str, Any]:
+    caches: dict[str, Any] = {}
+    for name, path_string in context["cache_paths"].items():
+        path = Path(path_string)
+        item: dict[str, Any] = {
+            "path": str(path),
+            "exists": path.exists(),
+            "size": path.stat().st_size if path.exists() else None,
+        }
+        if path.suffix == ".sqlite":
+            item["sqlite"] = sqlite_payload(path, limit=0)
+        elif path.suffix == ".json":
+            item["json"] = json_file_summary(path)
+        caches[name] = item
+    return {"active_library": context["active_library"], "caches": caches}
+
+
+def recipes_payload(context: dict[str, Any]) -> dict[str, Any]:
+    root = resolve_recipes_root(context["settings"], context["active_library"])
+    files: list[str] = []
+    if root and root.exists():
+        files = [str(path) for path in sorted(root.rglob("*.recipe.json"))[:20]]
+    return {
+        "recipes_root": str(root or ""),
+        "exists": bool(root and root.exists()),
+        "recipe_json_count": count_recipe_files(root),
+        "sample_recipe_json": files,
+        "recipe_cache": context["cache_paths"].get("recipe"),
+    }
+
+
+def model_payload(raw_path: str) -> dict[str, Any]:
+    path = Path(raw_path).expanduser()
+    metadata_path = path if path.name.endswith(".metadata.json") else path.with_suffix(".metadata.json")
+    payload = {
+        "input_path": str(path),
+        "metadata_path": str(metadata_path),
+        "model_exists": path.exists(),
+        "metadata_exists": metadata_path.exists(),
+    }
+    if metadata_path.exists():
+        data = load_json(metadata_path)
+        payload["metadata_summary"] = redact(summarize_value(data))
+    return payload
+
+
+def sqlite_payload(path: Path, limit: int = 3, allow_copy: bool = True) -> dict[str, Any]:
+    result: dict[str, Any] = {"path": str(path), "exists": path.exists(), "tables": {}}
+    if not path.exists():
+        return result
+    try:
+        conn = connect_sqlite_readonly(path)
+    except sqlite3.Error as exc:
+        result["error"] = str(exc)
+        return result
+    try:
+        table_rows = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
+        ).fetchall()
+        for table_row in table_rows:
+            table = table_row["name"]
+            columns = [
+                row["name"]
+                for row in conn.execute(f"PRAGMA table_info({quote_identifier(table)})").fetchall()
+            ]
+            table_info: dict[str, Any] = {"columns": columns}
+            try:
+                table_info["count"] = conn.execute(
+                    f"SELECT COUNT(*) FROM {quote_identifier(table)}"
+                ).fetchone()[0]
+            except sqlite3.Error as exc:
+                table_info["count_error"] = str(exc)
+            if limit > 0 and columns and not is_internal_sqlite_table(table):
+                try:
+                    rows = conn.execute(
+                        f"SELECT * FROM {quote_identifier(table)} LIMIT ?", (limit,)
+                    ).fetchall()
+                    table_info["sample"] = [redact(dict(row)) for row in rows]
+                except sqlite3.Error as exc:
+                    table_info["sample_error"] = str(exc)
+            result["tables"][table] = table_info
+    except sqlite3.Error as exc:
+        fallback = sqlite_copy_payload(path, limit, str(exc)) if allow_copy else None
+        if fallback is not None:
+            result.update(fallback)
+        else:
+            result["error"] = str(exc)
+    finally:
+        conn.close()
+    return result
+
+
+def connect_sqlite_readonly(path: Path) -> sqlite3.Connection:
+    errors: list[str] = []
+    for query in ("mode=ro", "mode=ro&immutable=1"):
+        try:
+            conn = sqlite3.connect(f"file:{path}?{query}", uri=True)
+            conn.row_factory = sqlite3.Row
+            return conn
+        except sqlite3.Error as exc:
+            errors.append(f"{query}: {exc}")
+    raise sqlite3.OperationalError("; ".join(errors))
+
+
+def sqlite_copy_payload(path: Path, limit: int, original_error: str) -> dict[str, Any] | None:
+    try:
+        with tempfile.TemporaryDirectory(prefix="lm-cache-inspect-") as temp_dir:
+            copy_path = Path(temp_dir) / path.name
+            shutil.copy2(path, copy_path)
+            payload = sqlite_payload(copy_path, limit, allow_copy=False)
+            payload["path"] = str(path)
+            payload["inspected_copy"] = True
+            payload["original_error"] = original_error
+            return payload
+    except Exception:
+        return None
+
+
+def json_file_summary(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {"exists": False}
+    data = load_json(path)
+    return {"exists": True, "summary": redact(summarize_value(data))}
+
+
+def model_roots(settings: dict[str, Any], active_library: str) -> dict[str, list[str]]:
+    roots: dict[str, list[str]] = {}
+    sources = [settings]
+    library = settings.get("libraries", {}).get(active_library)
+    if isinstance(library, dict):
+        sources.insert(0, library)
+    for source in sources:
+        folder_paths = source.get("folder_paths")
+        if isinstance(folder_paths, dict):
+            for key, value in folder_paths.items():
+                roots.setdefault(key, []).extend(normalize_path_list(value))
+    for default_key, folder_key in (
+        ("default_lora_root", "loras"),
+        ("default_checkpoint_root", "checkpoints"),
+        ("default_embedding_root", "embeddings"),
+        ("default_unet_root", "unet"),
+    ):
+        value = settings.get(default_key)
+        if isinstance(value, str) and value:
+            roots.setdefault(folder_key, []).append(expand_path(value))
+    return {key: dedupe(values) for key, values in roots.items()}
+
+
+def resolve_recipes_root(settings: dict[str, Any], active_library: str) -> Path | None:
+    recipes_path = settings.get("recipes_path")
+    library = settings.get("libraries", {}).get(active_library)
+    if isinstance(library, dict) and isinstance(library.get("recipes_path"), str):
+        recipes_path = library["recipes_path"] or recipes_path
+    if isinstance(recipes_path, str) and recipes_path.strip():
+        return Path(expand_path(recipes_path.strip()))
+    lora_roots = model_roots(settings, active_library).get("loras") or []
+    return Path(lora_roots[0]) / "recipes" if lora_roots else None
+
+
+def example_images_payload(settings: dict[str, Any], active_library: str) -> dict[str, Any]:
+    root = settings.get("example_images_path") or ""
+    libraries = settings.get("libraries")
+    library_count = len(libraries) if isinstance(libraries, dict) else 0
+    scoped = library_count > 1
+    root_path = Path(expand_path(root)) if isinstance(root, str) and root else None
+    library_root = root_path / sanitize_library_name(active_library) if root_path and scoped else root_path
+    return {
+        "root": str(root_path or ""),
+        "uses_library_scoped_folders": scoped,
+        "library_root": str(library_root or ""),
+    }
+
+
+def count_recipe_files(root: Path | None) -> int:
+    if not root or not root.exists():
+        return 0
+    return sum(1 for _ in root.rglob("*.recipe.json"))
+
+
+def normalize_path_list(value: Any) -> list[str]:
+    if isinstance(value, str):
+        return [expand_path(value)] if value else []
+    if isinstance(value, list):
+        return [expand_path(item) for item in value if isinstance(item, str) and item]
+    return []
+
+
+def expand_path(value: str) -> str:
+    return str(Path(value).expanduser().resolve(strict=False))
+
+
+def sanitize_library_name(name: str) -> str:
+    safe = re.sub(r"[^A-Za-z0-9_.-]", "_", name or "default")
+    return safe or "default"
+
+
+def dedupe(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for value in values:
+        if value not in seen:
+            result.append(value)
+            seen.add(value)
+    return result
+
+
+def redact(value: Any, key: str = "") -> Any:
+    if key and SECRET_PATTERN.search(key):
+        return "<redacted>"
+    if isinstance(value, dict):
+        return {str(k): redact(v, str(k)) for k, v in value.items()}
+    if isinstance(value, list):
+        return [redact(item) for item in value]
+    return value
+
+
+def summarize_value(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {key: summarize_value(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return {
+            "type": "array",
+            "length": len(value),
+            "first": summarize_value(value[0]) if value else None,
+        }
+    return value
+
+
+def quote_identifier(identifier: str) -> str:
+    return '"' + identifier.replace('"', '""') + '"'
+
+
+def is_internal_sqlite_table(table: str) -> bool:
+    return table.startswith("sqlite_") or table.endswith(("_data", "_idx", "_docsize", "_config", "_content"))
+
+
+def print_json(payload: Any) -> None:
+    json.dump(payload, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -1,153 +0,0 @@
-# Recipe Batch Import Feature Design
-
-## Overview
-Enable users to import multiple images as recipes in a single operation, rather than processing them individually. This feature addresses the need for efficient bulk recipe creation from existing image collections.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Frontend                                  │
-├─────────────────────────────────────────────────────────────────┤
-│  BatchImportManager.js                                          │
-│  ├── InputCollector (收集URL列表/目录路径)                        │
-│  ├── ConcurrencyController (自适应并发控制)                       │
-│  ├── ProgressTracker (进度追踪)                                   │
-│  └── ResultAggregator (结果汇总)                                  │
-├─────────────────────────────────────────────────────────────────┤
-│  batch_import_modal.html                                        │
-│  └── 批量导入UI组件                                              │
-├─────────────────────────────────────────────────────────────────┤
-│  batch_import_progress.css                                      │
-│  └── 进度显示样式                                                │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                        Backend                                   │
-├─────────────────────────────────────────────────────────────────┤
-│  py/routes/handlers/recipe_handlers.py                          │
-│  ├── start_batch_import() - 启动批量导入                         │
-│  ├── get_batch_import_progress() - 查询进度                      │
-│  └── cancel_batch_import() - 取消导入                            │
-├─────────────────────────────────────────────────────────────────┤
-│  py/services/batch_import_service.py                            │
-│  ├── 自适应并发执行                                              │
-│  ├── 结果汇总                                                    │
-│  └── WebSocket进度广播                                           │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## API Endpoints
-
-| 端点 | 方法 | 说明 |
-|------|------|------|
-| `/api/lm/recipes/batch-import/start` | POST | 启动批量导入，返回 operation_id |
-| `/api/lm/recipes/batch-import/progress` | GET | 查询进度状态 |
-| `/api/lm/recipes/batch-import/cancel` | POST | 取消导入 |
-
-## Backend Implementation Details
-
-### BatchImportService
-
-Location: `py/services/batch_import_service.py`
-
-Key classes:
- `BatchImportItem`: Dataclass for individual import item
- `BatchImportProgress`: Dataclass for tracking progress
- `BatchImportService`: Main service class
-
-Features:
- Adaptive concurrency control (adjusts based on success/failure rate)
- WebSocket progress broadcasting
- Graceful error handling (individual failures don't stop the batch)
- Result aggregation
-
-### WebSocket Message Format
-
-```json
-{
-    "type": "batch_import_progress",
-    "operation_id": "xxx",
-    "total": 50,
-    "completed": 23,
-    "success": 21,
-    "failed": 2,
-    "skipped": 0,
-    "current_item": "image_024.png",
-    "status": "running"
-}
-```
-
-### Input Types
-
-1. **URL List**: Array of URLs (http/https)
-2. **Local Paths**: Array of local file paths
-3. **Directory**: Path to directory with optional recursive flag
-
-### Error Handling
-
- Invalid URLs/paths: Skip and record error
- Download failures: Record error, continue
- Metadata extraction failures: Mark as "no metadata"
- Duplicate detection: Option to skip duplicates
-
-## Frontend Implementation Details (TODO)
-
-### UI Components
-
-1. **BatchImportModal**: Main modal with tabs for URLs/Directory input
-2. **ProgressDisplay**: Real-time progress bar and status
-3. **ResultsSummary**: Final results with success/failure breakdown
-
-### Adaptive Concurrency Controller
-
-```javascript
-class AdaptiveConcurrencyController {
-    constructor(options = {}) {
-        this.minConcurrency = options.minConcurrency || 1;
-        this.maxConcurrency = options.maxConcurrency || 5;
-        this.currentConcurrency = options.initialConcurrency || 3;
-    }
-
-    adjustConcurrency(taskDuration, success) {
-        if (success && taskDuration < 1000 && this.currentConcurrency < this.maxConcurrency) {
-            this.currentConcurrency = Math.min(this.currentConcurrency + 1, this.maxConcurrency);
-        }
-        if (!success || taskDuration > 10000) {
-            this.currentConcurrency = Math.max(this.currentConcurrency - 1, this.minConcurrency);
-        }
-        return this.currentConcurrency;
-    }
-}
-```
-
-## File Structure
-
-```
-Backend (implemented):
-├── py/services/batch_import_service.py            # 后端服务
-├── py/routes/handlers/batch_import_handler.py     # API处理器 (added to recipe_handlers.py)
-├── tests/services/test_batch_import_service.py    # 单元测试
-└── tests/routes/test_batch_import_routes.py       # API集成测试
-
-Frontend (TODO):
-├── static/js/managers/BatchImportManager.js       # 主管理器
-├── static/js/managers/batch/                       # 子模块
-│   ├── ConcurrencyController.js                    # 并发控制
-│   ├── ProgressTracker.js                          # 进度追踪
-│   └── ResultAggregator.js                         # 结果汇总
-├── static/css/components/batch-import-modal.css   # 样式
-└── templates/components/batch_import_modal.html    # Modal模板
-```
-
-## Implementation Status
-
- [x] Backend BatchImportService
- [x] Backend API handlers
- [x] WebSocket progress broadcasting
- [x] Unit tests
- [x] Integration tests
- [ ] Frontend BatchImportManager
- [ ] Frontend UI components
- [ ] E2E tests
@@ -13,8 +13,5 @@ A clear and concise description of what the problem is. Ex. I'm always frustrate
 **Describe the solution you'd like**
 A clear and concise description of what you want to happen.

-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
-
 **Additional context**
 Add any other context or screenshots about the feature request here.
@@ -7,15 +7,25 @@ py/run_test.py
 .vscode/
 cache/
 civitai/
+stats/
+wildcards/
+backups/
+logs/
 node_modules/
 coverage/
 .coverage
 model_cache/

-# agent
+# agent / dev tooling
 .opencode/
 .claude/
+.sisyphus/
 .codex
+.omo
+reasonix.toml
+.reasonix/
+.codegraph/
+.playwright-mcp/

 # Vue widgets development cache (but keep build output)
 vue-widgets/node_modules/
@@ -24,3 +34,10 @@ vue-widgets/dist/

 # Hypothesis test cache
 .hypothesis/
+
+# 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/
@@ -0,0 +1,202 @@
+---
+slug: undo-delete-staging
+status: drafting
+intent: clear
+review_required: false
+pending-action: write .omo/plans/undo-delete-staging.md
+approach: "Option B: delayed physical deletion with Undo. Backend: same-volume rename to per-root staging dir (.lm-pending-delete/) [updated 2026-08: model staging moved to a SIBLING dir inside each deleted model's own folder — see 'Symlink fix (2026-08)' under Decisions] + manifest JSON (batch_id, expires_at, staged->original map) + purge (30s TTL timer + startup sweep + opportunistic) + undo-delete endpoint + settings toggle 'skip undo'. Small files (recipes: JSON+preview) copy to global staging under settings dir instead of rename. Frontend: extend toast system with action button + 30s countdown; delete flows (single model / recipe / bulk / duplicates) consume batch_id from delete response and show Undo toast; expired undo -> 'undo expired' toast. Plus confirm-modal friction (C-friction, NO type-to-confirm): delete button delay-activation 1.5s + modal shows file size 'will free X GB' + Cancel gets initial focus. i18n keys + sync_translation_keys.py."
+---
+
+# Draft: undo-delete-staging
+
+## Components (topology ledger)
+<!-- Lock the SHAPE before depth. One row per top-level component that can succeed or fail independently. -->
+<!-- id | outcome (one line) | status: active|deferred | evidence path -->
+- backend staging module (stage/purge/undo + manifest + per-volume dir resolution) | new module, active | pending exploration: model_lifecycle_service.py delete_model / delete_model_artifacts
+- delete endpoints return batch_id (model/recipe/bulk/duplicates) | active | pending exploration: handlers + response shapes
+- undo-delete HTTP endpoint + route registration | active | pending exploration: route registrar pattern
+- purge scheduling (30s timer + startup sweep + opportunistic) | active | pending exploration: app on_startup hooks
+- settings toggle "skip undo window" | active | pending exploration: settings service read pattern
+- frontend toast extension (action button + countdown) | active | pending exploration: showToast impl
+- frontend delete flows consume batch_id + Undo toast | active | pending exploration: call sites
+- confirm-modal friction (delay-activate + size display + cancel focus) | active | pending exploration: modal focus behavior
+- i18n keys + sync_translation_keys.py | active | known
+
+## Open assumptions (announced defaults)
+<!-- Record any default you adopt instead of asking, so the user can veto it at the gate. -->
+<!-- assumption | adopted default | rationale | reversible? -->
+- Undo window TTL = 30s | 30s balances space-freeing intent vs accident recovery | yes (constant)
+- Staging dir name: `.lm-pending-delete/` under each model root; recipes: `{settings_dir}/.lm-pending-delete/` | hidden, same-volume [updated 2026-08: same-volume is now guaranteed by sibling staging inside the model's own folder, not by the root location], consistent | yes
+- Staging failure falls back to existing hard delete | user intent is delete; staging is best-effort; hard delete likely fails identically under same conditions | yes
+- Purge on startup uses expires_at (not purge-all) so a <30s restart with live tab can still undo | robust, matches client-side timer | yes
+- Settings toggle label: "Delete permanently immediately (skip undo window)" | power users freeing space | yes
+- C-friction: delete button enabled after 1.5s + modal shows freed size; NO type-to-confirm (user vetoed) | user explicitly rejected type-to-confirm | n/a
+- Bulk/duplicates delete: one batch id for whole action, one undo restores all | simplest consistent semantics | yes
+
+## Findings (cited - path:lines)
+
+### Backend
+- `delete_model_artifacts` (py/services/model_lifecycle_service.py:19-48) = physical delete via os.remove; patterns: main file + `{name}.metadata.json` + PREVIEW_EXTENSIONS (py/utils/constants.py:22-37). ALSO called by ModelScanner.bulk_delete_models (py/services/model_scanner.py:2221) - single swap point covers bulk models.
+- `ModelLifecycleService.delete_model` (model_lifecycle_service.py:101-154): fetches `cached_entry` (111-116) - SNAPSHOT available for cache restore; after delete: cache.raw_data removal + resort + bump_cache_version (136-143), `_hash_index.remove_by_path` (145-146), `_sync_update_for_model` (148; update-service only, no recipe JSON rewrites - recipe refs are hash-based, re-resolve on restore), `_persist_current_cache` (150-152), returns `{"success": True, "deleted_files": [...]}` (154).
+- Handler `delete_model` (py/routes/handlers/model_handlers.py:478-492): POST /api/lm/{prefix}/delete; response passthrough; `_broadcast_models_changed()` (57-74) after success; 400 `{"success":false,"error"}`; 500 plain text.
+- Recipe delete: handler (recipe_handlers.py:1422-1438) DELETE /api/lm/recipe/{recipe_id} -> persistence_service.delete_recipe (py/services/recipes/persistence_service.py:193-209): os.remove(recipe_json_path) + os.remove(image_path) (204-206), recipe_scanner.remove_recipe (208), returns `{"success": true, "message": ...}`. PersistenceResult dataclass (20-25).
+- Bulk models: POST /api/lm/{prefix}/bulk-delete (model_route_registrar.py:39) -> handler (model_handlers.py:974-994) -> lifecycle_service.bulk_delete_models (model_lifecycle_service.py:308-318) -> scanner.bulk_delete_models (model_scanner.py:2181-2269) which calls delete_model_artifacts per file (2221) + `_batch_update_cache_for_deleted_models` (2271-2335); response `{"success","status","total_deleted","total_attempted","cache_updated","results"}` (2254-2269).
+- Bulk recipes: POST /api/lm/recipes/bulk-delete (recipe_route_registrar.py:50) -> handler (recipe_handlers.py:1554-1573) -> persistence_service.bulk_delete (persistence_service.py:439-482): per-id os.remove x2 (464-466), recipe_scanner.bulk_remove (472); response `{"success","deleted","failed","total_deleted","total_failed"}` (474-482).
+- Duplicates: NO dedicated delete endpoints (find-only: GET /api/lm/{prefix}/find-duplicates model_route_registrar.py:59, GET /api/lm/recipes/find-duplicates recipe_route_registrar.py:49). Duplicate deletion reuses bulk-delete endpoints.
+- Startup hooks: lora_manager.py:183-187 `app.on_startup.append(lambda app: cls._initialize_services())` (ComfyUI mode, app = PromptServer.instance.app at :78); standalone.py:370-374 same (StandaloneLoraManager.add_routes). Background tasks: `asyncio.create_task(name=...)` (lora_manager.py:224-239; recipe_handlers.py:793). Singleton+asyncio.Lock pattern: model_scanner.py:40-63.
+- Settings: DEFAULT_SETTINGS (py/services/settings_manager.py:57-119), `get(key, default)` (1390-1392), get_settings_manager() (2215-2228), reset_settings_manager() (2231). Typed-bool getter example: get_skip_previously_downloaded_model_versions (1253-1262). Handlers: base_model_routes.py:70, base_recipe_routes.py:54.
+- Model roots: ModelScanner.get_model_roots base NotImplementedError (model_scanner.py:1073-1075); impls lora_scanner.py:31-45, checkpoint_scanner.py:428-441, embedding_scanner.py:24-36. `_find_root_for_file(file_path)` (model_scanner.py:1108-1124) returns containing root - for per-root staging dir computation [updated 2026-08: staging no longer uses the containing root; batches are siblings inside the model's own folder]. Business-path rule (AGENTS.md): use os.path.abspath, never realpath, for staging/undo routing.
+- Cache restore methods: ModelCache has raw_data + resort (conftest mocks: tests/conftest.py:144-154); ModelHashIndex.add_entry(sha256, file_path, autov3) (py/services/model_hash_index.py:16); RecipeScanner.add_recipe(recipe_data) (recipe_scanner.py:2136) -> recipe_cache.add_recipe (recipe_cache.py:64). No single-file incremental model rescan - use snapshot restore instead of rescan.
+- Route registrar: model_route_registrar.py:177 add_route(method, path, handler), :180 add_prefixed_route - undo endpoint can be a non-prefixed route via add_route.
+- Tests: tests/services/test_model_lifecycle_service.py (inline tmp_path files, per-test stub scanners ScannerForDelete/VersionAwareScanner etc); conftest MockScanner/MockCache/MockHashIndex (tests/conftest.py:134-212); integration fixtures tests/integration/conftest.py; lifecycle hook tests tests/routes/test_lora_manager_lifecycle.py:177-178, tests/standalone/test_standalone_server.py:83-84.
+
+### Frontend
+- 5 delete call sites:
+  a) Single model: static/js/utils/modalUtils.js confirmDelete (27-42) -> getModelApiClient().deleteModel(path); ignores return.
+  b) Recipe single: static/js/components/RecipeCard.js confirmDeleteRecipe (405-449) - RAW fetch DELETE /api/lm/recipe/{id}, checks only response.ok, showToast toast.recipes.deletedSuccessfully, state.virtualScroller.removeItemByFilePath.
+  c) Bulk: static/js/managers/BulkManager.js confirmBulkDelete (633-672) -> getActiveApiClient() (134-142) -> bulkDeleteModels(filePaths); reads result.cancelled/success/deleted_count/error.
+  d) Recipe duplicates: static/js/components/DuplicatesManager.js confirmDeleteDuplicates (457-494) - RAW fetch POST /api/lm/recipes/bulk-delete, reads data.success/data.total_deleted, exitDuplicateMode().
+  e) Model duplicates: static/js/components/ModelDuplicatesManager.js confirmDeleteDuplicates (710-776) - RAW fetch POST /api/lm/{type}/bulk-delete, reads data.total_deleted, then resetAndReload(true) + find-duplicates re-check.
+  Bonus: static/js/components/shared/ModelVersionsTab.js:1136-1144 client.deleteModel (ignores return).
+- API clients: BaseModelApiClient.deleteModel (static/js/api/baseModelApi.js:184-216) returns true/false, shows its own toasts, does removeItemByFilePath inside; bulkDeleteModels (1591-1642) returns {success, deleted_count, failed_count, errors} or {success:false, cancelled:true}; RecipeSidebarApiClient.bulkDeleteModels (recipeApi.js:623-664) returns {success, deleted_count: total_deleted, ...}. Endpoint map apiConfig.js:56,64.
+- Toast: showToast(key, params={}, type='info', fallback=null) (static/js/utils/uiHelpers.js:136-193) - textContent only, NO action/button support; durations 2000/5000ms; CSS static/css/components/toast.css (.toast flex gap:12px - button can be added). Closest action pattern: bannerService.registerBanner actions array + onRegister (static/js/managers/BannerService.js; used uiHelpers.js:18-57).
+- i18n: locales/en.json delete keys (1303-1314 bulkDelete, 1945-1948 recipes, 1987-1991 models, 2124-2130 duplicates, 2166-2170 toast.api); t()/interpolate (static/js/i18n/index.js:193-248); translate wrapper (utils/i18nHelpers.js:13-23); sync script scripts/sync_translation_keys.py (en reference, [TODO: Translate] placeholders).
+- Refresh after undo: recipes -> window.recipeManager.loadRecipes(true) (recipes.js:359; used by FilterManager.js:752 etc) or refreshRecipes (recipeApi.js:308); models -> resetAndReload(true) from modelApiFactory (used by ModelDuplicatesManager.js:740).
+- Size for modal: card.dataset.file_size (ModelCard.js:467), formatFileSize (ModelModal.js:615).
+- Tests: tests/frontend/utils/uiHelpers.dom.test.js (toast), api/recipeApi.bulk.test.js, components/duplicatesManager.test.js, components/modelDuplicatesManager.test.js, pages/*Page.test.js, i18n tests tests/i18n/test_i18n.py.
+
+## Decisions (with rationale)
+
+1. Same-volume rename staging for model files (atomic, no copy cost for multi-GB files); cross-volume rename forbidden. [CORRECTED 2026-08: "same-volume because under the containing root" was only true for plain directories — nested symlinked subdirs could cross volumes. Superseded by sibling staging: `.lm-pending-delete/<batch_id>/` inside the deleted model's own folder makes stage/undo same-device by construction; see "Symlink fix (2026-08)" below.]
+2. Copy-to-global-staging for recipes (small files; avoids recipe JSON vs preview image cross-volume problem).
+3. Manifest JSON files are the only state - no DB changes. Manifest includes model cached_entry snapshot for exact cache restore (no rescan needed).
+4. Undo endpoint returns restored paths; expired batch -> 404-style error -> frontend 'undo expired' toast.
+5. Skip-undo setting honored server-side (no batch_id in response -> no undo toast client-side).
+6. Staging failure falls back to existing hard delete (best-effort undo, never blocks delete).
+7. Undo window TTL = 30s constant (PENDING_DELETE_TTL_SECONDS); startup sweep uses expires_at (survives restart; browser-tab timer survives).
+8. Purge triple-trigger: per-batch asyncio timer task + on_startup sweep + opportunistic purge at each stage/undo.
+9. Frontend: new showActionToast (keep showToast signature untouched; extract shared createToastElement/appendToast internals); undo click -> shared handleUndoDelete(batchId, refreshFn); full list refresh after undo (recipes: window.recipeManager.loadRecipes(true); models: resetAndReload(true)).
+10. C-friction wave (NO type-to-confirm - user vetoed): delete buttons delay-activate 1.5s after modal open, initial focus on Cancel, model delete modal gains "permanently deleted from disk" warning + file size display (card.dataset.file_size + formatFileSize).
+11. Model cache restore on undo: append snapshot to cache.raw_data (dedupe by file_path) + resort + bump_cache_version + _persist_current_cache + _hash_index.add_entry + _broadcast_models_changed. Recipe restore: copy back files + recipe_scanner.add_recipe(recipe_data loaded from restored JSON).
+
+### Symlink fix (2026-08)
+
+Post-execution addendum (plan `.omo/plans/undo-delete-symlink-fix.md`, commits 5fd4946b / 0c00ee22):
+
+12. Model staging moved from `<model_root>/.lm-pending-delete/<batch_id>/` to `<model_dir>/.lm-pending-delete/<batch_id>/` (sibling of the model artifacts, inside the deleted model's own folder). Stage/undo renames are same-device BY CONSTRUCTION — EXDEV is impossible even when the business path traverses nested symlinks to other volumes (the decision-1 "containing root" guarantee covered only plain directories). EXDEV remains possible only for cross-volume merges, which keep the batch_ids-array fallback. Accepted edge: deleting the model's whole FOLDER during the 30s window destroys that batch (undo returns 404). Batch discovery uses an in-memory registry (`_known_batch_dirs`) with a startup reconciliation scan (`purge_expired(scan_roots=True)`) covering restarts and crash leftovers. Recipe batches unchanged (copy-based settings-dir staging with the `_restore_file` EXDEV fallback).
+
+## Scope IN
+
+- Model single delete (model_handlers delete_model / model_lifecycle_service)
+- Recipe delete (recipe_handlers delete_recipe / persistence_service)
+- Bulk delete (models scanner + recipes persistence) + duplicates (reuse bulk endpoints)
+- Undo endpoint POST /api/lm/undo-delete (models + recipes, one batch space)
+- Purge: timer + startup sweep + opportunistic
+- Settings toggle delete_undo_enabled + settings page checkbox
+- Frontend: showActionToast + all 5 delete flows + shared undo handler
+- C-friction modal changes (delay-activate + cancel focus + warning copy + size display)
+- i18n keys + sync_translation_keys.py
+- Backend + frontend tests
+
+## Scope OUT (Must NOT have)
+
+- NO type-to-confirm / hold-to-confirm friction (user vetoed)
+- NO OS trash integration (send2trash) in this iteration
+- NO persistent recycle-bin UI (no trash browsing page)
+- NO changes to exclude/unexclude flow
+- NO DB migrations
+- NO new dependencies (no send2trash)
+- NO changes to download flows
+- NO recipe-JSON rewriting on model undo (hash-based refs re-resolve themselves)
+
+## Open questions
+
+None - all implementation details resolved by exploration. Design decisions settled in conversation (B+C, no type-to-confirm).
+
+## Approval gate
+status: approved
+<!-- Approach approved -> rerun scaffold without --draft-only, run Metis gap analysis, APPEND todo batches, fill TL;DR last, run structural self-check, then Phase 4 handoff. -->
+
+## Review round state (ulw-plan-review-round-state-contract)
+```json
+{
+  "transition": "replace",
+  "phase": "review_round_initialized",
+  "applies_when": ["retry_after_plan_change"],
+  "atomic": true,
+  "review_required": true,
+  "plan_path": ".omo/plans/undo-delete-staging.md",
+  "plan_sha256": "8cf7c9be38a76d8ef1fb832aba043d6d7e82b60465b1bf28c6eafa7045117adc",
+  "review_round_id": "rr-undo-del-20260811-006",
+  "round_status": "active",
+  "pending-action": "review .omo/plans/undo-delete-staging.md",
+  "review": {
+    "momus": { "status": "pending", "workspace_root": "/mnt/data/reinstall-backup-2026-04-12/data/workspace/ComfyUI/custom_nodes/ComfyUI-Lora-Manager", "runtime_home": null, "target": ".omo/plans/undo-delete-staging.md", "round_id": "rr-undo-del-20260811-006", "plan_sha256": "8cf7c9be38a76d8ef1fb832aba043d6d7e82b60465b1bf28c6eafa7045117adc", "launch_id": null, "session": null, "result": null },
+    "independent": { "status": "pending", "workspace_root": "/mnt/data/reinstall-backup-2026-04-12/data/workspace/ComfyUI/custom_nodes/ComfyUI-Lora-Manager", "runtime_home": null, "target": ".omo/plans/undo-delete-staging.md", "round_id": "rr-undo-del-20260811-006", "plan_sha256": "8cf7c9be38a76d8ef1fb832aba043d6d7e82b60465b1bf28c6eafa7045117adc", "launch_id": null, "session": null, "result": null }
+  }
+}
+```
+
+## Review results + fix/retry ledger
+
+### Round 1 (rr-undo-del-20260811-001, plan sha256 6c52bf99...)
+- momus: APPROVE (non-blocking notes: todo1+7 duplicate DEFAULT_SETTINGS key -> fixed todo 7 to verify-only; "batch_ids" plural in todos 8/9 acceptance -> fixed; purge OSError note -> folded into todo 1 purge semantics)
+- independent (oracle): CHANGES_REQUESTED
+  - BLOCKING S1: scanner walks would index .lm-pending-delete staged files as ghost entries -> fixed: todo 1 now mandates scanner walk exclusion at model_scanner.py:706/:867/:1404/_process_model_file + acceptance (o) scanner-visibility test
+  - BLOCKING S2: manifest lacks model_type, undo could restore into wrong cache/hash index -> fixed: manifest now carries model_type + todo 5 resolves per-type scanner via registrar pattern + acceptance (b) checkpoint-batch test
+  - S3 merged-batch expires_at re-anchor -> fixed: merge_batches re-anchors now+TTL in todo 1 + todo 3/4 assertions
+  - S4 manifest-less dir policy -> fixed: quarantine to <batch_id>.orphaned, never delete (todo 1 + acceptance g)
+  - S5 partial-undo retry semantics -> fixed: per-entry restored flag write-through + retry test (acceptance e)
+  - S6 purge locked-file failure semantics -> fixed: skip file, keep batch, never rmtree past errors (todo 1 + acceptance i)
+  - T8 undo-after-restart test -> fixed: todo 5 acceptance (f)
+  - T9 recipe undo -> re-delete test -> fixed: todo 5 acceptance (h)
+  - T7 rescan-stale-entry test -> fixed: todo 5 acceptance (g)
+  - Route registration pinned to shared routes class per mode (NOT per-model-type registrar which registers 3x) -> fixed: todo 5 now creates py/routes/pending_delete_routes.py registered once in lora_manager.py:170-172 + standalone.py:356-358 + duplicate-route test (e)
+  - Version-index staleness on single-delete undo -> fixed: todo 5 follows bulk cache-update pattern incl. rebuild_version_index (model_scanner.py:2324)
+  - Cancelled-bulk batch_id frontend handling -> fixed: todo 9 shows action toast on cancelled+staged-subset
+  - Single-instance assumption -> added to Scope OUT
+  - Occupied-refusal loss UX -> accepted-intent documented in success criteria + modal copy
+
+### Round 2 (rr-undo-del-20260811-002, plan sha256 f3d52235...)
+- momus: APPROVE (all 12 round-1 fixes verified present; zero dead references; non-blocking nits only)
+- independent (oracle): CHANGES_REQUESTED
+  - BLOCK-1: merge_batches file-movement semantics unspecified (silent data-loss vector) -> fixed: todo 1 now specifies move-into-winner-dir + entry re-point + loser-dirs-removed-only-when-empty + abort-on-move-failure (all batches intact) + merge inside service lock + acceptance (k) file-survival assertions + acceptance (l) merge-failure abort test
+  - BLOCK-2: same-file parallel edits within waves (todo 5 vs 6 on lora_manager.py; todo 8 vs 9 on baseModelApi.js) -> fixed: waves/matrix now serialize 5->6 and 8->9 with explicit reasons; matrix updated
+  - Recommended: checkpoint_scanner.py:331 exclusion -> fixed (todo 1 + acceptance p); S5 pre-check skips restored:true entries -> fixed (todo 1); _tags_count restore on undo -> fixed (todo 5 + acceptance j); undo-blind flows documented (ModelVersionsTab + misc_handlers:2456) -> fixed (todo 8 note + Scope OUT); merge-failure no-merge fallback contract (batch_ids array) -> fixed (todos 3/4/9)
+
+### Round 3 (rr-undo-del-20260811-003, plan sha256 8f2dfd46...)
+- momus: APPROVE (all round-2 fixes verified present + spot-checked refs; no new contradictions)
+- independent (oracle): CHANGES_REQUESTED
+  - BLOCKING A: merged batches never timer-purged after re-anchor (winner's original timer no-ops at old expiry; no fresh timer for re-anchored expiry; idle server -> merged batch lingers, violating "30s purge" success criterion; affects EVERY bulk delete) -> fixed: todo 1 merge_batches now ARMS A FRESH PURGE TIMER for the winner with re-anchored expiry + acceptance (q) fresh-timer test + purge_expired must enumerate ALL scanner types' roots (explicit in todo 1)
+  - BLOCKING B: dependency matrix contradicted same-file policy for todos 8/9<->11 (5 shared files) and 12<->11 -> fixed: todo 11 now "Blocked by: 8, 9 (same files...)"; todo 12 blocked by 11 (sync after 11); wave text updated (11, then 12 AFTER 11); "Can parallelize with" columns corrected
+  - BLOCKING C: frontend batch_ids sequential-undo fallback has NO test + merge->undo loser-restore + merge->purge assertions missing -> fixed: todo 9 acceptance now tests the batch_ids fallback path; todo 1 acceptance now has (k2)/(k3)
+  - Notes folded: sub-second toast-tail expiry race accepted; EXDEV fallback = NORMAL path for cross-volume bulks [annotated 2026-08: after the sibling-staging fix, EXDEV can only arise during cross-volume MERGES, never during single stage/undo renames]
+
+### Round 4 (rr-undo-del-20260811-004, plan sha256 179e7ff7...)
+- momus: APPROVE (round-3 fixes verified; one non-blocking nit: todo 11 inline "Blocked by: —" stale -> fixed to "8, 9")
+- independent (oracle): CHANGES_REQUESTED
+  - BLOCKING GAP-1 (NEW, introduced by round-3 fix): todo 8 handleUndoDelete always-refresh/always-toast contract contradicted todo 9's sequential loop "exactly ONE final refresh" -> fixed: handleUndoDelete(batchId, refreshFn, {showToast, refresh}) suppression options; todo 9 loop uses suppressed calls + one final refresh/toast; acceptance extended (loop failure mid-way -> stop + error toast + no final refresh; 404 body discrimination expired vs occupied)
+  - BLOCKING GAP-2: no cross-type purge enumeration test -> fixed: todo 1 acceptance (r) purges expired batches across lora root + checkpoint root + recipe staging dir in one call
+  - Non-blocking folded: GAP-3 404-copy discrimination -> fixed in todo 8 (d); GAP-4 merge partial-failure rollback direction (move back + restore manifests, extended (l) asserts sequential constituent undo still restores everything) -> fixed in todo 1; GAP-5 post-restart timer-loss residual gap documented -> fixed in todo 6; GAP-6 usage_stats.py:424 walk added to exclusion mandate + todo 5 acceptance (k) embeddings undo test
+
+### Round 5 (rr-undo-del-20260811-005, plan sha256 dfaa39ea...)
+- momus: APPROVE (all round-4 fixes verified; no new contradictions)
+- independent (oracle): CHANGES_REQUESTED
+  - BLOCK-1: lock-ordering deadlock ambiguity (asyncio.Lock not re-entrant: opportunistic purge_expired called while stage/undo hold the lock would deadlock on first use) -> fixed: todo 1 now has explicit LOCK HIERARCHY (lock acquired ONLY by stage/merge/undo/purge_batch; purge_expired is lock-free and must be called BEFORE lock acquisition); todo 6 (c) updated with the same rule + acceptance (u) lock-no-deadlock test
+  - BLOCK-2: purge edge semantics unspecified -> fixed: purge_batch treats missing staged files (partially-restored batches) as already-purged (FileNotFoundError silent no-op); sweep skips `.orphaned`-suffixed dirs (quarantine is terminal); acceptance (s) partially-restored purge + (t) quarantine-terminal tests
+  - Non-blocking folded: todo 2/3 test-file collision -> todo 3's bulk tests moved to tests/services/test_model_scanner.py; todo 9 (d) DuplicatesManager refreshFn stated explicitly (recipes loadRecipes / models resetAndReload); modal-copy + bulk-count trade-offs acknowledged in success criteria; acceptance (r) extended with embeddings root
+
+### Round 6 (rr-undo-del-20260811-006, plan sha256 8cf7c9be...)
+- momus: APPROVE (all round-5 fixes verified; no new contradictions; references verified)
+- independent (oracle): APPROVE — no blocking issues; all round-5 items fixed with working, tested solutions; no new race/data-loss/consistency defects
+- Deferred optional improvements (non-blocking, recorded for executor awareness; plan file left untouched to preserve the approved digest):
+  1. Tag-count asymmetry: single delete_model never decrements _tags_count (lifecycle 101-154), bulk does (scanner 2297-2303); undo re-increment is exact for bulk, over-counts for single until rescan (cosmetic, self-healing). Optional fix riding in todo 2: decrement tags in the single-delete path to mirror bulk.
+  2. Todo 5 factual nit: ModelCache.resort() already rebuilds the version index — explicit rebuild in undo is belt-and-braces, no action needed.
+  3. Todo 8 premise nit: ModelVersionsTab call ignores deleteModel's return entirely — nothing breaks, no adaptation needed.
+  4. Todo 3's pytest command includes test_model_lifecycle_service.py which todo 2 edits in the same wave — run that file's tests after todo 2 lands.
+  5. merge_batches with a missing/quarantined constituent id: any sane fallback (abort -> batch_ids, or skip missing) acceptable — files stay staged either way.
+
+## Review lifecycle
+- rounds: 6 (rr-undo-del-20260811-001..006); final round both lanes APPROVE
+- final live-plan validation: sha256 = 8cf7c9be38a76d8ef1fb832aba043d6d7e82b60465b1bf28c6eafa7045117adc — MATCHES approved round-6 digest
+- status: APPROVED — ready for execution handoff ($start-work undo-delete-staging)
@@ -0,0 +1,181 @@
+# Embeddings Usage Tracking — Hybrid Approach (Plan C)
+
+> **Status**: Reference document for future implementation
+> **Current implementation**: Plan A (prompt text parsing only, see `usage_stats.py:_process_embeddings`)
+> **Next step**: Add Plan B as a supplement when edge-case coverage is needed
+
+## Problem
+
+Embeddings in ComfyUI are not loaded through dedicated ComfyUI nodes like LoRAs or
+Checkpoints. They are resolved during CLIP tokenization when the prompt text contains
+`embedding:<name>` syntax (see `comfy/sd1_clip.py:SDTokenizer.tokenize_with_weights`).
+
+This means the existing metadata_collector hook (which intercepts node execution via
+`_map_node_over_list`) cannot capture embeddings the same way it captures LoRAs and
+checkpoints — there is no "EmbeddingLoader" node to intercept.
+
+## Solution Architecture
+
+The hybrid approach combines **two complementary mechanisms** to capture embedding
+usage from all possible paths.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                 Plan A (已实现)                          │
+│                                                         │
+│  MetadataRegistry.prompt_metadata["prompts"]            │
+│       │                                                  │
+│       ▼                                                  │
+│  _process_embeddings()                                   │
+│       │                                                  │
+│       ├─ Iterate all prompt node texts                   │
+│       ├─ regex extract "embedding:<name>"                │
+│       ├─ resolve name → sha256 via EmbeddingScanner      │
+│       └─ UsageStats.stats["embeddings"][sha256]++        │
+│                                                         │
+│  Coverage: ~95% — all CLIPTextEncode/Flux/etc nodes     │
+│                                                         │
+│  Gap: Custom nodes that load embeddings programmatically │
+│       without putting embedding:name in prompt text      │
+└─────────────────────────────────────────────────────────┘
+
+                         +
+                         ↓  (future: enable Plan B when needed)
+
+┌─────────────────────────────────────────────────────────┐
+│                 Plan B (未来 — monkey-patch)              │
+│                                                         │
+│  comfy/sd1_clip.py:load_embed()                         │
+│       │                                                  │
+│       ▼                                                  │
+│  Monkey-patch intercepts EVERY embedding file load       │
+│       │                                                  │
+│       ├─ Records embedding_name + success/failure        │
+│       ├─ Associates with current prompt_id (via registry)│
+│       └─ Feeds into UsageStats same as Plan A            │
+│                                                         │
+│  Coverage: 100% — catches ALL embedding loads            │
+│                                                         │
+│  Cost: Requires patching into ComfyUI internals          │
+│        (sd1_clip.py, sdxl_clip.py, some text_encoders)   │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Plan B Detail — Monkey-patch `load_embed`
+
+### Target Function
+
+**`comfy.sd1_clip.load_embed(embedding_name, embedding_directory, embedding_size, embed_key=None)`**
+at line 415 of `sd1_clip.py`.
+
+This is the **single choke point** for all embedding file loads in ComfyUI. Every
+CLIP variant (SD1, SDXL, SD3, Flux) calls this same function.
+
+### Implementation Sketch
+
+```python
+# In metadata_collector/metadata_hook.py (or a new module)
+import comfy.sd1_clip as sd1_clip
+
+_original_load_embed = sd1_clip.load_embed
+
+def _patched_load_embed(embedding_name, embedding_directory, embedding_size, embed_key=None):
+    result = _original_load_embed(
+        embedding_name, embedding_directory, embedding_size, embed_key
+    )
+    if result is not None:
+        _record_embedding_usage(embedding_name)
+    return result
+
+sd1_clip.load_embed = _patched_load_embed
+```
+
+### Prompt ID Association
+
+The challenge is associating the `load_embed` call with the current `prompt_id`.
+Options:
+
+1. **Thread-local / contextvar**: Store current `prompt_id` in a `contextvars.ContextVar`
+   that the metadata_collector sets at the start of each prompt execution.
+
+2. **MetadataRegistry singleton**: The MetadataRegistry already has `current_prompt_id`.
+   The patch can read it directly since both run in the same thread.
+
+3. **Lazy aggregation**: Instead of associating with prompt_id at load time, collect
+   all loaded embedding names in a global set during execution, then flush to
+   UsageStats after the prompt completes.
+
+### Files to Patch
+
+| File | Function | Coverage |
+|------|----------|----------|
+| `comfy/sd1_clip.py:415` | `load_embed()` | Primary — SD1.x, SDXL, SD3, Flux |
+| `comfy/sdxl_clip.py` | Not needed (calls `sd1_clip.SDTokenizer`) | — |
+| `comfy/text_encoders/sd3_clip.py` | Not needed (calls `sd1_clip.SDTokenizer`) | — |
+| `comfy/text_encoders/flux.py` | Not needed (calls `sd1_clip.SDTokenizer`) | — |
+
+The SD1 tokenizer is the base class for all CLIP variants' tokenizers, so patching
+`load_embed` covers them all.
+
+### Edge Cases
+
+| Edge Case | Plan A | Plan B |
+|-----------|--------|--------|
+| `embedding:name` in CLIPTextEncode | ✅ | ✅ |
+| `embedding:name` in CLIPTextEncodeFlux | ✅ | ✅ |
+| `embedding:name` in PromptLM (LoRA Manager) | ✅ | ✅ |
+| `embedding:name` in WAS_Text_to_Conditioning | ✅ | ✅ |
+| Custom node that loads embedding programmatically | ❌ | ✅ |
+| Embedding loaded multiple times in same prompt | ✅ (dedup via set) | ✅ (dedup via set) |
+| Embedding file not found | N/A | ✅ (can log) |
+| Embedding dimension mismatch | N/A | ✅ (can log) |
+| Text encoder with non-standard tokenizer (LLaMA, T5...) | Partial | ✅ (if it calls load_embed) |
+
+## Migration Path: Standalone → Hybrid
+
+### Phase 1 — Plan A (当前状态)
+- Prompt text parsing only
+- No monkey-patching required
+- Covers all standard workflows
+
+### Phase 2 — Enable Plan B (未来工作)
+1. Add monkey-patch of `load_embed` in `metadata_collector/metadata_hook.py` (alongside
+   the existing `_map_node_over_list` hook)
+2. Collect loaded embedding names in a `set()` on the registry
+3. In `UsageStats._process_embeddings()`, merge the Plan A results (from prompt text)
+   with the Plan B results (from the patch)
+4. Add `prompt_data` field on MetadataRegistry to store loaded embeddings per prompt
+
+### Deduplication
+
+```python
+# Merge Plan A + Plan B results in _process_embeddings
+plan_a_names = extract_from_prompt_texts(prompts_data)
+plan_b_names = registry.get_loaded_embeddings(prompt_id)
+
+all_names = plan_a_names | plan_b_names
+```
+
+## Testing the Hybrid
+
+| Scenario | What to verify |
+|----------|---------------|
+| Standard `embedding:name` in prompt | Plan A captures it |
+| Embedding loaded by custom node script | Plan B captures it |
+| Both paths fire for same embedding | No double-counting (dedup) |
+| Embedding name resolves to hash | EmbeddingScanner.get_hash_by_filename works |
+| No embedding scanner available | Graceful skip, no crash |
+| Missing embedding file | Plan B logs warning, Plan A skips gracefully |
+| Empty prompt | No crash, no entries |
+| Standalone mode | Both plans disabled gracefully |
+
+## Key Files Reference
+
+| File | Role |
+|------|------|
+| `py/utils/usage_stats.py` | Core — `_process_embeddings()` for Plan A |
+| `py/metadata_collector/constants.py` | `EMBEDDINGS` category constant |
+| `py/metadata_collector/metadata_hook.py` | Future — monkey-patch for Plan B |
+| `py/services/embedding_scanner.py` | Hash resolution service |
+| `py/routes/stats_routes.py` | Already handles `usage_data.get('embeddings', {})` |
+| `comfy/sd1_clip.py` (ComfyUI) | `load_embed()` — Plan B target |
@@ -31,7 +31,7 @@ COVERAGE_FILE=coverage/backend/.coverage pytest \
  --cov-report=xml:coverage/backend/coverage.xml
 ```

-### Frontend Development (Standalone Web UI)
+### Frontend Development (LoRA Manager Web UI)

 ```bash
 npm install
@@ -102,6 +102,7 @@ npm run test:coverage       # Generate coverage report
 - ComfyUI: `app.registerExtension()`, `node.addDOMWidget(name, type, element, options)`
 - Event handlers via `addEventListener` or widget callbacks
 - Shared utilities: `web/comfyui/utils.js`
+- Dual-mode rendering patterns (canvas vs Vue): see `docs/comfyui-dual-mode-widgets.md`

 ### Vue Composables Pattern

@@ -136,7 +137,13 @@ npm run test:coverage       # Generate coverage report
 - Dual mode: ComfyUI plugin (folder_paths) vs standalone (settings.json)
 - Detection: `os.environ.get("LORA_MANAGER_STANDALONE", "0") == "1"`
 - Run `python scripts/sync_translation_keys.py` after adding UI strings to `locales/en.json`
- Symlinks require normalized paths
+- Symlinks require normalized paths.
+  **Business paths vs real paths**: All stored paths and operation routing use the
+  original paths as they appear under configured model roots — symlinks are NOT
+  resolved. `os.path.realpath` is only for scanner dedup and the symlink cache.
+  Any path passed to `os.remove`/`os.rename`/`shutil.move` or validated by a
+  containment check MUST use the business path (i.e. `os.path.abspath`, not
+  `realpath`).

 ## Git / Commit Messages

@@ -147,9 +154,9 @@ npm run test:coverage       # Generate coverage report

 ## Frontend UI Architecture

-### 1. Standalone Web UI
+### 1. LoRA Manager Web UI
 - Location: `./static/` and `./templates/`
- Tech: Vanilla JS + CSS, served by standalone server
+- Tech: Vanilla JS + CSS, served by the hosting server (ComfyUI app in plugin mode, `standalone.py` in standalone mode)
 - Tests via npm in root directory

 ### 2. ComfyUI Custom Node Widgets
@@ -3,6 +3,8 @@ try:  # pragma: no cover - import fallback for pytest collection
    from .py.nodes.lora_loader import LoraLoaderLM, LoraTextLoaderLM
    from .py.nodes.checkpoint_loader import CheckpointLoaderLM
    from .py.nodes.unet_loader import UNETLoaderLM
+    from .py.nodes.random_checkpoint_loader import RandomCheckpointLoaderLM
+    from .py.nodes.random_unet_loader import RandomUNETLoaderLM
    from .py.nodes.trigger_word_toggle import TriggerWordToggleLM
    from .py.nodes.prompt import PromptLM
    from .py.nodes.text import TextLM
@@ -15,6 +17,10 @@ try:  # pragma: no cover - import fallback for pytest collection
    from .py.nodes.lora_pool import LoraPoolLM
    from .py.nodes.lora_randomizer import LoraRandomizerLM
    from .py.nodes.lora_cycler import LoraCyclerLM
+    from .py.nodes.lora_info import LoraInfoLM
+    from .py.nodes.lora_syntax_to_path import LoraSyntaxToPath
+    from .py.nodes.create_hook_lora import CreateHookLoraLM
+    from .py.nodes.metadata_overwrite import MetadataOverwriteLM
    from .py.metadata_collector import init as init_metadata_collector
 except (
    ImportError
@@ -36,6 +42,12 @@ except (
        "py.nodes.checkpoint_loader"
    ).CheckpointLoaderLM
    UNETLoaderLM = importlib.import_module("py.nodes.unet_loader").UNETLoaderLM
+    RandomCheckpointLoaderLM = importlib.import_module(
+        "py.nodes.random_checkpoint_loader"
+    ).RandomCheckpointLoaderLM
+    RandomUNETLoaderLM = importlib.import_module(
+        "py.nodes.random_unet_loader"
+    ).RandomUNETLoaderLM
    TriggerWordToggleLM = importlib.import_module(
        "py.nodes.trigger_word_toggle"
    ).TriggerWordToggleLM
@@ -56,6 +68,16 @@ except (
        "py.nodes.lora_randomizer"
    ).LoraRandomizerLM
    LoraCyclerLM = importlib.import_module("py.nodes.lora_cycler").LoraCyclerLM
+    LoraInfoLM = importlib.import_module("py.nodes.lora_info").LoraInfoLM
+    LoraSyntaxToPath = importlib.import_module(
+        "py.nodes.lora_syntax_to_path"
+    ).LoraSyntaxToPath
+    CreateHookLoraLM = importlib.import_module(
+        "py.nodes.create_hook_lora"
+    ).CreateHookLoraLM
+    MetadataOverwriteLM = importlib.import_module(
+        "py.nodes.metadata_overwrite"
+    ).MetadataOverwriteLM
    init_metadata_collector = importlib.import_module("py.metadata_collector").init

 NODE_CLASS_MAPPINGS = {
@@ -65,6 +87,8 @@ NODE_CLASS_MAPPINGS = {
    LoraTextLoaderLM.NAME: LoraTextLoaderLM,
    CheckpointLoaderLM.NAME: CheckpointLoaderLM,
    UNETLoaderLM.NAME: UNETLoaderLM,
+    RandomCheckpointLoaderLM.NAME: RandomCheckpointLoaderLM,
+    RandomUNETLoaderLM.NAME: RandomUNETLoaderLM,
    TriggerWordToggleLM.NAME: TriggerWordToggleLM,
    LoraStackerLM.NAME: LoraStackerLM,
    LoraStackCombinerLM.NAME: LoraStackCombinerLM,
@@ -75,6 +99,10 @@ NODE_CLASS_MAPPINGS = {
    LoraPoolLM.NAME: LoraPoolLM,
    LoraRandomizerLM.NAME: LoraRandomizerLM,
    LoraCyclerLM.NAME: LoraCyclerLM,
+    LoraInfoLM.NAME: LoraInfoLM,
+    LoraSyntaxToPath.NAME: LoraSyntaxToPath,
+    CreateHookLoraLM.NAME: CreateHookLoraLM,
+    MetadataOverwriteLM.NAME: MetadataOverwriteLM,
 }

 WEB_DIRECTORY = "./web/comfyui"
@@ -1,183 +0,0 @@
-## Overview
-
-The **LoRA Manager Civitai Extension** is a Browser extension designed to work seamlessly with [LoRA Manager](https://github.com/willmiao/ComfyUI-Lora-Manager) to significantly enhance your browsing experience on [Civitai](https://civitai.com). With this extension, you can:
-
-✅ Instantly see which models are already present in your local library  
-✅ Download new models with a single click  
-✅ Manage downloads efficiently with queue and parallel download support  
-✅ Keep your downloaded models automatically organized according to your custom settings    
-
-![Civitai Models page](https://github.com/willmiao/ComfyUI-Lora-Manager/blob/main/wiki-images/civitai-models-page.png) 
-
-**Update:** It now also supports browsing on [CivArchive](https://civarchive.com/) (formerly CivitaiArchive). 
-
-![CivArchive Models page](https://github.com/willmiao/ComfyUI-Lora-Manager/blob/main/wiki-images/civarchive-models-page.png)  
-
---
-
-## Why Supporter Access?
-
-LoRA Manager is built with love for the Stable Diffusion and ComfyUI communities. Your support makes it possible for me to keep improving and maintaining the tool full-time.
-
-Supporter-exclusive features help ensure the long-term sustainability of LoRA Manager, allowing continuous updates, new features, and better performance for everyone.
-
-Every contribution directly fuels development and keeps the core LoRA Manager free and open-source. In addition to monthly supporters, one-time donation supporters will also receive a license key, with the duration scaling according to the contribution amount. Thank you for helping keep this project alive and growing. ❤️
-
-
---
-
-## Installation
-
-### Supported Browsers & Installation Methods
-
-| Browser            | Installation Method                                                                 |
-|--------------------|-------------------------------------------------------------------------------------|
-| **Google Chrome**   | [Chrome Web Store link](https://chromewebstore.google.com/detail/capigligggeijgmocnaflanlbghnamgm?utm_source=item-share-cb) |
-| **Microsoft Edge**  | Install via Chrome Web Store (compatible)                                          |
-| **Brave Browser**   | Install via Chrome Web Store (compatible)                                          |
-| **Opera**           | Install via Chrome Web Store (compatible)                                          |
-| **Firefox**         | <div id="firefox-install" class="install-ok"><a href="https://github.com/willmiao/lm-civitai-extension-firefox/releases/latest/download/extension.xpi">📦 Install Firefox Extension (reviewed and verified by Mozilla)</a></div>             |
-
-For non-Chrome browsers (e.g., Microsoft Edge), you can typically install extensions from the Chrome Web Store by following these steps: open the extension’s Chrome Web Store page, click 'Get extension', then click 'Allow' when prompted to enable installations from other stores, and finally click 'Add extension' to complete the installation.
-
---
-
-## Privacy & Security
-
-I understand concerns around browser extensions and privacy, and I want to be fully transparent about how the **LM Civitai Extension** works:
-
- **Reviewed and Verified**  
-  This extension has been **manually reviewed and approved by the Chrome Web Store**. The Firefox version uses the **exact same code** (only the packaging format differs) and has passed **Mozilla’s Add-on review**.
-
- **Minimal Network Access**  
-  The only external server this extension connects to is:  
-  **`https://willmiao.shop`** — used solely for **license validation**.
-
-  It does **not collect, transmit, or store any personal or usage data**.  
-  No browsing history, no user IDs, no analytics, no hidden trackers.
-
- **Local-Only Model Detection**  
-  Model detection and LoRA Manager communication all happen **locally** within your browser, directly interacting with your local LoRA Manager backend.
-
-I value your trust and are committed to keeping your local setup private and secure. If you have any questions, feel free to reach out!
-
---
-
-## How to Use
-
-After installing the extension, you'll automatically receive a **7-day trial** to explore all features.
-
-When the extension is correctly installed and your license is valid:
-
- Open **Civitai**, and you'll see visual indicators added by the extension on model cards, showing:
-  - ✅ Models already present in your local library  
-  - ⬇️ A download button for models not in your library  
-
-Clicking the download button adds the corresponding model version to the download queue, waiting to be downloaded. You can set up to **5 models to download simultaneously**.
-
-### Visual Indicators Appear On:
-
- **Home Page** — Featured models  
- **Models Page**  
- **Creator Profiles** — If the creator has set their models to be visible  
- **Recommended Resources** — On individual model pages  
-
-### Version Buttons on Model Pages
-
-On a specific model page, visual indicators also appear on version buttons, showing which versions are already in your local library.
-
-**Starting from v0.4.8**, model pages use a dedicated download button for better compatibility. When switching to a specific version by clicking a version button:
-
- The new **dedicated download button** directly triggers download via **LoRA Manager**
- The **original download button** remains unchanged for standard browser downloads
-
-![Civitai Model Page](https://github.com/willmiao/ComfyUI-Lora-Manager/blob/main/wiki-images/civitai-model-page.png)
-
-### Hide Models Already in Library (Beta)
-
-**New in v0.4.8**: A new **Hide models already in library (Beta)** option makes it easier to focus on models you haven't added yet. It can be enabled from Settings, or toggled quickly using **Ctrl + Shift + H** (macOS: **Command + Shift + H**).
-
-### Resources on Image Pages — now shows in-library indicators for image resources plus one-click recipe import
-
- **One-Click Import Civitai Image as Recipe** — Import any Civitai image as a recipe with a single click in the Resources Used panel.
- **Auto-Queue Missing Assets** — In Settings you can decide if LoRAs or checkpoints referenced by that image should automatically be added to your download queue.
- **More Accurate Metadata** — Importing directly from the page is faster than copying inside LM and keeps on-site tags and other metadata perfectly aligned.
-
-![Civitai Image Page](https://github.com/willmiao/ComfyUI-Lora-Manager/blob/main/wiki-images/civitai-image-page.jpg)
-
-[![alt](url)](https://github.com/user-attachments/assets/41fd4240-c949-4f83-bde7-8f3124c09494)
-
---
-
-## Model Download Location & LoRA Manager Settings
-
-To use the **one-click download function**, you must first set:
-
- Your **Default LoRAs Root**  
- Your **Default Checkpoints Root**  
-
-These are set within LoRA Manager's settings.
-
-When everything is configured, downloaded model files will be placed in:  
-
-`<Default_Models_Root>/<Base_Model_of_the_Model>/<First_Tag_of_the_Model>`
-
-
-### Update: Default Path Customization (2025-07-21)  
-
-A new setting to customize the default download path has been added in the nightly version. You can now personalize where models are saved when downloading via the LM Civitai Extension.
-
-![Default Path Customization](https://github.com/willmiao/ComfyUI-Lora-Manager/blob/main/wiki-images/default-path-customization.png)
-
-The previous YAML path mapping file will be deprecated—settings will now be unified in settings.json to simplify configuration.
-
---
-
-## Backend Port Configuration
-
-If your **ComfyUI** or **LoRA Manager** backend is running on a port **other than the default 8188**, you must configure the backend port in the extension's settings.
-
-After correctly setting and saving the port, you'll see in the extension's header area:  
- A **Healthy** status with the tooltip:  `Connected to LoRA Manager on port xxxx`
-
-
---
-
-## Advanced Usage
-
-### Connecting to a Remote LoRA Manager
-
-If your LoRA Manager is running on another computer, you can still connect from your browser using port forwarding.
-
-> **Why can't you set a remote IP directly?**
->
-> For privacy and security, the extension only requests access to `http://127.0.0.1/*`. Supporting remote IPs would require much broader permissions, which may be rejected by browser stores and could raise user concerns.
-
-**Solution: Port Forwarding with `socat`**
-
-On your browser computer, run:
-
-`socat TCP-LISTEN:8188,bind=127.0.0.1,fork TCP:REMOTE.IP.ADDRESS.HERE:8188`
-
- Replace `REMOTE.IP.ADDRESS.HERE` with the IP of the machine running LoRA Manager.
- Adjust the port if needed.
-
-This lets the extension connect to `127.0.0.1:8188` as usual, with traffic forwarded to your remote server.
-
-_Thanks to user **Temikus** for sharing this solution!_
-
---
-
-## Roadmap
-
-The extension will evolve alongside **LoRA Manager** improvements. Planned features include:
-
- [x] Support for **additional model types** (e.g., embeddings)
- [x] One-click **Recipe Import**
- [x] Display of in-library status for all resources in the **Resources Used** section of the image page
- [x] One-click **Auto-organize Models**
- [x] **Hide models already in library (Beta)** - Focus on models you haven't added yet
-
-**Stay tuned — and thank you for your support!**
-
---
@@ -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` |
@@ -0,0 +1,65 @@
+# ComfyUI Dual-Mode Widget Rendering
+
+ComfyUI custom node widgets render in one of two modes. Patterns that work in one often fail silently in the other. Test both.
+
+## Mode Detection
+
+```js
+typeof LiteGraph !== 'undefined' && LiteGraph.vueNodesMode
+```
+
+In Vue SFCs, `window.LiteGraph` is unavailable — pass as a prop from `main.ts`.
+
+## Canvas Mode Layout
+
+Uses `computeLayoutSize()` + `distributeSpace()` to allocate widget height within the node. Widgets with `computeLayoutSize` participate in space distribution; those with `computeSize` have fixed height.
+
+- `getMinHeight()` in `addDOMWidget` options → minimum widget height
+- `widget.computeLayoutSize()` → `{ minHeight, minWidth, maxHeight? }`
+- Avoid `getMaxHeight()` unless the widget genuinely needs a fixed cap (prevents user resize)
+
+## Vue Mode Layout
+
+Uses CSS Grid (`grid-template-rows`) + `ResizeObserver`. The ResizeObserver watches the widget's DOM and feeds back into grid row sizing. This creates a feedback loop: content grows → row resizes → more space for content → content reflows/grows → row resizes again.
+
+### Height Containment
+
+The fix: `contain: layout size` on the widget root. This tells the browser the element's intrinsic size is CSS-determined, not driven by descendant content. The ResizeObserver sees a stable size and the loop is broken.
+
+```css
+.widget-root.lm-vue-node {
+  height: 100%;
+  min-height: var(--comfy-widget-min-height, 200px);
+  contain: layout size;
+}
+```
+
+Existing examples: `.lm-loras-container.lm-vue-node` and `.comfy-tags-container.lm-vue-node` in `web/comfyui/lm_styles.css`.
+
+**Do NOT** fix height issues with `maxHeight`, `getMaxHeight()`, or inline `max-height` — these prevent the user from resizing the node.
+
+## Scroll Wheel Isolation
+
+Both modes need to distinguish "user wants to scroll widget content" from "user wants to zoom canvas".
+
+**Canvas mode:** Add `@wheel` on widget root. Check `event.target.closest(selector)` for scrollable sub-areas. If scrollable → `event.stopPropagation()`. Otherwise → `app.canvas.processMouseWheel(event)`.
+
+**Vue mode:** Add CSS class `lm-wheel-scrollable` to scrollable elements. The global capture-phase hook in `web/comfyui/utils.js` (`enableListWheelScroll`) detects wheel events on marked elements and manually scrolls them via `element.scrollTop`, consuming the event before canvas zoom sees it.
+
+## DOM Structure
+
+`main.ts` creates an outer `<div>` container, then `vueApp.mount(container)`. The Vue app renders its own root element inside.
+
+- `container.id` / `container.style.*` → outer element
+- Vue scoped `<style>` → `[data-v-hash]` applies only to Vue root
+
+Classes needed by scoped Vue CSS must go on the Vue root element. Pass data as props and bind with `:class` rather than manipulating the DOM from `main.ts`.
+
+## Serialization
+
+For stateful widgets that need workflow persistence:
+
+- `serialize: true` in `addDOMWidget` options
+- `serializeValue()` → state snapshot (called on workflow save)
+- `onSetValue(v)` → restore state (called on workflow load)
+- Always handle missing keys in restored value for backward compatibility with old workflows
@@ -39,6 +39,7 @@ These fields are present in all model metadata files.
 | `metadata_source` | string\|null | ❌ No | ✅ Yes | Last provider that supplied metadata (see below) |
 | `last_checked_at` | float | ❌ No (default: `0`) | ✅ Yes | Unix timestamp of last metadata check |
 | `hash_status` | string | ❌ No (default: `"completed"`) | ✅ Yes | Hash calculation status: `"pending"`, `"calculating"`, `"completed"`, `"failed"` |
+| `autov3` | string\|null | ❌ No | ✅ Yes | CivitAI AutoV3 hash (first 12 chars, lowercase hex) sourced from the safetensors embedded metadata (`sshs_model_hash` / `modelspec.hash_sha256`). **Absent** = not yet checked (may be backfilled later); **`null`** = checked but unavailable (header has no recognized hash); **12-char hex string** = value |

 ---

@@ -287,6 +288,7 @@ These fields are automatically synchronized with the filesystem:
 - `preview_url` — Updated if preview file is moved/removed
 - `sha256` — Updated during hash calculation (when `hash_status="pending"`)
 - `hash_status` — Updated during hash calculation
+- `autov3` — Set when metadata is first created (from safetensors header); may be backfilled later for entries where it is absent
 - `last_checked_at` — Timestamp of scan
 - `metadata_source` — Set based on metadata provider

@@ -345,6 +347,7 @@ These fields can be edited by users at any time through the Lora Manager UI or b
 | `metadata_source` | `null` |
 | `last_checked_at` | `0` |
 | `hash_status` | `"completed"` |
+| `autov3` | absent (not checked) or `null` (checked, no value) |
 | `usage_tips` | `"{}"` (LoRA only) |
 | `model_type` | `"checkpoint"` or `"embedding"` (not present in LoRA models) |

@@ -354,6 +357,7 @@ These fields can be edited by users at any time through the Lora Manager UI or b

 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1 | 2026-08 | Added `autov3` field (CivitAI AutoV3 hash with three-state semantics) |
 | 1.0 | 2026-03 | Initial schema documentation |

 ---
@@ -1,12 +1,19 @@
+# pyright: reportImportCycles=false
+# Lazy (function-local) imports still count as static edges in basedpyright's
+# reportImportCycles, so the ServiceRegistry singleton pattern necessarily forms
+# import cycles. Breaking them would require an architectural refactor.
 import os
 import platform
+import posixpath
 import threading
 from pathlib import Path
-import folder_paths  # type: ignore
+import folder_paths  # pyright: ignore[reportMissingImports]
 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
@@ -25,21 +32,57 @@ standalone_mode = (
 logger = logging.getLogger(__name__)


+def _normalize_root_identity(path: str) -> str:
+    """Normalize a root path for comparisons across slash styles."""
+
+    normalized = posixpath.normpath(path.strip().replace("\\", "/"))
+    if len(normalized) >= 2 and normalized[1] == ":":
+        return normalized.lower()
+    return normalized
+
+
 def _resolve_valid_default_root(
-    current: str, primary_paths: List[str], name: str
+    current: str, primary_paths: List[str], allowed_paths: List[str], name: str
 ) -> str:
-    """Return a valid default root from the current primary path set."""
+    """Return a valid default root from the current primary/extra path set."""

    valid_paths = [path for path in primary_paths if isinstance(path, str) and path.strip()]
-    if not valid_paths:
-        return ""
+    fallback_paths: List[str] = []
+    seen: Set[str] = set()
+    for path in allowed_paths:
+        if not isinstance(path, str):
+            continue
+        stripped = path.strip()
+        if not stripped:
+            continue
+        identity = _normalize_root_identity(stripped)
+        if identity in seen:
+            continue
+        seen.add(identity)
+        fallback_paths.append(stripped)

-    if current in valid_paths:
+    allowed = {_normalize_root_identity(path) for path in fallback_paths}
+
+    if current and _normalize_root_identity(current) in allowed:
        return current

+    if not valid_paths:
+        if not fallback_paths:
+            return ""
+        if current:
+            logger.info(
+                "Repaired stale %s from '%s' to '%s' because it is not present in primary or extra roots",
+                name,
+                current,
+                fallback_paths[0],
+            )
+        else:
+            logger.info("Auto-setting %s to '%s'", name, fallback_paths[0])
+        return fallback_paths[0]
+
    if current:
        logger.info(
-            "Repaired stale %s from '%s' to '%s'",
+            "Repaired stale %s from '%s' to '%s' because it is not present in primary or extra roots",
            name,
            current,
            valid_paths[0],
@@ -51,7 +94,7 @@ def _resolve_valid_default_root(


 def _normalize_folder_paths_for_comparison(
-    folder_paths: Mapping[str, Iterable[str]],
+    folder_paths: Mapping[str, Any],
 ) -> Dict[str, Set[str]]:
    """Normalize folder paths for comparison across libraries."""

@@ -135,6 +178,11 @@ class Config:
        self.extra_unet_roots: List[str] = []
        self.extra_embeddings_roots: List[str] = []
        self.recipes_path: str = ""
+
+        # Load extra folder paths from active library settings before symlink scan
+        # so both primary and extra paths are discovered in a single pass.
+        self._load_extra_paths_from_settings()
+
        # Scan symbolic links during initialization
        self._initialize_symlink_mappings()

@@ -142,6 +190,98 @@ class Config:
            # Save the paths to settings.json when running in ComfyUI mode
            self.save_folder_paths_to_settings()

+    def _load_extra_paths_from_settings(self) -> None:
+        """Read extra folder paths from the active library and apply them.
+
+        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 via ``folder_paths.get_folder_paths``.
+        """
+        try:
+            from .services.settings_manager import get_settings_manager
+
+            settings_manager = get_settings_manager()
+            library_name = settings_manager.get_active_library_name()
+            libraries = settings_manager.get_libraries()
+
+            if not library_name or library_name not in libraries:
+                return
+
+            library_config = libraries[library_name]
+            if not isinstance(library_config, dict):
+                return
+
+            # Always read recipes_path — it is independent of extra folder paths
+            # and must be set before any early returns below.
+            recipes_path = library_config.get("recipes_path", "")
+            if isinstance(recipes_path, str) and recipes_path:
+                self.recipes_path = recipes_path
+
+            extra_folder_paths = library_config.get("extra_folder_paths")
+            if not isinstance(extra_folder_paths, dict):
+                return
+
+            extra_lora = extra_folder_paths.get("loras", []) or []
+            extra_checkpoint = extra_folder_paths.get("checkpoints", []) or []
+            extra_unet = extra_folder_paths.get("unet", []) or []
+            extra_embedding = extra_folder_paths.get("embeddings", []) or []
+
+            if not any([extra_lora, extra_checkpoint, extra_unet, extra_embedding]):
+                return
+
+            filtered_extra_lora = self._filter_overlapping_extra_lora_paths(
+                self.loras_roots, extra_lora
+            )
+            self.extra_loras_roots = self._prepare_lora_paths(filtered_extra_lora)
+            (
+                _,
+                self.extra_checkpoints_roots,
+                self.extra_unet_roots,
+            ) = self._prepare_checkpoint_paths(extra_checkpoint, extra_unet)
+            self.extra_embeddings_roots = self._prepare_embedding_paths(
+                extra_embedding
+            )
+
+            if self.extra_loras_roots:
+                logger.info(
+                    "Found extra LoRA roots:"
+                    + "\n - "
+                    + "\n - ".join(self.extra_loras_roots)
+                )
+            if self.extra_checkpoints_roots:
+                logger.info(
+                    "Found extra checkpoint roots:"
+                    + "\n - "
+                    + "\n - ".join(self.extra_checkpoints_roots)
+                )
+            if self.extra_unet_roots:
+                logger.info(
+                    "Found extra diffusion model roots:"
+                    + "\n - "
+                    + "\n - ".join(self.extra_unet_roots)
+                )
+            if self.extra_embeddings_roots:
+                logger.info(
+                    "Found extra embedding roots:"
+                    + "\n - "
+                    + "\n - ".join(self.extra_embeddings_roots)
+                )
+
+            logger.info(
+                "Applied library settings for '%s' with extra paths: loras=%s, "
+                "checkpoints=%s, embeddings=%s",
+                library_name,
+                extra_lora,
+                extra_checkpoint,
+                extra_embedding,
+            )
+
+        except Exception as exc:
+            logger.debug(
+                "Could not load extra paths from library settings: %s", exc
+            )
+
    def save_folder_paths_to_settings(self):
        """Persist ComfyUI-derived folder paths to the multi-library settings."""
        try:
@@ -223,42 +363,120 @@ class Config:
                        "Failed to rename legacy 'default' library: %s", rename_error
                    )

+            # Clean up a stale "default" library entry that has no meaningful
+            # paths configured (e.g. leftover bootstrap artifact).  This only
+            # fires when "comfyui" already exists so we never delete the last
+            # remaining library.
+            if (
+                "default" in libraries
+                and "comfyui" in libraries
+                and isinstance(default_library, Mapping)
+            ):
+                default_folder_paths = _normalize_library_folder_paths(
+                    default_library
+                )
+                default_extra_paths = default_library.get("extra_folder_paths", {})
+                has_meaningful_paths = bool(default_folder_paths) or bool(
+                    default_extra_paths
+                ) or any(
+                    default_library.get(key)
+                    for key in (
+                        "default_lora_root",
+                        "default_checkpoint_root",
+                        "default_unet_root",
+                        "default_embedding_root",
+                        "recipes_path",
+                    )
+                )
+                if not has_meaningful_paths:
+                    try:
+                        settings_service.delete_library("default")
+                        libraries_changed = True
+                        logger.info(
+                            "Removed stale 'default' library entry "
+                            "with no meaningful paths configured"
+                        )
+                        libraries = settings_service.get_libraries()
+                        comfy_library = libraries.get("comfyui", {})
+                    except Exception as delete_error:
+                        logger.debug(
+                            "Failed to remove stale 'default' library: %s",
+                            delete_error,
+                        )
+
            default_lora_root = _resolve_valid_default_root(
                comfy_library.get("default_lora_root", ""),
                list(self.loras_roots or []),
+                list(self.loras_roots or [])
+                + list(comfy_library.get("extra_folder_paths", {}).get("loras", []) or []),
                "default_lora_root",
            )

            default_checkpoint_root = _resolve_valid_default_root(
                comfy_library.get("default_checkpoint_root", ""),
                list(self.checkpoints_roots or []),
+                list(self.checkpoints_roots or [])
+                + list(comfy_library.get("extra_folder_paths", {}).get("checkpoints", []) or []),
                "default_checkpoint_root",
            )

            default_embedding_root = _resolve_valid_default_root(
                comfy_library.get("default_embedding_root", ""),
                list(self.embeddings_roots or []),
+                list(self.embeddings_roots or [])
+                + list(comfy_library.get("extra_folder_paths", {}).get("embeddings", []) or []),
                "default_embedding_root",
            )

            metadata = dict(comfy_library.get("metadata", {}))
            metadata.setdefault("display_name", "ComfyUI")
            metadata["source"] = "comfyui"
+            extra_folder_paths = {}
+            if isinstance(comfy_library, Mapping):
+                existing_extra_paths = comfy_library.get("extra_folder_paths", {})
+                if isinstance(existing_extra_paths, Mapping):
+                    extra_folder_paths = {
+                        key: list(value) if isinstance(value, list) else []
+                        for key, value in existing_extra_paths.items()
+                    }
+
+            active_library_name = settings_service.get_active_library_name()
+            should_activate = (
+                active_library_name == "comfyui"
+                or self._should_activate_comfy_library(libraries, libraries_changed)
+            )

            settings_service.upsert_library(
                "comfyui",
                folder_paths=target_folder_paths,
+                extra_folder_paths=extra_folder_paths,
                default_lora_root=default_lora_root,
                default_checkpoint_root=default_checkpoint_root,
                default_embedding_root=default_embedding_root,
                metadata=metadata,
-                activate=True,
+                activate=should_activate,
            )

-            logger.info("Updated 'comfyui' library with current folder paths")
+            if should_activate:
+                logger.info("Updated 'comfyui' library with current folder paths")
+            else:
+                logger.info(
+                    "Updated 'comfyui' library with current folder paths without activating it"
+                )
        except Exception as e:
            logger.warning(f"Failed to save folder paths: {e}")

+    def _should_activate_comfy_library(
+        self, libraries: Mapping[str, Any], libraries_changed: bool
+    ) -> bool:
+        """Return whether startup sync should make the ComfyUI library active."""
+
+        if libraries_changed:
+            return True
+        if not libraries:
+            return True
+        return "comfyui" in libraries and len(libraries) == 1
+
    def _is_link(self, path: str) -> bool:
        try:
            if os.path.islink(path):
@@ -268,7 +486,7 @@ class Config:
                    import ctypes

                    FILE_ATTRIBUTE_REPARSE_POINT = 0x400
-                    attrs = ctypes.windll.kernel32.GetFileAttributesW(str(path))  # type: ignore[attr-defined]
+                    attrs = ctypes.windll.kernel32.GetFileAttributesW(str(path))  # pyright: ignore[reportAttributeAccessIssue]
                    return attrs != -1 and (attrs & FILE_ATTRIBUTE_REPARSE_POINT)
                except Exception as e:
                    logger.error(f"Error checking Windows reparse point: {e}")
@@ -277,7 +495,7 @@ class Config:
            logger.error(f"Error checking link status for {path}: {e}")
            return False

-    def _entry_is_symlink(self, entry: os.DirEntry) -> bool:
+    def _entry_is_symlink(self, entry: os.DirEntry[str]) -> bool:
        """Check if a directory entry is a symlink, including Windows junctions."""
        if entry.is_symlink():
            return True
@@ -286,7 +504,7 @@ class Config:
                import ctypes

                FILE_ATTRIBUTE_REPARSE_POINT = 0x400
-                attrs = ctypes.windll.kernel32.GetFileAttributesW(entry.path)  # type: ignore[attr-defined]
+                attrs = ctypes.windll.kernel32.GetFileAttributesW(entry.path)  # pyright: ignore[reportAttributeAccessIssue]
                return attrs != -1 and (attrs & FILE_ATTRIBUTE_REPARSE_POINT)
            except Exception:
                pass
@@ -912,8 +1130,8 @@ class Config:

    def _apply_library_paths(
        self,
-        folder_paths: Mapping[str, Iterable[str]],
-        extra_folder_paths: Optional[Mapping[str, Iterable[str]]] = None,
+        folder_paths: Mapping[str, Any],
+        extra_folder_paths: Optional[Mapping[str, Any]] = None,
        recipes_path: str = "",
    ) -> None:
        self._path_mappings.clear()
@@ -1210,4 +1428,21 @@ 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"
+config: Config
+if _CONFIG_SENTINEL in _sys.modules:
+    # Re-import: reuse the existing singleton from the sentinel.
+    config = _sys.modules[_CONFIG_SENTINEL].config
+else:
+    config = Config()
+    # Register the sentinel so re-imports of py.config find us.
+    _sentinel_mod = _types.ModuleType(_CONFIG_SENTINEL)
+    setattr(_sentinel_mod, "config", config)
+    _sys.modules[_CONFIG_SENTINEL] = _sentinel_mod
@@ -14,7 +14,7 @@ standalone_mode = (
 if not standalone_mode:
    setup_logging()

-from server import PromptServer  # type: ignore
+from server import PromptServer  # pyright: ignore[reportMissingImports]

 from .config import config
 from .services.model_service_factory import (
@@ -25,14 +25,17 @@ from .routes.recipe_routes import RecipeRoutes
 from .routes.stats_routes import StatsRoutes
 from .routes.update_routes import UpdateRoutes
 from .routes.misc_routes import MiscRoutes
+from .routes.pending_delete_routes import PendingDeleteRoutes
 from .routes.preview_routes import PreviewRoutes
 from .routes.example_images_routes import ExampleImagesRoutes
 from .services.service_registry import ServiceRegistry
 from .services.settings_manager import get_settings_manager
+from .services.pending_delete_service import get_pending_delete_service
 from .utils.example_images_migration import ExampleImagesMigration
 from .services.websocket_manager import ws_manager
 from .services.example_images_cleanup_service import ExampleImagesCleanupService
 from .middleware.csp_middleware import relax_csp_for_remote_media
+from .middleware.error_middleware import api_json_error

 logger = logging.getLogger(__name__)

@@ -76,6 +79,11 @@ class LoraManager:
        """Initialize and register all routes using the new refactored architecture"""
        app = PromptServer.instance.app

+        # Register JSON error middleware for /api/* routes as the outermost
+        # middleware so it catches errors from all other middlewares.
+        if api_json_error not in app.middlewares:
+            app.middlewares.insert(0, api_json_error)
+
        if relax_csp_for_remote_media not in app.middlewares:
            # Ensure CSP relaxer executes after ComfyUI's block_external_middleware so it can
            # see and extend the restrictive header instead of being overwritten by it.
@@ -164,6 +172,7 @@ class LoraManager:
        RecipeRoutes.setup_routes(app)
        UpdateRoutes.setup_routes(app)
        MiscRoutes.setup_routes(app)
+        PendingDeleteRoutes.setup_routes(app)
        ExampleImagesRoutes.setup_routes(app, ws_manager=ws_manager)
        PreviewRoutes.setup_routes(app)

@@ -184,44 +193,15 @@ class LoraManager:
    async def _initialize_services(cls):
        """Initialize all services using the ServiceRegistry"""
        try:
-            # Apply library settings to load extra folder paths before scanning
-            # Only apply if extra paths haven't been loaded yet (preserves test mocks)
-            try:
-                from .services.settings_manager import get_settings_manager
-
-                settings_manager = get_settings_manager()
-                library_name = settings_manager.get_active_library_name()
-                libraries = settings_manager.get_libraries()
-                if library_name and library_name in libraries:
-                    library_config = libraries[library_name]
-                    # Only apply settings if extra paths are not already configured
-                    # This preserves values set by tests via monkeypatch
-                    extra_paths = library_config.get("extra_folder_paths", {})
-                    has_extra_paths = (
-                        config.extra_loras_roots
-                        or config.extra_checkpoints_roots
-                        or config.extra_unet_roots
-                        or config.extra_embeddings_roots
-                    )
-                    if not has_extra_paths and any(extra_paths.values()):
-                        config.apply_library_settings(library_config)
-                        logger.info(
-                            "Applied library settings for '%s' with extra paths: loras=%s, checkpoints=%s, embeddings=%s",
-                            library_name,
-                            extra_paths.get("loras", []),
-                            extra_paths.get("checkpoints", []),
-                            extra_paths.get("embeddings", []),
-                        )
-            except Exception as exc:
-                logger.warning(
-                    "Failed to apply library settings during initialization: %s", exc
-                )
-
            # Initialize CivitaiClient first to ensure it's ready for other services
            await ServiceRegistry.get_civitai_client()

            # Register DownloadManager with ServiceRegistry
            await ServiceRegistry.get_download_manager()
+
+            # Initialize DownloadQueueService for persistent queue/history
+            await ServiceRegistry.get_download_queue_service()
+
            await ServiceRegistry.get_backup_service()

            from .services.metadata_service import initialize_metadata_providers
@@ -231,6 +211,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()
@@ -264,6 +248,20 @@ class LoraManager:
                cls._run_post_initialization_tasks(init_tasks), name="post_init_tasks"
            )

+            # Startup sweep: purge pending-delete batches that expired during a
+            # previous run. Non-blocking (fire-and-forget); purge_expired only
+            # removes already-expired batches, so a staged undo that survived a
+            # restart stays restorable. scan_roots=True runs the reconciliation
+            # pass first so leftover batches (the in-process registry is empty
+            # after a restart) are re-discovered on disk. Covers both plugin
+            # and standalone modes (StandaloneLoraManager reuses this
+            # classmethod).
+            pending_delete_service = await get_pending_delete_service()
+            asyncio.create_task(
+                pending_delete_service.purge_expired(scan_roots=True),
+                name="pending_delete_startup_sweep",
+            )
+
            logger.debug(
                "LoRA Manager: All services initialized and background tasks scheduled"
            )
@@ -459,5 +457,21 @@ class LoraManager:
        try:
            logger.info("LoRA Manager: Cleaning up services")

+            # Cancel any in-flight scanner initialization tasks so thread-pool
+            # workers (e.g. _initialize_cache_sync) can break out of their loops
+            # when the server shuts down (e.g. Ctrl+C on WSL).
+            for name in ("lora_scanner", "checkpoint_scanner", "embedding_scanner"):
+                scanner = ServiceRegistry.get_service_sync(name)
+                if scanner is not None and hasattr(scanner, "cancel_task"):
+                    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)
@@ -22,7 +22,7 @@ if not standalone_mode:

        logger.info("ComfyUI Metadata Collector initialized")

-    def get_metadata(prompt_id=None):  # type: ignore[no-redef]
+    def get_metadata(prompt_id=None):  # pyright: ignore[reportRedeclaration]
        """Helper function to get metadata from the registry"""
        registry = MetadataRegistry()
        return registry.get_metadata(prompt_id)
@@ -31,6 +31,6 @@ else:
    def init():
        logger.info("ComfyUI Metadata Collector disabled in standalone mode")

-    def get_metadata(prompt_id=None):  # type: ignore[no-redef]
+    def get_metadata(prompt_id=None):  # pyright: ignore[reportRedeclaration]
        """Dummy implementation for standalone mode"""
        return {}
@@ -1,13 +1,28 @@
 """Constants used by the metadata collector"""

+# Sentinel value for clip_skip to distinguish "unconnected / widget default"
+# from "user wired value 0".  Both ComfyUI CLIPSetLastLayer (-24..-1) and
+# A1111 conventions treat 0 as meaningless for clip skipping, but users may
+# explicitly wire 0 to the overwrite node to express "no clip skip / default".
+CLIP_SKIP_SENTINEL = -25
+
 # Metadata categories
 MODELS = "models"
 PROMPTS = "prompts"
 SAMPLING = "sampling"
 LORAS = "loras"
+EMBEDDINGS = "embeddings"
 SIZE = "size"
 IMAGES = "images"
 IS_SAMPLER = "is_sampler"  # New constant to mark sampler nodes
+OVERWRITE = "overwrite"  # Manual metadata overwrite from MetadataOverwriteLM node
+
+# Field names that the MetadataOverwriteLM node and its extractor share
+METADATA_OVERWRITE_FIELDS = (
+    "prompt", "negative_prompt", "seed", "steps", "cfg_scale",
+    "sampler", "scheduler", "model", "loras", "size",
+    "clip_skip", "additional_data",
+)

 # Complete list of categories to track
-METADATA_CATEGORIES = [MODELS, PROMPTS, SAMPLING, LORAS, SIZE, IMAGES]
+METADATA_CATEGORIES = [MODELS, PROMPTS, SAMPLING, LORAS, EMBEDDINGS, SIZE, IMAGES, OVERWRITE]
@@ -16,7 +16,7 @@ class MetadataHook:
            execution = None
            try:
                # Try direct import first
-                import execution # type: ignore
+                import execution # pyright: ignore[reportMissingImports]
            except ImportError:
                # Try to locate from system modules
                for module_name in sys.modules:
@@ -83,7 +83,8 @@ class MetadataHook:
                        
                        # Record inputs before execution
                        if node_id is not None:
-                            registry.record_node_execution(node_id, class_type, input_data_all, None)
+                            return_types = getattr(obj, 'RETURN_TYPES', None)
+                            registry.record_node_execution(node_id, class_type, input_data_all, None, return_types=return_types)
                except Exception as e:
                    logger.error(f"Error collecting metadata (pre-execution): {str(e)}")
            
@@ -114,7 +115,8 @@ class MetadataHook:
                        
                        # Record outputs after execution
                        if node_id is not None:
-                            registry.update_node_execution(node_id, class_type, results)
+                            return_types = getattr(obj, 'RETURN_TYPES', None)
+                            registry.update_node_execution(node_id, class_type, results, return_types=return_types)
                except Exception as e:
                    logger.error(f"Error collecting metadata (post-execution): {str(e)}")
            
@@ -135,10 +137,13 @@ class MetadataHook:
                # Store the dynprompt reference for node lookups
                if hasattr(prompt, 'original_prompt'):
                    registry.set_current_prompt(prompt)
-            
+
+                # Store extra_data for accessing full workflow node properties
+                registry.set_extra_data(extra_data)
+
            # Execute the original function
            return original_execute(*args, **kwargs)
-            
+
        # Replace the functions
        execution._map_node_over_list = map_node_over_list_with_metadata
        execution.execute = execute_with_prompt_tracking
@@ -163,7 +168,8 @@ class MetadataHook:
                        class_type = obj.__class__.__name__
                        node_id = unique_id
                        if node_id is not None:
-                            registry.record_node_execution(node_id, class_type, input_data_all, None)
+                            return_types = getattr(obj, 'RETURN_TYPES', None)
+                            registry.record_node_execution(node_id, class_type, input_data_all, None, return_types=return_types)
                except Exception as e:
                    logger.error(f"Error collecting metadata (pre-execution): {str(e)}")

@@ -180,7 +186,8 @@ class MetadataHook:
                        class_type = obj.__class__.__name__
                        node_id = unique_id
                        if node_id is not None:
-                            registry.update_node_execution(node_id, class_type, results)
+                            return_types = getattr(obj, 'RETURN_TYPES', None)
+                            registry.update_node_execution(node_id, class_type, results, return_types=return_types)
                except Exception as e:
                    logger.error(f"Error collecting metadata (post-execution): {str(e)}")

@@ -202,6 +209,9 @@ class MetadataHook:
                if hasattr(prompt, 'original_prompt'):
                    registry.set_current_prompt(prompt)

+                # Store extra_data for accessing full workflow node properties
+                registry.set_extra_data(extra_data)
+
            # Execute the original function
            return await original_execute(*args, **kwargs)

@@ -1,15 +1,68 @@
 import json
+import logging
 import os
 from .constants import IMAGES

 # Check if running in standalone mode
 standalone_mode = os.environ.get("LORA_MANAGER_STANDALONE", "0") == "1" or os.environ.get("HF_HUB_DISABLE_TELEMETRY", "0") == "0"

-from .constants import MODELS, PROMPTS, SAMPLING, LORAS, SIZE, IS_SAMPLER
+from .constants import MODELS, PROMPTS, SAMPLING, LORAS, SIZE, IS_SAMPLER, OVERWRITE
+from .node_extractors import NODE_EXTRACTORS
+
+logger = logging.getLogger(__name__)
+
+# Keys that identify metadata hint marks stored in node.properties.lm_marker_role
+_META_MARK_PREFIX = "meta_"
+_MARK_PRIMARY_MODEL = "primary_model"
+_MARK_PRIMARY_SAMPLER = "primary_sampler"
+_MARK_POSITIVE_PROMPT = "positive_prompt"
+_MARK_NEGATIVE_PROMPT = "negative_prompt"

 class MetadataProcessor:
    """Process and format collected metadata"""
-    
+
+    @staticmethod
+    def _get_user_marks(metadata):
+        """Scan workflow nodes (from extra_data.extra_pnginfo.workflow) for user-assigned
+        metadata hint marks stored in node.properties.lm_marker_role.
+
+        Returns a dict mapping mark type keys to node IDs.
+        Example: {'primary_model': '42', 'primary_sampler': '17'}
+        """
+        marks: dict[str, str] = {}
+
+        # Primary source: extra_data.extra_pnginfo.workflow.nodes (has full properties)
+        extra_data = metadata.get("extra_data")
+        if extra_data and isinstance(extra_data, dict):
+            extra_pnginfo = extra_data.get("extra_pnginfo", {})
+            if isinstance(extra_pnginfo, dict):
+                workflow = extra_pnginfo.get("workflow", {})
+                nodes = workflow.get("nodes", [])
+                for node in nodes:
+                    node_id = str(node.get("id", ""))
+                    role = node.get("properties", {}).get("lm_marker_role", "")
+                    if role.startswith(_META_MARK_PREFIX):
+                        mark_type = role[len(_META_MARK_PREFIX):]
+                        if mark_type in marks:
+                            logger.warning(
+                                "Duplicate meta hint '%s': node %s (previous: %s), "
+                                "last match wins",
+                                mark_type, node_id, marks[mark_type],
+                            )
+                        marks[mark_type] = node_id
+
+        # Fallback: try prompt.original_prompt (API-only submissions may not have workflow)
+        if not marks:
+            prompt = metadata.get("current_prompt")
+            if prompt and getattr(prompt, "original_prompt", None):
+                for node_id, node_data in prompt.original_prompt.items():
+                    role = node_data.get("properties", {}).get("lm_marker_role", "")
+                    if role.startswith(_META_MARK_PREFIX):
+                        mark_type = role[len(_META_MARK_PREFIX):]
+                        marks[mark_type] = node_id
+
+        return marks
+
    @staticmethod
    def find_primary_sampler(metadata, downstream_id=None):
        """
@@ -161,6 +214,24 @@ class MetadataProcessor:
                    max_denoise = denoise
                    primary_sampler = sampler_info
                    primary_sampler_id = node_id
+
+        # Last resort: any registered sampler. Samplers without a denoise or
+        # add_noise parameter (e.g. multi-stage samplers like KreaTwoStageSampler)
+        # are not caught by the criteria above. Prefer execution order so the
+        # first executed sampler wins, matching the downstream_id branch.
+        if primary_sampler is None:
+            sampler_ids = [
+                node_id
+                for node_id, sampler_info in metadata.get(SAMPLING, {}).items()
+                if sampler_info.get(IS_SAMPLER, False)
+            ]
+            if sampler_ids:
+                if downstream_id and "execution_order" in metadata:
+                    for node_id in metadata["execution_order"]:
+                        if node_id in sampler_ids:
+                            return node_id, metadata[SAMPLING][node_id]
+                primary_sampler_id = sampler_ids[0]
+                primary_sampler = metadata[SAMPLING][sampler_ids[0]]
                
        return primary_sampler_id, primary_sampler
    
@@ -352,50 +423,101 @@ class MetadataProcessor:
        
        # Check if we have stored conditioning objects for this sampler
        if sampler_id in metadata.get(PROMPTS, {}) and (
-            "pos_conditioning" in metadata[PROMPTS][sampler_id] or 
-            "neg_conditioning" in metadata[PROMPTS][sampler_id]):
-            
+            "pos_conditioning" in metadata[PROMPTS][sampler_id] or
+            "neg_conditioning" in metadata[PROMPTS][sampler_id]
+        ):
            pos_conditioning = metadata[PROMPTS][sampler_id].get("pos_conditioning")
            neg_conditioning = metadata[PROMPTS][sampler_id].get("neg_conditioning")
-            
-            # Helper function to recursively find prompt text for a conditioning object
-            def find_prompt_text_for_conditioning(conditioning_obj, is_positive=True):
+
+            def extend_unique(target, values):
+                for value in values:
+                    if value and value not in target:
+                        target.append(value)
+
+            # Helper function to recursively find prompt texts for a conditioning object.
+            # Transform nodes can map one output conditioning to multiple source conditionings.
+            def find_prompt_texts_for_conditioning(
+                conditioning_obj, is_positive=True, visited=None
+            ):
                if conditioning_obj is None:
-                    return ""
-                    
+                    return []
+
+                if visited is None:
+                    visited = set()
+
+                conditioning_id = id(conditioning_obj)
+                if conditioning_id in visited:
+                    return []
+                visited.add(conditioning_id)
+
+                prompt_texts = []
+
                # Try to match conditioning objects with those stored by extractors
                for prompt_node_id, prompt_data in metadata[PROMPTS].items():
-                    # For nodes with single conditioning output
-                    if "conditioning" in prompt_data:
-                        if id(prompt_data["conditioning"]) == id(conditioning_obj):
-                            return prompt_data.get("text", "")
-                    
-                    # For nodes with separate pos_conditioning and neg_conditioning outputs (like TSC_EfficientLoader)
-                    if is_positive and "positive_encoded" in prompt_data:
-                        if id(prompt_data["positive_encoded"]) == id(conditioning_obj):
-                            if "positive_text" in prompt_data:
-                                return prompt_data["positive_text"]
-                            else:
-                                orig_conditioning = prompt_data.get("orig_pos_cond", None)
-                                if orig_conditioning is not None:
-                                    # Recursively find the prompt text for the original conditioning
-                                    return find_prompt_text_for_conditioning(orig_conditioning, is_positive=True)
-                    
-                    if not is_positive and "negative_encoded" in prompt_data:
-                        if id(prompt_data["negative_encoded"]) == id(conditioning_obj):
-                            if "negative_text" in prompt_data:
-                                return prompt_data["negative_text"]
-                            else:
-                                orig_conditioning = prompt_data.get("orig_neg_cond", None)
-                                if orig_conditioning is not None:
-                                    # Recursively find the prompt text for the original conditioning
-                                    return find_prompt_text_for_conditioning(orig_conditioning, is_positive=False)
-                
-                return ""
-            
+                    if not isinstance(prompt_data, dict):
+                        continue
+
+                    # For CLIP text nodes with a single conditioning output.
+                    if id(prompt_data.get("conditioning")) == conditioning_id:
+                        text = prompt_data.get("text", "")
+                        if text:
+                            extend_unique(prompt_texts, [text])
+
+                    # Generic provenance for passthrough/transform/combine nodes.
+                    for source in prompt_data.get("conditioning_sources", []):
+                        if id(source.get("output")) != conditioning_id:
+                            continue
+                        for input_conditioning in source.get("inputs", []):
+                            extend_unique(
+                                prompt_texts,
+                                find_prompt_texts_for_conditioning(
+                                    input_conditioning, is_positive, visited
+                                ),
+                            )
+
+                    # For nodes with separate pos_conditioning and neg_conditioning outputs
+                    # like TSC_EfficientLoader and existing ControlNet-style metadata.
+                    if (
+                        is_positive
+                        and id(prompt_data.get("positive_encoded")) == conditioning_id
+                    ):
+                        if prompt_data.get("positive_text"):
+                            extend_unique(prompt_texts, [prompt_data["positive_text"]])
+                        else:
+                            extend_unique(
+                                prompt_texts,
+                                find_prompt_texts_for_conditioning(
+                                    prompt_data.get("orig_pos_cond"),
+                                    is_positive=True,
+                                    visited=visited,
+                                ),
+                            )
+
+                    if (
+                        not is_positive
+                        and id(prompt_data.get("negative_encoded")) == conditioning_id
+                    ):
+                        if prompt_data.get("negative_text"):
+                            extend_unique(prompt_texts, [prompt_data["negative_text"]])
+                        else:
+                            extend_unique(
+                                prompt_texts,
+                                find_prompt_texts_for_conditioning(
+                                    prompt_data.get("orig_neg_cond"),
+                                    is_positive=False,
+                                    visited=visited,
+                                ),
+                            )
+
+                return prompt_texts
+
            # Find prompt texts using the helper function
-            result["prompt"] = find_prompt_text_for_conditioning(pos_conditioning, is_positive=True)
-            result["negative_prompt"] = find_prompt_text_for_conditioning(neg_conditioning, is_positive=False)
+            result["prompt"] = ", ".join(
+                find_prompt_texts_for_conditioning(pos_conditioning, is_positive=True)
+            )
+            result["negative_prompt"] = ", ".join(
+                find_prompt_texts_for_conditioning(neg_conditioning, is_positive=False)
+            )
            
        return result
    
@@ -420,20 +542,57 @@ class MetadataProcessor:
            "checkpoint": None,
            "loras": "",
            "size": None,
-            "clip_skip": None
+            "clip_skip": None,
+            "additional_data": "",
        }
        
        # Get the prompt object for node relationship tracing
        prompt = metadata.get("current_prompt")
-        
-        # Find the primary KSampler node
-        primary_sampler_id, primary_sampler = MetadataProcessor.find_primary_sampler(metadata, id)
-        
-        # Directly get checkpoint from metadata instead of tracing
-        # Pass primary_sampler_id to avoid redundant calculation
-        checkpoint = MetadataProcessor.find_primary_checkpoint(metadata, id, primary_sampler_id)
-        if checkpoint:
-            params["checkpoint"] = checkpoint
+
+        # ---- User marks: override heuristic inference with user-assigned hints ----
+        user_marks = MetadataProcessor._get_user_marks(metadata)
+
+        # Find the primary KSampler node (user mark takes priority)
+        primary_sampler_id = None
+        primary_sampler = None
+        if _MARK_PRIMARY_SAMPLER in user_marks:
+            marked_id = user_marks[_MARK_PRIMARY_SAMPLER]
+            sampler_data = metadata.get(SAMPLING, {}).get(marked_id)
+            if sampler_data and sampler_data.get(IS_SAMPLER):
+                primary_sampler_id = marked_id
+                primary_sampler = sampler_data
+            else:
+                logger.warning(
+                    "User-marked primary sampler %s has no runtime metadata, "
+                    "falling back to heuristic",
+                    marked_id,
+                )
+        if primary_sampler is None:
+            primary_sampler_id, primary_sampler = MetadataProcessor.find_primary_sampler(metadata, id)
+
+        # Resolve checkpoint / model (user mark takes priority)
+        if _MARK_PRIMARY_MODEL in user_marks:
+            marked_id = user_marks[_MARK_PRIMARY_MODEL]
+            if marked_id in metadata.get(MODELS, {}):
+                params["checkpoint"] = metadata[MODELS][marked_id].get("name")
+            else:
+                extra_data = metadata.get("extra_data")
+                extra_pnginfo = extra_data.get("extra_pnginfo", {}) if extra_data and isinstance(extra_data, dict) else {}
+                workflow = extra_pnginfo.get("workflow", {}) if isinstance(extra_pnginfo, dict) else {}
+                node_type = "unknown"
+                for n in workflow.get("nodes", []):
+                    if str(n.get("id", "")) == marked_id:
+                        node_type = n.get("type", "unknown")
+                        break
+                logger.warning(
+                    "User-marked primary model %s (type=%s, registered=%s) has no runtime metadata, "
+                    "falling back to heuristic",
+                    marked_id, node_type, node_type in NODE_EXTRACTORS,
+                )
+        if params["checkpoint"] is None:
+            checkpoint = MetadataProcessor.find_primary_checkpoint(metadata, id, primary_sampler_id)
+            if checkpoint:
+                params["checkpoint"] = checkpoint
        
        # Check if guidance parameter exists in any sampling node
        for node_id, sampler_info in metadata.get(SAMPLING, {}).items():
@@ -488,7 +647,22 @@ class MetadataProcessor:
                    
                    # For SamplerCustom, handle any additional parameters
                    MetadataProcessor.handle_custom_advanced_sampler(metadata, prompt, primary_sampler_id, params)
-                
+
+            # ---- User marks: override prompts with explicitly tagged nodes ----
+            prompts_data = metadata.get(PROMPTS, {})
+            if _MARK_POSITIVE_PROMPT in user_marks:
+                pos_id = user_marks[_MARK_POSITIVE_PROMPT]
+                if pos_id in prompts_data:
+                    prompt_text = prompts_data[pos_id].get("text") or prompts_data[pos_id].get("positive_text")
+                    if prompt_text:
+                        params["prompt"] = prompt_text
+            if _MARK_NEGATIVE_PROMPT in user_marks:
+                neg_id = user_marks[_MARK_NEGATIVE_PROMPT]
+                if neg_id in prompts_data:
+                    prompt_text = prompts_data[neg_id].get("text") or prompts_data[neg_id].get("negative_text")
+                    if prompt_text:
+                        params["negative_prompt"] = prompt_text
+
            # Size extraction is same for all sampler types
            # Check if the sampler itself has size information (from latent_image)
            if primary_sampler_id in metadata.get(SIZE, {}):
@@ -509,9 +683,34 @@ class MetadataProcessor:
        
        params["loras"] = " ".join(lora_parts)
        
-        # Set default clip_skip value
-        params["clip_skip"] = "1"  # Common default
-        
+        # Extract clip_skip from any SAMPLING node that provides it
+        for sampler_info in metadata.get(SAMPLING, {}).values():
+            clip_skip = sampler_info.get("parameters", {}).get("clip_skip")
+            if clip_skip is not None:
+                params["clip_skip"] = clip_skip
+                break
+        if params["clip_skip"] is None:
+            params["clip_skip"] = "1"
+
+        # ---- Apply manual metadata overwrites ----
+        for overwrite_info in metadata.get(OVERWRITE, {}).values():
+            overwrite_params = overwrite_info.get("parameters", {})
+            for key, value in overwrite_params.items():
+                if key == "clip_skip":
+                    # Accept any value from overwrite node (sentinel -25 already
+                    # filtered upstream).  Needed because falsy check treats 0
+                    # as "not set" even though 0 is a valid wired input here.
+                    params[key] = value
+                elif value:  # truthy check — only overwrite when user provided a real value
+                    params[key] = value
+
+        # Bridge: the overwrite node exposes the field as "model" (more accurate),
+        # but the internal pipeline key remains "checkpoint" for backward compatibility
+        # with A1111 metadata format and downstream consumers.
+        if params.get("model"):
+            params["checkpoint"] = params["model"]
+            del params["model"]
+
        return params
    
    @staticmethod
@@ -1,7 +1,8 @@
 import time
-from nodes import NODE_CLASS_MAPPINGS  # type: ignore
+from typing import Any
+from nodes import NODE_CLASS_MAPPINGS  # pyright: ignore[reportMissingImports, reportAttributeAccessIssue]
 from .node_extractors import NODE_EXTRACTORS, GenericNodeExtractor
-from .constants import METADATA_CATEGORIES, IMAGES
+from .constants import METADATA_CATEGORIES, IMAGES, OVERWRITE


 class MetadataRegistry:
@@ -9,6 +10,15 @@ class MetadataRegistry:

    _instance = None

+    current_prompt_id: Any = None
+    current_prompt: Any = None
+    metadata: dict[str, Any] = {}
+    prompt_metadata: dict[str, Any] = {}
+    executed_nodes: set[str] = set()
+    node_cache: dict[str, Any] = {}
+    max_prompt_history: int = 3
+    metadata_categories: list[str] = METADATA_CATEGORIES
+
    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
@@ -61,6 +71,7 @@ class MetadataRegistry:
            {
                "execution_order": [],
                "current_prompt": None,  # Will store the prompt object
+                "extra_data": None,  # Will store the API extra_data for workflow metadata
                "timestamp": time.time(),
            }
        )
@@ -75,6 +86,11 @@ class MetadataRegistry:
            # Store the prompt in the metadata for later relationship tracing
            self.prompt_metadata[self.current_prompt_id]["current_prompt"] = prompt

+    def set_extra_data(self, extra_data):
+        """Store the API extra_data (contains extra_pnginfo.workflow with node properties)"""
+        if self.current_prompt_id and self.current_prompt_id in self.prompt_metadata:
+            self.prompt_metadata[self.current_prompt_id]["extra_data"] = extra_data
+
    def get_metadata(self, prompt_id=None):
        """Get collected metadata for a prompt"""
        key = prompt_id if prompt_id is not None else self.current_prompt_id
@@ -122,20 +138,28 @@ class MetadataRegistry:
            cache_key = f"{node_id}:{class_type}"

            # Check if this node type is relevant for metadata collection
-            if class_type in NODE_EXTRACTORS:
+            if class_type in NODE_EXTRACTORS or cache_key in self.node_cache:
                # Check if we have cached metadata for this node
                if cache_key in self.node_cache:
                    cached_data = self.node_cache[cache_key]

+                    # Detect bypass (mode=4) / mute (mode=2) — these nodes
+                    # were intentionally disabled and should not contribute
+                    # overwrite values from a previous execution's cache.
+                    node_mode = node_data.get("mode", 0)
+                    node_is_disabled = node_mode in (2, 4)
+
                    # Apply cached metadata to the current metadata
                    for category in self.metadata_categories:
+                        if category == OVERWRITE and node_is_disabled:
+                            continue
                        if category in cached_data and node_id in cached_data[category]:
                            if node_id not in metadata[category]:
                                metadata[category][node_id] = cached_data[category][
                                    node_id
                                ]

-    def record_node_execution(self, node_id, class_type, inputs, outputs):
+    def record_node_execution(self, node_id, class_type, inputs, outputs, return_types=None):
        """Record information about a node's execution"""
        if not self.current_prompt_id:
            return
@@ -158,17 +182,18 @@ class MetadataRegistry:

        # Extract node-specific metadata
        extractor = NODE_EXTRACTORS.get(class_type, GenericNodeExtractor)
-        extractor.extract(
-            node_id,
-            processed_inputs,
-            outputs,
-            self.prompt_metadata[self.current_prompt_id],
-        )
+        if extractor is GenericNodeExtractor:
+            extractor.extract(node_id, processed_inputs, outputs,
+                              self.prompt_metadata[self.current_prompt_id],
+                              return_types=return_types)
+        else:
+            extractor.extract(node_id, processed_inputs, outputs,
+                              self.prompt_metadata[self.current_prompt_id])

        # Cache this node's metadata
        self._cache_node_metadata(node_id, class_type)

-    def update_node_execution(self, node_id, class_type, outputs):
+    def update_node_execution(self, node_id, class_type, outputs, return_types=None):
        """Update node metadata with output information"""
        if not self.current_prompt_id:
            return
@@ -179,9 +204,17 @@ class MetadataRegistry:
        # Use the same extractor to update with outputs
        extractor = NODE_EXTRACTORS.get(class_type, GenericNodeExtractor)
        if hasattr(extractor, "update"):
-            extractor.update(
-                node_id, processed_outputs, self.prompt_metadata[self.current_prompt_id]
-            )
+            if extractor is GenericNodeExtractor:
+                extractor.update(
+                    node_id, processed_outputs,
+                    self.prompt_metadata[self.current_prompt_id],
+                    return_types=return_types,
+                )
+            else:
+                extractor.update(
+                    node_id, processed_outputs,
+                    self.prompt_metadata[self.current_prompt_id],
+                )

        # Update the cached metadata for this node
        self._cache_node_metadata(node_id, class_type)
@@ -2,7 +2,8 @@ import json
 import os
 import re

-from .constants import MODELS, PROMPTS, SAMPLING, LORAS, SIZE, IMAGES, IS_SAMPLER
+from .constants import MODELS, PROMPTS, SAMPLING, LORAS, SIZE, IMAGES, IS_SAMPLER, OVERWRITE
+from .overwrite_utils import collect_overwrite_params


 def _store_checkpoint_metadata(metadata, node_id, model_name):
@@ -31,11 +32,95 @@ class NodeMetadataExtractor:
        pass
        
 class GenericNodeExtractor(NodeMetadataExtractor):
-    """Default extractor for nodes without specific handling"""
+    """Fallback extractor with type-signature-based detection.
+
+    When a node is not in the NODE_EXTRACTORS registry, the hook layer
+    passes ``return_types`` from ``obj.RETURN_TYPES``:
+
+    * ``MODEL`` output: common input fields (ckpt_name, unet_name, etc.)
+      are checked for a model file name and stored as checkpoint metadata.
+    * ``CONDITIONING`` output: common text input fields are checked for
+      prompt text, and conditioning inputs are tracked through transforms.
+    """
+
+    # Input field names that carry a model path in loader-style nodes.
+    _MODEL_NAME_FIELDS = (
+        "ckpt_name", "unet_name", "model_path", "model_name", "gguf_name",
+    )
+
+    # Extensions used by checkpoint_scanner.py — only record values that look
+    # like real model filenames to avoid capturing unrelated string fields.
+    _MODEL_EXTENSIONS = {
+        ".ckpt", ".pt", ".pt2", ".bin", ".pth", ".safetensors", ".pkl", ".sft", ".gguf",
+    }
+
+    # Input field names that may carry prompt text in encoder-style nodes.
+    _TEXT_FIELDS = ("text", "clip_l", "t5xxl", "prompt", "positive", "negative")
+
    @staticmethod
-    def extract(node_id, inputs, outputs, metadata):
-        pass
-        
+    def extract(node_id, inputs, outputs, metadata, return_types=None):
+        if return_types is None:
+            return
+
+        # — MODEL loader detection (checkpoint / UNET / GGUF) —
+        if "MODEL" in return_types or any("MODEL" in str(t) for t in return_types):
+            for field in GenericNodeExtractor._MODEL_NAME_FIELDS:
+                val = inputs.get(field)
+                if val and isinstance(val, str) and val.strip():
+                    name = val.strip()
+                    if not any(name.lower().endswith(ext) for ext in GenericNodeExtractor._MODEL_EXTENSIONS):
+                        continue
+                    _store_checkpoint_metadata(metadata, node_id, name)
+                    return
+
+        # — CONDITIONING encoder / transform detection —
+        if "CONDITIONING" in return_types or any("CONDITIONING" in str(t) for t in return_types):
+            text = None
+            for field in GenericNodeExtractor._TEXT_FIELDS:
+                val = inputs.get(field)
+                if val and isinstance(val, str) and val.strip():
+                    text = val.strip()
+                    break
+
+            input_conditionings = _collect_conditioning_inputs(inputs)
+            if text or input_conditionings:
+                prompt_metadata = _ensure_prompt_metadata(metadata, node_id)
+                if text:
+                    prompt_metadata["text"] = text
+                if input_conditionings:
+                    prompt_metadata["orig_conditionings"] = input_conditionings
+
+    @staticmethod
+    def update(node_id, outputs, metadata, return_types=None):
+        if return_types is None:
+            return
+        if "CONDITIONING" not in return_types and not any(
+            "CONDITIONING" in str(t) for t in return_types
+        ):
+            return
+        if node_id not in metadata.get(PROMPTS, {}):
+            return
+        output_tuple = _first_output_tuple(outputs)
+        if not output_tuple or len(output_tuple) < 1:
+            return
+
+        conditioning_index = _first_conditioning_index(return_types)
+        if conditioning_index is None or len(output_tuple) <= conditioning_index:
+            return
+
+        output_conditioning = output_tuple[conditioning_index]
+        if output_conditioning is None:
+            return
+
+        prompt_metadata = metadata[PROMPTS][node_id]
+        prompt_metadata["conditioning"] = output_conditioning
+        _record_conditioning_source(
+            metadata,
+            node_id,
+            output_conditioning,
+            prompt_metadata.get("orig_conditionings", []),
+        )
+
 class CheckpointLoaderExtractor(NodeMetadataExtractor):
    @staticmethod
    def extract(node_id, inputs, outputs, metadata):
@@ -144,6 +229,118 @@ class TSCCheckpointLoaderExtractor(NodeMetadataExtractor):
                metadata[PROMPTS][node_id]["positive_encoded"] = positive_conditioning
                metadata[PROMPTS][node_id]["negative_encoded"] = negative_conditioning

+
+class EasyComfyLoaderExtractor(NodeMetadataExtractor):
+    @staticmethod
+    def extract(node_id, inputs, outputs, metadata):
+        if not inputs:
+            return
+
+        if "ckpt_name" in inputs:
+            _store_checkpoint_metadata(metadata, node_id, inputs["ckpt_name"])
+
+        # Only extract from optional_lora_stack — skip the single lora_name to
+        # avoid double-counting LoRAs that come through the LORA_STACK path.
+        active_loras = []
+        optional_lora_stack = inputs.get("optional_lora_stack")
+        if optional_lora_stack is not None and isinstance(optional_lora_stack, (list, tuple)):
+            for item in optional_lora_stack:
+                if isinstance(item, (list, tuple)) and len(item) >= 2:
+                    lora_path = item[0]
+                    model_strength = item[1]
+                    lora_name = os.path.splitext(os.path.basename(lora_path))[0]
+                    active_loras.append({
+                        "name": lora_name,
+                        "strength": model_strength
+                    })
+
+        if active_loras:
+            metadata[LORAS][node_id] = {
+                "lora_list": active_loras,
+                "node_id": node_id
+            }
+
+        positive_text = inputs.get("positive", "")
+        negative_text = inputs.get("negative", "")
+
+        if positive_text or negative_text:
+            if node_id not in metadata[PROMPTS]:
+                metadata[PROMPTS][node_id] = {"node_id": node_id}
+            metadata[PROMPTS][node_id]["positive_text"] = positive_text
+            metadata[PROMPTS][node_id]["negative_text"] = negative_text
+
+        if "clip_skip" in inputs:
+            clip_skip = inputs["clip_skip"]
+            if node_id not in metadata[SAMPLING]:
+                metadata[SAMPLING][node_id] = {"parameters": {}, "node_id": node_id}
+            metadata[SAMPLING][node_id]["parameters"]["clip_skip"] = clip_skip
+
+        width = inputs.get("empty_latent_width")
+        height = inputs.get("empty_latent_height")
+        if width is not None and height is not None:
+            if SIZE not in metadata:
+                metadata[SIZE] = {}
+            metadata[SIZE][node_id] = {
+                "width": int(width),
+                "height": int(height),
+                "node_id": node_id
+            }
+
+    @staticmethod
+    def update(node_id, outputs, metadata):
+        # outputs: [(pipe_dict, model, vae), ...]
+        if not outputs or not isinstance(outputs, list) or len(outputs) == 0:
+            return
+        first_output = outputs[0]
+        if not isinstance(first_output, tuple) or len(first_output) < 1:
+            return
+        pipe = first_output[0]
+        if not isinstance(pipe, dict):
+            return
+
+        positive_conditioning = pipe.get("positive")
+        negative_conditioning = pipe.get("negative")
+
+        if positive_conditioning is not None or negative_conditioning is not None:
+            if node_id not in metadata[PROMPTS]:
+                metadata[PROMPTS][node_id] = {"node_id": node_id}
+            if positive_conditioning is not None:
+                metadata[PROMPTS][node_id]["positive_encoded"] = positive_conditioning
+            if negative_conditioning is not None:
+                metadata[PROMPTS][node_id]["negative_encoded"] = negative_conditioning
+
+
+class EasyPreSamplingExtractor(NodeMetadataExtractor):
+    @staticmethod
+    def extract(node_id, inputs, outputs, metadata):
+        if not inputs:
+            return
+
+        sampling_params = {}
+        for key in ("steps", "cfg", "sampler_name", "scheduler", "denoise", "seed"):
+            if key in inputs:
+                sampling_params[key] = inputs[key]
+
+        metadata[SAMPLING][node_id] = {
+            "parameters": sampling_params,
+            "node_id": node_id,
+            IS_SAMPLER: True
+        }
+
+
+class EasySeedExtractor(NodeMetadataExtractor):
+    @staticmethod
+    def extract(node_id, inputs, outputs, metadata):
+        if not inputs or "seed" not in inputs:
+            return
+
+        metadata[SAMPLING][node_id] = {
+            "parameters": {"seed": inputs["seed"]},
+            "node_id": node_id,
+            IS_SAMPLER: False
+        }
+
+
 class CLIPTextEncodeExtractor(NodeMetadataExtractor):
    @staticmethod
    def extract(node_id, inputs, outputs, metadata):
@@ -163,6 +360,281 @@ class CLIPTextEncodeExtractor(NodeMetadataExtractor):
                conditioning = outputs[0][0]
                metadata[PROMPTS][node_id]["conditioning"] = conditioning

+
+class MyOriginalWaifuTextExtractor(NodeMetadataExtractor):
+    """Extractor for ComfyUI-MyOriginalWaifu TextProvider nodes."""
+
+    @staticmethod
+    def extract(node_id, inputs, outputs, metadata):
+        if not inputs:
+            return
+
+        positive_text = inputs.get("positive", "")
+        negative_text = inputs.get("negative", "")
+
+        if positive_text or negative_text:
+            metadata[PROMPTS][node_id] = {
+                "positive_text": positive_text,
+                "negative_text": negative_text,
+                "node_id": node_id,
+            }
+
+    @staticmethod
+    def update(node_id, outputs, metadata):
+        output_tuple = _first_output_tuple(outputs)
+        if not output_tuple or len(output_tuple) < 2:
+            return
+
+        prompt_metadata = _ensure_prompt_metadata(metadata, node_id)
+        prompt_metadata["positive_text"] = output_tuple[0]
+        prompt_metadata["negative_text"] = output_tuple[1]
+
+
+class MyOriginalWaifuClipExtractor(NodeMetadataExtractor):
+    """Extractor for ComfyUI-MyOriginalWaifu ClipProvider nodes."""
+
+    @staticmethod
+    def extract(node_id, inputs, outputs, metadata):
+        if not inputs:
+            return
+
+        positive_text = inputs.get("positive", "")
+        negative_text = inputs.get("negative", "")
+
+        if positive_text or negative_text:
+            metadata[PROMPTS][node_id] = {
+                "positive_text": positive_text,
+                "negative_text": negative_text,
+                "node_id": node_id,
+            }
+
+    @staticmethod
+    def update(node_id, outputs, metadata):
+        output_tuple = _first_output_tuple(outputs)
+        if not output_tuple or len(output_tuple) < 2:
+            return
+
+        prompt_metadata = _ensure_prompt_metadata(metadata, node_id)
+        prompt_metadata["positive_encoded"] = output_tuple[0]
+        prompt_metadata["negative_encoded"] = output_tuple[1]
+
+
+def _ensure_prompt_metadata(metadata, node_id):
+    if node_id not in metadata[PROMPTS]:
+        metadata[PROMPTS][node_id] = {"node_id": node_id}
+    return metadata[PROMPTS][node_id]
+
+
+def _first_output_tuple(outputs):
+    if not outputs or not isinstance(outputs, list) or len(outputs) == 0:
+        return None
+    first_output = outputs[0]
+    if isinstance(first_output, tuple):
+        return first_output
+    return None
+
+
+def _first_conditioning_index(return_types):
+    """Return the index of the first CONDITIONING output slot, or None."""
+    if not return_types:
+        return None
+    for index, return_type in enumerate(return_types):
+        if "CONDITIONING" in str(return_type):
+            return index
+    return None
+
+
+def _collect_conditioning_inputs(inputs):
+    """Collect conditioning object inputs (``conditioning*`` keys).
+
+    Primitive values (None, str, int, float, bool) are excluded so scalar
+    fields like ``conditioning_strength`` are not mistaken for conditioning
+    objects during provenance tracking.
+    """
+    if not inputs:
+        return []
+    return [
+        value
+        for input_name, value in inputs.items()
+        if input_name.startswith("conditioning")
+        and value is not None
+        and not isinstance(value, (str, int, float, bool))
+    ]
+
+
+def _record_conditioning_source(
+    metadata, node_id, output_conditioning, input_conditionings
+):
+    if output_conditioning is None:
+        return
+
+    sources = [
+        conditioning for conditioning in input_conditionings if conditioning is not None
+    ]
+    if not sources:
+        return
+
+    # Identity-preserving selectors return one of their inputs unchanged:
+    # only that input contributed to the output, so record it alone instead
+    # of treating every input as a combination source.
+    for conditioning in sources:
+        if id(conditioning) == id(output_conditioning):
+            sources = [conditioning]
+            break
+
+    prompt_metadata = _ensure_prompt_metadata(metadata, node_id)
+    prompt_metadata.setdefault("conditioning_sources", []).append(
+        {
+            "output": output_conditioning,
+            "inputs": sources,
+        }
+    )
+
+
+def _get_variable_name(inputs):
+    for key in ("key", "name", "variable_name", "tag", "text"):
+        value = inputs.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return None
+
+
+def _get_node_variable_name(metadata, node_id, inputs):
+    variable_name = _get_variable_name(inputs)
+    if variable_name:
+        return variable_name
+
+    prompt = metadata.get("current_prompt")
+    original_prompt = getattr(prompt, "original_prompt", None)
+    if not original_prompt or node_id not in original_prompt:
+        return None
+
+    node_data = original_prompt[node_id]
+    variable_name = _get_variable_name(node_data.get("inputs", {}))
+    if variable_name:
+        return variable_name
+
+    widgets_values = node_data.get("widgets_values", [])
+    if widgets_values and isinstance(widgets_values[0], str):
+        return widgets_values[0]
+
+    return None
+
+
+class ControlNetApplyAdvancedExtractor(NodeMetadataExtractor):
+    @staticmethod
+    def extract(node_id, inputs, outputs, metadata):
+        if not inputs:
+            return
+
+        prompt_metadata = _ensure_prompt_metadata(metadata, node_id)
+        if inputs.get("positive") is not None:
+            prompt_metadata["orig_pos_cond"] = inputs["positive"]
+        if inputs.get("negative") is not None:
+            prompt_metadata["orig_neg_cond"] = inputs["negative"]
+
+    @staticmethod
+    def update(node_id, outputs, metadata):
+        output_tuple = _first_output_tuple(outputs)
+        if not output_tuple:
+            return
+
+        prompt_metadata = _ensure_prompt_metadata(metadata, node_id)
+        positive_input = prompt_metadata.get("orig_pos_cond")
+        negative_input = prompt_metadata.get("orig_neg_cond")
+
+        if len(output_tuple) >= 1:
+            prompt_metadata["positive_encoded"] = output_tuple[0]
+            _record_conditioning_source(
+                metadata, node_id, output_tuple[0], [positive_input]
+            )
+        if len(output_tuple) >= 2:
+            prompt_metadata["negative_encoded"] = output_tuple[1]
+            _record_conditioning_source(
+                metadata, node_id, output_tuple[1], [negative_input]
+            )
+
+
+class ConditioningCombineExtractor(NodeMetadataExtractor):
+    @staticmethod
+    def extract(node_id, inputs, outputs, metadata):
+        if not inputs:
+            return
+
+        input_conditionings = _collect_conditioning_inputs(inputs)
+
+        if input_conditionings:
+            prompt_metadata = _ensure_prompt_metadata(metadata, node_id)
+            prompt_metadata["orig_conditionings"] = input_conditionings
+
+    @staticmethod
+    def update(node_id, outputs, metadata):
+        output_tuple = _first_output_tuple(outputs)
+        if not output_tuple or len(output_tuple) < 1:
+            return
+
+        prompt_metadata = _ensure_prompt_metadata(metadata, node_id)
+        output_conditioning = output_tuple[0]
+        prompt_metadata["conditioning"] = output_conditioning
+        _record_conditioning_source(
+            metadata,
+            node_id,
+            output_conditioning,
+            prompt_metadata.get("orig_conditionings", []),
+        )
+
+
+class SetNodeExtractor(NodeMetadataExtractor):
+    @staticmethod
+    def extract(node_id, inputs, outputs, metadata):
+        if not inputs:
+            return
+
+        variable_name = _get_node_variable_name(metadata, node_id, inputs)
+        conditioning = inputs.get("CONDITIONING")
+        if conditioning is None:
+            conditioning = inputs.get("conditioning")
+        if conditioning is None:
+            return
+
+        prompt_metadata = _ensure_prompt_metadata(metadata, node_id)
+        prompt_metadata["conditioning"] = conditioning
+        if variable_name:
+            prompt_metadata["variable_name"] = variable_name
+            metadata[PROMPTS].setdefault("__conditioning_variables__", {})[
+                variable_name
+            ] = conditioning
+
+
+class GetNodeExtractor(NodeMetadataExtractor):
+    @staticmethod
+    def extract(node_id, inputs, outputs, metadata):
+        variable_name = _get_node_variable_name(metadata, node_id, inputs or {})
+        if variable_name:
+            prompt_metadata = _ensure_prompt_metadata(metadata, node_id)
+            prompt_metadata["variable_name"] = variable_name
+
+    @staticmethod
+    def update(node_id, outputs, metadata):
+        output_tuple = _first_output_tuple(outputs)
+        if not output_tuple or len(output_tuple) < 1:
+            return
+
+        prompt_metadata = _ensure_prompt_metadata(metadata, node_id)
+        output_conditioning = output_tuple[0]
+        prompt_metadata["conditioning"] = output_conditioning
+
+        variable_name = prompt_metadata.get("variable_name")
+        if not variable_name:
+            return
+
+        input_conditioning = metadata[PROMPTS].get("__conditioning_variables__", {}).get(
+            variable_name
+        )
+        _record_conditioning_source(
+            metadata, node_id, output_conditioning, [input_conditioning]
+        )
+
 # Base Sampler Extractor to reduce code redundancy
 class BaseSamplerExtractor(NodeMetadataExtractor):
    """Base extractor for sampler nodes with common functionality"""
@@ -389,6 +861,65 @@ class TSCKSamplerAdvancedExtractor(KSamplerAdvancedExtractor, TSCSamplerBaseExtr

    # Update method is inherited from TSCSamplerBaseExtractor

+class KreaTwoStageSamplerExtractor(BaseSamplerExtractor):
+    """Extractor for Krea Two/Three Stage Samplers (Auryg/Krea-2-Two-Stage-Sampler).
+
+    The node samples in two (or three) stages with per-stage settings
+    (stage1_steps/stage2_steps, stage1_cfg/stage2_cfg, ...). The canonical
+    metadata fields consumed by ``extract_generation_params`` (steps, cfg,
+    sampler_name, scheduler) are derived from the base stage (stage 1; the
+    three-stage variant reuses stage 1 settings for stage 3), while the full
+    per-stage breakdown is preserved in the raw parameters.
+    """
+
+    # All per-stage parameter keys present on both node variants.
+    _STAGE_PARAM_KEYS = (
+        "stage1_steps", "stage1_cfg", "stage1_sampler_name", "stage1_scheduler",
+        "stage2_steps", "stage2_cfg", "stage2_sampler_name", "stage2_scheduler",
+    )
+
+    @staticmethod
+    def extract(node_id, inputs, outputs, metadata):
+        if not inputs:
+            return
+
+        BaseSamplerExtractor.extract_sampling_params(
+            node_id,
+            inputs,
+            metadata,
+            ("seed", "handoff_percent", "stage3_handoff_percent")
+            + KreaTwoStageSamplerExtractor._STAGE_PARAM_KEYS,
+        )
+
+        # Derive the canonical fields expected by extract_generation_params.
+        sampling_params = metadata[SAMPLING][node_id]["parameters"]
+        if "stage1_steps" in sampling_params or "stage2_steps" in sampling_params:
+            sampling_params["steps"] = (
+                (sampling_params.get("stage1_steps") or 0)
+                + (sampling_params.get("stage2_steps") or 0)
+            )
+        if "stage1_cfg" in sampling_params:
+            sampling_params["cfg"] = sampling_params["stage1_cfg"]
+        if "stage1_sampler_name" in sampling_params:
+            sampling_params["sampler_name"] = sampling_params["stage1_sampler_name"]
+        if "stage1_scheduler" in sampling_params:
+            sampling_params["scheduler"] = sampling_params["stage1_scheduler"]
+
+        BaseSamplerExtractor.extract_conditioning(node_id, inputs, metadata)
+
+        # Prefer the final generation resolution; latent dims are the fallback.
+        BaseSamplerExtractor.extract_latent_dimensions(node_id, inputs, metadata)
+        final_width = inputs.get("final_width")
+        final_height = inputs.get("final_height")
+        if final_width and final_height:
+            if SIZE not in metadata:
+                metadata[SIZE] = {}
+            metadata[SIZE][node_id] = {
+                "width": final_width,
+                "height": final_height,
+                "node_id": node_id,
+            }
+
 class LoraLoaderExtractor(NodeMetadataExtractor):
    @staticmethod
    def extract(node_id, inputs, outputs, metadata):
@@ -429,6 +960,37 @@ class ImageSizeExtractor(NodeMetadataExtractor):
            "node_id": node_id
        }

+class KreaDualResolutionSelectorExtractor(NodeMetadataExtractor):
+    """Extract base resolution from Krea Dual Resolution Selector outputs
+    (Auryg/Krea-2-Two-Stage-Sampler).
+
+    The node computes base/final dimensions at runtime from aspect ratio and
+    megapixel settings, so the values are only available in the update phase
+    (outputs: base_width, base_height, final_width, final_height, seed).
+    """
+
+    @staticmethod
+    def extract(node_id, inputs, outputs, metadata):
+        # Dimensions are computed at runtime; nothing to do here.
+        pass
+
+    @staticmethod
+    def update(node_id, outputs, metadata):
+        output_tuple = _first_output_tuple(outputs)
+        if not output_tuple or len(output_tuple) < 2:
+            return
+        width, height = output_tuple[0], output_tuple[1]
+        if not isinstance(width, int) or not isinstance(height, int):
+            return
+
+        if SIZE not in metadata:
+            metadata[SIZE] = {}
+        metadata[SIZE][node_id] = {
+            "width": width,
+            "height": height,
+            "node_id": node_id,
+        }
+
 class RgthreePowerLoraLoaderExtractor(NodeMetadataExtractor):
    """Extract LoRA metadata from rgthree Power Lora Loader.

@@ -544,6 +1106,55 @@ class LoraLoaderManagerExtractor(NodeMetadataExtractor):
                "node_id": node_id
            }

+class LoraTextLoaderManagerExtractor(NodeMetadataExtractor):
+    """Extract LoRA metadata from LoraTextLoaderLM (LoRA Text Loader).
+
+    The node accepts a `lora_syntax` STRING containing <lora:name:strength> tags
+    (same format as the ComfyUI prompt), plus an optional `lora_stack`.
+    This extractor parses the syntax string using the same regex as the node.
+    """
+    @staticmethod
+    def extract(node_id, inputs, outputs, metadata):
+        if not inputs:
+            return
+
+        active_loras = []
+
+        # Process lora_stack if available (optional input)
+        if "lora_stack" in inputs:
+            lora_stack = inputs.get("lora_stack", [])
+            for item in lora_stack:
+                # lora_stack entries are (path, model_strength, clip_strength) tuples
+                if isinstance(item, (list, tuple)) and len(item) >= 2:
+                    lora_path = item[0]
+                    model_strength = item[1]
+                    lora_name = os.path.splitext(os.path.basename(lora_path))[0]
+                    active_loras.append({
+                        "name": lora_name,
+                        "strength": round(float(model_strength), 2)
+                    })
+
+        # Process lora_syntax string input
+        if "lora_syntax" in inputs:
+            lora_syntax = inputs.get("lora_syntax", "")
+            if lora_syntax and isinstance(lora_syntax, str):
+                pattern = r"<lora:([^:>]+):([^:>]+)(?::([^:>]+))?>"
+                matches = re.findall(pattern, lora_syntax, re.IGNORECASE)
+                for match in matches:
+                    lora_name = match[0]
+                    model_strength = float(match[1])
+                    active_loras.append({
+                        "name": lora_name,
+                        "strength": round(model_strength, 2)
+                    })
+
+        if active_loras:
+            metadata[LORAS][node_id] = {
+                "lora_list": active_loras,
+                "node_id": node_id
+            }
+
+
 class FluxGuidanceExtractor(NodeMetadataExtractor):
    @staticmethod
    def extract(node_id, inputs, outputs, metadata):
@@ -748,6 +1359,28 @@ class CR_ApplyControlNetStackExtractor(NodeMetadataExtractor):
                metadata[PROMPTS][node_id]["positive_encoded"] = transformed_positive
                metadata[PROMPTS][node_id]["negative_encoded"] = transformed_negative

+class MetadataOverwriteExtractor(NodeMetadataExtractor):
+    """Extract manually specified metadata from MetadataOverwriteLM node.
+
+    Stores truthy input values under the OVERWRITE category so that
+    extract_generation_params can merge them over the inferred params.
+    """
+
+    @staticmethod
+    def extract(node_id, inputs, outputs, metadata):
+        if not inputs:
+            return
+
+        overwrite_params = collect_overwrite_params(inputs)
+
+        if overwrite_params:
+            metadata.setdefault(OVERWRITE, {})
+            metadata[OVERWRITE][node_id] = {
+                "parameters": overwrite_params,
+                "node_id": node_id,
+            }
+
+
 # Registry of node-specific extractors
 # Keys are node class names
 NODE_EXTRACTORS = {
@@ -759,6 +1392,8 @@ NODE_EXTRACTORS = {
    "ClownsharKSampler_Beta": SamplerExtractor,
    "TSC_KSampler": TSCKSamplerExtractor,   # Efficient Nodes
    "TSC_KSamplerAdvanced": TSCKSamplerAdvancedExtractor,  # Efficient Nodes
+    "KreaTwoStageSampler": KreaTwoStageSamplerExtractor,  # Auryg/Krea-2-Two-Stage-Sampler
+    "KreaThreeStageSampler": KreaTwoStageSamplerExtractor,  # Auryg/Krea-2-Two-Stage-Sampler
    "KSamplerBasicPipe": KSamplerBasicPipeExtractor,    # comfyui-impact-pack
    "KSamplerAdvancedBasicPipe": KSamplerAdvancedBasicPipeExtractor,    # comfyui-impact-pack
    "KSampler_inspire_pipe": KSamplerBasicPipeExtractor,    # comfyui-inspire-pack
@@ -768,9 +1403,12 @@ NODE_EXTRACTORS = {
    "KSamplerSelect": KSamplerSelectExtractor,  # Add KSamplerSelect
    "BasicScheduler": BasicSchedulerExtractor,  # Add BasicScheduler
    "AlignYourStepsScheduler": BasicSchedulerExtractor,  # Add AlignYourStepsScheduler
+    # ComfyUI-Easy-Use pre-sampling / seed
+    "samplerSettings": EasyPreSamplingExtractor,  # easy preSampling
+    "easySeed": EasySeedExtractor,  # easy seed
    # Loaders
    "CheckpointLoaderSimple": CheckpointLoaderExtractor,
-    "comfyLoader": CheckpointLoaderExtractor,  # easy comfyLoader
+    "comfyLoader": EasyComfyLoaderExtractor,  # ComfyUI-Easy-Use easy comfyLoader
    "CheckpointLoaderSimpleWithImages": CheckpointLoaderExtractor,  # CheckpointLoader|pysssss
    "TSC_EfficientLoader": TSCCheckpointLoaderExtractor,  # Efficient Nodes
    "NunchakuFluxDiTLoader": NunchakuFluxDiTLoaderExtractor,  # ComfyUI-Nunchaku
@@ -780,10 +1418,13 @@ NODE_EXTRACTORS = {
    "GGUFLoaderKJ": KJNodesModelLoaderExtractor,  # KJNodes
    "DiffusionModelLoaderKJ": KJNodesModelLoaderExtractor,  # KJNodes
    "CheckpointLoaderKJ": CheckpointLoaderExtractor,  # KJNodes
+    "CheckpointLoaderLM": CheckpointLoaderExtractor,  # LoRA Manager
    "UNETLoader": UNETLoaderExtractor,          # Updated to use dedicated extractor
    "UnetLoaderGGUF": UNETLoaderExtractor,  # Updated to use dedicated extractor
+    "UNETLoaderLM": UNETLoaderExtractor,  # LoRA Manager
    "LoraLoader": LoraLoaderExtractor,
    "LoraLoaderLM": LoraLoaderManagerExtractor,
+    "LoraTextLoaderLM": LoraTextLoaderManagerExtractor,
    "RgthreePowerLoraLoader": RgthreePowerLoraLoaderExtractor,
    "TensorRTLoader": TensorRTLoaderExtractor,
    # Conditioning
@@ -796,12 +1437,21 @@ NODE_EXTRACTORS = {
    "smZ_CLIPTextEncode": CLIPTextEncodeExtractor,  # From https://github.com/shiimizu/ComfyUI_smZNodes
    "CR_ApplyControlNetStack": CR_ApplyControlNetStackExtractor,  # Add CR_ApplyControlNetStack
    "PCTextEncode": CLIPTextEncodeExtractor,  # From https://github.com/asagi4/comfyui-prompt-control
+    "TextProvider": MyOriginalWaifuTextExtractor,  # ComfyUI-MyOriginalWaifu
+    "ClipProvider": MyOriginalWaifuClipExtractor,  # ComfyUI-MyOriginalWaifu
+    "ControlNetApplyAdvanced": ControlNetApplyAdvancedExtractor,
+    "ConditioningCombine": ConditioningCombineExtractor,
+    "SetNode": SetNodeExtractor,
+    "GetNode": GetNodeExtractor,
    # Latent
    "EmptyLatentImage": ImageSizeExtractor,
+    "KreaDualResolutionSelector": KreaDualResolutionSelectorExtractor,  # Auryg/Krea-2-Two-Stage-Sampler
    # Flux
    "FluxGuidance": FluxGuidanceExtractor,      # Add FluxGuidance
    "CFGGuider": CFGGuiderExtractor,            # Add CFGGuider
    # Image
    "VAEDecode": VAEDecodeExtractor,  # Added VAEDecode extractor
+    # Metadata overwrite
+    "MetadataOverwriteLM": MetadataOverwriteExtractor,
    # Add other nodes as needed
 }
@@ -0,0 +1,51 @@
+"""Shared helpers for Metadata Overwrite node metadata collection.
+
+Used by both the MetadataOverwriteLM node (execution time) and the
+MetadataOverwriteExtractor (hook time) so the conversion/filtering logic
+cannot drift between the two paths.
+"""
+
+import logging
+from typing import Any, Dict
+
+from ..utils.utils import model_patcher_to_name, sampler_object_to_name
+from .constants import CLIP_SKIP_SENTINEL, METADATA_OVERWRITE_FIELDS
+
+logger = logging.getLogger(__name__)
+
+
+def collect_overwrite_params(values: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert node input values into non-default overwrite parameters.
+
+    For most fields, a falsy value (empty string, 0) means "not set" and is
+    skipped.  clip_skip uses a dedicated sentinel (-25) so that a wired value
+    of 0 is preserved.  The ``model`` field accepts either a manual string or
+    a wired MODEL (ModelPatcher) connection; in the latter case the source
+    model name is extracted from the patcher's ``cached_patcher_init`` and
+    stored as a ComfyUI-style relative path.  The ``sampler`` field likewise
+    accepts a manual string or a wired SAMPLER (KSAMPLER) connection, from
+    which the sampler name is extracted via the sampler function's name.
+    """
+    result: Dict[str, Any] = {}
+    for key in METADATA_OVERWRITE_FIELDS:
+        value = values.get(key)
+        if key == "model" and not isinstance(value, str):
+            value = model_patcher_to_name(value)
+            if value is None:
+                logger.warning(
+                    "Could not extract model name from wired MODEL input "
+                    "(no cached_patcher_init); model metadata overwrite skipped"
+                )
+        elif key == "sampler" and not isinstance(value, str):
+            value = sampler_object_to_name(value)
+            if value is None:
+                logger.warning(
+                    "Could not extract sampler name from wired SAMPLER input "
+                    "(unrecognized sampler function); sampler metadata overwrite skipped"
+                )
+        if key == "clip_skip":
+            if value != CLIP_SKIP_SENTINEL:
+                result[key] = value
+        elif value:
+            result[key] = value
+    return result
@@ -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[Any, 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[Any, 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
@@ -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()
@@ -16,6 +16,8 @@ IMG_EXTENSIONS = (
    ".tif",
    ".tiff",
    ".webp",
+    ".avif",
+    ".jxl",
    ".mp4"
 )

@@ -0,0 +1,76 @@
+"""JSON error middleware for API routes.
+
+Ensures all responses to /api/* requests return valid JSON that the
+browser-extension frontend can JSON.parse() without crashing, even when
+the route does not exist (404) or the handler raises an exception (500).
+
+Extension consumers call response.json() unconditionally — an HTML error
+page causes ``SyntaxError: unexpected end of data`` that leaks into the
+popup UI as a toast notification.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Awaitable, Callable
+
+from aiohttp import web
+
+logger = logging.getLogger(__name__)
+
+
+@web.middleware
+async def api_json_error(
+    request: web.Request,
+    handler: Callable[[web.Request], Awaitable[web.Response]],
+) -> web.Response:
+    """Return JSON ``{"success": false, "error": "..."}`` for API errors.
+
+    Only intercepts paths starting with ``/api/`` — all other routes
+    (frontend pages, static files, WebSocket upgrades) pass through
+    unchanged.
+    """
+    if not request.path.startswith("/api/"):
+        return await handler(request)
+
+    try:
+        response = await handler(request)
+        return response
+    except web.HTTPException as exc:
+        # Let redirects (301, 302, 307, 308) propagate — they are not errors.
+        if exc.status < 400:
+            raise
+
+        # Preview 404 is routine (file deleted from disk) — not worth a warning.
+        logger_method = logger.warning
+        if request.path.startswith("/api/lm/previews") and exc.status == 404:
+            logger_method = logger.debug
+
+        logger_method(
+            "API %s %s returned HTTP %d: %s",
+            request.method,
+            request.path,
+            exc.status,
+            exc.reason,
+        )
+
+        return web.json_response(
+            {"success": False, "error": f"{exc.status}: {exc.reason}"},
+            status=exc.status,
+        )
+    except Exception as exc:
+        logger.error(
+            "API %s %s raised unhandled exception: %s",
+            request.method,
+            request.path,
+            exc,
+            exc_info=True,
+        )
+
+        return web.json_response(
+            {
+                "success": False,
+                "error": f"500: Internal Server Error ({type(exc).__name__})",
+            },
+            status=500,
+        )
@@ -1,7 +1,8 @@
 import logging
-from typing import List, Tuple
-import comfy.sd # type: ignore
-import folder_paths # type: ignore
+import os
+from typing import Any, List, Tuple
+import comfy.sd  # pyright: ignore[reportMissingImports]
+import folder_paths  # pyright: ignore[reportMissingImports]
 from ..utils.utils import get_checkpoint_info_absolute, _format_model_name_for_comfyui

 logger = logging.getLogger(__name__)
@@ -18,9 +19,9 @@ class CheckpointLoaderLM:
    CATEGORY = "Lora Manager/loaders"

    @classmethod
-    def INPUT_TYPES(s):
+    def INPUT_TYPES(cls):
        # Get list of checkpoint names from scanner (includes extra folder paths)
-        checkpoint_names = s._get_checkpoint_names()
+        checkpoint_names = cls._get_checkpoint_names()
        return {
            "required": {
                "ckpt_name": (
@@ -58,7 +59,10 @@ class CheckpointLoaderLM:
                for item in cache.raw_data:
                    if item.get("sub_type") == "checkpoint":
                        file_path = item.get("file_path", "")
-                        if file_path:
+                        # Only offer models that still exist on disk so ComfyUI
+                        # flags missing checkpoints at queue time via
+                        # "value not in list" (the scanner cache can be stale).
+                        if file_path and os.path.exists(file_path):
                            # Format using relative path with OS-native separator
                            formatted_name = _format_model_name_for_comfyui(
                                file_path, model_roots
@@ -89,7 +93,7 @@ class CheckpointLoaderLM:
            logger.error(f"Error getting checkpoint names: {e}")
            return []

-    def load_checkpoint(self, ckpt_name: str) -> Tuple:
+    def load_checkpoint(self, ckpt_name: str) -> Tuple[Any, Any, Any]:
        """Load a checkpoint by name, supporting extra folder paths

        Args:
@@ -0,0 +1,123 @@
+"""Create Hook LoRA (LoraManager) — multi-LoRA hook node compatible with ComfyUI's built-in hook pipeline.
+
+Produces ``("HOOKS",)`` output that chains seamlessly with downstream hook consumers
+(ConditioningSetProperties, SetHookKeyframes, CombineHooks, SetClipHooks, etc.).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from ..utils.utils import get_lora_info_absolute
+from .utils import (
+    FlexibleOptionalInputType,
+    any_type,
+    apply_lora_syntax_format,
+    get_loras_list,
+    validate_lora_entries,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class CreateHookLoraLM:
+    NAME = "Create Hook LoRA (LoraManager)"
+    CATEGORY = "Lora Manager/hooks"
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "text": (
+                    "AUTOCOMPLETE_TEXT_LORAS",
+                    {
+                        "placeholder": "Search LoRAs to add...",
+                        "tooltip": (
+                            "Search and select LoRAs. Each LoRA gets its own "
+                            "model/clip strength. Hooks chain with prev_hooks."
+                        ),
+                    },
+                ),
+            },
+            "optional": FlexibleOptionalInputType(any_type),
+        }
+
+    @classmethod
+    def VALIDATE_INPUTS(cls, loras=None):
+        """Queue-time validation: reject missing local LoRAs before execution."""
+        return validate_lora_entries({"loras": loras}) or True
+
+    RETURN_TYPES = ("HOOKS", "STRING", "STRING")
+    RETURN_NAMES = ("HOOKS", "trigger_words", "active_loras")
+    FUNCTION = "create_hook"
+
+    def create_hook(self, text: str, **kwargs):
+        """Create a HookGroup from the selected LoRAs, chained with prev_hooks.
+
+        Each active LoRA from the widget is loaded and wrapped in a WeightHook
+        via :func:`comfy.hooks.create_hook_lora`.  All hooks are combined into a
+        single group and returned alongside trigger words and a human-readable
+        summary of the active LoRAs.
+        """
+        del text  # used by the frontend widget only
+
+        # Lazy imports: comfy is not available in CI/test environment at module level
+        import comfy.hooks  # pyright: ignore[reportMissingImports]  # noqa: C0415
+        import comfy.utils  # pyright: ignore[reportMissingImports]  # noqa: C0415
+
+        prev_hooks: comfy.hooks.HookGroup | None = kwargs.get("prev_hooks")
+
+        hook_group = prev_hooks.clone() if prev_hooks is not None else comfy.hooks.HookGroup()
+
+        all_trigger_words: list[str] = []
+        active_loras: list[tuple[str, float, float]] = []
+
+        for lora in get_loras_list(kwargs):
+            if not lora.get("active", False):
+                continue
+
+            lora_name = apply_lora_syntax_format(lora["name"])
+            model_strength = float(lora["strength"])
+            clip_strength = float(lora.get("clipStrength", model_strength))
+
+            # Skip useless no-op entries (both strengths are zero)
+            if model_strength == 0.0 and clip_strength == 0.0:
+                continue
+
+            lora_path, trigger_words = get_lora_info_absolute(lora_name)
+            if not lora_path or not os.path.isfile(lora_path):
+                logger.warning("LoRA '%s' not found — skipping", lora_name)
+                continue
+
+            try:
+                lora_weights = comfy.utils.load_torch_file(lora_path, safe_load=True)
+
+                lora_hooks = comfy.hooks.create_hook_lora(
+                    lora=lora_weights,
+                    strength_model=model_strength,
+                    strength_clip=clip_strength,
+                )
+            except Exception:
+                logger.exception("Failed to load LoRA '%s' — skipping", lora_name)
+                continue
+            hook_group = hook_group.clone_and_combine(lora_hooks)
+
+            active_loras.append((lora_name, model_strength, clip_strength))
+            all_trigger_words.extend(trigger_words)
+
+        # Format trigger words (group mode separator)
+        trigger_words_text = ",, ".join(all_trigger_words) if all_trigger_words else ""
+
+        # Format active LoRAs summary
+        formatted_loras = []
+        for name, model_s, clip_s in active_loras:
+            if abs(model_s - clip_s) > 0.001:
+                formatted_loras.append(
+                    f"<lora:{name}:{model_s}:{clip_s}>"
+                )
+            else:
+                formatted_loras.append(f"<lora:{name}:{model_s}>")
+        active_loras_text = " ".join(formatted_loras)
+
+        return (hook_group, trigger_words_text, active_loras_text)
@@ -0,0 +1,45 @@
+"""Lora Info display node — pure frontend node for showing selected LoRA info.
+
+This node does NOT participate in workflow execution. Its single optional
+"lora_source" input exists solely as a wire-connection anchor so that the
+frontend can traverse the graph and push selection data to connected info nodes.
+"""
+
+from __future__ import annotations
+
+
+class LoraInfoLM:
+    """Display node that shows filename and notes for the selected LoRA."""
+
+    NAME = "Lora Info (LoraManager)"
+    CATEGORY = "Lora Manager/utils"
+    DESCRIPTION = (
+        "Displays information (filename, notes) about the currently selected "
+        "LoRA. Connect any output from a LoRA Loader or Stacker to the "
+        "lora_source input, then select a LoRA in the source widget — the "
+        "info updates automatically. Does not affect workflow execution."
+    )
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {},
+        }
+
+    RETURN_TYPES = ()
+    RETURN_NAMES = ()
+    OUTPUT_NODE = False
+    FUNCTION = "noop"
+
+    def noop(self, **kwargs):
+        # This node is display-only — no workflow execution needed.
+        return ()
+
+
+NODE_CLASS_MAPPINGS = {
+    LoraInfoLM.NAME: LoraInfoLM,
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    LoraInfoLM.NAME: "Lora Info (LoraManager)",
+}
@@ -1,18 +1,20 @@
 import importlib
 import logging
-import re

-import comfy.sd  # type: ignore
-import comfy.utils  # type: ignore
+import comfy.sd  # pyright: ignore[reportMissingImports]
+import comfy.utils  # pyright: ignore[reportMissingImports]

 from ..utils.utils import get_lora_info_absolute
 from .utils import (
    FlexibleOptionalInputType,
    any_type,
+    apply_lora_syntax_format,
    detect_nunchaku_model_kind,
    extract_lora_name,
    get_loras_list,
    nunchaku_load_lora,
+    parse_lora_syntax,
+    validate_lora_entries,
 )

 logger = logging.getLogger(__name__)
@@ -52,7 +54,7 @@ def _collect_widget_entries(kwargs):
    for lora in get_loras_list(kwargs):
        if not lora.get("active", False):
            continue
-        lora_name = lora["name"]
+        lora_name = apply_lora_syntax_format(lora["name"])
        model_strength = float(lora["strength"])
        clip_strength = float(lora.get("clipStrength", model_strength))
        lora_path, trigger_words = get_lora_info_absolute(lora_name)
@@ -141,6 +143,11 @@ class LoraLoaderLM:
            "optional": FlexibleOptionalInputType(any_type),
        }

+    @classmethod
+    def VALIDATE_INPUTS(cls, loras=None):
+        """Queue-time validation: reject missing local LoRAs before execution."""
+        return validate_lora_entries({"loras": loras}) or True
+
    RETURN_TYPES = ("MODEL", "CLIP", "STRING", "STRING")
    RETURN_NAMES = ("MODEL", "CLIP", "trigger_words", "loaded_loras")
    FUNCTION = "load_loras"
@@ -188,25 +195,10 @@ class LoraTextLoaderLM:
    RETURN_NAMES = ("MODEL", "CLIP", "trigger_words", "loaded_loras")
    FUNCTION = "load_loras_from_text"

-    def parse_lora_syntax(self, text):
-        """Parse LoRA syntax from text input."""
-        pattern = r"<lora:([^:>]+):([^:>]+)(?::([^:>]+))?>"
-        matches = re.findall(pattern, text, re.IGNORECASE)
-
-        loras = []
-        for match in matches:
-            model_strength = float(match[1])
-            loras.append({
-                "name": match[0],
-                "model_strength": model_strength,
-                "clip_strength": float(match[2]) if match[2] else model_strength,
-            })
-        return loras
-
    def load_loras_from_text(self, model, lora_syntax, clip=None, lora_stack=None):
        """Load LoRAs based on text syntax input."""
        lora_entries = _collect_stack_entries(lora_stack)
-        for lora in self.parse_lora_syntax(lora_syntax):
+        for lora in parse_lora_syntax(lora_syntax):
            lora_path, trigger_words = get_lora_info_absolute(lora["name"])
            lora_entries.append({
                "name": lora["name"],
@@ -9,6 +9,7 @@ and tracks the last used combination for reuse.
 import logging
 import os
 from ..utils.utils import get_lora_info
+from .utils import validate_lora_entries

 logger = logging.getLogger(__name__)

@@ -31,6 +32,11 @@ class LoraRandomizerLM:
            },
        }

+    @classmethod
+    def VALIDATE_INPUTS(cls, loras=None):
+        """Queue-time validation: reject missing local LoRAs before execution."""
+        return validate_lora_entries({"loras": loras}) or True
+
    RETURN_TYPES = ("LORA_STACK",)
    RETURN_NAMES = ("LORA_STACK",)

@@ -1,26 +1,102 @@
+from __future__ import annotations
+
+import inspect
+import re
+from typing import Any
+
+_STACK_INPUT_PATTERN = re.compile(r"^lora_stack(?:_([ab])|(\d+))$")
+
+
+def _is_stack_input(name: str) -> bool:
+    return bool(_STACK_INPUT_PATTERN.match(name))
+
+
+def _stack_slot_number(name: str) -> int:
+    """Numeric slot used to order stack inputs; legacy a/b map to 1/2."""
+    match = _STACK_INPUT_PATTERN.match(name)
+    if not match:
+        return -1
+    letter, digits = match.group(1), match.group(2)
+    if digits is not None:
+        return int(digits)
+    return 1 if letter == "a" else 2
+
+
+class _LoraStackOptionalInputs:
+    """Lookup that preserves explicit optional inputs and dynamic lora_stack slots."""
+
+    def __init__(self, explicit_inputs: dict[str, tuple[str, dict[str, Any]]]) -> None:
+        self._explicit_inputs = explicit_inputs
+
+    def __contains__(self, item: object) -> bool:
+        if not isinstance(item, str):
+            return False
+        return item in self._explicit_inputs or _is_stack_input(item)
+
+    def __getitem__(self, key: str) -> tuple[str, dict[str, Any]]:
+        if key in self._explicit_inputs:
+            return self._explicit_inputs[key]
+        if _is_stack_input(key):
+            return (
+                "LORA_STACK",
+                {
+                    "tooltip": "A LoRA stack to combine. Connect to add more inputs.",
+                },
+            )
+        raise KeyError(key)
+
+
 class LoraStackCombinerLM:
    NAME = "Lora Stack Combiner (LoraManager)"
    CATEGORY = "Lora Manager/stackers"
+    DESCRIPTION = (
+        "Combines multiple LoRA stacks into a single stack. "
+        "Supports dynamic inputs: connect a stack to add more inputs."
+    )

    @classmethod
    def INPUT_TYPES(cls):
+        optional_inputs: dict[str, tuple[str, dict[str, Any]]] = {
+            "lora_stack1": (
+                "LORA_STACK",
+                {
+                    "tooltip": "A LoRA stack to combine. Connect to add more inputs.",
+                },
+            ),
+            "lora_stack2": (
+                "LORA_STACK",
+                {
+                    "tooltip": "A LoRA stack to combine. Connect to add more inputs.",
+                },
+            ),
+        }
+
+        stack = inspect.stack()
+        if len(stack) > 2 and stack[2].function == "get_input_info":
+            optional_inputs = _LoraStackOptionalInputs(optional_inputs)  # pyright: ignore[reportAssignmentType]
+
        return {
-            "required": {
-                "lora_stack_a": ("LORA_STACK",),
-                "lora_stack_b": ("LORA_STACK",),
-            },
+            "required": {},
+            "optional": optional_inputs,
        }

    RETURN_TYPES = ("LORA_STACK",)
    RETURN_NAMES = ("LORA_STACK",)
    FUNCTION = "combine_stacks"

-    def combine_stacks(self, lora_stack_a, lora_stack_b):
-        combined_stack = []
+    def combine_stacks(self, lora_stack1=None, lora_stack2=None, **kwargs):
+        stacks = {
+            "lora_stack1": lora_stack1,
+            "lora_stack2": lora_stack2,
+        }
+        for key, value in kwargs.items():
+            if _is_stack_input(key) and value is not None:
+                stacks[key] = value

-        if lora_stack_a:
-            combined_stack.extend(lora_stack_a)
-        if lora_stack_b:
-            combined_stack.extend(lora_stack_b)
+        combined_stack = []
+        for key in sorted(stacks, key=_stack_slot_number):
+            stack = stacks[key]
+            if stack:
+                combined_stack.extend(stack)

        return (combined_stack,)
@@ -1,6 +1,6 @@
 import os
 from ..utils.utils import get_lora_info
-from .utils import FlexibleOptionalInputType, any_type, extract_lora_name, get_loras_list
+from .utils import FlexibleOptionalInputType, any_type, apply_lora_syntax_format, extract_lora_name, get_loras_list, validate_lora_entries

 import logging

@@ -22,6 +22,11 @@ class LoraStackerLM:
            "optional": FlexibleOptionalInputType(any_type),
        }

+    @classmethod
+    def VALIDATE_INPUTS(cls, loras=None):
+        """Queue-time validation: reject missing local LoRAs before execution."""
+        return validate_lora_entries({"loras": loras}) or True
+
    RETURN_TYPES = ("LORA_STACK", "STRING", "STRING")
    RETURN_NAMES = ("LORA_STACK", "trigger_words", "active_loras")
    FUNCTION = "stack_loras"
@@ -48,7 +53,7 @@ class LoraStackerLM:
            if not lora.get('active', False):
                continue
                
-            lora_name = lora['name']
+            lora_name = apply_lora_syntax_format(lora['name'])
            model_strength = float(lora['strength'])
            # Get clip strength - use model strength as default if not specified
            clip_strength = float(lora.get('clipStrength', model_strength))
@@ -0,0 +1,62 @@
+"""Node to resolve `<lora:name:strength>` syntax to absolute file system paths.
+
+Takes the loaded_loras / active_loras STRING output from LoraLoaderLM or
+LoraStackerLM and resolves each lora name to its absolute path on disk via
+the scanner cache. Unknown names are returned as-is.
+"""
+
+import logging
+
+from ..utils.utils import get_lora_info_absolute
+from .utils import parse_lora_syntax
+
+logger = logging.getLogger(__name__)
+
+
+class LoraSyntaxToPath:
+    NAME = "LoRA Syntax → Path (LoraManager)"
+    CATEGORY = "Lora Manager/utils"
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "lora_syntax": (
+                    "STRING",
+                    {
+                        "forceInput": True,
+                        "multiline": True,
+                        "tooltip": (
+                            "<lora:name:strength> formatted text from "
+                            "loaded_loras / active_loras output"
+                        ),
+                    },
+                ),
+            },
+        }
+
+    RETURN_TYPES = ("STRING",)
+    RETURN_NAMES = ("paths",)
+    FUNCTION = "resolve"
+
+    def resolve(self, lora_syntax: str) -> tuple[str]:
+        """Parse <lora:...> syntax and resolve each name to its absolute path."""
+        if not lora_syntax or not lora_syntax.strip():
+            logger.info("Received empty lora_syntax input")
+            return ("",)
+
+        parsed = parse_lora_syntax(lora_syntax)
+        if not parsed:
+            logger.info("No valid <lora:...> entries found in input")
+            return ("",)
+
+        paths: list[str] = []
+        for entry in parsed:
+            try:
+                absolute_path, _ = get_lora_info_absolute(entry["name"])
+                paths.append(absolute_path)
+            except Exception:
+                logger.warning("Failed to resolve lora '%s', skipping", entry["name"])
+                continue
+
+        return ("\n".join(paths),)
@@ -0,0 +1,179 @@
+"""Metadata Overwrite node — allows users to manually specify generation parameters
+that override the automatically collected/inferred metadata.
+
+Most inputs have falsy defaults (empty string / 0) which are skipped.
+clip_skip uses a sentinel default (-25) so that a wired value of 0 is
+preserved — both ComfyUI and A1111 conventions have no meaningful 0 value,
+but users may wire 0 to express "no clip skip / default".
+"""
+
+from typing import Any
+
+from ..metadata_collector.constants import CLIP_SKIP_SENTINEL as _CLIP_SKIP_SENTINEL
+from ..metadata_collector.overwrite_utils import collect_overwrite_params
+
+
+class MetadataOverwriteLM:
+    NAME = "Metadata Overwrite (LoraManager)"
+    CATEGORY = "Lora Manager/utils"
+    DESCRIPTION = (
+        "Manually specify generation parameters to override automatically collected "
+        "metadata. Only filled/connected inputs will take effect — empty defaults "
+        "are ignored."
+    )
+
+    @classmethod
+    def INPUT_TYPES(cls) -> dict[str, Any]:
+        return {
+            "optional": {
+                "prompt": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": "Positive prompt. Only overwrites when non-empty.",
+                    },
+                ),
+                "negative_prompt": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": "Negative prompt. Only overwrites when non-empty.",
+                    },
+                ),
+                "seed": (
+                    "INT",
+                    {
+                        "default": 0,
+                        "min": 0,
+                        "max": 0xFFFFFFFFFFFFFFFF,
+                        "control_after_generate": False,
+                        "tooltip": "Seed value. Only overwrites when > 0.",
+                    },
+                ),
+                "steps": (
+                    "INT",
+                    {
+                        "default": 0,
+                        "min": 0,
+                        "max": 10000,
+                        "tooltip": "Number of steps. Only overwrites when > 0.",
+                    },
+                ),
+                "cfg_scale": (
+                    "FLOAT",
+                    {
+                        "default": 0.0,
+                        "min": 0.0,
+                        "max": 100.0,
+                        "tooltip": "CFG scale. Only overwrites when > 0.",
+                    },
+                ),
+                "sampler": (
+                    "STRING,SAMPLER",
+                    {
+                        "default": "",
+                        "widgetType": "STRING",
+                        "tooltip": (
+                            "Sampler name. Fill in the name manually or "
+                            "connect a SAMPLER output (e.g. KSamplerSelect) "
+                            "— the sampler name is then extracted "
+                            "automatically. Note: ddim is recorded as "
+                            "euler (ComfyUI internal representation). "
+                            "Only overwrites when non-empty."
+                        ),
+                    },
+                ),
+                "scheduler": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "tooltip": "Scheduler name. Only overwrites when non-empty.",
+                    },
+                ),
+                "model": (
+                    "STRING,MODEL",
+                    {
+                        "default": "",
+                        "widgetType": "STRING",
+                        "tooltip": (
+                            "The checkpoint or diffusion model (UNet) used "
+                            "for generation. Fill in the name manually or "
+                            "connect a MODEL output — the model name is then "
+                            "extracted automatically. Only overwrites when "
+                            "non-empty."
+                        ),
+                    },
+                ),
+                "loras": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": (
+                            "LoRA syntax, e.g. <lora:name:strength> "
+                            "or <lora:name:model_strength:clip_strength>, "
+                            "separated by spaces. Only overwrites when non-empty."
+                        ),
+                    },
+                ),
+                "size": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "tooltip": (
+                            "Image size in WIDTHxHEIGHT format (e.g. 512x768). "
+                            "Only overwrites when non-empty."
+                        ),
+                    },
+                ),
+                "clip_skip": (
+                    "INT",
+                    {
+                        "default": _CLIP_SKIP_SENTINEL,
+                        "min": -25,
+                        "max": 24,
+                        "tooltip": (
+                            "Clip skip (ComfyUI: -24..-1, A1111: 1+). "
+                            "Default -25 means not set — any other value "
+                            "overwrites."
+                        ),
+                    },
+                ),
+                "additional_data": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": (
+                            "Additional data to embed in the image metadata. "
+                            "Inserted between Clip skip and Model hash in the "
+                            "A1111-compatible parameters string. "
+                            'Example: "Copyright": "Some license info"'
+                        ),
+                    },
+                ),
+            },
+        }
+
+    RETURN_TYPES = ("METADATA",)
+    RETURN_NAMES = ("metadata",)
+    FUNCTION = "collect_metadata"
+    OUTPUT_NODE = True
+
+    def collect_metadata(self, **kwargs: Any) -> tuple[dict[str, Any]]:
+        """Collect non-default input values into a metadata dict.
+
+        For most fields, a falsy value (empty string, 0) means "not set"
+        and is skipped.  clip_skip uses a dedicated sentinel (-25) so that
+        a wired value of 0 is preserved and reaches the metadata pipeline.
+
+        The ``model`` field accepts either a manual string or a wired MODEL
+        (ModelPatcher) connection; in the latter case the underlying model
+        name is extracted from the patcher's ``cached_patcher_init`` and
+        stored as a ComfyUI-style relative path.  The ``sampler`` field
+        likewise accepts a manual string or a wired SAMPLER (KSAMPLER)
+        connection, from which the sampler name is extracted automatically.
+        """
+        return (collect_overwrite_params(kwargs),)
@@ -15,15 +15,15 @@ import os
 import re
 from collections import defaultdict
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, List, Optional, Tuple, Union, cast

-import comfy.utils  # type: ignore
-import folder_paths  # type: ignore
+import comfy.utils  # pyright: ignore[reportMissingImports]
+import folder_paths  # pyright: ignore[reportMissingImports]
 import torch
 import torch.nn as nn
 from safetensors import safe_open

-from nunchaku.lora.flux.nunchaku_converter import (
+from nunchaku.lora.flux.nunchaku_converter import (  # pyright: ignore[reportMissingTypeStubs]
    pack_lowrank_weight,
    unpack_lowrank_weight,
 )
@@ -87,10 +87,6 @@ def _rename_layer_underscore_layer_name(old_name: str) -> str:
    return new_name


-def _is_indexable_module(module):
-    return isinstance(module, (nn.ModuleList, nn.Sequential, list, tuple))
-
-
 def _get_module_by_name(model: nn.Module, name: str) -> Optional[nn.Module]:
    if not name:
        return model
@@ -100,7 +96,7 @@ def _get_module_by_name(model: nn.Module, name: str) -> Optional[nn.Module]:
            continue
        if hasattr(module, part):
            module = getattr(module, part)
-        elif part.isdigit() and _is_indexable_module(module):
+        elif part.isdigit() and isinstance(module, (nn.ModuleList, nn.Sequential, list, tuple)):
            try:
                module = module[int(part)]
            except (IndexError, TypeError):
@@ -267,7 +263,9 @@ def _handle_proj_out_split(lora_dict: Dict[str, Dict[str, torch.Tensor]], base_k
    return result, consumed


-def _apply_lora_to_module(module: nn.Module, a_tensor: torch.Tensor, b_tensor: torch.Tensor, module_name: str, model: nn.Module) -> None:
+def _apply_lora_to_module(module: Any, a_tensor: torch.Tensor, b_tensor: torch.Tensor, module_name: str, model: Any) -> None:
+    # These modules are dynamic torch containers; monkey-patched attributes
+    # below are set at runtime, so the module/model types are deliberately Any.
    if not hasattr(module, "in_features") or not hasattr(module, "out_features"):
        raise ValueError(f"{module_name}: unsupported module without in/out features")
    if a_tensor.shape[1] != module.in_features or b_tensor.shape[0] != module.out_features:
@@ -336,7 +334,7 @@ def _apply_lora_to_module(module: nn.Module, a_tensor: torch.Tensor, b_tensor: t
    raise ValueError(f"{module_name}: unsupported module type {type(module)}")


-def reset_lora_v2(model: nn.Module) -> None:
+def reset_lora_v2(model: Any) -> None:
    slots = getattr(model, "_lora_slots", None)
    if not slots:
        return
@@ -344,6 +342,7 @@ def reset_lora_v2(model: nn.Module) -> None:
        module = _get_module_by_name(model, name)
        if module is None:
            continue
+        module = cast(Any, module)
        module_type = info.get("type", "nunchaku")
        if module_type == "nunchaku":
            base_rank = info["base_rank"]
@@ -371,7 +370,7 @@ def reset_lora_v2(model: nn.Module) -> None:
 def compose_loras_v2(model: nn.Module, lora_configs: List[Tuple[Union[str, Path, Dict[str, torch.Tensor]], float]], apply_awq_mod: bool = True) -> bool:
    del apply_awq_mod  # retained for interface compatibility
    reset_lora_v2(model)
-    aggregated_weights: Dict[str, List[Dict[str, object]]] = defaultdict(list)
+    aggregated_weights: Dict[str, List[Dict[str, Any]]] = defaultdict(list)
    saw_supported_format = False
    unresolved_targets = 0

@@ -471,7 +470,7 @@ def compose_loras_v2(model: nn.Module, lora_configs: List[Tuple[Union[str, Path,
 class ComfyQwenImageWrapperLM(nn.Module):
    def __init__(self, model: nn.Module, config=None, apply_awq_mod: bool = True):
        super().__init__()
-        self.model = model
+        self.model: Any = model
        self.config = {} if config is None else config
        self.dtype = next(model.parameters()).dtype
        self.loras: List[Tuple[Union[str, Path, Dict[str, torch.Tensor]], float]] = []
@@ -67,7 +67,7 @@ class PromptLM:

        stack = inspect.stack()
        if len(stack) > 2 and stack[2].function == "get_input_info":
-            optional_inputs = _PromptOptionalInputs(optional_inputs)  # type: ignore[assignment]
+            optional_inputs = _PromptOptionalInputs(optional_inputs)  # pyright: ignore[reportAssignmentType]

        return {
            "required": {
@@ -126,7 +126,7 @@ class PromptLM:
        else:
            prompt = expanded_text

-        from nodes import CLIPTextEncode  # type: ignore
+        from nodes import CLIPTextEncode  # pyright: ignore[reportMissingImports, reportAttributeAccessIssue]

        conditioning = CLIPTextEncode().encode(clip, prompt)[0]
        return (conditioning, prompt)
@@ -0,0 +1,214 @@
+import logging
+import os
+import random
+from typing import Any, List, Optional, Tuple
+import comfy.sd  # pyright: ignore[reportMissingImports]
+import folder_paths  # pyright: ignore[reportMissingImports]
+from ..utils.utils import get_checkpoint_info_absolute, _format_model_name_for_comfyui
+
+logger = logging.getLogger(__name__)
+
+
+class RandomCheckpointLoaderLM:
+    """Checkpoint Loader that can randomly pick a checkpoint from the pool
+
+    Loads checkpoints from both standard ComfyUI folders and LoRA Manager's
+    extra folder paths. When select_at_random is enabled, ignores ckpt_name
+    and picks a random checkpoint (optionally filtered by base_model) on
+    every run.
+    """
+
+    NAME = "Random Checkpoint Loader (LoraManager)"
+    CATEGORY = "Lora Manager/loaders"
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        # Get list of checkpoint names from scanner (includes extra folder paths)
+        checkpoint_names = cls._get_checkpoint_names()
+        base_models = cls._get_available_base_models()
+        return {
+            "required": {
+                "ckpt_name": (
+                    checkpoint_names,
+                    {"tooltip": "The name of the checkpoint (model) to load."},
+                ),
+                "select_at_random": (
+                    "BOOLEAN",
+                    {
+                        "default": False,
+                        "tooltip": (
+                            "Ignore ckpt_name and pick a random checkpoint from the "
+                            "pool (optionally filtered by base_model) on every run."
+                        ),
+                    },
+                ),
+                "base_model": (
+                    base_models,
+                    {
+                        "default": "Any",
+                        "tooltip": "Restrict random selection to this base model. 'Any' uses the full pool.",
+                    },
+                ),
+            }
+        }
+
+    RETURN_TYPES = ("MODEL", "CLIP", "VAE", "STRING")
+    RETURN_NAMES = ("MODEL", "CLIP", "VAE", "model_name")
+    OUTPUT_TOOLTIPS = (
+        "The model used for denoising latents.",
+        "The CLIP model used for encoding text prompts.",
+        "The VAE model used for encoding and decoding images to and from latent space.",
+        "The name of the checkpoint that was loaded (useful when select_at_random is enabled).",
+    )
+    FUNCTION = "load_checkpoint"
+
+    @classmethod
+    def IS_CHANGED(cls, ckpt_name, select_at_random=False, base_model="Any"):
+        # Force re-execution on every run while randomizing, since the widget
+        # values themselves don't change between queue runs.
+        if select_at_random:
+            return float("nan")
+        return ckpt_name
+
+    @staticmethod
+    def _run_async(coro_fn):
+        """Run an async fetcher, handling the case where an event loop is already running."""
+        import asyncio
+
+        try:
+            asyncio.get_running_loop()
+            import concurrent.futures
+
+            def run_in_thread():
+                new_loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(new_loop)
+                try:
+                    return new_loop.run_until_complete(coro_fn())
+                finally:
+                    new_loop.close()
+
+            with concurrent.futures.ThreadPoolExecutor() as executor:
+                future = executor.submit(run_in_thread)
+                return future.result()
+        except RuntimeError:
+            return asyncio.run(coro_fn())
+
+    @classmethod
+    def _get_checkpoint_names(cls, base_model: Optional[str] = None) -> List[str]:
+        """Get list of checkpoint names from scanner cache in ComfyUI format (relative path with extension)
+
+        Args:
+            base_model: If given (and not "Any"), only include checkpoints matching this base model.
+        """
+        try:
+            from ..services.service_registry import ServiceRegistry
+
+            async def _get_names():
+                scanner = await ServiceRegistry.get_checkpoint_scanner()
+                cache = await scanner.get_cached_data()
+
+                # Get all model roots for calculating relative paths
+                model_roots = scanner.get_model_roots()
+
+                # Filter only checkpoint type (not diffusion_model) and format names
+                names = []
+                for item in cache.raw_data:
+                    if item.get("sub_type") != "checkpoint":
+                        continue
+                    if (
+                        base_model
+                        and base_model != "Any"
+                        and item.get("base_model") != base_model
+                    ):
+                        continue
+                    file_path = item.get("file_path", "")
+                    # Only offer models that still exist on disk so ComfyUI
+                    # flags missing checkpoints at queue time via
+                    # "value not in list" (the scanner cache can be stale).
+                    if file_path and os.path.exists(file_path):
+                        # Format using relative path with OS-native separator
+                        formatted_name = _format_model_name_for_comfyui(
+                            file_path, model_roots
+                        )
+                        if formatted_name:
+                            names.append(formatted_name)
+
+                return sorted(names)
+
+            return cls._run_async(_get_names)
+        except Exception as e:
+            logger.error(f"Error getting checkpoint names: {e}")
+            return []
+
+    @classmethod
+    def _get_available_base_models(cls) -> List[str]:
+        """Get distinct base_model values present among indexed checkpoints, for the random-selection filter."""
+        try:
+            from ..services.service_registry import ServiceRegistry
+
+            async def _get_base_models():
+                scanner = await ServiceRegistry.get_checkpoint_scanner()
+                cache = await scanner.get_cached_data()
+
+                base_models = set()
+                for item in cache.raw_data:
+                    if item.get("sub_type") != "checkpoint":
+                        continue
+                    base_model = item.get("base_model")
+                    file_path = item.get("file_path", "")
+                    if base_model and file_path and os.path.exists(file_path):
+                        base_models.add(base_model)
+
+                return sorted(base_models)
+
+            return ["Any"] + cls._run_async(_get_base_models)
+        except Exception as e:
+            logger.error(f"Error getting available base models: {e}")
+            return ["Any"]
+
+    def load_checkpoint(
+        self,
+        ckpt_name: str,
+        select_at_random: bool = False,
+        base_model: str = "Any",
+    ) -> Tuple[Any, Any, Any, str]:
+        """Load a checkpoint by name, supporting extra folder paths
+
+        Args:
+            ckpt_name: The name of the checkpoint to load (relative path with extension)
+            select_at_random: If True, ignore ckpt_name and pick randomly from the pool
+            base_model: Restricts random selection to this base model ("Any" = no filter)
+
+        Returns:
+            Tuple of (MODEL, CLIP, VAE, model_name)
+        """
+        if select_at_random:
+            pool = self._get_checkpoint_names(base_model)
+            if not pool:
+                raise FileNotFoundError(
+                    f"No checkpoints found for base model '{base_model}'. "
+                    "Pick a different base model or disable 'select_at_random'."
+                )
+            ckpt_name = random.choice(pool)
+            logger.info(
+                f"[RandomCheckpointLoaderLM] Randomly selected checkpoint: {ckpt_name}"
+            )
+
+        # Get absolute path from cache using ComfyUI-style name
+        ckpt_path, metadata = get_checkpoint_info_absolute(ckpt_name)
+
+        if metadata is None:
+            raise FileNotFoundError(
+                f"Checkpoint '{ckpt_name}' not found in LoRA Manager cache. "
+                "Make sure the checkpoint is indexed and try again."
+            )
+
+        # Load regular checkpoint using ComfyUI's API
+        logger.info(f"Loading checkpoint from: {ckpt_path}")
+        out = comfy.sd.load_checkpoint_guess_config(
+            ckpt_path,
+            output_vae=True,
+            output_clip=True,
+            embedding_directory=folder_paths.get_folder_paths("embeddings"),
+        )
+        return out[:3] + (ckpt_name,)
@@ -0,0 +1,326 @@
+import logging
+import os
+import random
+from typing import Any, List, Optional, Tuple
+import comfy.sd  # pyright: ignore[reportMissingImports]
+from ..utils.utils import get_checkpoint_info_absolute, _format_model_name_for_comfyui
+
+logger = logging.getLogger(__name__)
+
+
+def _reload_gguf_unet(
+    unet_path: str, weight_dtype: str, disable_dynamic: bool = False
+) -> object:
+    """Reload a GGUF diffusion model from disk (cached_patcher_init factory).
+
+    Mirrors the GGUF branch of RandomUNETLoaderLM.load_unet so ModelPatcher
+    deepclone/dynamic machinery can rebuild GGUF models with the correct
+    GGMLOps. ``disable_dynamic`` is accepted for signature compatibility
+    with core ComfyUI loaders.
+    """
+    loader = RandomUNETLoaderLM()
+    model, _unet_name = loader._load_gguf_unet(unet_path, unet_path, weight_dtype)
+    return model
+
+
+class RandomUNETLoaderLM:
+    """UNET Loader that can randomly pick a diffusion model from the pool
+
+    Loads diffusion models/UNets from both standard ComfyUI folders and LoRA
+    Manager's extra folder paths. Supports both regular diffusion models and
+    GGUF format models. When select_at_random is enabled, ignores unet_name
+    and picks a random diffusion model (optionally filtered by base_model)
+    on every run.
+    """
+
+    NAME = "Random Unet Loader (LoraManager)"
+    CATEGORY = "Lora Manager/loaders"
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        # Get list of unet names from scanner (includes extra folder paths)
+        unet_names = cls._get_unet_names()
+        base_models = cls._get_available_base_models()
+        return {
+            "required": {
+                "unet_name": (
+                    unet_names,
+                    {"tooltip": "The name of the diffusion model to load."},
+                ),
+                "weight_dtype": (
+                    ["default", "fp8_e4m3fn", "fp8_e4m3fn_fast", "fp8_e5m2"],
+                    {"tooltip": "The dtype to use for the model weights."},
+                ),
+                "select_at_random": (
+                    "BOOLEAN",
+                    {
+                        "default": False,
+                        "tooltip": (
+                            "Ignore unet_name and pick a random diffusion model from "
+                            "the pool (optionally filtered by base_model) on every run."
+                        ),
+                    },
+                ),
+                "base_model": (
+                    base_models,
+                    {
+                        "default": "Any",
+                        "tooltip": "Restrict random selection to this base model. 'Any' uses the full pool.",
+                    },
+                ),
+            }
+        }
+
+    RETURN_TYPES = ("MODEL", "STRING")
+    RETURN_NAMES = ("MODEL", "model_name")
+    OUTPUT_TOOLTIPS = (
+        "The model used for denoising latents.",
+        "The name of the diffusion model that was loaded (useful when select_at_random is enabled).",
+    )
+    FUNCTION = "load_unet"
+
+    @classmethod
+    def IS_CHANGED(
+        cls, unet_name, weight_dtype, select_at_random=False, base_model="Any"
+    ):
+        # Force re-execution on every run while randomizing, since the widget
+        # values themselves don't change between queue runs.
+        if select_at_random:
+            return float("nan")
+        return unet_name
+
+    @staticmethod
+    def _run_async(coro_fn):
+        """Run an async fetcher, handling the case where an event loop is already running."""
+        import asyncio
+
+        try:
+            asyncio.get_running_loop()
+            import concurrent.futures
+
+            def run_in_thread():
+                new_loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(new_loop)
+                try:
+                    return new_loop.run_until_complete(coro_fn())
+                finally:
+                    new_loop.close()
+
+            with concurrent.futures.ThreadPoolExecutor() as executor:
+                future = executor.submit(run_in_thread)
+                return future.result()
+        except RuntimeError:
+            return asyncio.run(coro_fn())
+
+    @classmethod
+    def _get_unet_names(cls, base_model: Optional[str] = None) -> List[str]:
+        """Get list of diffusion model names from scanner cache in ComfyUI format (relative path with extension)
+
+        Args:
+            base_model: If given (and not "Any"), only include models matching this base model.
+        """
+        try:
+            from ..services.service_registry import ServiceRegistry
+
+            async def _get_names():
+                scanner = await ServiceRegistry.get_checkpoint_scanner()
+                cache = await scanner.get_cached_data()
+
+                # Get all model roots for calculating relative paths
+                model_roots = scanner.get_model_roots()
+
+                # Filter only diffusion_model type and format names
+                names = []
+                for item in cache.raw_data:
+                    if item.get("sub_type") != "diffusion_model":
+                        continue
+                    if (
+                        base_model
+                        and base_model != "Any"
+                        and item.get("base_model") != base_model
+                    ):
+                        continue
+                    file_path = item.get("file_path", "")
+                    # Only offer models that still exist on disk so ComfyUI
+                    # flags missing diffusion models at queue time via
+                    # "value not in list" (the scanner cache can be stale).
+                    if file_path and os.path.exists(file_path):
+                        # Format using relative path with OS-native separator
+                        formatted_name = _format_model_name_for_comfyui(
+                            file_path, model_roots
+                        )
+                        if formatted_name:
+                            names.append(formatted_name)
+
+                return sorted(names)
+
+            return cls._run_async(_get_names)
+        except Exception as e:
+            logger.error(f"Error getting unet names: {e}")
+            return []
+
+    @classmethod
+    def _get_available_base_models(cls) -> List[str]:
+        """Get distinct base_model values present among indexed diffusion models, for the random-selection filter."""
+        try:
+            from ..services.service_registry import ServiceRegistry
+
+            async def _get_base_models():
+                scanner = await ServiceRegistry.get_checkpoint_scanner()
+                cache = await scanner.get_cached_data()
+
+                base_models = set()
+                for item in cache.raw_data:
+                    if item.get("sub_type") != "diffusion_model":
+                        continue
+                    base_model = item.get("base_model")
+                    file_path = item.get("file_path", "")
+                    if base_model and file_path and os.path.exists(file_path):
+                        base_models.add(base_model)
+
+                return sorted(base_models)
+
+            return ["Any"] + cls._run_async(_get_base_models)
+        except Exception as e:
+            logger.error(f"Error getting available base models: {e}")
+            return ["Any"]
+
+    def load_unet(
+        self,
+        unet_name: str,
+        weight_dtype: str,
+        select_at_random: bool = False,
+        base_model: str = "Any",
+    ) -> Tuple[Any, ...]:
+        """Load a diffusion model by name, supporting extra folder paths
+
+        Args:
+            unet_name: The name of the diffusion model to load (relative path with extension)
+            weight_dtype: The dtype to use for model weights
+            select_at_random: If True, ignore unet_name and pick randomly from the pool
+            base_model: Restricts random selection to this base model ("Any" = no filter)
+
+        Returns:
+            Tuple of (MODEL, model_name)
+        """
+        import torch
+
+        if select_at_random:
+            pool = self._get_unet_names(base_model)
+            if not pool:
+                raise FileNotFoundError(
+                    f"No diffusion models found for base model '{base_model}'. "
+                    "Pick a different base model or disable 'select_at_random'."
+                )
+            unet_name = random.choice(pool)
+            logger.info(
+                f"[RandomUNETLoaderLM] Randomly selected diffusion model: {unet_name}"
+            )
+
+        # Get absolute path from cache using ComfyUI-style name
+        unet_path, metadata = get_checkpoint_info_absolute(unet_name)
+
+        if metadata is None:
+            raise FileNotFoundError(
+                f"Diffusion model '{unet_name}' not found in LoRA Manager cache. "
+                "Make sure the model is indexed and try again."
+            )
+
+        # Check if it's a GGUF model
+        if unet_path.endswith(".gguf"):
+            return self._load_gguf_unet(unet_path, unet_name, weight_dtype)
+
+        # Load regular diffusion model using ComfyUI's API
+        logger.info(f"Loading diffusion model from: {unet_path}")
+
+        # Build model options based on weight_dtype
+        model_options = {}
+        if weight_dtype == "fp8_e4m3fn":
+            model_options["dtype"] = torch.float8_e4m3fn
+        elif weight_dtype == "fp8_e4m3fn_fast":
+            model_options["dtype"] = torch.float8_e4m3fn
+            model_options["fp8_optimizations"] = True
+        elif weight_dtype == "fp8_e5m2":
+            model_options["dtype"] = torch.float8_e5m2
+
+        model = comfy.sd.load_diffusion_model(unet_path, model_options=model_options)
+        return (model, unet_name)
+
+    def _load_gguf_unet(
+        self, unet_path: str, unet_name: str, weight_dtype: str
+    ) -> Tuple[Any, ...]:
+        """Load a GGUF format diffusion model
+
+        Args:
+            unet_path: Absolute path to the GGUF file
+            unet_name: Name of the model for error messages
+            weight_dtype: The dtype to use for model weights
+
+        Returns:
+            Tuple of (MODEL, model_name)
+        """
+        import torch
+        from .gguf_import_helper import get_gguf_modules
+
+        # Get ComfyUI-GGUF modules using helper (handles various import scenarios)
+        try:
+            loader_module, ops_module, nodes_module = get_gguf_modules()
+            gguf_sd_loader = getattr(loader_module, "gguf_sd_loader")
+            GGMLOps = getattr(ops_module, "GGMLOps")
+            GGUFModelPatcher = getattr(nodes_module, "GGUFModelPatcher")
+        except RuntimeError as e:
+            raise RuntimeError(f"Cannot load GGUF model '{unet_name}'. {str(e)}")
+
+        logger.info(f"Loading GGUF diffusion model from: {unet_path}")
+
+        try:
+            # Load GGUF state dict
+            sd, extra = gguf_sd_loader(unet_path)
+
+            # Prepare kwargs for metadata if supported
+            kwargs = {}
+            import inspect
+
+            valid_params = inspect.signature(
+                comfy.sd.load_diffusion_model_state_dict
+            ).parameters
+            if "metadata" in valid_params:
+                kwargs["metadata"] = extra.get("metadata", {})
+
+            # Setup custom operations with GGUF support
+            ops = GGMLOps()
+
+            # Handle weight_dtype for GGUF models
+            if weight_dtype in ("default", None):
+                ops.Linear.dequant_dtype = None
+            elif weight_dtype in ["target"]:
+                ops.Linear.dequant_dtype = weight_dtype
+            else:
+                ops.Linear.dequant_dtype = getattr(torch, weight_dtype, None)
+
+            # Load the model
+            model = comfy.sd.load_diffusion_model_state_dict(
+                sd, model_options={"custom_operations": ops}, **kwargs
+            )
+
+            if model is None:
+                raise RuntimeError(
+                    f"Could not detect model type for GGUF diffusion model: {unet_path}"
+                )
+
+            # Wrap with GGUFModelPatcher
+            model = GGUFModelPatcher.clone(model)
+
+            # Register a reload factory so the MODEL carries its source path
+            # (cached_patcher_init) like core ComfyUI loaders do — required
+            # for model-name extraction downstream and for ModelPatcher
+            # deepclone/dynamic machinery.
+            model.cached_patcher_init = (_reload_gguf_unet, (unet_path, weight_dtype))
+
+            return (model, unet_name)
+
+        except Exception as e:
+            logger.error(f"Error loading GGUF diffusion model '{unet_name}': {e}")
+            raise RuntimeError(
+                f"Failed to load GGUF diffusion model '{unet_name}': {str(e)}"
+            )
@@ -1,16 +1,171 @@
 import json
 import os
 import re
+import time
+import uuid
 from typing import Any, Dict, Optional
 import numpy as np
-import folder_paths  # type: ignore
+import folder_paths  # pyright: ignore[reportMissingImports]
 from ..services.service_registry import ServiceRegistry
 from ..metadata_collector.metadata_processor import MetadataProcessor
 from ..metadata_collector import get_metadata
+from ..utils.constants import CARD_PREVIEW_WIDTH
+from ..utils.exif_utils import ExifUtils
+from ..utils.utils import calculate_recipe_fingerprint, sanitize_folder_name
 from PIL import Image, PngImagePlugin
-import piexif
+import piexif  # pyright: ignore[reportMissingTypeStubs]
 import logging

+# Civitai-compatible sampler name mapping: ComfyUI internal → A1111 display name
+CIVITAI_SAMPLER_MAP = {
+    "euler": "Euler",
+    "euler_ancestral": "Euler a",
+    "lms": "LMS",
+    "heun": "Heun",
+    "dpm_2": "DPM2",
+    "dpm_2_ancestral": "DPM2 a",
+    "dpmpp_2s_ancestral": "DPM++ 2S a",
+    "dpmpp_2m": "DPM++ 2M",
+    "dpmpp_sde": "DPM++ SDE",
+    "dpmpp_sde_gpu": "DPM++ SDE",
+    "dpmpp_2m_sde": "DPM++ 2M SDE",
+    "dpmpp_2m_sde_gpu": "DPM++ 2M SDE",
+    "dpmpp_3m_sde": "DPM++ 3M SDE",
+    "dpm_fast": "DPM fast",
+    "dpm_adaptive": "DPM adaptive",
+    "ddim": "DDIM",
+    "plms": "PLMS",
+    "uni_pc_bh2": "UniPC",
+    "uni_pc": "UniPC",
+    "lcm": "LCM",
+}
+
+# Base model display name → AIR URN slug
+# Sourced from civitai source: src/shared/constants/basemodel.constants.ts
+BASE_MODEL_AIR_SLUG = {
+    # Stable Diffusion family
+    "SD 1.4": "sd1",
+    "SD 1.5": "sd1",
+    "SD 1.5 LCM": "sd1",
+    "SD 1.5 Hyper": "sd1",
+    "SD 2.0": "sd2",
+    "SD 2.0 768": "sd2",
+    "SD 2.1": "sd2",
+    "SD 2.1 768": "sd2",
+    "SD 2.1 Unclip": "sd2",
+    "SD 3.0": "sd3",
+    "SD 3.5": "sd35",
+    "SD 3.5 Large": "sd35",
+    "SD 3.5 Large Turbo": "sd35",
+    "SD 3.5 Medium": "sd35",
+    "SDXL 0.9": "sdxl",
+    "SDXL 1.0": "sdxl",
+    "SDXL 1.0 LCM": "sdxl",
+    "SDXL Lightning": "sdxl",
+    "SDXL Hyper": "sdxl",
+    "SDXL Turbo": "sdxl",
+    "SDXL Distilled": "sdxldistilled",
+    "Stable Cascade": "scascade",
+    "Stable Video Diffusion": "svd",
+    "SVD": "svd",
+    "SVD XT": "svdxt",
+
+    # SDXL community fine-tunes
+    "Pony": "pony",
+    "Pony Diffusion": "pony",
+    "Illustrious": "illustrious",
+    "NoobAI": "noobai",
+    "Animagine": "illustrious",
+
+    # Flux family
+    "Flux.1": "flux1",
+    "Flux.1 D": "flux1",
+    "Flux.1 S": "flux1",
+    "Flux.1 Krea": "fluxkrea",
+    "Flux.1 Kontext": "flux1kontext",
+    "Flux.2": "flux2",
+    "Flux.2 D": "flux2",
+    "Flux.2 Klein 9B": "flux2klein_9b",
+    "Flux.2 Klein 9B Base": "flux2klein_9b_base",
+    "Flux.2 Klein 4B": "flux2klein_4b",
+    "Flux.2 Klein 4B Base": "flux2klein_4b_base",
+
+    # Other image models (sorted alphabetically)
+    "AuraFlow": "auraflow",
+    "Chroma": "chroma",
+    "HiDream": "hidream",
+    "HiDream-O1": "hidream-o1",
+    "Hunyuan DiT": "hydit1",
+    "Hunyuan Video": "hyv1",
+    "Kolors": "kolors",
+    "Lumina": "lumina",
+    "Mochi": "mochi",
+    "ODOR": "odor",
+    "PixArt Alpha": "pixarta",
+    "PixArt Sigma": "pixarte",
+    "Playground v2": "playgroundv2",
+    "Playground v2.5": "playgroundv2",
+    "Pony Diffusion V7": "ponyv7",
+
+    # Video models
+    "CogVideoX": "cogvideox",
+    "LTX Video": "ltxv",
+    "LTX Video 2": "ltxv2",
+    "LTX Video 2.3": "ltxv23",
+    "Wan Video": "wanvideo",
+    "Wan Video 1.3B T2V": "wanvideo_13b_t2v",
+    "Wan Video 14B T2V": "wanvideo_14b_t2v",
+    "Wan Video 14B I2V 480p": "wanvideo_14b_i2v_480p",
+    "Wan Video 14B I2V 720p": "wanvideo_14b_i2v_720p",
+
+    # Third-party / proprietary image models
+    "Boogu": "boogu",
+    "Ernie": "ernie",
+    "Grok": "grok",
+    "HappyHorse": "happyhorse",
+    "Ideogram": "ideogram",
+    "Ideogram 4.0": "ideogram",
+    "Imagen": "imagen4",
+    "Imagen 4": "imagen4",
+    "Krea": "krea2",
+    "Krea 2": "krea2",
+    "Lens": "lens",
+    "MAI": "mai",
+    "Nano Banana": "nanobanana",
+    "OpenAI": "openai",
+    "Reve": "reve",
+    "Reve 2": "reve",
+    "Reve 2.1": "reve",
+    "Seedream": "seedream",
+    "Sora": "sora2",
+    "Sora 2": "sora2",
+    "Veo": "veo3",
+    "Veo 2": "veo3",
+    "Veo 3": "veo3",
+    "ZImageTurbo": "zimageturbo",
+    "ZImageBase": "zimagebase",
+    "ZImage": "zimagebase",
+
+    # Third-party video models
+    "Hailuo by MiniMax": "minimax",
+    "Haiper": "haiper",
+    "Kling": "kling",
+    "Lightricks": "lightricks",
+    "Seedance": "seedance",
+    "Vidu": "vidu",
+
+    # Qwen family
+    "Qwen": "qwen",
+    "Qwen 2": "qwen2",
+
+    # Anima
+    "Anima": "anima",
+
+    # Special
+    "Upscaler": "upscaler",
+    "Other": "other",
+}
+
 logger = logging.getLogger(__name__)


@@ -65,11 +220,29 @@ class SaveImageLM:
                        "tooltip": "Compression quality for JPEG and lossy WebP formats (1-100). Higher values mean better quality but larger files.",
                    },
                ),
+                "webp_method": (
+                    "INT",
+                    {
+                        "default": 6,
+                        "min": 0,
+                        "max": 6,
+                        "tooltip": "WebP compression method (0-6). 0=fastest/largest, 6=slowest/smallest. Only applies when file_format is 'webp'.",
+                    },
+                ),
+                "jpeg_subsampling": (
+                    "INT",
+                    {
+                        "default": 0,
+                        "min": 0,
+                        "max": 2,
+                        "tooltip": "JPEG chroma subsampling level. 0=4:4:4 (best quality), 1=4:2:2, 2=4:2:0 (smallest files). Only applies when file_format is 'jpeg'.",
+                    },
+                ),
                "embed_workflow": (
                    "BOOLEAN",
                    {
                        "default": False,
-                        "tooltip": "Embeds the complete workflow data into the image metadata. Only works with PNG and WebP formats.",
+                        "tooltip": "When enabled, saved images store the complete workflow. Drag the image back into ComfyUI to restore the original node graph. PNG and WebP only.",
                    },
                ),
                "save_with_metadata": (
@@ -79,6 +252,13 @@ class SaveImageLM:
                        "tooltip": "When enabled, embeds generation parameters into the saved image metadata. Disable to skip writing generation metadata.",
                    },
                ),
+                "add_loras_to_prompt": (
+                    "BOOLEAN",
+                    {
+                        "default": False,
+                        "tooltip": "When enabled, appends the LoRA syntax line (e.g. <lora:name:strength>) after the positive prompt in the saved metadata.",
+                    },
+                ),
                "add_counter_to_filename": (
                    "BOOLEAN",
                    {
@@ -86,6 +266,13 @@ class SaveImageLM:
                        "tooltip": "Adds an incremental counter to filenames to prevent overwriting previous images.",
                    },
                ),
+                "save_as_recipe": (
+                    "BOOLEAN",
+                    {
+                        "default": False,
+                        "tooltip": "Also saves each generated image as a LoRA Manager recipe.",
+                    },
+                ),
            },
            "hidden": {
                "id": "UNIQUE_ID",
@@ -130,148 +317,197 @@ class SaveImageLM:

        return None

-    def format_metadata(self, metadata_dict):
-        """Format metadata in the requested format similar to userComment example"""
-        if not metadata_dict:
-            return ""
+    def _resolve_model_cache_entry(self, scanner_type: str, name: str):
+        """Resolve model hash, civitai metadata, and base_model from scanner cache.
+        Returns (hash_str, civitai_dict, base_model_str). All values are empty defaults when not found."""
+        scanner = ServiceRegistry.get_service_sync(scanner_type)
+        if scanner is None or not name:
+            return "", {}, ""

-        # Helper function to only add parameter if value is not None
-        def add_param_if_not_none(param_list, label, value):
-            if value is not None:
-                param_list.append(f"{label}: {value}")
+        entry = self._get_cached_model_by_name(scanner, name)
+        if entry is None:
+            basename = os.path.splitext(os.path.basename(name))[0]
+            hash_val = scanner.get_hash_by_filename(basename)
+            return (hash_val or "").lower(), {}, ""
+
+        hash_val = (entry.get("sha256") or "").lower()
+        civitai = entry.get("civitai") or {}
+        base_model = entry.get("base_model") or ""
+        return hash_val, civitai, base_model
+
+    @staticmethod
+    def _get_civitai_sampler_name(sampler_name: str, scheduler: str) -> str:
+        if sampler_name in CIVITAI_SAMPLER_MAP:
+            civitai_name = CIVITAI_SAMPLER_MAP[sampler_name]
+            if scheduler == "karras":
+                civitai_name += " Karras"
+            elif scheduler == "exponential":
+                civitai_name += " Exponential"
+            return civitai_name
+        else:
+            if scheduler and scheduler != "normal":
+                return f"{sampler_name}_{scheduler}"
+            return sampler_name
+
+    @staticmethod
+    def _build_air_string(base_model: str, model_type: str, model_id: int, version_id: int) -> str:
+        slug = BASE_MODEL_AIR_SLUG.get(base_model, "other")
+        type_lower = model_type.lower() if model_type else "other"
+        return f"urn:air:{slug}:{type_lower}:civitai:{model_id}@{version_id}"
+
+    def format_metadata(self, metadata_dict: dict[str, Any], add_loras_to_prompt: bool = False) -> str:
+        """Format metadata as A1111-compatible parameters string with Hashes JSON and Civitai resources."""
+        if not metadata_dict: return ""

-        # Extract the prompt and negative prompt
        prompt = metadata_dict.get("prompt", "")
        negative_prompt = metadata_dict.get("negative_prompt", "")
-
-        # Extract loras from the prompt if present
+        steps = metadata_dict.get("steps")
+        cfg = metadata_dict.get("guidance")
+        if cfg is None:
+            cfg = metadata_dict.get("cfg_scale")
+        if cfg is None:
+            cfg = metadata_dict.get("cfg")
+        seed = metadata_dict.get("seed")
+        size = metadata_dict.get("size")
+        sampler = metadata_dict.get("sampler") or ""
+        scheduler = metadata_dict.get("scheduler") or "normal"
+        checkpoint = metadata_dict.get("checkpoint") or ""
        loras_text = metadata_dict.get("loras", "")
-        lora_hashes = {}
+        clip_skip = metadata_dict.get("clip_skip")

-        # If loras are found, add them on a new line after the prompt
+        # Parse LoRA entries from <lora:name:strength> format
+        lora_entries: list[tuple[str, float]] = []
        if loras_text:
-            prompt_with_loras = f"{prompt}\n{loras_text}"
+            for match in re.findall(r"<lora:([^:]+):([^>]+)>", loras_text):
+                lora_name, strength_str = match
+                try:
+                    strength = float(strength_str)
+                except (ValueError, TypeError):
+                    strength = 1.0
+                lora_entries.append((lora_name, strength))

-            # Extract lora names from the format <lora:name:strength>
-            lora_matches = re.findall(r"<lora:([^:]+):([^>]+)>", loras_text)
+        # Resolve checkpoint hash and Civitai data from local cache
+        ckpt_hash, ckpt_civitai, ckpt_base_model = "", {}, ""
+        ckpt_display_name = ""
+        if checkpoint:
+            ckpt_hash, ckpt_civitai, ckpt_base_model = self._resolve_model_cache_entry(
+                "checkpoint_scanner", checkpoint
+            )
+            ckpt_display_name = os.path.splitext(os.path.basename(checkpoint))[0]

-            # Get hash for each lora
-            for lora_name, strength in lora_matches:
-                hash_value = self.get_lora_hash(lora_name)
-                if hash_value:
-                    lora_hashes[lora_name] = hash_value
-        else:
-            prompt_with_loras = prompt
+        # Resolve LoRA hash and Civitai data from local cache
+        loras_data: list[dict[str, Any]] = []
+        for lora_name, strength in lora_entries:
+            lora_hash, lora_civitai, lora_base_model = self._resolve_model_cache_entry(
+                "lora_scanner", lora_name
+            )
+            loras_data.append({
+                "name": lora_name,
+                "strength": strength,
+                "hash": lora_hash,
+                "civitai": lora_civitai,
+                "base_model": lora_base_model,
+            })

-        # Format the first part (prompt and loras)
-        metadata_parts = [prompt_with_loras]
+        # Build Hashes JSON (A1111 / Civitai standard format)
+        hashes: dict[str, str] = {}
+        if ckpt_hash:
+            hashes["model"] = ckpt_hash[:10].upper()
+        for lora in loras_data:
+            if lora["hash"]:
+                hashes[f"LORA:{lora['name']}"] = lora["hash"][:10].upper()

-        # Add negative prompt
+        # Build Civitai resources JSON array
+        civitai_resources: list[dict[str, Any]] = []
+        if ckpt_civitai.get("id", 0) > 0:
+            ckpt_resource: dict[str, Any] = {}
+            ckpt_type = (ckpt_civitai.get("model") or {}).get("type", "Checkpoint")
+            model_id = ckpt_civitai.get("modelId", 0)
+            version_id = ckpt_civitai.get("id", 0)
+            if model_id and version_id:
+                ckpt_resource["air"] = self._build_air_string(
+                    ckpt_base_model, ckpt_type, int(model_id), int(version_id)
+                )
+            elif version_id:
+                ckpt_resource["modelVersionId"] = int(version_id)
+            if ckpt_civitai.get("name"):
+                ckpt_resource["versionName"] = ckpt_civitai["name"]
+            if ckpt_resource:
+                civitai_resources.append(ckpt_resource)
+
+        for lora in loras_data:
+            lora_civitai = lora["civitai"]
+            if not lora_civitai or lora_civitai.get("id", 0) <= 0:
+                continue
+            lora_resource: dict[str, Any] = {"weight": lora["strength"]}
+            lora_type = (lora_civitai.get("model") or {}).get("type", "LORA")
+            model_id = lora_civitai.get("modelId", 0)
+            version_id = lora_civitai.get("id", 0)
+            if model_id and version_id:
+                lora_resource["air"] = self._build_air_string(
+                    lora["base_model"], lora_type, int(model_id), int(version_id)
+                )
+            elif version_id:
+                lora_resource["modelVersionId"] = int(version_id)
+            if lora_civitai.get("name"):
+                lora_resource["versionName"] = lora_civitai["name"]
+            civitai_resources.append(lora_resource)
+
+        sampler_name = CIVITAI_SAMPLER_MAP.get(sampler, sampler) if sampler else None
+
+        scheduler_mapping = {
+            "normal": "Normal",
+            "karras": "Karras",
+            "exponential": "Exponential",
+            "sgm_uniform": "SGM Uniform",
+            "sgm_quadratic": "SGM Quadratic",
+        }
+        scheduler_name = scheduler_mapping.get(scheduler, scheduler) if scheduler else None
+
+        # Build output lines
+        prompt_line = prompt if prompt else ""
+        if add_loras_to_prompt and loras_text:
+            prompt_line = f"{prompt_line}\n{loras_text}" if prompt_line else loras_text
+        lines = [prompt_line] if prompt_line else [""]
        if negative_prompt:
-            metadata_parts.append(f"Negative prompt: {negative_prompt}")
+            lines.append(f"Negative prompt: {negative_prompt}")

-        # Format the second part (generation parameters)
-        params = []
-
-        # Add standard parameters in the correct order
-        if "steps" in metadata_dict:
-            add_param_if_not_none(params, "Steps", metadata_dict.get("steps"))
-
-        # Combine sampler and scheduler information
-        sampler_name = None
-        scheduler_name = None
-
-        if "sampler" in metadata_dict:
-            sampler = metadata_dict.get("sampler")
-            # Convert ComfyUI sampler names to user-friendly names
-            sampler_mapping = {
-                "euler": "Euler",
-                "euler_ancestral": "Euler a",
-                "dpm_2": "DPM2",
-                "dpm_2_ancestral": "DPM2 a",
-                "heun": "Heun",
-                "dpm_fast": "DPM fast",
-                "dpm_adaptive": "DPM adaptive",
-                "lms": "LMS",
-                "dpmpp_2s_ancestral": "DPM++ 2S a",
-                "dpmpp_sde": "DPM++ SDE",
-                "dpmpp_sde_gpu": "DPM++ SDE",
-                "dpmpp_2m": "DPM++ 2M",
-                "dpmpp_2m_sde": "DPM++ 2M SDE",
-                "dpmpp_2m_sde_gpu": "DPM++ 2M SDE",
-                "ddim": "DDIM",
-            }
-            sampler_name = sampler_mapping.get(sampler, sampler)
-
-        if "scheduler" in metadata_dict:
-            scheduler = metadata_dict.get("scheduler")
-            scheduler_mapping = {
-                "normal": "Simple",
-                "karras": "Karras",
-                "exponential": "Exponential",
-                "sgm_uniform": "SGM Uniform",
-                "sgm_quadratic": "SGM Quadratic",
-            }
-            scheduler_name = scheduler_mapping.get(scheduler, scheduler)
-
-        # Add combined sampler and scheduler information
+        params: list[str] = []
+        if steps is not None:
+            params.append(f"Steps: {steps}")
        if sampler_name:
            if scheduler_name:
                params.append(f"Sampler: {sampler_name} {scheduler_name}")
            else:
                params.append(f"Sampler: {sampler_name}")
+        if cfg is not None:
+            params.append(f"CFG scale: {cfg}")
+        if seed is not None:
+            params.append(f"Seed: {seed}")
+        if size:
+            params.append(f"Size: {size}")
+        if clip_skip is not None:
+            try:
+                params.append(f"Clip skip: {abs(int(clip_skip))}")
+            except (ValueError, TypeError):
+                pass
+        additional_data = metadata_dict.get("additional_data", "")
+        if additional_data:
+            params.append(additional_data)
+        if ckpt_hash:
+            params.append(f"Model hash: {ckpt_hash[:10].upper()}")
+        if ckpt_display_name:
+            params.append(f"Model: {ckpt_display_name}")
+        if hashes:
+            params.append(f"Hashes: {json.dumps(hashes, separators=(',', ':'))}")
+        params.append("Version: ComfyUI")
+        if civitai_resources:
+            params.append(
+                f"Civitai resources: {json.dumps(civitai_resources, separators=(',', ':'))}"
+            )

-        # CFG scale (Use guidance if available, otherwise fall back to cfg_scale or cfg)
-        if "guidance" in metadata_dict:
-            add_param_if_not_none(params, "CFG scale", metadata_dict.get("guidance"))
-        elif "cfg_scale" in metadata_dict:
-            add_param_if_not_none(params, "CFG scale", metadata_dict.get("cfg_scale"))
-        elif "cfg" in metadata_dict:
-            add_param_if_not_none(params, "CFG scale", metadata_dict.get("cfg"))
-
-        # Seed
-        if "seed" in metadata_dict:
-            add_param_if_not_none(params, "Seed", metadata_dict.get("seed"))
-
-        # Size
-        if "size" in metadata_dict:
-            add_param_if_not_none(params, "Size", metadata_dict.get("size"))
-
-        # Model info
-        if "checkpoint" in metadata_dict:
-            # Ensure checkpoint is a string before processing
-            checkpoint = metadata_dict.get("checkpoint")
-            if checkpoint is not None:
-                # Get model hash
-                model_hash = self.get_checkpoint_hash(checkpoint)
-
-                # Extract basename without path
-                checkpoint_name = os.path.basename(checkpoint)
-                # Remove extension if present
-                checkpoint_name = os.path.splitext(checkpoint_name)[0]
-
-                # Add model hash if available
-                if model_hash:
-                    params.append(
-                        f"Model hash: {model_hash[:10]}, Model: {checkpoint_name}"
-                    )
-                else:
-                    params.append(f"Model: {checkpoint_name}")
-
-        # Add LoRA hashes if available
-        if lora_hashes:
-            lora_hash_parts = []
-            for lora_name, hash_value in lora_hashes.items():
-                lora_hash_parts.append(f"{lora_name}: {hash_value[:10]}")
-
-            if lora_hash_parts:
-                params.append(f'Lora hashes: "{", ".join(lora_hash_parts)}"')
-
-        # Combine all parameters with commas
-        metadata_parts.append(", ".join(params))
-
-        # Join all parts with a new line
-        return "\n".join(metadata_parts)
+        lines.append(", ".join(params))
+        return "\n".join(lines)

    # credit to nkchocoai
    # Add format_filename method to handle pattern substitution
@@ -286,7 +522,12 @@ class SaveImageLM:
            key = parts[0]

            if key == "seed" and "seed" in metadata_dict:
-                filename = filename.replace(segment, str(metadata_dict.get("seed", "")))
+                seed_value = metadata_dict.get("seed")
+                if seed_value is not None:
+                    filename = filename.replace(segment, str(seed_value))
+                else:
+                    # Fallback if seed was not captured by metadata collector
+                    filename = filename.replace(segment, "0")
            elif key == "width" and "size" in metadata_dict:
                size = metadata_dict.get("size", "x")
                w = size.split("x")[0] if isinstance(size, str) else size[0]
@@ -297,12 +538,14 @@ class SaveImageLM:
                filename = filename.replace(segment, str(h))
            elif key == "pprompt" and "prompt" in metadata_dict:
                prompt = metadata_dict.get("prompt", "").replace("\n", " ")
+                prompt = sanitize_folder_name(prompt)
                if len(parts) >= 2:
                    length = int(parts[1])
                    prompt = prompt[:length]
                filename = filename.replace(segment, prompt.strip())
            elif key == "nprompt" and "negative_prompt" in metadata_dict:
                prompt = metadata_dict.get("negative_prompt", "").replace("\n", " ")
+                prompt = sanitize_folder_name(prompt)
                if len(parts) >= 2:
                    length = int(parts[1])
                    prompt = prompt[:length]
@@ -316,6 +559,7 @@ class SaveImageLM:
                    model = "model_unavailable"
                else:
                    model = os.path.splitext(os.path.basename(model_value))[0]
+                    model = sanitize_folder_name(model)
                if len(parts) >= 2:
                    length = int(parts[1])
                    model = model[:length]
@@ -346,6 +590,203 @@ class SaveImageLM:

        return filename

+    @staticmethod
+    def _get_cached_model_by_name(scanner, name):
+        cache = getattr(scanner, "_cache", None)
+        if cache is None or not name:
+            return None
+
+        candidates = [
+            name,
+            os.path.basename(name),
+            os.path.splitext(os.path.basename(name))[0],
+        ]
+        for model in getattr(cache, "raw_data", []):
+            file_name = model.get("file_name")
+            if file_name in candidates:
+                return model
+        return None
+
+    def _build_recipe_loras(self, recipe_scanner, lora_stack):
+        lora_matches = re.findall(r"<lora:([^:]+):([^>]+)>", lora_stack or "")
+        lora_scanner = getattr(recipe_scanner, "_lora_scanner", None)
+        loras_data = []
+        base_model_counts = {}
+
+        for name, strength in lora_matches:
+            lora_info = self._get_cached_model_by_name(lora_scanner, name)
+            civitai = (lora_info or {}).get("civitai") or {}
+            civitai_model = civitai.get("model") or {}
+            try:
+                parsed_strength = float(strength)
+            except (TypeError, ValueError):
+                parsed_strength = 1.0
+
+            loras_data.append(
+                {
+                    "file_name": name,
+                    "strength": parsed_strength,
+                    "hash": ((lora_info or {}).get("sha256") or "").lower(),
+                    "modelVersionId": civitai.get("id", 0),
+                    "modelName": civitai_model.get("name", name) if lora_info else "",
+                    "modelVersionName": civitai.get("name", "") if lora_info else "",
+                    "isDeleted": False,
+                    "exclude": False,
+                }
+            )
+
+            base_model = (lora_info or {}).get("base_model")
+            if base_model:
+                base_model_counts[base_model] = base_model_counts.get(base_model, 0) + 1
+
+        return lora_matches, loras_data, base_model_counts
+
+    def _build_recipe_checkpoint(self, recipe_scanner, checkpoint_raw):
+        if not isinstance(checkpoint_raw, str) or not checkpoint_raw.strip():
+            return None
+
+        checkpoint_name = checkpoint_raw.strip()
+        file_name = os.path.splitext(os.path.basename(checkpoint_name))[0]
+        checkpoint_scanner = getattr(recipe_scanner, "_checkpoint_scanner", None)
+        checkpoint_info = self._get_cached_model_by_name(
+            checkpoint_scanner, checkpoint_name
+        )
+
+        if not checkpoint_info:
+            return {
+                "type": "checkpoint",
+                "name": checkpoint_name,
+                "file_name": file_name,
+                "hash": self.get_checkpoint_hash(checkpoint_name) or "",
+            }
+
+        civitai = checkpoint_info.get("civitai") or {}
+        civitai_model = civitai.get("model") or {}
+        file_path = checkpoint_info.get("file_path") or checkpoint_info.get("path") or ""
+        cached_file_name = (
+            checkpoint_info.get("file_name")
+            or (os.path.splitext(os.path.basename(file_path))[0] if file_path else "")
+            or file_name
+        )
+
+        return {
+            "type": "checkpoint",
+            "modelId": civitai_model.get("id", 0),
+            "modelVersionId": civitai.get("id", 0),
+            "name": civitai_model.get("name")
+            or checkpoint_info.get("model_name")
+            or checkpoint_name,
+            "version": civitai.get("name", ""),
+            "hash": (
+                checkpoint_info.get("sha256") or checkpoint_info.get("hash") or ""
+            ).lower(),
+            "file_name": cached_file_name,
+            "modelName": civitai_model.get("name", ""),
+            "modelVersionName": civitai.get("name", ""),
+            "baseModel": checkpoint_info.get("base_model")
+            or civitai.get("baseModel", ""),
+        }
+
+    @staticmethod
+    def _derive_recipe_name(lora_matches):
+        recipe_name_parts = [
+            f"{name.strip()}-{float(strength):.2f}" for name, strength in lora_matches[:3]
+        ]
+        return "_".join(recipe_name_parts) or "recipe"
+
+    @staticmethod
+    def _sync_recipe_cache(recipe_scanner, recipe_data, json_path):
+        cache = getattr(recipe_scanner, "_cache", None)
+        if cache is not None:
+            cache.raw_data.append(recipe_data)
+            cache.sorted_by_name = sorted(
+                cache.raw_data, key=lambda item: item.get("title", "").lower()
+            )
+            cache.sorted_by_date = sorted(
+                cache.raw_data,
+                key=lambda item: (
+                    item.get("modified", item.get("created_date", 0)),
+                    item.get("file_path", ""),
+                ),
+                reverse=True,
+            )
+            recipe_scanner._update_folder_metadata(cache)
+            recipe_scanner._update_fts_index_for_recipe(recipe_data, "add")
+
+        recipe_id = str(recipe_data.get("id", ""))
+        if recipe_id:
+            recipe_scanner._json_path_map[recipe_id] = json_path
+        persistent_cache = getattr(recipe_scanner, "_persistent_cache", None)
+        if persistent_cache:
+            persistent_cache.update_recipe(recipe_data, json_path)
+
+    def _save_image_as_recipe(self, file_path, metadata_dict):
+        if not metadata_dict:
+            raise ValueError("No generation metadata found")
+
+        recipe_scanner = ServiceRegistry.get_service_sync("recipe_scanner")
+        if recipe_scanner is None:
+            raise RuntimeError("Recipe scanner unavailable")
+
+        recipes_dir = recipe_scanner.recipes_dir
+        if not recipes_dir:
+            raise RuntimeError("Recipes directory unavailable")
+        os.makedirs(recipes_dir, exist_ok=True)
+
+        recipe_id = str(uuid.uuid4())
+        optimized_image, extension = ExifUtils.optimize_image(
+            image_data=file_path,
+            target_width=CARD_PREVIEW_WIDTH,
+            format="webp",
+            quality=85,
+            preserve_metadata=True,
+        )
+        image_path = os.path.normpath(os.path.join(recipes_dir, f"{recipe_id}{extension}"))
+        with open(image_path, "wb") as file_obj:
+            file_obj.write(optimized_image)
+
+        lora_stack = metadata_dict.get("loras", "")
+        lora_matches, loras_data, base_model_counts = self._build_recipe_loras(
+            recipe_scanner, lora_stack
+        )
+        checkpoint_entry = self._build_recipe_checkpoint(
+            recipe_scanner, metadata_dict.get("checkpoint")
+        )
+        most_common_base_model = (
+            max(base_model_counts.items(), key=lambda item: item[1])[0]
+            if base_model_counts
+            else ""
+        )
+        current_time = time.time()
+        recipe_data = {
+            "id": recipe_id,
+            "file_path": image_path,
+            "title": self._derive_recipe_name(lora_matches),
+            "modified": current_time,
+            "created_date": current_time,
+            "base_model": most_common_base_model
+            or (checkpoint_entry or {}).get("baseModel", ""),
+            "loras": loras_data,
+            "gen_params": {
+                key: value
+                for key, value in metadata_dict.items()
+                if key not in ["checkpoint", "loras"]
+            },
+            "loras_stack": lora_stack,
+            "fingerprint": calculate_recipe_fingerprint(loras_data),
+        }
+        if checkpoint_entry:
+            recipe_data["checkpoint"] = checkpoint_entry
+
+        json_path = os.path.normpath(
+            os.path.join(recipes_dir, f"{recipe_id}.recipe.json")
+        )
+        with open(json_path, "w", encoding="utf-8") as file_obj:
+            json.dump(recipe_data, file_obj, indent=4, ensure_ascii=False)
+
+        ExifUtils.append_recipe_metadata(image_path, recipe_data)
+        self._sync_recipe_cache(recipe_scanner, recipe_data, json_path)
+
    def save_images(
        self,
        images,
@@ -356,9 +797,13 @@ class SaveImageLM:
        extra_pnginfo=None,
        lossless_webp=True,
        quality=100,
+        webp_method=6,
+        jpeg_subsampling=0,
        embed_workflow=False,
        save_with_metadata=True,
        add_counter_to_filename=True,
+        save_as_recipe=False,
+        add_loras_to_prompt=False,
    ):
        """Save images with metadata"""
        results = []
@@ -367,7 +812,7 @@ class SaveImageLM:
        raw_metadata = get_metadata()
        metadata_dict = MetadataProcessor.to_dict(raw_metadata, id)

-        metadata = self.format_metadata(metadata_dict)
+        metadata = self.format_metadata(metadata_dict, add_loras_to_prompt)

        # Process filename_prefix with pattern substitution
        filename_prefix = self.format_filename(filename_prefix, metadata_dict)
@@ -390,7 +835,7 @@ class SaveImageLM:
            img = Image.fromarray(np.clip(img, 0, 255).astype(np.uint8))

            # Generate filename with counter if needed
-            base_filename = filename
+            base_filename = filename.replace("%batch_num%", str(i))
            if add_counter_to_filename:
                # Use counter + i to ensure unique filenames for all images in batch
                current_counter = counter + i
@@ -409,15 +854,14 @@ class SaveImageLM:
            elif file_format == "jpeg":
                file = base_filename + ".jpg"
                file_extension = ".jpg"
-                save_kwargs = {"quality": quality, "optimize": True}
+                save_kwargs = {"quality": quality, "optimize": True, "subsampling": jpeg_subsampling}
            elif file_format == "webp":
                file = base_filename + ".webp"
                file_extension = ".webp"
-                # Add optimization param to control performance
                save_kwargs = {
                    "quality": quality,
                    "lossless": lossless_webp,
-                    "method": 0,
+                    "method": webp_method,
                }
            else:
                raise ValueError(f"Unsupported file format: {file_format}")
@@ -477,6 +921,14 @@ class SaveImageLM:

                    img.save(file_path, format="WEBP", **save_kwargs)

+                if save_as_recipe:
+                    try:
+                        self._save_image_as_recipe(file_path, metadata_dict)
+                    except Exception as e:
+                        logger.warning(
+                            "Failed to save image as recipe: %s", e, exc_info=True
+                        )
+
                results.append(
                    {"filename": file, "subfolder": subfolder, "type": self.type}
                )
@@ -496,9 +948,13 @@ class SaveImageLM:
        extra_pnginfo=None,
        lossless_webp=True,
        quality=100,
+        webp_method=6,
+        jpeg_subsampling=0,
        embed_workflow=False,
        save_with_metadata=True,
        add_counter_to_filename=True,
+        save_as_recipe=False,
+        add_loras_to_prompt=False,
    ):
        """Process and save image with metadata"""
        # Make sure the output directory exists
@@ -524,9 +980,13 @@ class SaveImageLM:
            extra_pnginfo,
            lossless_webp,
            quality,
+            webp_method,
+            jpeg_subsampling,
            embed_workflow,
            save_with_metadata,
            add_counter_to_filename,
+            save_as_recipe,
+            add_loras_to_prompt,
        )

        return {
@@ -76,6 +76,9 @@ class TriggerWordToggleLM:
        # Filter out empty strings and return as set
        return set(word for word in words if word)

+    def _group_has_child_items(self, item):
+        return isinstance(item, dict) and isinstance(item.get("items"), list)
+
    def process_trigger_words(
        self,
        id,
@@ -112,7 +115,11 @@ class TriggerWordToggleLM:

                if isinstance(trigger_data, list):
                    if group_mode:
-                        if allow_strength_adjustment:
+                        if any(self._group_has_child_items(item) for item in trigger_data):
+                            filtered_groups = self._process_group_items(
+                                trigger_data, allow_strength_adjustment
+                            )
+                        elif allow_strength_adjustment:
                            parsed_items = [
                                self._parse_trigger_item(
                                    item, allow_strength_adjustment
@@ -174,6 +181,41 @@ class TriggerWordToggleLM:

        return (filtered_triggers,)

+    def _process_group_items(self, trigger_data, allow_strength_adjustment):
+        filtered_groups = []
+
+        for item in trigger_data:
+            group = self._parse_trigger_item(item, allow_strength_adjustment)
+            if not group["text"] or not group["active"]:
+                continue
+
+            raw_items = item.get("items") if isinstance(item, dict) else None
+            if isinstance(raw_items, list):
+                active_items = []
+                for raw_item in raw_items:
+                    child = self._parse_trigger_item(
+                        raw_item, allow_strength_adjustment=False
+                    )
+                    if child["text"] and child["active"]:
+                        active_items.append(child["text"])
+
+                if not active_items:
+                    continue
+
+                group_text = ", ".join(active_items)
+            else:
+                group_text = group["text"]
+
+            filtered_groups.append(
+                self._format_word_output(
+                    group_text,
+                    group["strength"],
+                    allow_strength_adjustment,
+                )
+            )
+
+        return filtered_groups
+
    def _parse_trigger_item(self, item, allow_strength_adjustment):
        text = (item.get("text") or "").strip()
        active = bool(item.get("active", False))
@@ -1,12 +1,27 @@
 import logging
 import os
-from typing import List, Tuple
-import comfy.sd # type: ignore
+from typing import Any, List, Tuple
+import comfy.sd  # pyright: ignore[reportMissingImports]
 from ..utils.utils import get_checkpoint_info_absolute, _format_model_name_for_comfyui

 logger = logging.getLogger(__name__)


+def _reload_gguf_unet(
+    unet_path: str, weight_dtype: str, disable_dynamic: bool = False
+) -> object:
+    """Reload a GGUF diffusion model from disk (cached_patcher_init factory).
+
+    Mirrors the GGUF branch of UNETLoaderLM.load_unet so ModelPatcher
+    deepclone/dynamic machinery can rebuild GGUF models with the correct
+    GGMLOps. ``disable_dynamic`` is accepted for signature compatibility
+    with core ComfyUI loaders.
+    """
+    loader = UNETLoaderLM()
+    model, = loader._load_gguf_unet(unet_path, unet_path, weight_dtype)
+    return model
+
+
 class UNETLoaderLM:
    """UNET Loader with support for extra folder paths

@@ -19,9 +34,9 @@ class UNETLoaderLM:
    CATEGORY = "Lora Manager/loaders"

    @classmethod
-    def INPUT_TYPES(s):
+    def INPUT_TYPES(cls):
        # Get list of unet names from scanner (includes extra folder paths)
-        unet_names = s._get_unet_names()
+        unet_names = cls._get_unet_names()
        return {
            "required": {
                "unet_name": (
@@ -59,7 +74,10 @@ class UNETLoaderLM:
                for item in cache.raw_data:
                    if item.get("sub_type") == "diffusion_model":
                        file_path = item.get("file_path", "")
-                        if file_path:
+                        # Only offer models that still exist on disk so ComfyUI
+                        # flags missing diffusion models at queue time via
+                        # "value not in list" (the scanner cache can be stale).
+                        if file_path and os.path.exists(file_path):
                            # Format using relative path with OS-native separator
                            formatted_name = _format_model_name_for_comfyui(
                                file_path, model_roots
@@ -90,7 +108,7 @@ class UNETLoaderLM:
            logger.error(f"Error getting unet names: {e}")
            return []

-    def load_unet(self, unet_name: str, weight_dtype: str) -> Tuple:
+    def load_unet(self, unet_name: str, weight_dtype: str) -> Tuple[Any, ...]:
        """Load a diffusion model by name, supporting extra folder paths

        Args:
@@ -133,7 +151,7 @@ class UNETLoaderLM:

    def _load_gguf_unet(
        self, unet_path: str, unet_name: str, weight_dtype: str
-    ) -> Tuple:
+    ) -> Tuple[Any, ...]:
        """Load a GGUF format diffusion model

        Args:
@@ -196,6 +214,12 @@ class UNETLoaderLM:
            # Wrap with GGUFModelPatcher
            model = GGUFModelPatcher.clone(model)

+            # Register a reload factory so the MODEL carries its source path
+            # (cached_patcher_init) like core ComfyUI loaders do — required
+            # for model-name extraction downstream and for ModelPatcher
+            # deepclone/dynamic machinery.
+            model.cached_patcher_init = (_reload_gguf_unet, (unet_path, weight_dtype))
+
            return (model,)

        except Exception as e:
@@ -1,3 +1,6 @@
+from typing import Any
+
+
 class AnyType(str):
    """A special class that is always equal in not equal comparisons. Credit to pythongosssss"""

@@ -6,7 +9,7 @@ class AnyType(str):


 # Credit to Regis Gaughan, III (rgthree)
-class FlexibleOptionalInputType(dict):
+class FlexibleOptionalInputType(dict[str, Any]):
    """A special class to make flexible nodes that pass data to our python handlers.

    Enables both flexible/dynamic input types (like for Any Switch) or a dynamic number of inputs
@@ -23,6 +26,7 @@ class FlexibleOptionalInputType(dict):
    """

    def __init__(self, type):
+        super().__init__()
        self.type = type

    def __getitem__(self, key):
@@ -36,19 +40,58 @@ any_type = AnyType("*")

 # Common methods extracted from lora_loader.py and lora_stacker.py
 import os
+import re
 import logging
 import copy
 import sys
-import folder_paths  # type: ignore
+import asyncio
+import folder_paths  # pyright: ignore[reportMissingImports]

 logger = logging.getLogger(__name__)


+def get_lora_syntax_format():
+    try:
+        from ..services.settings_manager import get_settings_manager
+        return get_settings_manager().get("lora_syntax_format", "legacy")
+    except Exception:
+        return "legacy"
+
+
+def apply_lora_syntax_format(name):
+    fmt = get_lora_syntax_format()
+    if fmt == "legacy":
+        return name.replace("\\", "/").rstrip("/").split("/")[-1]
+    return name
+
+
 def extract_lora_name(lora_path):
-    """Extract the lora name from a lora path (e.g., 'IL\\aorunIllstrious.safetensors' -> 'aorunIllstrious')"""
-    # Get the basename without extension
-    basename = os.path.basename(lora_path)
-    return os.path.splitext(basename)[0]
+    normalized = lora_path.replace("\\", "/")
+    basename = os.path.basename(normalized)
+    name_no_ext = os.path.splitext(basename)[0]
+    dirname = os.path.dirname(normalized)
+    if dirname and dirname not in (".", "/") and not normalized.startswith("/"):
+        return apply_lora_syntax_format(f"{dirname}/{name_no_ext}")
+    return apply_lora_syntax_format(name_no_ext)
+
+
+def parse_lora_syntax(text: str) -> list[dict[str, Any]]:
+    """Parse <lora:name:strength> syntax from text input into a list of dicts.
+
+    Each entry contains: name, model_strength, clip_strength.
+    Supports both ``<lora:name:strength>`` and ``<lora:name:model_strength:clip_strength>``.
+    """
+    pattern = r"<lora:([^:>]+):([^:>]+)(?::([^:>]+))?>"
+    matches = re.findall(pattern, text, re.IGNORECASE)
+    loras = []
+    for match in matches:
+        model_strength = float(match[1])
+        loras.append({
+            "name": match[0],
+            "model_strength": model_strength,
+            "clip_strength": float(match[2]) if match[2] else model_strength,
+        })
+    return loras


 def get_loras_list(kwargs):
@@ -69,6 +112,157 @@ def get_loras_list(kwargs):
        return []


+_LORA_EXTENSIONS = (".safetensors", ".ckpt", ".pt", ".bin")
+
+
+def _strip_lora_extension(name: str) -> str:
+    """Strip a known LoRA model extension from a name (case-insensitive)."""
+    lowered = name.lower()
+    for ext in _LORA_EXTENSIONS:
+        if lowered.endswith(ext):
+            return name[: -len(ext)]
+    return name
+
+
+def _find_missing_loras(names: list[str]) -> list[str]:
+    """Return the names that cannot be resolved to an existing local LoRA file.
+
+    Mirrors the matching semantics of ``get_lora_info_absolute``
+    (py/utils/utils.py): after stripping the extension, a name matches a cached
+    LoRA when it equals the cached file name or the ``folder/file`` path. As a
+    fallback, a name containing a folder that only matches by basename resolves
+    to the first basename match (same behavior as the runtime resolver). Raw
+    absolute paths that exist on disk are always considered available.
+
+    The scanner cache is fetched once for all names; the cache may be stale, so
+    resolved paths are additionally verified with ``os.path.isfile``.
+    """
+    if not names:
+        return []
+
+    async def _check() -> list[str]:
+        from ..services.service_registry import ServiceRegistry
+
+        scanner = await ServiceRegistry.get_lora_scanner()
+        # The scanner cache may not be hydrated yet (startup, library path
+        # change). An empty cache is not authoritative — treat it as "cannot
+        # verify" and skip validation instead of flagging every active LoRA
+        # as missing.
+        if getattr(scanner, "_cache", None) is None or getattr(
+            scanner, "_is_initializing", False
+        ):
+            return []
+        cache = await scanner.get_cached_data()
+
+        lookup = {}
+        basename_candidates = {}
+        for item in cache.raw_data:
+            file_path = item.get("file_path")
+            if not file_path:
+                continue
+            file_name = item.get("file_name", "")
+            folder = item.get("folder", "")
+            file_name_no_ext = _strip_lora_extension(file_name)
+            path_name_no_ext = (
+                f"{folder}/{file_name_no_ext}".replace("\\", "/")
+                if folder
+                else file_name_no_ext
+            )
+            lookup.setdefault(file_name_no_ext, file_path)
+            lookup.setdefault(path_name_no_ext, file_path)
+            basename_candidates.setdefault(file_name_no_ext, []).append(
+                (folder, file_path)
+            )
+
+        missing = []
+        for name in names:
+            if not name:
+                continue
+            normalized = name.replace("\\", "/")
+            # Raw absolute paths (outside the library) are usable as-is.
+            if os.path.isfile(normalized):
+                continue
+            no_ext = _strip_lora_extension(normalized)
+            file_path = lookup.get(no_ext)
+            if file_path is None and "/" in no_ext:
+                # A name with a folder that matches only by basename resolves
+                # at runtime like get_lora_info_absolute's fallback does:
+                # prefer a candidate whose folder prefixes the name, else the
+                # first basename match.
+                folder, basename = no_ext.rsplit("/", 1)
+                candidates = basename_candidates.get(basename, [])
+                file_path = next(
+                    (
+                        fp
+                        for fld, fp in candidates
+                        if fld and no_ext.startswith(fld + "/")
+                    ),
+                    None,
+                )
+                if file_path is None and candidates:
+                    file_path = candidates[0][1]
+            if file_path is None or not os.path.isfile(file_path):
+                missing.append(name)
+        return missing
+
+    try:
+        # Check if we're already in an event loop
+        loop = asyncio.get_running_loop()
+        # If we're in a running loop, run the async check in a separate thread
+        import concurrent.futures
+
+        def run_in_thread():
+            new_loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(new_loop)
+            try:
+                return new_loop.run_until_complete(_check())
+            finally:
+                new_loop.close()
+
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            future = executor.submit(run_in_thread)
+            return future.result()
+    except RuntimeError:
+        # No event loop is running, we can use asyncio.run()
+        return asyncio.run(_check())
+
+
+def validate_lora_entries(kwargs):
+    """Validate active LoRA widget entries against the local library.
+
+    Used by node ``VALIDATE_INPUTS`` implementations so ComfyUI rejects the
+    prompt at queue time (``custom_validation_failed``) when an active entry
+    references a LoRA that is not available locally — mirroring how built-in
+    loader nodes flag missing models before execution starts.
+
+    Returns:
+        None when every active entry resolves to an existing local file,
+        otherwise a descriptive error string listing the missing LoRAs.
+        Verification failures (e.g. scanner not ready) are treated as valid
+        so queueing is never blocked by validation machinery itself.
+    """
+    # Missing/empty loras input is always valid; skip get_loras_list so it
+    # does not log a warning for the None case on every queue.
+    if not kwargs.get("loras"):
+        return None
+    loras = get_loras_list(kwargs)
+    active_names = []
+    for lora in loras:
+        if not isinstance(lora, dict):
+            continue
+        if not lora.get("active", False):
+            continue
+        active_names.append(apply_lora_syntax_format(str(lora.get("name") or "")))
+    try:
+        missing = _find_missing_loras(active_names)
+    except Exception:
+        logger.exception("Failed to validate LoRA entries against the local library")
+        return None
+    if not missing:
+        return None
+    return "Missing LoRA(s) in local library: " + ", ".join(missing)
+
+
 def load_state_dict_in_safetensors(path, device="cpu", filter_prefix=""):
    """Simplified version of load_state_dict_in_safetensors that just loads from a local path"""
    import safetensors.torch
@@ -1,10 +1,22 @@
-import folder_paths # type: ignore
-from ..utils.utils import get_lora_info
-from .utils import FlexibleOptionalInputType, any_type, get_loras_list
+import os
+from ..utils.utils import get_lora_info_absolute
+from ..config import config
+from .utils import FlexibleOptionalInputType, any_type, get_loras_list, validate_lora_entries
 import logging

 logger = logging.getLogger(__name__)

+
+def _relpath_within_loras(abs_path):
+    """Return abs_path relative to the first matching lora root, or basename as fallback."""
+    all_roots = list(config.loras_roots or []) + list(config.extra_loras_roots or [])
+    for root in all_roots:
+        try:
+            return os.path.relpath(abs_path, root)
+        except ValueError:
+            continue
+    return os.path.basename(abs_path)
+
 class WanVideoLoraSelectLM:
    NAME = "WanVideo Lora Select (LoraManager)"
    CATEGORY = "Lora Manager/stackers"
@@ -23,6 +35,11 @@ class WanVideoLoraSelectLM:
            "optional": FlexibleOptionalInputType(any_type),
        }

+    @classmethod
+    def VALIDATE_INPUTS(cls, loras=None):
+        """Queue-time validation: reject missing local LoRAs before execution."""
+        return validate_lora_entries({"loras": loras}) or True
+
    RETURN_TYPES = ("WANVIDLORA", "STRING", "STRING")
    RETURN_NAMES = ("lora", "trigger_words", "active_loras")
    FUNCTION = "process_loras"
@@ -56,13 +73,13 @@ class WanVideoLoraSelectLM:
            clip_strength = float(lora.get('clipStrength', model_strength))
            
            # Get lora path and trigger words
-            lora_path, trigger_words = get_lora_info(lora_name)
+            lora_path, trigger_words = get_lora_info_absolute(lora_name)
            
            # Create lora item for WanVideo format
            lora_item = {
-                "path": folder_paths.get_full_path("loras", lora_path),
+                "path": lora_path,
                "strength": model_strength,
-                "name": lora_path.split(".")[0],
+                "name": os.path.splitext(_relpath_within_loras(lora_path))[0],
                "blocks": selected_blocks,
                "layer_filter": layer_filter,
                "low_mem_load": low_mem_load,
@@ -1,11 +1,23 @@
-import folder_paths # type: ignore
-from ..utils.utils import get_lora_info
+import os
+from ..utils.utils import get_lora_info_absolute
+from ..config import config
 from .utils import any_type 
 import logging

 # 初始化日志记录器
 logger = logging.getLogger(__name__)

+
+def _relpath_within_loras(abs_path):
+    """Return abs_path relative to the first matching lora root, or basename as fallback."""
+    all_roots = list(config.loras_roots or []) + list(config.extra_loras_roots or [])
+    for root in all_roots:
+        try:
+            return os.path.relpath(abs_path, root)
+        except ValueError:
+            continue
+    return os.path.basename(abs_path)
+
 # 定义新节点的类
 class WanVideoLoraTextSelectLM:
    # 节点在UI中显示的名称
@@ -87,12 +99,12 @@ class WanVideoLoraTextSelectLM:
            else:
                continue

-            lora_path, trigger_words = get_lora_info(lora_name_raw)
+            lora_path, trigger_words = get_lora_info_absolute(lora_name_raw)

            lora_item = {
-                "path": folder_paths.get_full_path("loras", lora_path),
+                "path": lora_path,
                "strength": model_strength,
-                "name": lora_path.split(".")[0],
+                "name": os.path.splitext(_relpath_within_loras(lora_path))[0],
                "blocks": selected_blocks,
                "layer_filter": layer_filter,
                "low_mem_load": low_mem_load,
@@ -1,3 +1,7 @@
+# pyright: reportImportCycles=false
+# Lazy (function-local) imports still count as static edges in basedpyright's
+# reportImportCycles, so the ServiceRegistry singleton pattern necessarily forms
+# import cycles. Breaking them would require an architectural refactor.
 """Base classes for recipe parsers."""

 import json
@@ -7,7 +11,7 @@ import re
 from typing import Dict, List, Any, Optional, Tuple
 from abc import ABC, abstractmethod
 from ..config import config
-from ..utils.constants import VALID_LORA_TYPES
+from ..utils.constants import MODEL_WEIGHT_FILE_TYPES, VALID_LORA_TYPES, VALID_CHECKPOINT_SUB_TYPES
 from ..utils.civitai_utils import rewrite_preview_url

 logger = logging.getLogger(__name__)
@@ -38,7 +42,7 @@ class RecipeMetadataParser(ABC):
        pass
    
    @staticmethod
-    async def populate_lora_from_civitai(lora_entry: Dict[str, Any], civitai_info_tuple: Tuple[Dict[str, Any], Optional[str]], 
+    async def populate_lora_from_civitai(lora_entry: Dict[str, Any], civitai_info_tuple: Tuple[Dict[str, Any] | None, str | None] | Dict[str, Any],
                                         recipe_scanner=None, base_model_counts=None, hash_value=None) -> Optional[Dict[str, Any]]:
        """
        Populate a lora entry with information from Civitai API response
@@ -58,9 +62,52 @@ class RecipeMetadataParser(ABC):
            civitai_info, error_msg = civitai_info_tuple if isinstance(civitai_info_tuple, tuple) else (civitai_info_tuple, None)
            
            if not civitai_info or error_msg == "Model not found":
-                # Model not found or deleted
-                lora_entry['isDeleted'] = True
-                lora_entry['thumbnailUrl'] = '/loras_static/images/no-preview.png'
+                # CivitAI may fail to resolve a hash that is still being
+                # computed (known CivitAI issue). Before marking as deleted,
+                # try to reconcile with a local model that has the same
+                # filename and matching AutoV3 hash.
+                reconciled = False
+                file_name = lora_entry.get("file_name")
+                if file_name and recipe_scanner and hash_value:
+                    lora_scanner = getattr(recipe_scanner, "_lora_scanner", None)
+                    if lora_scanner:
+                        try:
+                            # Local import to avoid circular dependency:
+                            # base.py → file_utils → settings_manager → ...
+                            #  → recipe_scanner → enrichment → base.py
+                            from ..utils.file_utils import calculate_autov3  # fmt: skip
+                            cache = await lora_scanner.get_cached_data()
+                            for item in getattr(cache, "raw_data", []):
+                                if item.get("file_name") == file_name:
+                                    local_path = item.get("file_path")
+                                    if local_path and os.path.exists(local_path):
+                                        local_autov3 = calculate_autov3(local_path)
+                                        if local_autov3 and local_autov3 == hash_value:
+                                            lora_entry["existsLocally"] = True
+                                            lora_entry["localPath"] = local_path
+                                            lora_entry["hash"] = item.get("sha256", hash_value)
+                                            if "preview_url" in item:
+                                                lora_entry["thumbnailUrl"] = config.get_preview_static_url(item["preview_url"])
+                                            civ = item.get("civitai") or {}
+                                            if isinstance(civ, dict):
+                                                if civ.get("id") is not None:
+                                                    lora_entry["id"] = civ["id"]
+                                                if civ.get("modelId") is not None:
+                                                    lora_entry["modelId"] = civ["modelId"]
+                                                if civ.get("name"):
+                                                    lora_entry["version"] = civ["name"]
+                                                # model_name is the CivitAI model display
+                                                # name stored directly in the cache column.
+                                                cached_model_name = item.get("model_name")
+                                                if cached_model_name:
+                                                    lora_entry["name"] = cached_model_name
+                                            reconciled = True
+                                            break
+                        except Exception:
+                            pass
+                if not reconciled:
+                    lora_entry['isDeleted'] = True
+                    lora_entry['thumbnailUrl'] = '/loras_static/images/no-preview.png'
                return lora_entry
                
            # Get model type and validate
@@ -108,9 +155,9 @@ class RecipeMetadataParser(ABC):
            
            # Process file information if available
            if 'files' in civitai_info:
-                # Find the primary model file (type="Model" and primary=true) in the files list
+                # Find the primary model file (weights-type and primary=true) in the files list
                model_file = next((file for file in civitai_info.get('files', []) 
-                                    if file.get('type') == 'Model' and file.get('primary') == True), None)
+                                    if file.get('type') in MODEL_WEIGHT_FILE_TYPES and file.get('primary') == True), None)
                
                if model_file:
                    # Get size
@@ -132,10 +179,18 @@ class RecipeMetadataParser(ABC):
                                lora_entry['localPath'] = local_path
                                lora_entry['file_name'] = os.path.splitext(os.path.basename(local_path))[0]
                                
-                                # Get thumbnail from local preview if available
+                                # Get thumbnail from local preview if available.
+                                # Match the cache item by local path first (get_path_by_hash
+                                # cascade: 10-char autov2 / 12-char autov3), then by hash.
                                lora_cache = await lora_scanner.get_cached_data()
-                                lora_item = next((item for item in lora_cache.raw_data 
-                                                    if item['sha256'].lower() == lora_entry['hash'].lower()), None)
+                                h = (lora_entry.get("hash") or "").lower()
+                                lora_item = next((item for item in lora_cache.raw_data
+                                                  if (item.get("file_path") or "") == local_path), None)
+                                if lora_item is None:
+                                    lora_item = next((item for item in lora_cache.raw_data
+                                                      if (item.get("sha256") or "").lower() == h
+                                                      or (item.get("autov3") or "").lower() == h
+                                                      or (item.get("sha256") or "")[:10].lower() == h), None)
                                if lora_item and 'preview_url' in lora_item:
                                    lora_entry['thumbnailUrl'] = config.get_preview_static_url(lora_item['preview_url'])
                            except Exception as e:
@@ -151,7 +206,7 @@ class RecipeMetadataParser(ABC):
        return lora_entry
    
    @staticmethod
-    async def populate_checkpoint_from_civitai(checkpoint: Dict[str, Any], civitai_info: Dict[str, Any]) -> Dict[str, Any]:
+    async def populate_checkpoint_from_civitai(checkpoint: Dict[str, Any], civitai_info: Dict[str, Any] | Tuple[Dict[str, Any] | None, str | None] | None) -> Dict[str, Any]:
        """
        Populate checkpoint information from Civitai API response
        
@@ -173,6 +228,20 @@ class RecipeMetadataParser(ABC):
                checkpoint['isDeleted'] = True
                return checkpoint

+            # Validate that the model type is actually a checkpoint.
+            # Unlike populate_lora_from_civitai which has this check,
+            # this function was missing type validation — allowing LoRA
+            # version data to be saved as the recipe's checkpoint when the
+            # wrong version ID was passed downstream (fixed in v2.7+).
+            model_type = civitai_data.get('model', {}).get('type', '').lower()
+            if model_type not in VALID_CHECKPOINT_SUB_TYPES:
+                logger.warning(
+                    f"Cannot populate checkpoint: model version {civitai_data.get('id')} "
+                    f"has type '{model_type}', expected one of {VALID_CHECKPOINT_SUB_TYPES}. "
+                    f"Skipping checkpoint enrichment."
+                )
+                return checkpoint
+
            if 'model' in civitai_data and 'name' in civitai_data['model']:
                checkpoint['name'] = civitai_data['model']['name']

@@ -192,11 +261,21 @@ class RecipeMetadataParser(ABC):
            checkpoint['id'] = civitai_data.get('id', 0)

            if 'files' in civitai_data:
+                # Prefer the file CivitAI marked primary; fall back to any
+                # weights-type file (providers without primary flags).
                model_file = next(
                    (
                        file
                        for file in civitai_data.get('files', [])
-                        if file.get('type') == 'Model'
+                        if file.get('type') in MODEL_WEIGHT_FILE_TYPES
+                        and file.get('primary') is True
+                    ),
+                    None,
+                ) or next(
+                    (
+                        file
+                        for file in civitai_data.get('files', [])
+                        if file.get('type') in MODEL_WEIGHT_FILE_TYPES
                    ),
                    None,
                )
@@ -1,3 +1,7 @@
+# pyright: reportImportCycles=false
+# Lazy (function-local) imports still count as static edges in basedpyright's
+# reportImportCycles, so the ServiceRegistry singleton pattern necessarily forms
+# import cycles. Breaking them would require an architectural refactor.
 import logging
 import json
 import os
@@ -16,55 +20,65 @@ class RecipeEnricher:
    async def enrich_recipe(
        recipe: Dict[str, Any],
        civitai_client: Any,
-        request_params: Optional[Dict[str, Any]] = None
+        request_params: Optional[Dict[str, Any]] = None,
+        prefetched_civitai_meta_raw: Optional[Dict[str, Any]] = None,
+        prefetched_model_version_id: Optional[int] = None,
    ) -> bool:
        """
        Enrich a recipe dictionary in-place with metadata from Civitai and embedded params.
-        
+
        Args:
            recipe: The recipe dictionary to enrich. Must have 'gen_params' initialized.
            civitai_client: Authenticated Civitai client instance.
            request_params: (Optional) Parameters from a user request (e.g. import).
-            
+            prefetched_civitai_meta_raw: (Optional) Pre-fetched raw meta from Civitai
+                get_image_info, avoiding a duplicate API call.
+            prefetched_model_version_id: (Optional) Pre-fetched model version ID.
+
        Returns:
            bool: True if the recipe was modified, False otherwise.
        """
        updated = False
        gen_params = recipe.get("gen_params", {})
-        
-        # 1. Fetch Civitai Info if available
+
+        # 1. Obtain Civitai metadata
        civitai_meta = None
-        model_version_id = None
-        
-        source_url = recipe.get("source_url") or recipe.get("source_path", "")
-        
-        # Check if it's a Civitai image URL
-        image_id = extract_civitai_image_id(str(source_url))
-        if image_id:
-            try:
-                image_info = await civitai_client.get_image_info(
-                    image_id, source_url=str(source_url)
-                )
-                if image_info:
-                    # Handle nested meta often found in Civitai API responses
-                    raw_meta = image_info.get("meta")
-                    if isinstance(raw_meta, dict):
-                        if "meta" in raw_meta and isinstance(raw_meta["meta"], dict):
-                            civitai_meta = raw_meta["meta"]
-                        else:
-                            civitai_meta = raw_meta
-                    
-                    model_version_id = image_info.get("modelVersionId")
-                    
-                    # If not at top level, check resources in meta
-                    if not model_version_id and civitai_meta:
-                        resources = civitai_meta.get("civitaiResources", [])
-                        for res in resources:
-                            if res.get("type") == "checkpoint":
-                                model_version_id = res.get("modelVersionId")
-                                break
-            except Exception as e:
-                logger.warning(f"Failed to fetch Civitai image info: {e}")
+        model_version_id = prefetched_model_version_id
+
+        source_path = recipe.get("source_path", "")
+
+        if prefetched_civitai_meta_raw is not None:
+            raw_meta = prefetched_civitai_meta_raw
+            if isinstance(raw_meta, dict):
+                if "meta" in raw_meta and isinstance(raw_meta["meta"], dict):
+                    civitai_meta = raw_meta["meta"]
+                else:
+                    civitai_meta = raw_meta
+        else:
+            image_id = extract_civitai_image_id(str(source_path))
+            if image_id:
+                try:
+                    image_info = await civitai_client.get_image_info(
+                        image_id, source_url=str(source_path)
+                    )
+                    if image_info:
+                        raw_meta = image_info.get("meta")
+                        if isinstance(raw_meta, dict):
+                            if "meta" in raw_meta and isinstance(raw_meta["meta"], dict):
+                                civitai_meta = raw_meta["meta"]
+                            else:
+                                civitai_meta = raw_meta
+
+                        model_version_id = image_info.get("modelVersionId")
+                except Exception as e:
+                    logger.warning(f"Failed to fetch Civitai image info: {e}")
+
+        if not model_version_id and civitai_meta:
+            resources = civitai_meta.get("civitaiResources", [])
+            for res in resources:
+                if res.get("type") == "checkpoint":
+                    model_version_id = res.get("modelVersionId")
+                    break

        # 2. Merge Parameters
        # Priority: request_params > civitai_meta > embedded (existing gen_params)
@@ -180,27 +194,42 @@ class RecipeEnricher:
            existing_cp = recipe.get("checkpoint")
            if existing_cp is None:
                existing_cp = {}
+
+            # Extract baseModel from raw civitai_info before populate_checkpoint_from_civitai
+            # (populate may reject non-checkpoint types and lose this data)
+            base_model_from_civitai: str = ""
+            if isinstance(civitai_info, dict):
+                base_model_from_civitai = civitai_info.get("baseModel", "") or ""
+            elif isinstance(civitai_info, tuple) and len(civitai_info) > 0 and isinstance(civitai_info[0], dict):
+                base_model_from_civitai = civitai_info[0].get("baseModel", "") or ""
+
            checkpoint_data = await RecipeMetadataParser.populate_checkpoint_from_civitai(existing_cp, civitai_info)
-            # 1. First, resolve base_model using full data before we format it away
+
+            # 1. Resolve base_model from checkpoint_data first, then fall back to raw civitai_info
            current_base_model = recipe.get("base_model")
-            resolved_base_model = checkpoint_data.get("baseModel")
+            resolved_base_model = checkpoint_data.get("baseModel") or base_model_from_civitai
            if resolved_base_model:
-                # Update if empty OR if it matches our generic prefix but is less specific
                is_generic = not current_base_model or current_base_model.lower() in ["flux", "sdxl", "sd15"]
                if is_generic and resolved_base_model != current_base_model:
                    recipe["base_model"] = resolved_base_model
-            
-            # 2. Format according to requirements: type, modelId, modelVersionId, modelName, modelVersionName
-            formatted_checkpoint = {
-                "type": "checkpoint",
-                "modelId": checkpoint_data.get("modelId"),
-                "modelVersionId": checkpoint_data.get("id") or checkpoint_data.get("modelVersionId"),
-                "modelName": checkpoint_data.get("name"), # In base.py, 'name' is populated from civitai_data['model']['name']
-                "modelVersionName": checkpoint_data.get("version") # In base.py, 'version' is populated from civitai_data['name']
-            }
-            # Remove None values
-            recipe["checkpoint"] = {k: v for k, v in formatted_checkpoint.items() if v is not None}
-            
+
+            # 2. Only format and save checkpoint if it has real data (not just type after type rejection)
+            has_checkpoint_data = any([
+                checkpoint_data.get("modelId"),
+                checkpoint_data.get("id") or checkpoint_data.get("modelVersionId"),
+                checkpoint_data.get("name"),
+                checkpoint_data.get("version"),
+            ])
+            if has_checkpoint_data:
+                formatted_checkpoint = {
+                    "type": "checkpoint",
+                    "modelId": checkpoint_data.get("modelId"),
+                    "modelVersionId": checkpoint_data.get("id") or checkpoint_data.get("modelVersionId"),
+                    "modelName": checkpoint_data.get("name"),
+                    "modelVersionName": checkpoint_data.get("version"),
+                }
+                recipe["checkpoint"] = {k: v for k, v in formatted_checkpoint.items() if v is not None}
+
            return True
        else:
            # Fallback to name extraction if we don't already have one
@@ -1,6 +1,7 @@
 """Factory for creating recipe metadata parsers."""

 import logging
+from typing import Any
 from .parsers import (
    RecipeFormatParser,
    ComfyMetadataParser,
@@ -31,7 +32,8 @@ class RecipeParserFactory:
        # First, try CivitaiApiMetadataParser for dict input
        if isinstance(metadata, dict):
            try:
-                if CivitaiApiMetadataParser().is_metadata_matching(metadata):
+                user_comment: Any = metadata
+                if CivitaiApiMetadataParser().is_metadata_matching(user_comment):
                    return CivitaiApiMetadataParser()
            except Exception as e:
                logger.debug(f"CivitaiApiMetadataParser check failed: {e}")
@@ -52,7 +52,7 @@ class AutomaticMetadataParser(RecipeMetadataParser):
                    negative_and_params = ""
            
            # Initialize metadata
-            metadata = {
+            metadata: Dict[str, Any] = {
                "prompt": prompt,
                "loras": []
            }
@@ -123,24 +123,39 @@ class AutomaticMetadataParser(RecipeMetadataParser):
                        if model_hash_from_hashes:
                            metadata["model_hash"] = model_hash_from_hashes
                    
-                    # Extract Lora hashes in alternative format
+                    # Extract Lora hashes in alternative format.
+                    # Run unconditionally (not just as fallback) so that
+                    # non-empty hashes from Lora hashes fill in the gaps left
+                    # by empty values in the Hashes JSON dict.  Some WebUI
+                    # builds write real hash values only to Lora hashes and
+                    # leave the Hashes JSON values empty.
                    lora_hashes_match = re.search(self.LORA_HASHES_REGEX, params_section)
-                    if not hashes_match and lora_hashes_match:
+                    if lora_hashes_match:
                        try:
                            lora_hashes_str = lora_hashes_match.group(1)
                            lora_hash_entries = lora_hashes_str.split(', ')
-                            
-                            # Initialize hashes dict if it doesn't exist
-                            if "hashes" not in metadata:
-                                metadata["hashes"] = {}
-                                
+
                            # Parse each lora hash entry (format: "name: hash")
                            for entry in lora_hash_entries:
                                if ': ' in entry:
                                    lora_name, lora_hash = entry.split(': ', 1)
-                                    # Add as lora type in the same format as regular hashes
-                                    metadata["hashes"][f"lora:{lora_name}"] = lora_hash.strip()
-                            
+                                    lora_hash = lora_hash.strip()
+                                    if not lora_hash:
+                                        # Skip entries without a hash value
+                                        continue
+                                    # Initialize hashes dict if it doesn't exist
+                                    if "hashes" not in metadata:
+                                        metadata["hashes"] = {}
+                                    # Add as lora type in the same format as
+                                    # regular hashes.  Only override an
+                                    # existing entry if its value is empty
+                                    # (Lora hashes is the more reliable
+                                    # source when Hashes JSON has blanks).
+                                    key = f"lora:{lora_name}"
+                                    existing = metadata["hashes"].get(key, "")
+                                    if not existing:
+                                        metadata["hashes"][key] = lora_hash
+
                            # Remove lora hashes from params section
                            params_section = params_section.replace(lora_hashes_match.group(0), '')
                        except Exception as e:
@@ -362,6 +377,12 @@ class AutomaticMetadataParser(RecipeMetadataParser):
                        # Only process lora or hypernet types
                        if not hash_key.startswith(("lora:", "hypernet:")):
                            continue
+                        
+                        # Skip entries without a hash value — they can't be
+                        # resolved via CivitAI and would only produce a
+                        # useless "Deleted" entry in the recipe.
+                        if not lora_hash:
+                            continue
                            
                        lora_type, lora_name = hash_key.split(':', 1)
                        
@@ -387,11 +408,7 @@ class AutomaticMetadataParser(RecipeMetadataParser):
                        # Try to get info from Civitai
                        if metadata_provider:
                            try:
-                                if lora_hash:
-                                    # If we have hash, use it for lookup
-                                    civitai_info = await metadata_provider.get_model_by_hash(lora_hash)
-                                else:
-                                    civitai_info = None
+                                civitai_info = await metadata_provider.get_model_by_hash(lora_hash)
                                
                                populated_entry = await self.populate_lora_from_civitai(
                                    lora_entry, 
@@ -4,8 +4,9 @@ import json
 import logging
 from typing import Dict, Any, Union
 from ..base import RecipeMetadataParser
-from ..constants import GEN_PARAM_KEYS
+from ..constants import GEN_PARAM_KEYS, VALID_LORA_TYPES
 from ...services.metadata_service import get_default_metadata_provider
+from ...config import config

 logger = logging.getLogger(__name__)

@@ -13,15 +14,16 @@ logger = logging.getLogger(__name__)
 class CivitaiApiMetadataParser(RecipeMetadataParser):
    """Parser for Civitai image metadata format"""

-    def is_metadata_matching(self, metadata) -> bool:
+    def is_metadata_matching(self, user_comment) -> bool:
        """Check if the metadata matches the Civitai image metadata format

        Args:
-            metadata: The metadata from the image (dict)
+            user_comment: The metadata from the image (dict)

        Returns:
            bool: True if this parser can handle the metadata
        """
+        metadata = user_comment
        if not metadata or not isinstance(metadata, dict):
            return False

@@ -72,8 +74,9 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):

        return False

-    async def parse_metadata(  # type: ignore[override]
-        self, user_comment, recipe_scanner=None, civitai_client=None
+    async def parse_metadata(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self, user_comment, recipe_scanner=None, civitai_client=None,
+        local_cache: dict[str, Any] | None = None,
    ) -> Dict[str, Any]:
        """Parse metadata from Civitai image format

@@ -81,12 +84,13 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
            user_comment: The metadata from the image (dict)
            recipe_scanner: Optional recipe scanner service
            civitai_client: Optional Civitai API client (deprecated, use metadata_provider instead)
+            local_cache: Optional dict mapping sha256/autov3 hash → scanner cache item.
+                         When provided, matching models skip CivitAI API calls.

        Returns:
            Dict containing parsed recipe data
        """
-        metadata: Dict[str, Any] = user_comment  # type: ignore[assignment]
-        metadata = user_comment
+        metadata: Dict[str, Any] = user_comment
        try:
            # Get metadata provider instead of using civitai_client directly
            metadata_provider = await get_default_metadata_provider()
@@ -112,7 +116,7 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
                    metadata = inner_meta

            # Initialize result structure
-            result = {
+            result: Dict[str, Any] = {
                "base_model": None,
                "loras": [],
                "model": None,
@@ -121,10 +125,10 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
            }

            # Track already added LoRAs to prevent duplicates
-            added_loras = {}  # key: model_version_id or hash, value: index in result["loras"]
+            added_loras: Dict[str, Any] = {}  # key: model_version_id or hash, value: index in result["loras"]

            # Extract hash information from hashes field for LoRA matching
-            lora_hashes = {}
+            lora_hashes: Dict[str, Any] = {}
            if "hashes" in metadata and isinstance(metadata["hashes"], dict):
                for key, hash_value in metadata["hashes"].items():
                    key_str = str(key)
@@ -180,13 +184,83 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
                            if model_info:
                                result["base_model"] = model_info.get("baseModel", "")

-            base_model_counts = {}
+            base_model_counts: Dict[str, int] = {}

            # Process standard resources array
            if "resources" in metadata and isinstance(metadata["resources"], list):
                for resource in metadata["resources"]:
+                    resource_type = resource.get("type", "lora")
+
+                    # Track resources with type "model" — these are checkpoint models.
+                    # The resources array is the most reliable source for checkpoint
+                    # identification because it has an explicit type field and hash,
+                    # unlike modelVersionIds which is a flat list with no type info.
+                    if resource_type == "model":
+                        checkpoint_entry: Dict[str, Any] = {
+                            "id": 0,
+                            "modelId": 0,
+                            "name": resource.get("name", "Unknown Model"),
+                            "version": "",
+                            "type": resource.get("type", "model"),
+                            "existsLocally": False,
+                            "localPath": None,
+                            "file_name": resource.get("name", ""),
+                            "hash": resource.get("hash", "") or "",
+                            "thumbnailUrl": "/loras_static/images/no-preview.png",
+                            "baseModel": "",
+                            "size": 0,
+                            "downloadUrl": "",
+                            "isDeleted": False,
+                        }
+
+                        # Try to look up base model from the checkpoint hash
+                        cp_hash = checkpoint_entry.get("hash")
+                        if cp_hash and metadata_provider:
+                            # local_cache keys are stored lowercase
+                            local_cached = local_cache.get(cp_hash.lower()) if local_cache else None
+                            if local_cached:
+                                self._populate_entry_from_cache(
+                                    checkpoint_entry, local_cached
+                                )
+                                bm = checkpoint_entry.get("baseModel", "")
+                                if bm and not result["base_model"]:
+                                    result["base_model"] = bm
+                            else:
+                                try:
+                                    civitai_info = (
+                                        await metadata_provider.get_model_by_hash(
+                                            cp_hash
+                                        )
+                                    )
+                                    civitai_data, error_msg = (
+                                        (civitai_info, None)
+                                        if not isinstance(civitai_info, tuple)
+                                        else civitai_info
+                                    )
+                                    if civitai_data and error_msg != "Model not found":
+                                        if 'model' in civitai_data and 'name' in civitai_data['model']:
+                                            checkpoint_entry['name'] = civitai_data['model']['name']
+                                        checkpoint_entry['id'] = civitai_data.get('id', 0)
+                                        checkpoint_entry['modelId'] = civitai_data.get('modelId', 0)
+                                        if 'name' in civitai_data:
+                                            checkpoint_entry['version'] = civitai_data['name']
+                                        base_model = civitai_data.get('baseModel', '')
+                                        if base_model:
+                                            checkpoint_entry['baseModel'] = base_model
+                                            if not result['base_model']:
+                                                result['base_model'] = base_model
+                                except Exception as e:
+                                    logger.error(
+                                        f"Error fetching checkpoint info for hash "
+                                        f"{cp_hash}: {e}"
+                                    )
+
+                        if result["model"] is None:
+                            result["model"] = checkpoint_entry
+                        continue
+
                    # Modified to process resources without a type field as potential LoRAs
-                    if resource.get("type", "lora") == "lora":
+                    if resource_type == "lora":
                        lora_hash = resource.get("hash", "")

                        # Try to get hash from the hashes field if not present in resource
@@ -220,34 +294,58 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
                        }

                        # Try to get info from Civitai if hash is available
-                        if lora_entry["hash"] and metadata_provider:
-                            try:
-                                civitai_info = (
-                                    await metadata_provider.get_model_by_hash(lora_hash)
+                        if lora_hash and metadata_provider:
+                            # local_cache keys are stored lowercase
+                            local_cached = local_cache.get(lora_hash.lower()) if local_cache else None
+                            if local_cached:
+                                cached_type = self._cache_item_model_type(local_cached)
+                                if cached_type and cached_type not in VALID_LORA_TYPES:
+                                    logger.debug(
+                                        f"Skipping non-LoRA cache item for hash {lora_hash}"
+                                    )
+                                    continue
+                                self._populate_entry_from_cache(
+                                    lora_entry, local_cached
                                )
-
-                                populated_entry = await self.populate_lora_from_civitai(
-                                    lora_entry,
-                                    civitai_info,
-                                    recipe_scanner,
-                                    base_model_counts,
-                                    lora_hash,
-                                )
-
-                                if populated_entry is None:
-                                    continue  # Skip invalid LoRA types
-
-                                lora_entry = populated_entry
-
-                                # If we have a version ID from Civitai, track it for deduplication
-                                if "id" in lora_entry and lora_entry["id"]:
+                                # Track by version ID for deduplication
+                                if lora_entry.get("id"):
                                    added_loras[str(lora_entry["id"])] = len(
                                        result["loras"]
                                    )
-                            except Exception as e:
-                                logger.error(
-                                    f"Error fetching Civitai info for LoRA hash {lora_entry['hash']}: {e}"
-                                )
+                                # Mirror base.py:150-151 counts for API-path loras
+                                bm = local_cached.get("base_model") or ""
+                                if bm:
+                                    base_model_counts[bm] = base_model_counts.get(
+                                        bm, 0
+                                    ) + 1
+                            else:
+                                try:
+                                    civitai_info = (
+                                        await metadata_provider.get_model_by_hash(lora_hash)
+                                    )
+
+                                    populated_entry = await self.populate_lora_from_civitai(
+                                        lora_entry,
+                                        civitai_info,
+                                        recipe_scanner,
+                                        base_model_counts,
+                                        lora_hash,
+                                    )
+
+                                    if populated_entry is None:
+                                        continue  # Skip invalid LoRA types
+
+                                    lora_entry = populated_entry
+
+                                    # If we have a version ID from Civitai, track it for deduplication
+                                    if "id" in lora_entry and lora_entry["id"]:
+                                        added_loras[str(lora_entry["id"])] = len(
+                                            result["loras"]
+                                        )
+                                except Exception as e:
+                                    logger.error(
+                                        f"Error fetching Civitai info for LoRA hash {lora_entry['hash']}: {e}"
+                                    )

                        # Track by hash if we have it
                        if lora_hash:
@@ -430,11 +528,21 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):

                        result["loras"].append(lora_entry)

-            # Process modelVersionIds from Civitai image API
-            # These are model version IDs returned at root level when meta doesn't contain resources
-            if "modelVersionIds" in metadata and isinstance(
-                metadata["modelVersionIds"], list
+            # Process modelVersionIds from Civitai image API.
+            # These are version IDs returned at root level of the API response.
+            # When resources or civitaiResources are already present in metadata
+            # (which they are when ?withMeta=true is passed), those sections have
+            # complete hash/type information — modelVersionIds is a fallback for
+            # when meta is null and only the flat ID list is available. Skipping
+            # it here avoids duplicates: the same file hash often resolves to
+            # different version IDs via hash lookup (resources) vs the original
+            # version ID in modelVersionIds, and both paths would create entries.
+            if (
+                "modelVersionIds" in metadata
+                and isinstance(metadata["modelVersionIds"], list)
+                and not result.get("loras")
            ):
+
                for version_id in metadata["modelVersionIds"]:
                    version_id_str = str(version_id)

@@ -442,6 +550,13 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
                    if version_id_str in added_loras:
                        continue

+                    # Skip if this version ID is already the recipe's checkpoint
+                    # (resolved earlier from embedded resources/Model hash,
+                    # avoiding a duplicate CivitAI API call).
+                    existing_model = result.get("model")
+                    if existing_model and str(existing_model.get("id")) == version_id_str:
+                        continue
+
                    # Initialize lora entry with version ID
                    lora_entry = {
                        "id": version_id,
@@ -475,9 +590,40 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
                            )

                            if populated_entry is None:
-                                continue  # Skip invalid LoRA types
+                                # Not a LoRA — try as checkpoint (only if we
+                                # don't already have one).  Reuses the same
+                                # civitai_info from the API call above so no
+                                # extra query is made.
+                                if result["model"] is None:
+                                    checkpoint_entry = {
+                                        "id": version_id,
+                                        "modelId": 0,
+                                        "name": "Unknown Model",
+                                        "version": "",
+                                        "type": "checkpoint",
+                                        "existsLocally": False,
+                                        "localPath": None,
+                                        "file_name": "",
+                                        "hash": "",
+                                        "thumbnailUrl": (
+                                            "/loras_static/images/no-preview.png"
+                                        ),
+                                        "baseModel": "",
+                                        "size": 0,
+                                        "downloadUrl": "",
+                                        "isDeleted": False,
+                                    }
+                                    cp_populated = await (
+                                        self.populate_checkpoint_from_civitai(
+                                            checkpoint_entry, civitai_info
+                                        )
+                                    )
+                                    if cp_populated.get("modelId"):
+                                        result["model"] = cp_populated
+                                continue  # Not a LoRA, don't add to loras

                            lora_entry = populated_entry
+
                        except Exception as e:
                            logger.error(
                                f"Error fetching Civitai info for model version {version_id}: {e}"
@@ -517,30 +663,47 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
                }

                if metadata_provider:
-                    try:
-                        civitai_info = await metadata_provider.get_model_by_hash(
-                            lora_hash
-                        )
-
-                        populated_entry = await self.populate_lora_from_civitai(
-                            lora_entry,
-                            civitai_info,
-                            recipe_scanner,
-                            base_model_counts,
-                            lora_hash,
-                        )
-
-                        if populated_entry is None:
+                    # local_cache keys are stored lowercase
+                    local_cached = local_cache.get(lora_hash.lower()) if local_cache else None
+                    if local_cached:
+                        cached_type = self._cache_item_model_type(local_cached)
+                        if cached_type and cached_type not in VALID_LORA_TYPES:
+                            logger.debug(
+                                f"Skipping non-LoRA cache item for hash {lora_hash}"
+                            )
                            continue
-
-                        lora_entry = populated_entry
-
+                        self._populate_entry_from_cache(lora_entry, local_cached)
+                        # Mirror base.py:150-151 counts for API-path loras
+                        bm = local_cached.get("base_model") or ""
+                        if bm:
+                            base_model_counts[bm] = base_model_counts.get(bm, 0) + 1
                        if "id" in lora_entry and lora_entry["id"]:
                            added_loras[str(lora_entry["id"])] = len(result["loras"])
-                    except Exception as e:
-                        logger.error(
-                            f"Error fetching Civitai info for LoRA hash {lora_hash}: {e}"
-                        )
+                    else:
+                        try:
+                            civitai_info = await metadata_provider.get_model_by_hash(
+                                lora_hash
+                            )
+
+                            populated_entry = await self.populate_lora_from_civitai(
+                                lora_entry,
+                                civitai_info,
+                                recipe_scanner,
+                                base_model_counts,
+                                lora_hash,
+                            )
+
+                            if populated_entry is None:
+                                continue
+
+                            lora_entry = populated_entry
+
+                            if "id" in lora_entry and lora_entry["id"]:
+                                added_loras[str(lora_entry["id"])] = len(result["loras"])
+                        except Exception as e:
+                            logger.error(
+                                f"Error fetching Civitai info for LoRA hash {lora_hash}: {e}"
+                            )

                added_loras[lora_hash] = len(result["loras"])
                result["loras"].append(lora_entry)
@@ -579,32 +742,51 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):

                # Try to get info from Civitai if hash is available
                if lora_entry["hash"] and metadata_provider:
-                    try:
-                        civitai_info = await metadata_provider.get_model_by_hash(
-                            lora_hash
-                        )
-
-                        populated_entry = await self.populate_lora_from_civitai(
-                            lora_entry,
-                            civitai_info,
-                            recipe_scanner,
-                            base_model_counts,
-                            lora_hash,
-                        )
-
-                        if populated_entry is None:
+                    # local_cache keys are stored lowercase
+                    local_cached = local_cache.get(lora_hash.lower()) if local_cache else None
+                    if local_cached:
+                        cached_type = self._cache_item_model_type(local_cached)
+                        if cached_type and cached_type not in VALID_LORA_TYPES:
+                            logger.debug(
+                                f"Skipping non-LoRA cache item for hash {lora_hash}"
+                            )
                            lora_index += 1
-                            continue  # Skip invalid LoRA types
-
-                        lora_entry = populated_entry
-
+                            continue  # Skip non-LoRA cache items
+                        self._populate_entry_from_cache(lora_entry, local_cached)
+                        # Mirror base.py:150-151 counts for API-path loras
+                        bm = local_cached.get("base_model") or ""
+                        if bm:
+                            base_model_counts[bm] = base_model_counts.get(bm, 0) + 1
                        # If we have a version ID from Civitai, track it for deduplication
                        if "id" in lora_entry and lora_entry["id"]:
                            added_loras[str(lora_entry["id"])] = len(result["loras"])
-                    except Exception as e:
-                        logger.error(
-                            f"Error fetching Civitai info for LoRA hash {lora_entry['hash']}: {e}"
-                        )
+                    else:
+                        try:
+                            civitai_info = await metadata_provider.get_model_by_hash(
+                                lora_hash
+                            )
+
+                            populated_entry = await self.populate_lora_from_civitai(
+                                lora_entry,
+                                civitai_info,
+                                recipe_scanner,
+                                base_model_counts,
+                                lora_hash,
+                            )
+
+                            if populated_entry is None:
+                                lora_index += 1
+                                continue  # Skip invalid LoRA types
+
+                            lora_entry = populated_entry
+
+                            # If we have a version ID from Civitai, track it for deduplication
+                            if "id" in lora_entry and lora_entry["id"]:
+                                added_loras[str(lora_entry["id"])] = len(result["loras"])
+                        except Exception as e:
+                            logger.error(
+                                f"Error fetching Civitai info for LoRA hash {lora_entry['hash']}: {e}"
+                            )

                # Track by hash if we have it
                if lora_hash:
@@ -625,3 +807,52 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
        except Exception as e:
            logger.error(f"Error parsing Civitai image metadata: {e}", exc_info=True)
            return {"error": str(e), "loras": []}
+
+    @staticmethod
+    def _populate_entry_from_cache(
+        entry: dict[str, Any],
+        cache_item: dict[str, Any],
+    ) -> None:
+        """Fill a lora/checkpoint entry from a scanner cache item.
+
+        Avoids CivitAI API calls for models that exist locally.
+        Mirrors the population logic in
+        ``RecipeMetadataParser.populate_lora_from_civitai()`` but operates
+        entirely on cached data.
+        """
+        civ = cache_item.get("civitai") or {}
+        if isinstance(civ, dict):
+            if civ.get("id") is not None:
+                entry["id"] = civ["id"]
+            if civ.get("modelId") is not None:
+                entry["modelId"] = civ["modelId"]
+            if civ.get("name"):
+                entry["version"] = civ["name"]
+            cached_name = cache_item.get("model_name")
+            if cached_name:
+                entry["name"] = cached_name
+        entry["existsLocally"] = True
+        local_path = cache_item.get("file_path")
+        if local_path:
+            entry["localPath"] = local_path
+        sha256 = cache_item.get("sha256")
+        if sha256:
+            entry["hash"] = sha256
+        if "preview_url" in cache_item:
+            entry["thumbnailUrl"] = config.get_preview_static_url(
+                cache_item["preview_url"]
+            )
+        base_model = cache_item.get("base_model", "")
+        if base_model:
+            entry["baseModel"] = base_model
+
+    @staticmethod
+    def _cache_item_model_type(cache_item: dict[str, Any]) -> str:
+        """Lowercased civitai.model.type of a cache item, or '' when unknown."""
+        civ = cache_item.get("civitai")
+        if not isinstance(civ, dict):
+            return ""
+        model_info = civ.get("model")
+        if not isinstance(model_info, dict):
+            return ""
+        return (model_info.get("type") or "").lower()
@@ -30,7 +30,7 @@ class MetaFormatParser(RecipeMetadataParser):
            prompt = parts[0].strip()
            
            # Initialize metadata
-            metadata = {"prompt": prompt, "loras": []}
+            metadata: Dict[str, Any] = {"prompt": prompt, "loras": []}
            
            # Extract negative prompt and parameters if available
            if len(parts) > 1:
@@ -91,7 +91,15 @@ class RecipeFormatParser(RecipeMetadataParser):
                        exists_locally = lora_scanner.has_hash(lora['hash'])
                        if exists_locally:
                            lora_cache = await lora_scanner.get_cached_data()
-                            lora_item = next((item for item in lora_cache.raw_data if item['sha256'].lower() == lora['hash'].lower()), None)
+                            # Cascade match: full sha256, stored autov3, or autov2 (sha256[:10]).
+                            h = (lora.get('hash') or '').lower()
+                            lora_item = next(
+                                (item for item in lora_cache.raw_data
+                                 if (item.get("sha256") or "").lower() == h
+                                 or (item.get("autov3") or "").lower() == h
+                                 or (item.get("sha256") or "")[:10].lower() == h),
+                                None
+                            )
                            if lora_item:
                                lora_entry['existsLocally'] = True
                                lora_entry['inLibrary'] = True
@@ -148,7 +156,7 @@ class RecipeFormatParser(RecipeMetadataParser):
            checkpoint_data = recipe_metadata.get('checkpoint') or {}
            if isinstance(checkpoint_data, dict) and checkpoint_data:
                version_id = checkpoint_data.get('modelVersionId') or checkpoint_data.get('id')
-                checkpoint_entry = {
+                checkpoint_entry: Dict[str, Any] = {
                    'id': version_id or 0,
                    'modelId': checkpoint_data.get('modelId', 0),
                    'name': checkpoint_data.get('name', 'Unknown Checkpoint'),
@@ -2,7 +2,7 @@ from __future__ import annotations

 import logging
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Callable, Dict, Mapping
+from typing import TYPE_CHECKING, Awaitable, Callable, Dict, Mapping

 import jinja2
 from aiohttp import web
@@ -30,6 +30,7 @@ from ..services.websocket_progress_callback import (
    WebSocketProgressCallback,
 )
 from ..utils.exif_utils import ExifUtils
+from ..utils.constants import MODEL_WEIGHT_FILE_TYPES
 from ..utils.metadata_manager import MetadataManager
 from .model_route_registrar import COMMON_ROUTE_DEFINITIONS, ModelRouteRegistrar
 from .handlers.model_handlers import (
@@ -84,7 +85,7 @@ class BaseModelRoutes(ABC):
        self.metadata_progress_callback = WebSocketBroadcastCallback()

        self._handler_set: ModelHandlerSet | None = None
-        self._handler_mapping: Dict[str, Callable[[web.Request], web.StreamResponse]] | None = None
+        self._handler_mapping: Dict[str, Callable[[web.Request], Awaitable[web.Response]]] | None = None

        self._preview_service = PreviewAssetService(
            metadata_manager=MetadataManager,
@@ -131,7 +132,7 @@ class BaseModelRoutes(ABC):
        self._handler_set = None
        self._handler_mapping = None

-    def _ensure_handler_mapping(self) -> Mapping[str, Callable[[web.Request], web.StreamResponse]]:
+    def _ensure_handler_mapping(self) -> Mapping[str, Callable[[web.Request], Awaitable[web.StreamResponse]]]:
        if self._handler_mapping is None:
            handler_set = self._create_handler_set()
            self._handler_set = handler_set
@@ -220,7 +221,7 @@ class BaseModelRoutes(ABC):
        )

    @property
-    def route_handlers(self) -> Mapping[str, Callable[[web.Request], web.StreamResponse]]:
+    def route_handlers(self) -> Mapping[str, Callable[[web.Request], Awaitable[web.StreamResponse]]]:
        return self._ensure_handler_mapping()

    def setup_routes(self, app: web.Application, prefix: str) -> None:
@@ -237,7 +238,7 @@ class BaseModelRoutes(ABC):
        """Setup model-specific routes."""
        raise NotImplementedError

-    def _parse_specific_params(self, request: web.Request) -> Dict:
+    def _parse_specific_params(self, request: web.Request) -> Dict[str, Any]:
        """Parse model-specific parameters - to be overridden by subclasses."""
        return {}

@@ -251,9 +252,9 @@ class BaseModelRoutes(ABC):

    def _find_model_file(self, files):
        """Find the appropriate model file from the files list - can be overridden by subclasses."""
-        return next((file for file in files if file.get("type") == "Model" and file.get("primary") is True), None)
+        return next((file for file in files if file.get("type") in MODEL_WEIGHT_FILE_TYPES and file.get("primary") is True), None)

-    def get_handler(self, name: str) -> Callable[[web.Request], web.StreamResponse]:
+    def get_handler(self, name: str) -> Callable[[web.Request], Awaitable[web.StreamResponse]]:
        """Expose handlers for subclasses or tests."""
        return self._ensure_handler_mapping()[name]

@@ -285,7 +286,7 @@ class BaseModelRoutes(ABC):
            )
        return self.model_lifecycle_service

-    def _make_handler_proxy(self, name: str) -> Callable[[web.Request], web.StreamResponse]:
+    def _make_handler_proxy(self, name: str) -> Callable[[web.Request], Awaitable[web.StreamResponse]]:
        async def proxy(request: web.Request) -> web.StreamResponse:
            try:
                handler = self.get_handler(name)
@@ -4,7 +4,7 @@ from __future__ import annotations

 import logging
 import os
-from typing import Callable, Mapping
+from typing import Awaitable, Callable, Mapping

 import jinja2
 from aiohttp import web
@@ -61,7 +61,9 @@ class BaseRecipeRoutes:
        self._i18n_registered = False
        self._startup_hooks_registered = False
        self._handler_set: RecipeHandlerSet | None = None
-        self._handler_mapping: dict[str, Callable] | None = None
+        self._handler_mapping: Mapping[
+            str, Callable[[web.Request], Awaitable[web.StreamResponse]]
+        ] | None = None

    async def attach_dependencies(self, app: web.Application | None = None) -> None:
        """Resolve shared services from the registry."""
@@ -84,7 +86,9 @@ class BaseRecipeRoutes:
        app.on_startup.append(self.attach_dependencies)
        self._startup_hooks_registered = True

-    def to_route_mapping(self) -> Mapping[str, Callable]:
+    def to_route_mapping(
+        self,
+    ) -> Mapping[str, Callable[[web.Request], Awaitable[web.StreamResponse]]]:
        """Return a mapping of handler name to coroutine for registrar binding."""

        if self._handler_mapping is None:
@@ -124,17 +128,17 @@ class BaseRecipeRoutes:
            or os.environ.get("HF_HUB_DISABLE_TELEMETRY", "0") == "0"
        )
        if not standalone_mode:
-            from ..metadata_collector import get_metadata  # type: ignore[import-not-found]
-            from ..metadata_collector.metadata_processor import (  # type: ignore[import-not-found]
+            from ..metadata_collector import get_metadata  # pyright: ignore[reportMissingImports]
+            from ..metadata_collector.metadata_processor import (  # pyright: ignore[reportMissingImports]
                MetadataProcessor,
            )
-            from ..metadata_collector.metadata_registry import (  # type: ignore[import-not-found]
+            from ..metadata_collector.metadata_registry import (  # pyright: ignore[reportMissingImports]
                MetadataRegistry,
            )
        else:  # pragma: no cover - optional dependency path
-            get_metadata = None  # type: ignore[assignment]
-            MetadataProcessor = None  # type: ignore[assignment]
-            MetadataRegistry = None  # type: ignore[assignment]
+            get_metadata = None  # pyright: ignore[reportAssignmentType]
+            MetadataProcessor = None  # pyright: ignore[reportAssignmentType]
+            MetadataRegistry = None  # pyright: ignore[reportAssignmentType]

        analysis_service = RecipeAnalysisService(
            exif_utils=ExifUtils,
@@ -1,5 +1,5 @@
 import logging
-from typing import Dict, List, Set
+from typing import Any, Dict, List, Set
 from aiohttp import web

 from .base_model_routes import BaseModelRoutes
@@ -28,13 +28,13 @@ class CheckpointRoutes(BaseModelRoutes):
        # Attach service dependencies
        self.attach_service(self.service)
    
-    def setup_routes(self, app: web.Application):
+    def setup_routes(self, app: web.Application, prefix: str = "checkpoints"):
        """Setup Checkpoint routes"""
        # Schedule service initialization on app startup
        app.on_startup.append(lambda _: self.initialize_services())
-        
+
        # Setup common routes with 'checkpoints' prefix (includes page route)
-        super().setup_routes(app, 'checkpoints')
+        super().setup_routes(app, prefix)
    
    def setup_specific_routes(self, registrar: ModelRouteRegistrar, prefix: str):
        """Setup Checkpoint-specific routes"""
@@ -53,9 +53,9 @@ class CheckpointRoutes(BaseModelRoutes):
        """Get expected model types string for error messages"""
        return "Checkpoint"

-    def _parse_specific_params(self, request: web.Request) -> Dict:
+    def _parse_specific_params(self, request: web.Request) -> Dict[str, Any]:
        """Parse Checkpoint-specific parameters"""
-        params: Dict = {}
+        params: Dict[str, Any] = {}

        if 'checkpoint_hash' in request.query:
            params['hash_filters'] = {'single_hash': request.query['checkpoint_hash'].lower()}
@@ -70,7 +70,7 @@ class CheckpointRoutes(BaseModelRoutes):
        """Get detailed information for a specific checkpoint by name"""
        try:
            name = request.match_info.get('name', '')
-            checkpoint_info = await self.service.get_model_info_by_name(name)
+            checkpoint_info = await self.service.get_model_info_by_name(name)  # pyright: ignore[reportAttributeAccessIssue]
            
            if checkpoint_info:
                return web.json_response(checkpoint_info)
@@ -89,7 +89,7 @@ class CheckpointRoutes(BaseModelRoutes):
            roots.extend(config.checkpoints_roots or [])
            roots.extend(config.extra_checkpoints_roots or [])
            # Remove duplicates while preserving order
-            seen: set = set()
+            seen: set[str] = set()
            unique_roots: List[str] = []
            for root in roots:
                if root and root not in seen:
@@ -114,7 +114,7 @@ class CheckpointRoutes(BaseModelRoutes):
            roots.extend(config.unet_roots or [])
            roots.extend(config.extra_unet_roots or [])
            # Remove duplicates while preserving order
-            seen: set = set()
+            seen: set[str] = set()
            unique_roots: List[str] = []
            for root in roots:
                if root and root not in seen:
@@ -26,13 +26,13 @@ class EmbeddingRoutes(BaseModelRoutes):
        # Attach service dependencies
        self.attach_service(self.service)
    
-    def setup_routes(self, app: web.Application):
+    def setup_routes(self, app: web.Application, prefix: str = "embeddings"):
        """Setup Embedding routes"""
        # Schedule service initialization on app startup
        app.on_startup.append(lambda _: self.initialize_services())
-        
+
        # Setup common routes with 'embeddings' prefix (includes page route)
-        super().setup_routes(app, 'embeddings')
+        super().setup_routes(app, prefix)
    
    def setup_specific_routes(self, registrar: ModelRouteRegistrar, prefix: str):
        """Setup Embedding-specific routes"""
@@ -51,7 +51,7 @@ class EmbeddingRoutes(BaseModelRoutes):
        """Get detailed information for a specific embedding by name"""
        try:
            name = request.match_info.get('name', '')
-            embedding_info = await self.service.get_model_info_by_name(name)
+            embedding_info = await self.service.get_model_info_by_name(name)  # pyright: ignore[reportAttributeAccessIssue]
            
            if embedding_info:
                return web.json_response(embedding_info)
@@ -1,7 +1,7 @@
 from __future__ import annotations

 import logging
-from typing import Callable, Mapping
+from typing import Any, Awaitable, Callable, Mapping

 from aiohttp import web

@@ -35,7 +35,7 @@ class ExampleImagesRoutes:
        *,
        ws_manager,
        download_manager: DownloadManager | None = None,
-        processor=ExampleImagesProcessor,
+        processor: Any = ExampleImagesProcessor,
        file_manager=ExampleImagesFileManager,
        cleanup_service: ExampleImagesCleanupService | None = None,
    ) -> None:
@@ -46,7 +46,9 @@ class ExampleImagesRoutes:
        self._file_manager = file_manager
        self._cleanup_service = cleanup_service or ExampleImagesCleanupService()
        self._handler_set: ExampleImagesHandlerSet | None = None
-        self._handler_mapping: Mapping[str, Callable[[web.Request], web.StreamResponse]] | None = None
+        self._handler_mapping: Mapping[
+            str, Callable[[web.Request], Awaitable[web.StreamResponse]]
+        ] | None = None

    @classmethod
    def setup_routes(cls, app: web.Application, *, ws_manager) -> None:
@@ -61,7 +63,9 @@ class ExampleImagesRoutes:
        registrar = ExampleImagesRouteRegistrar(app)
        registrar.register_routes(self.to_route_mapping())

-    def to_route_mapping(self) -> Mapping[str, Callable[[web.Request], web.StreamResponse]]:
+    def to_route_mapping(
+        self,
+    ) -> Mapping[str, Callable[[web.Request], Awaitable[web.StreamResponse]]]:
        """Return the registrar-compatible mapping of handler names to callables."""

        if self._handler_mapping is None:
@@ -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,
+        )
@@ -3,7 +3,7 @@ from __future__ import annotations

 import logging
 from dataclasses import dataclass
-from typing import Callable, Mapping
+from typing import Awaitable, Callable, Mapping

 from aiohttp import web

@@ -170,7 +170,7 @@ class ExampleImagesHandlerSet:
    management: ExampleImagesManagementHandler
    files: ExampleImagesFileHandler

-    def to_route_mapping(self) -> Mapping[str, Callable[[web.Request], web.StreamResponse]]:
+    def to_route_mapping(self) -> Mapping[str, Callable[[web.Request], Awaitable[web.StreamResponse]]]:
        """Flatten handler methods into the registrar mapping."""

        return {
@@ -0,0 +1,508 @@
+"""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
+
+        metadata_dict = metadata.to_dict()
+        if "trainedWords" in metadata_dict and not metadata_dict["trainedWords"]:
+            del metadata_dict["trainedWords"]
+
+        # 3. Save metadata atomically
+        await MetadataManager.save_metadata(dest_path, metadata_dict)
+        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)
+
+
+def _find_matching_root(dest_dir: str) -> str | None:
+    """Walk up *dest_dir* to find which configured scanner root it belongs to."""
+    norm = os.path.normpath(dest_dir).replace(os.sep, "/")
+    all_roots = []
+    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 [],
+    ):
+        all_roots.extend([os.path.normpath(p).replace(os.sep, "/") for p in root_list])
+    # Find the longest matching prefix
+    match: str | None = None
+    for root in all_roots:
+        if norm.startswith(root):
+            if match is None or len(root) > len(match):
+                match = root
+    return match
+
+
+async def _add_to_scanner_cache(dest_path: str, metadata: dict[str, Any]) -> None:
+    model_dir = os.path.dirname(dest_path)
+    model_root = _find_matching_root(model_dir)
+    if not model_root:
+        raise ValueError(f"File path {dest_path} is not within any configured scanner root")
+    scanner_getter_name = _infer_model_type(model_root)[1]
+    scanner_getter = getattr(ServiceRegistry, scanner_getter_name, None)
+    if scanner_getter is None:
+        raise RuntimeError(f"Scanner getter '{scanner_getter_name}' not found in ServiceRegistry")
+    scanner = await scanner_getter()
+    if scanner is None:
+        raise RuntimeError(f"Scanner '{scanner_getter_name}' returned None")
+    await scanner.update_single_model_cache(dest_path, dest_path, metadata)
+
+
+class HfHandler:
+    """Handle Hugging Face model browsing and download."""
+
+    async def set_hf_url(self, request: web.Request) -> web.Response:
+        try:
+            payload: dict[str, Any] = await request.json()
+        except json.JSONDecodeError:
+            return web.json_response({"success": False, "error": "Invalid JSON"}, status=400)
+
+        file_path = (payload.get("file_path") or "").strip()
+        hf_url = (payload.get("hf_url") or "").strip()
+
+        if not file_path or not hf_url:
+            return web.json_response(
+                {"success": False, "error": "Missing required fields: 'file_path' and 'hf_url'"},
+                status=400,
+            )
+
+        m = re.match(r"^https?://huggingface\.co/([^/]+/[^/]+)/?$", hf_url)
+        if not m:
+            return web.json_response(
+                {
+                    "success": False,
+                    "error": "Invalid HuggingFace URL. Expected format: https://huggingface.co/user/repo",
+                },
+                status=400,
+            )
+
+        if not os.path.isfile(file_path):
+            return web.json_response(
+                {"success": False, "error": f"File not found: {file_path}"},
+                status=404,
+            )
+
+        model_root = _find_matching_root(os.path.dirname(file_path))
+        if not model_root:
+            return web.json_response(
+                {
+                    "success": False,
+                    "error": "File is not within any configured model directory. Cannot link to HuggingFace.",
+                },
+                status=400,
+            )
+
+        try:
+            existing = await MetadataManager.load_metadata_payload(file_path)
+            if existing.get("hf_url") == hf_url:
+                return web.json_response({
+                    "success": True,
+                    "message": "hf_url already set",
+                    "hf_url": hf_url,
+                })
+
+            existing["hf_url"] = hf_url
+            existing["from_civitai"] = False
+            await MetadataManager.save_metadata(file_path, existing)
+
+            await _add_to_scanner_cache(file_path, existing)
+
+            logger.info("Set hf_url=%s for %s", hf_url, file_path)
+            return web.json_response({
+                "success": True,
+                "message": f"hf_url set to {hf_url}",
+                "hf_url": hf_url,
+            })
+        except Exception as exc:
+            logger.error("Failed to set hf_url for %s: %s", file_path, exc)
+            return web.json_response(
+                {"success": False, "error": str(exc)},
+                status=500,
+            )
+
+    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 traversal
+        if ".." 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)
+
+        # Use model_root directly as the base directory — same approach as
+        # CivitAI's download path (download_manager.py).  No realpath, no
+        # allowed-roots validation, no path-traversal check; those are
+        # unnecessary when the frontend sends the path from its own dropdown
+        # (populated from scanner roots).  Using the "business path" directly
+        # keeps dest_path consistent with scanner roots so that later folder
+        # derivation (in _save_hf_metadata) works correctly.
+        if os.path.isabs(model_root):
+            base_dir = os.path.normpath(model_root)
+        else:
+            base_dir = os.path.normpath(os.path.join(os.getcwd(), "models", 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
+
+        # Strip HF repo subdirectory — "diffusion_models/xxx.safetensors"
+        # is an HF repo convention, not meaningful for local storage.
+        file_base = os.path.basename(filename)
+
+        os.makedirs(target_dir, exist_ok=True)
+        dest_path = os.path.join(target_dir, file_base)
+
+        # 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
+            )
@@ -0,0 +1,323 @@
+"""Handler for the pending-delete undo endpoint.
+
+Restores a staged delete batch (models or recipes) via
+``PendingDeleteService.undo`` and then repairs the affected library caches:
+the model cache entry is restored from the manifest's ``model_snapshot``
+(including the version index and hash index), tag counts are re-incremented,
+and the recipe cache is re-populated via ``RecipeScanner.add_recipe``.
+
+The per-type scanner is resolved from the manifest's ``model_type`` page value
+through the SAME ServiceRegistry getters the model route registrars use
+(lora/checkpoint/embedding) - never a hardcoded lora scanner.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import logging
+import os
+import re
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Set, cast
+
+from aiohttp import web
+
+from ...services.pending_delete_service import get_pending_delete_service
+from .model_handlers import _broadcast_models_changed
+
+logger = logging.getLogger(__name__)
+
+# Manifest ``model_type`` page values -> ServiceRegistry scanner getter names.
+# The model route registrars resolve per-type scanners via these getters
+# (lora_routes / checkpoint_routes / embedding_routes); undo must do the same
+# so the CORRECT cache is restored for the deleted model's type.
+_MODEL_TYPE_GETTER_NAMES: Dict[str, str] = {
+    "loras": "get_lora_scanner",
+    "checkpoints": "get_checkpoint_scanner",
+    "embeddings": "get_embedding_scanner",
+}
+
+# Staged batch ids are ``uuid.uuid4().hex`` (32 lowercase hex chars). The id is
+# joined into filesystem paths by ``_find_batch_dir``, so reject anything that
+# does not match this exact shape (blocks path-traversal via batch_id).
+_BATCH_ID_RE = re.compile(r"^[0-9a-f]{32}$")
+
+
+class PendingDeleteHandler:
+    """Handle undo requests for staged model/recipe deletions."""
+
+    def __init__(
+        self,
+        *,
+        service_factory: Callable[[], Awaitable[Any]] = get_pending_delete_service,
+        scanner_getter: Optional[Callable[[str], Awaitable[Any]]] = None,
+        recipe_scanner_getter: Optional[Callable[[], Awaitable[Any]]] = None,
+    ) -> None:
+        self._service_factory: Callable[[], Awaitable[Any]] = service_factory
+        self._scanner_getter: Callable[[str], Awaitable[Any]] = (
+            scanner_getter or self._resolve_scanner
+        )
+        self._recipe_scanner_getter: Callable[[], Awaitable[Any]] = (
+            recipe_scanner_getter or self._resolve_recipe_scanner
+        )
+
+    @staticmethod
+    async def _resolve_scanner(model_type: str) -> Any:
+        """Resolve the per-type scanner for a manifest ``model_type``.
+
+        The getter is looked up on the ServiceRegistry module namespace at call
+        time so tests (and the registry stubs) can patch it.
+        """
+        from ...services import service_registry
+
+        getter_name = _MODEL_TYPE_GETTER_NAMES.get(model_type)
+        if getter_name is None:
+            raise ValueError(f"Unknown model type: {model_type}")
+        getter = getattr(service_registry.ServiceRegistry, getter_name, None)
+        if not callable(getter):
+            raise ValueError(f"No scanner getter for model type: {model_type}")
+        scanner = await cast(Callable[[], Awaitable[Any]], getter)()
+        if scanner is None:
+            raise ValueError(f"No scanner registered for model type: {model_type}")
+        return scanner
+
+    @staticmethod
+    async def _resolve_recipe_scanner() -> Any:
+        """Resolve the recipe scanner via the ServiceRegistry module namespace."""
+        from ...services import service_registry
+
+        getter = getattr(service_registry.ServiceRegistry, "get_recipe_scanner", None)
+        if not callable(getter):
+            raise ValueError("Recipe scanner getter unavailable")
+        scanner = await cast(Callable[[], Awaitable[Any]], getter)()
+        if scanner is None:
+            raise ValueError("No recipe scanner registered")
+        return scanner
+
+    async def undo_delete(self, request: web.Request) -> web.Response:
+        """Restore a staged batch and its library cache entry.
+
+        Body: ``{"batch_id": str}``. On success returns
+        ``{"success": True, "restored": [<original paths>], "kind": kind}``.
+        Expired/unknown batches and occupied target paths -> 404.
+        """
+        try:
+            data = await request.json()
+        except Exception:
+            return web.json_response(
+                {"success": False, "error": "Invalid JSON body"}, status=400
+            )
+        if not isinstance(data, dict):
+            return web.json_response(
+                {"success": False, "error": "Invalid JSON body"}, status=400
+            )
+        batch_id = data.get("batch_id")
+        if not batch_id or not isinstance(batch_id, str):
+            return web.json_response(
+                {"success": False, "error": "batch_id is required"}, status=400
+            )
+        if not _BATCH_ID_RE.fullmatch(batch_id):
+            # batch_id is joined into a path by _find_batch_dir - restrict to
+            # the exact staged-id shape so traversal payloads get 400.
+            return web.json_response(
+                {"success": False, "error": "Invalid batch_id"}, status=400
+            )
+
+        service = await self._service_factory()
+        try:
+            # Read the manifest BEFORE undo: undo() removes the batch dir.
+            manifest = await self._read_staged_manifest(service, batch_id)
+            result = await service.undo(batch_id)
+        except ValueError as exc:
+            return web.json_response({"success": False, "error": str(exc)}, status=404)
+        except Exception as exc:
+            logger.error("Unexpected error undoing batch %s: %s", batch_id, exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+        kind = result.get("kind")
+        try:
+            if kind == "model":
+                if manifest is not None:
+                    await self._restore_model_cache(manifest)
+                else:
+                    # undo() raises when the manifest is missing, so this only
+                    # happens defensively - files are restored regardless.
+                    logger.warning(
+                        "Manifest missing after undo of %s; skipping cache restore",
+                        batch_id,
+                    )
+                _broadcast_models_changed()
+            elif kind == "recipe":
+                # Recipe undo is client-refresh only: re-add to the scanner
+                # cache, no models_changed broadcast.
+                if manifest is not None:
+                    await self._restore_recipe_cache(result, manifest)
+                else:
+                    logger.warning(
+                        "Manifest missing after undo of %s; skipping cache restore",
+                        batch_id,
+                    )
+        except Exception as exc:
+            # Files are already restored; only the cache restoration failed.
+            logger.error(
+                "Cache restoration failed after undo of %s: %s",
+                batch_id,
+                exc,
+                exc_info=True,
+            )
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+        return web.json_response(
+            {
+                "success": True,
+                "restored": result.get("restored", []),
+                "kind": kind,
+            }
+        )
+
+    @staticmethod
+    async def _read_staged_manifest(
+        service: Any, batch_id: str
+    ) -> Optional[Dict[str, Any]]:
+        """Locate and read the batch manifest while it still exists on disk."""
+        batch_dir = await service._find_batch_dir(batch_id)
+        if not batch_dir:
+            return None
+        manifest_path = os.path.join(batch_dir, "manifest.json")
+        try:
+            with open(manifest_path, "r", encoding="utf-8") as handle:
+                payload = json.load(handle)
+        except (OSError, json.JSONDecodeError) as exc:
+            logger.debug("Failed to read manifest for batch %s: %s", batch_id, exc)
+            return None
+        return payload if isinstance(payload, dict) else None
+
+    async def _restore_model_cache(self, manifest: Dict[str, Any]) -> None:
+        """Re-add every deleted model's cache entry from the manifest.
+
+        Each main-file entry carries the deleted model's ``snapshot`` (added at
+        stage time), so a merged bulk manifest holds ALL snapshots - undo must
+        restore every one, not just the top-level winner's. Old-format
+        manifests without entry snapshots fall back to the top-level
+        ``model_snapshot`` (backward compat / single-delete path).
+        """
+        model_type = manifest.get("model_type")
+        if not model_type or not isinstance(model_type, str):
+            raise ValueError(f"Manifest carries no model_type: {manifest.get('batch_id')}")
+        scanner = await self._scanner_getter(model_type)
+
+        # Collect one snapshot per distinct file_path from the entry snapshots.
+        snapshots: List[Dict[str, Any]] = []
+        seen: Set[str] = set()
+        for entry in manifest.get("entries") or []:
+            snapshot = entry.get("snapshot")
+            if not isinstance(snapshot, dict):
+                continue
+            file_path = snapshot.get("file_path")
+            if not file_path or not isinstance(file_path, str):
+                continue
+            if file_path in seen:
+                continue
+            seen.add(file_path)
+            snapshots.append(snapshot)
+
+        if not snapshots:
+            # Backward compat: pre-F3 manifests carry only the top-level
+            # model_snapshot (single-delete path, unchanged behavior).
+            top = manifest.get("model_snapshot")
+            if isinstance(top, dict) and top.get("file_path"):
+                snapshots = [top]
+            else:
+                logger.warning(
+                    "Manifest %s has no restorable model snapshot; skipping cache restore",
+                    manifest.get("batch_id"),
+                )
+                return
+
+        cache = await scanner.get_cached_data()
+        if cache is None:
+            logger.warning(
+                "Scanner cache unavailable for %s; skipping cache restore", model_type
+            )
+            return
+
+        for snapshot in snapshots:
+            file_path = str(snapshot["file_path"])
+            # A rescan between delete and undo may have re-added a stale entry
+            # for this path - drop it so exactly one (the snapshot) remains.
+            cache.raw_data = [
+                item for item in cache.raw_data if item.get("file_path") != file_path
+            ]
+
+            # Restore tag counts (mirror of the bulk-delete decrement in
+            # _batch_update_cache_for_deleted_models: undo re-increments).
+            tags = snapshot.get("tags")
+            if isinstance(tags, list):
+                for tag in tags:
+                    if not isinstance(tag, str) or not tag:
+                        continue
+                    scanner._tags_count[tag] = scanner._tags_count.get(tag, 0) + 1
+
+            cache.raw_data.append(dict(snapshot))
+
+            # Re-register the path in the hash index (add_entry guards a
+            # missing sha256 internally; still guard defensively here).
+            sha256 = snapshot.get("sha256") or ""
+            autov3 = snapshot.get("autov3")
+            hash_index = getattr(scanner, "_hash_index", None)
+            if hash_index is not None and sha256 and file_path:
+                hash_index.add_entry(sha256, file_path, autov3)
+
+        # Follow the bulk-delete cache-update pattern ONCE after all entries,
+        # including the explicit version-index rebuild so the version index
+        # does not go stale.
+        cache.rebuild_version_index()
+        await cache.resort()
+
+        scanner.bump_cache_version()
+
+        persist = getattr(scanner, "_persist_current_cache", None)
+        if callable(persist):
+            result = persist()
+            if inspect.isawaitable(result):
+                await result
+
+    async def _restore_recipe_cache(
+        self, result: Dict[str, Any], manifest: Dict[str, Any]
+    ) -> None:
+        """Re-add a restored recipe via ``RecipeScanner.add_recipe``.
+
+        The recipe JSON embeds the full recipe_data (incl. id/file_path);
+        ``add_recipe`` only READS the ``_json_path_map`` so the forced frontend
+        refresh self-heals any transient path-map gap.
+        """
+        restored = result.get("restored") or []
+        json_path = next(
+            (p for p in restored if isinstance(p, str) and p.endswith(".json")),
+            None,
+        )
+        if not json_path or not os.path.exists(json_path):
+            # Defensive fallback to the manifest's recipe_snapshot file_path.
+            snapshot = manifest.get("recipe_snapshot") or {}
+            fallback = snapshot.get("file_path")
+            if fallback and os.path.exists(fallback):
+                json_path = fallback
+            else:
+                logger.warning(
+                    "Restored recipe JSON not found in %s; skipping cache restore",
+                    restored,
+                )
+                return
+        try:
+            with open(json_path, "r", encoding="utf-8") as handle:
+                recipe_data = json.load(handle)
+        except (OSError, json.JSONDecodeError) as exc:
+            logger.warning("Failed to load restored recipe JSON %s: %s", json_path, exc)
+            return
+        if not isinstance(recipe_data, dict):
+            return
+        recipe_scanner = await self._recipe_scanner_getter()
+        await recipe_scanner.add_recipe(recipe_data)
+
+
+__all__ = ["PendingDeleteHandler"]
@@ -2,7 +2,9 @@

 from __future__ import annotations

+import asyncio
 import logging
+import mimetypes
 import urllib.parse
 from pathlib import Path

@@ -12,6 +14,12 @@ from ...config import config as global_config

 logger = logging.getLogger(__name__)

+_CHUNK_SIZE = 1024 * 1024  # 1 MB — balance between streaming iteration overhead and per-chunk memory
+
+# Video file extensions that bypass native sendfile on Windows
+# to avoid IOCP/ProactorEventLoop crashes during client disconnect.
+_VIDEO_EXTENSIONS = frozenset({".mp4", ".webm", ".mov", ".avi", ".mkv"})
+

 class PreviewHandler:
    """Serve preview assets for the active library at request time."""
@@ -46,10 +54,90 @@ class PreviewHandler:

        if not resolved.is_file():
            logger.debug("Preview file not found at %s", str(resolved))
+            asyncio.create_task(self._cleanup_stale_preview_url(normalized))
            raise web.HTTPNotFound(text="Preview file not found")

-        # aiohttp's FileResponse handles range requests and content headers for us.
-        return web.FileResponse(path=resolved, chunk_size=256 * 1024)
+        # aiohttp's FileResponse handles range requests, content headers, and
+        # uses kernel sendfile (zero-copy DMA) on Linux/macOS. On Windows it
+        # uses IOCP-based _sendfile_native which can crash when the client
+        # disconnects mid-transfer during fast scrolling. The _stream_file()
+        # fallback is kept for a future compat toggle.
+        #
+        # Set explicit Cache-Control so the browser can cache video (and image)
+        # previews across VirtualScroller recycling cycles. Without this,
+        # Chrome does not cache 206 Partial Content responses for <video>
+        # elements, causing the same video to be re-downloaded on every scroll.
+        resp = web.FileResponse(path=resolved, chunk_size=_CHUNK_SIZE)
+        resp.headers["Cache-Control"] = "public, max-age=86400"
+        return resp
+
+    async def _cleanup_stale_preview_url(self, normalized_preview_path: str) -> None:
+        """Fire-and-forget: clear stale preview_url from all model caches.
+
+        When a preview file is no longer on disk, remove its reference from
+        every cached entry so subsequent list API responses return an empty
+        ``preview_url``, letting the frontend show the no-preview placeholder.
+        """
+        try:
+            from ...services.service_registry import ServiceRegistry
+
+            for service_name in ("lora_scanner", "checkpoint_scanner", "embedding_scanner"):
+                scanner = ServiceRegistry.get_service_sync(service_name)
+                if scanner is None or not hasattr(scanner, "_cache"):
+                    continue
+                cache = getattr(scanner, "_cache", None)
+                if cache is None or not hasattr(cache, "clear_preview_by_path"):
+                    continue
+                cleared = await cache.clear_preview_by_path(normalized_preview_path)
+                if cleared and hasattr(scanner, "_persist_current_cache"):
+                    await scanner._persist_current_cache()
+                    logger.info(
+                        "Cleared stale preview_url for %d %s entries (%s)",
+                        cleared,
+                        service_name,
+                        normalized_preview_path,
+                    )
+        except Exception as exc:
+            logger.debug("Failed to clean up stale preview_url: %s", exc)
+
+    async def _stream_file(
+        self, request: web.Request, path: Path
+    ) -> web.StreamResponse:
+        """Stream a file chunk-by-chunk, bypassing native sendfile.
+
+        This avoids the Windows IOCP ``_sendfile_native`` crash that occurs
+        when the client disconnects during a large file transfer.
+        """
+        content_type, _ = mimetypes.guess_type(str(path))
+        if content_type is None:
+            content_type = "application/octet-stream"
+
+        file_size = path.stat().st_size
+        resp = web.StreamResponse()
+        resp.content_type = content_type
+        resp.content_length = file_size
+
+        # Allow browser caching: video previews rarely change during a session.
+        # The frontend already appends ?t={version} to bust cache on update.
+        resp.headers["Cache-Control"] = "public, max-age=86400"
+
+        await resp.prepare(request)
+
+        try:
+            with open(path, "rb") as f:
+                while True:
+                    chunk = f.read(_CHUNK_SIZE)
+                    if not chunk:
+                        break
+                    await resp.write(chunk)
+        except (ConnectionResetError, ConnectionAbortedError):
+            # Client disconnected during streaming — expected when scrolling
+            # rapidly through a library with animated previews.
+            pass
+        except OSError as exc:
+            logger.debug("I/O error streaming preview %s: %s", path, exc)
+
+        return resp


 __all__ = ["PreviewHandler"]
@@ -1,8 +1,8 @@
 import asyncio
 import logging
 from aiohttp import web
-from typing import Dict
-from server import PromptServer  # type: ignore
+from typing import Any, Dict
+from server import PromptServer  # pyright: ignore[reportMissingImports]

 from .base_model_routes import BaseModelRoutes
 from .model_route_registrar import ModelRouteRegistrar
@@ -31,13 +31,13 @@ class LoraRoutes(BaseModelRoutes):
        # Attach service dependencies
        self.attach_service(self.service)

-    def setup_routes(self, app: web.Application):
+    def setup_routes(self, app: web.Application, prefix: str = "loras"):
        """Setup LoRA routes"""
        # Schedule service initialization on app startup
        app.on_startup.append(lambda _: self.initialize_services())

        # Setup common routes with 'loras' prefix (includes page route)
-        super().setup_routes(app, "loras")
+        super().setup_routes(app, prefix)

    def setup_specific_routes(self, registrar: ModelRouteRegistrar, prefix: str):
        """Setup LoRA-specific routes"""
@@ -73,7 +73,7 @@ class LoraRoutes(BaseModelRoutes):
            "POST", "/api/lm/{prefix}/get_trigger_words", prefix, self.get_trigger_words
        )

-    def _parse_specific_params(self, request: web.Request) -> Dict:
+    def _parse_specific_params(self, request: web.Request) -> Dict[str, Any]:
        """Parse LoRA-specific parameters"""
        params = {}

@@ -119,25 +119,6 @@ class LoraRoutes(BaseModelRoutes):
            logger.error(f"Error getting letter counts: {e}")
            return web.json_response({"success": False, "error": str(e)}, status=500)

-    async def get_lora_notes(self, request: web.Request) -> web.Response:
-        """Get notes for a specific LoRA file"""
-        try:
-            lora_name = request.query.get("name")
-            if not lora_name:
-                return web.Response(text="Lora file name is required", status=400)
-
-            notes = await self.service.get_lora_notes(lora_name)
-            if notes is not None:
-                return web.json_response({"success": True, "notes": notes})
-            else:
-                return web.json_response(
-                    {"success": False, "error": "LoRA not found in cache"}, status=404
-                )
-
-        except Exception as e:
-            logger.error(f"Error getting lora notes: {e}", exc_info=True)
-            return web.json_response({"success": False, "error": str(e)}, status=500)
-
    async def get_lora_trigger_words(self, request: web.Request) -> web.Response:
        """Get trigger words for a specific LoRA file"""
        try:
@@ -168,52 +149,6 @@ class LoraRoutes(BaseModelRoutes):
            logger.error(f"Error getting lora usage tips by path: {e}", exc_info=True)
            return web.json_response({"success": False, "error": str(e)}, status=500)

-    async def get_lora_preview_url(self, request: web.Request) -> web.Response:
-        """Get the static preview URL for a LoRA file"""
-        try:
-            lora_name = request.query.get("name")
-            if not lora_name:
-                return web.Response(text="Lora file name is required", status=400)
-
-            preview_url = await self.service.get_lora_preview_url(lora_name)
-            if preview_url:
-                return web.json_response({"success": True, "preview_url": preview_url})
-            else:
-                return web.json_response(
-                    {
-                        "success": False,
-                        "error": "No preview URL found for the specified lora",
-                    },
-                    status=404,
-                )
-
-        except Exception as e:
-            logger.error(f"Error getting lora preview URL: {e}", exc_info=True)
-            return web.json_response({"success": False, "error": str(e)}, status=500)
-
-    async def get_lora_civitai_url(self, request: web.Request) -> web.Response:
-        """Get the Civitai URL for a LoRA file"""
-        try:
-            lora_name = request.query.get("name")
-            if not lora_name:
-                return web.Response(text="Lora file name is required", status=400)
-
-            result = await self.service.get_lora_civitai_url(lora_name)
-            if result["civitai_url"]:
-                return web.json_response({"success": True, **result})
-            else:
-                return web.json_response(
-                    {
-                        "success": False,
-                        "error": "No Civitai data found for the specified lora",
-                    },
-                    status=404,
-                )
-
-        except Exception as e:
-            logger.error(f"Error getting lora Civitai URL: {e}", exc_info=True)
-            return web.json_response({"success": False, "error": str(e)}, status=500)
-
    async def get_random_loras(self, request: web.Request) -> web.Response:
        """Get random LoRAs based on filters and strength ranges"""
        try:
@@ -337,7 +272,7 @@ class LoraRoutes(BaseModelRoutes):
                    graph_identifier = entry.get("graph_id")

                try:
-                    parsed_node_id = int(node_identifier)
+                    parsed_node_id = int(node_identifier)  # pyright: ignore[reportArgumentType]
                except (TypeError, ValueError):
                    parsed_node_id = node_identifier

@@ -5,7 +5,7 @@ miscellaneous endpoints share a consistent registration flow.
 """

 from dataclasses import dataclass
-from typing import Callable, Iterable, Mapping
+from typing import Any, Callable, Iterable, Mapping

 from aiohttp import web

@@ -22,8 +22,11 @@ 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"),
    RouteDefinition("POST", "/api/lm/doctor/export-bundle", "export_doctor_bundle"),
    RouteDefinition("GET", "/api/lm/priority-tags", "get_priority_tags"),
    RouteDefinition("GET", "/api/lm/settings/libraries", "get_settings_libraries"),
@@ -36,12 +39,15 @@ MISC_ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
    RouteDefinition("POST", "/api/lm/update-usage-stats", "update_usage_stats"),
    RouteDefinition("GET", "/api/lm/get-usage-stats", "get_usage_stats"),
    RouteDefinition("POST", "/api/lm/update-lora-code", "update_lora_code"),
+    RouteDefinition("GET", "/api/lm/update-lora-code", "get_update_lora_code"),
    RouteDefinition("GET", "/api/lm/trained-words", "get_trained_words"),
    RouteDefinition("GET", "/api/lm/model-example-files", "get_model_example_files"),
    RouteDefinition("POST", "/api/lm/register-nodes", "register_nodes"),
    RouteDefinition("POST", "/api/lm/update-node-widget", "update_node_widget"),
+    RouteDefinition("GET", "/api/lm/update-node-widget", "get_update_node_widget"),
    RouteDefinition("GET", "/api/lm/get-registry", "get_registry"),
    RouteDefinition("GET", "/api/lm/check-model-exists", "check_model_exists"),
+    RouteDefinition("GET", "/api/lm/check-models-exist", "check_models_exist"),
    RouteDefinition(
        "GET",
        "/api/lm/model-version-download-status",
@@ -89,6 +95,29 @@ MISC_ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
    RouteDefinition(
        "GET", "/api/lm/base-models/cache-status", "get_base_model_cache_status"
    ),
+    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"
+    ),
+    RouteDefinition(
+        "POST", "/api/lm/set-hf-url", "set_hf_url"
+    ),
+    # 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"
+    ),
 )


@@ -118,7 +147,7 @@ class MiscRouteRegistrar:
                handler_lookup[definition.handler_name],
            )

-    def _bind(self, method: str, path: str, handler: Callable) -> None:
+    def _bind(self, method: str, path: str, handler: Callable[..., Any]) -> None:
        add_method_name = self._METHOD_MAP[method.upper()]
        add_method = getattr(self._app.router, add_method_name)
        add_method(path, handler)
@@ -7,7 +7,7 @@ import os
 from typing import Awaitable, Callable, Mapping

 from aiohttp import web
-from server import PromptServer  # type: ignore
+from server import PromptServer  # pyright: ignore[reportMissingImports]

 from ..services.metadata_service import (
    get_metadata_archive_manager,
@@ -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,
        )


@@ -3,7 +3,7 @@
 from __future__ import annotations

 from dataclasses import dataclass
-from typing import Callable, Iterable, Mapping
+from typing import Any, Callable, Iterable, Mapping

 from aiohttp import web

@@ -22,8 +22,10 @@ class RouteDefinition:

 COMMON_ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
    RouteDefinition("GET", "/api/lm/{prefix}/list", "get_models"),
+    RouteDefinition("GET", "/api/lm/{prefix}/excluded", "get_excluded_models"),
    RouteDefinition("POST", "/api/lm/{prefix}/delete", "delete_model"),
    RouteDefinition("POST", "/api/lm/{prefix}/exclude", "exclude_model"),
+    RouteDefinition("POST", "/api/lm/{prefix}/unexclude", "unexclude_model"),
    RouteDefinition("POST", "/api/lm/{prefix}/fetch-civitai", "fetch_civitai"),
    RouteDefinition("POST", "/api/lm/{prefix}/fetch-all-civitai", "fetch_all_civitai"),
    RouteDefinition("POST", "/api/lm/{prefix}/relink-civitai", "relink_civitai"),
@@ -44,6 +46,7 @@ COMMON_ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
        "GET", "/api/lm/{prefix}/auto-organize-progress", "get_auto_organize_progress"
    ),
    RouteDefinition("GET", "/api/lm/{prefix}/top-tags", "get_top_tags"),
+    RouteDefinition("GET", "/api/lm/{prefix}/search-tags", "search_tags"),
    RouteDefinition("GET", "/api/lm/{prefix}/base-models", "get_base_models"),
    RouteDefinition("GET", "/api/lm/{prefix}/model-types", "get_model_types"),
    RouteDefinition("GET", "/api/lm/{prefix}/scan", "scan_models"),
@@ -99,11 +102,46 @@ COMMON_ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
    RouteDefinition("POST", "/api/lm/download-model", "download_model"),
    RouteDefinition("GET", "/api/lm/download-model-get", "download_model_get"),
    RouteDefinition("GET", "/api/lm/cancel-download-get", "cancel_download_get"),
+    RouteDefinition("GET", "/api/lm/skip-download", "skip_download_get"),
    RouteDefinition("GET", "/api/lm/pause-download", "pause_download_get"),
    RouteDefinition("GET", "/api/lm/resume-download", "resume_download_get"),
    RouteDefinition(
        "GET", "/api/lm/download-progress/{download_id}", "get_download_progress"
    ),
+    RouteDefinition("GET", "/api/lm/downloads/queue", "get_download_queue"),
+    RouteDefinition("GET", "/api/lm/downloads/queue/add", "add_to_download_queue"),
+    RouteDefinition(
+        "GET", "/api/lm/downloads/queue/remove", "remove_from_download_queue"
+    ),
+    RouteDefinition(
+        "GET", "/api/lm/downloads/queue/move-to-top", "move_queue_item_to_top"
+    ),
+    RouteDefinition(
+        "GET", "/api/lm/downloads/queue/move-to-end", "move_queue_item_to_end"
+    ),
+    RouteDefinition(
+        "GET", "/api/lm/downloads/queue/clear", "clear_download_queue"
+    ),
+    RouteDefinition("GET", "/api/lm/downloads/history", "get_download_history"),
+    RouteDefinition(
+        "GET", "/api/lm/downloads/history/clear", "clear_download_history"
+    ),
+    RouteDefinition(
+        "GET", "/api/lm/downloads/history/delete", "delete_download_history_item"
+    ),
+    RouteDefinition(
+        "GET", "/api/lm/downloads/history/retry", "retry_download_from_history"
+    ),
+    RouteDefinition(
+        "GET", "/api/lm/downloads/history/retry-all", "retry_all_failed_downloads"
+    ),
+    RouteDefinition("GET", "/api/lm/downloads/stats", "get_download_stats"),
+    RouteDefinition(
+        "GET", "/api/lm/downloads/queue/complete", "complete_download_in_queue"
+    ),
+    RouteDefinition(
+        "GET", "/api/lm/downloads/queue/status", "update_download_queue_status"
+    ),
    RouteDefinition("POST", "/api/lm/{prefix}/cancel-task", "cancel_task"),
    RouteDefinition("GET", "/{prefix}", "handle_models_page"),
 )
@@ -136,15 +174,15 @@ class ModelRouteRegistrar:
                handler_lookup[definition.handler_name],
            )

-    def add_route(self, method: str, path: str, handler: Callable) -> None:
+    def add_route(self, method: str, path: str, handler: Callable[..., Any]) -> None:
        self._bind_route(method, path, handler)

    def add_prefixed_route(
-        self, method: str, path_template: str, prefix: str, handler: Callable
+        self, method: str, path_template: str, prefix: str, handler: Callable[..., Any]
    ) -> None:
        self._bind_route(method, path_template.replace("{prefix}", prefix), handler)

-    def _bind_route(self, method: str, path: str, handler: Callable) -> None:
+    def _bind_route(self, method: str, path: str, handler: Callable[..., Any]) -> None:
        add_method_name = self._METHOD_MAP[method.upper()]
        add_method = getattr(self._app.router, add_method_name)
        add_method(path, handler)
@@ -0,0 +1,25 @@
+"""Route controller for the pending-delete undo endpoint."""
+
+from __future__ import annotations
+
+from aiohttp import web
+
+from .handlers.pending_delete_handler import PendingDeleteHandler
+
+
+class PendingDeleteRoutes:
+    """Shared route controller mirroring MiscRoutes/UpdateRoutes.
+
+    Registered ONCE per mode (py/lora_manager.py, standalone.py); NEVER through
+    the per-model-type ModelRouteRegistrar, which is instantiated per model
+    type and would register this non-prefixed route three times.
+    """
+
+    @staticmethod
+    def setup_routes(app: web.Application) -> None:
+        """Register the shared undo-delete endpoint."""
+        handler = PendingDeleteHandler()
+        _ = app.router.add_post("/api/lm/undo-delete", handler.undo_delete)
+
+
+__all__ = ["PendingDeleteRoutes"]
@@ -3,7 +3,7 @@
 from __future__ import annotations

 from dataclasses import dataclass
-from typing import Callable, Mapping
+from typing import Any, Callable, Mapping

 from aiohttp import web

@@ -29,6 +29,7 @@ ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
    RouteDefinition("POST", "/api/lm/recipes/save", "save_recipe"),
    RouteDefinition("DELETE", "/api/lm/recipe/{recipe_id}", "delete_recipe"),
    RouteDefinition("GET", "/api/lm/recipes/top-tags", "get_top_tags"),
+    RouteDefinition("GET", "/api/lm/recipes/search-tags", "search_tags"),
    RouteDefinition("GET", "/api/lm/recipes/base-models", "get_base_models"),
    RouteDefinition("GET", "/api/lm/recipes/roots", "get_roots"),
    RouteDefinition("GET", "/api/lm/recipes/folders", "get_folders"),
@@ -42,6 +43,9 @@ ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
    ),
    RouteDefinition("GET", "/api/lm/recipe/{recipe_id}/syntax", "get_recipe_syntax"),
    RouteDefinition("PUT", "/api/lm/recipe/{recipe_id}/update", "update_recipe"),
+    RouteDefinition(
+        "POST", "/api/lm/recipe/{recipe_id}/opened", "record_recipe_open"
+    ),
    RouteDefinition("POST", "/api/lm/recipe/move", "move_recipe"),
    RouteDefinition("POST", "/api/lm/recipes/move-bulk", "move_recipes_bulk"),
    RouteDefinition("POST", "/api/lm/recipe/lora/reconnect", "reconnect_lora"),
@@ -58,7 +62,13 @@ ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
    RouteDefinition("POST", "/api/lm/recipes/repair", "repair_recipes"),
    RouteDefinition("POST", "/api/lm/recipes/cancel-repair", "cancel_repair"),
    RouteDefinition("POST", "/api/lm/recipe/{recipe_id}/repair", "repair_recipe"),
+    RouteDefinition("POST", "/api/lm/recipes/repair-bulk", "repair_recipes_bulk"),
    RouteDefinition("GET", "/api/lm/recipes/repair-progress", "get_repair_progress"),
+    RouteDefinition("POST", "/api/lm/recipes/rematch", "rematch_recipes"),
+    RouteDefinition("POST", "/api/lm/recipes/rematch-bulk", "rematch_recipes_bulk"),
+    RouteDefinition("POST", "/api/lm/recipe/{recipe_id}/rematch", "rematch_recipe"),
+    RouteDefinition("POST", "/api/lm/recipes/cancel-rematch", "cancel_rematch"),
+    RouteDefinition("GET", "/api/lm/recipes/rematch-progress", "get_rematch_progress"),
    RouteDefinition("POST", "/api/lm/recipes/batch-import/start", "start_batch_import"),
    RouteDefinition(
        "GET", "/api/lm/recipes/batch-import/progress", "get_batch_import_progress"
@@ -70,6 +80,16 @@ ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
        "POST", "/api/lm/recipes/batch-import/directory", "start_directory_import"
    ),
    RouteDefinition("POST", "/api/lm/recipes/browse-directory", "browse_directory"),
+    RouteDefinition(
+        "GET", "/api/lm/recipes/check-image-exists", "check_image_exists"
+    ),
+    RouteDefinition("GET", "/api/lm/recipes/import-from-url", "import_from_url"),
+    RouteDefinition(
+        "POST", "/api/lm/recipes/create-from-example", "create_from_example"
+    ),
+    RouteDefinition(
+        "POST", "/api/lm/recipe/{recipe_id}/reimport", "reimport_recipe"
+    ),
 )


@@ -93,7 +113,7 @@ class RecipeRouteRegistrar:
            handler = handler_lookup[definition.handler_name]
            self._bind_route(definition.method, definition.path, handler)

-    def _bind_route(self, method: str, path: str, handler: Callable) -> None:
+    def _bind_route(self, method: str, path: str, handler: Callable[..., Any]) -> None:
        add_method_name = self._METHOD_MAP[method.upper()]
        add_method = getattr(self._app.router, add_method_name)
        add_method(path, handler)
@@ -11,6 +11,8 @@ from ..config import config
 from ..services.settings_manager import get_settings_manager
 from ..services.server_i18n import server_i18n
 from ..services.service_registry import ServiceRegistry
+from ..services.model_query import normalize_sub_type, resolve_sub_type
+from ..utils.constants import VALID_LORA_SUB_TYPES, VALID_CHECKPOINT_SUB_TYPES
 from ..utils.usage_stats import UsageStats

 logger = logging.getLogger(__name__)
@@ -38,10 +40,11 @@ class StatsRoutes:
    """Route handlers for Statistics page and API endpoints"""
    
    def __init__(self):
-        self.lora_scanner = None
-        self.checkpoint_scanner = None
-        self.embedding_scanner = None
-        self.usage_stats = None
+        self.lora_scanner: Any = None
+        self.checkpoint_scanner: Any = None
+        self.embedding_scanner: Any = None
+        self.usage_stats: Any = None
+        self._i18n_filter_added = False
        self.template_env = jinja2.Environment(
            loader=jinja2.FileSystemLoader(config.templates_path),
            autoescape=True
@@ -93,9 +96,9 @@ class StatsRoutes:
            server_i18n.set_locale(user_language)
            
            # 为模板环境添加i18n过滤器
-            if not hasattr(self.template_env, '_i18n_filter_added'):
+            if not self._i18n_filter_added:
                self.template_env.filters['t'] = server_i18n.create_template_filter()
-                self.template_env._i18n_filter_added = True
+                self._i18n_filter_added = True

            template = self.template_env.get_template('statistics.html')
            rendered = template.render(
@@ -140,6 +143,21 @@ class StatsRoutes:
            # Get usage statistics
            usage_data = await self.usage_stats.get_stats()
            
+            # CivitAI model type distribution across all model types
+            # Use the same logic as the filter panel: normalize_sub_type(resolve_sub_type(entry))
+            # with sub-type validation per model type
+            model_types_counter: Counter[str] = Counter()
+            for entry in lora_cache.raw_data:
+                ntype = normalize_sub_type(resolve_sub_type(entry))
+                if ntype and ntype in VALID_LORA_SUB_TYPES:
+                    model_types_counter[ntype] += 1
+            for entry in checkpoint_cache.raw_data:
+                ntype = normalize_sub_type(resolve_sub_type(entry))
+                if ntype and ntype in VALID_CHECKPOINT_SUB_TYPES:
+                    model_types_counter[ntype] += 1
+            # Embeddings: always count as "embedding" regardless of CivitAI sub-type
+            model_types_counter['embedding'] = len(embedding_cache.raw_data)
+            
            return web.json_response({
                'success': True,
                'data': {
@@ -154,7 +172,8 @@ class StatsRoutes:
                    'total_generations': usage_data.get('total_executions', 0),
                    'unused_loras': self._count_unused_models(lora_cache.raw_data, usage_data.get('loras', {})),
                    'unused_checkpoints': self._count_unused_models(checkpoint_cache.raw_data, usage_data.get('checkpoints', {})),
-                    'unused_embeddings': self._count_unused_models(embedding_cache.raw_data, usage_data.get('embeddings', {}))
+                    'unused_embeddings': self._count_unused_models(embedding_cache.raw_data, usage_data.get('embeddings', {})),
+                    'model_types_distribution': dict(model_types_counter.most_common())
                }
            })
            
@@ -459,9 +478,12 @@ class StatsRoutes:
                if unused_lora_percent > 50:
                    insights.append({
                        'type': 'warning',
-                        'title': 'High Number of Unused LoRAs',
-                        'description': f'{unused_lora_percent:.1f}% of your LoRAs ({unused_loras}/{total_loras}) have never been used.',
-                        'suggestion': 'Consider organizing or archiving unused models to free up storage space.'
+                        'key': 'insights.unusedLoras.high',
+                        'params': {
+                            'percent': f'{unused_lora_percent:.1f}',
+                            'count': str(unused_loras),
+                            'total': str(total_loras)
+                        }
                    })
            
            if total_checkpoints > 0:
@@ -469,9 +491,12 @@ class StatsRoutes:
                if unused_checkpoint_percent > 30:
                    insights.append({
                        'type': 'warning',
-                        'title': 'Unused Checkpoints Detected',
-                        'description': f'{unused_checkpoint_percent:.1f}% of your checkpoints ({unused_checkpoints}/{total_checkpoints}) have never been used.',
-                        'suggestion': 'Review and consider removing checkpoints you no longer need.'
+                        'key': 'insights.unusedCheckpoints.detected',
+                        'params': {
+                            'percent': f'{unused_checkpoint_percent:.1f}',
+                            'count': str(unused_checkpoints),
+                            'total': str(total_checkpoints)
+                        }
                    })
            
            if total_embeddings > 0:
@@ -479,9 +504,12 @@ class StatsRoutes:
                if unused_embedding_percent > 50:
                    insights.append({
                        'type': 'warning',
-                        'title': 'High Number of Unused Embeddings',
-                        'description': f'{unused_embedding_percent:.1f}% of your embeddings ({unused_embeddings}/{total_embeddings}) have never been used.',
-                        'suggestion': 'Consider organizing or archiving unused embeddings to optimize your collection.'
+                        'key': 'insights.unusedEmbeddings.high',
+                        'params': {
+                            'percent': f'{unused_embedding_percent:.1f}',
+                            'count': str(unused_embeddings),
+                            'total': str(total_embeddings)
+                        }
                    })
            
            # Storage insights
@@ -492,18 +520,20 @@ class StatsRoutes:
            if total_size > 100 * 1024 * 1024 * 1024:  # 100GB
                insights.append({
                    'type': 'info',
-                    'title': 'Large Collection Detected',
-                    'description': f'Your model collection is using {self._format_size(total_size)} of storage.',
-                    'suggestion': 'Consider using external storage or cloud solutions for better organization.'
+                    'key': 'insights.collection.large',
+                    'params': {
+                        'size': self._format_size(total_size)
+                    }
                })
            
            # Recent activity insight
            if usage_data.get('total_executions', 0) > 100:
                insights.append({
                    'type': 'success',
-                    'title': 'Active User',
-                    'description': f'You\'ve completed {usage_data["total_executions"]} generations so far!',
-                    'suggestion': 'Keep exploring and creating amazing content with your models.'
+                    'key': 'insights.activity.active',
+                    'params': {
+                        'count': str(usage_data['total_executions'])
+                    }
                })
            
            return web.json_response({
@@ -520,7 +550,7 @@ class StatsRoutes:
                'error': str(e)
            }, status=500)

-    def _count_unused_models(self, models: List[Dict], usage_data: Dict) -> int:
+    def _count_unused_models(self, models: List[Dict[str, Any]], usage_data: Dict[str, Any]) -> int:
        """Count models that have never been used"""
        used_hashes = set(usage_data.keys())
        unused_count = 0
@@ -531,7 +561,7 @@ class StatsRoutes:
                
        return unused_count

-    def _get_top_used_models(self, usage_data: Dict, model_map: Dict, limit: int) -> List[Dict]:
+    def _get_top_used_models(self, usage_data: Dict[str, Any], model_map: Dict[str, Any], limit: int) -> List[Dict[str, Any]]:
        """Get top used models with their metadata"""
        sorted_usage = sorted(usage_data.items(), key=lambda x: x[1].get('total', 0), reverse=True)
        
@@ -549,7 +579,7 @@ class StatsRoutes:
        
        return top_models

-    def _get_usage_timeline(self, usage_data: Dict, days: int) -> List[Dict]:
+    def _get_usage_timeline(self, usage_data: Dict[str, Any], days: int) -> List[Dict[str, Any]]:
        """Get usage timeline for the past N days"""
        timeline = []
        today = datetime.now()
@@ -585,7 +615,7 @@ class StatsRoutes:
        
        return list(reversed(timeline))  # Oldest to newest

-    def _format_size(self, size_bytes: int) -> str:
+    def _format_size(self, size_bytes: float) -> str:
        """Format file size in human readable format"""
        for unit in ['B', 'KB', 'MB', 'GB', 'TB']:
            if size_bytes < 1024.0:
@@ -1,21 +1,120 @@
 import os
 import logging
 import toml
-import git
 import zipfile
 import shutil
 import tempfile
 import asyncio
 from aiohttp import web, ClientError
-from typing import Dict, List
+from typing import Any, Dict, List, cast

 from ..utils.settings_paths import ensure_settings_file
 from ..services.downloader import get_downloader
+from ..services.service_registry import ServiceRegistry

 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
+
+
+def _stage_preserved_items(plugin_root: str) -> tuple[str, list[str]]:
+    """Move preserved user-data items to a temp directory outside *plugin_root*.
+
+    This ensures that ``git reset --hard``, ``git clean -fd``, and ZIP-based
+    replacement cannot touch these files even when ``-e`` exclusion patterns
+    are mishandled (e.g. on Windows where forward-slash patterns may not
+    match backslash-prefixed paths in some Git builds, or where file locks
+    prevent deletion/recreation).
+
+    Returns:
+        ``(backup_root, staged_names)``: the temp directory path and the
+        list of item names that were successfully moved.
+    """
+    backup_root = tempfile.mkdtemp(prefix='lora_manager_update_')
+    staged: list[str] = []
+    for name in _PRESERVE_DIRS:
+        src = os.path.join(plugin_root, name)
+        if not os.path.lexists(src):
+            continue
+        dst = os.path.join(backup_root, name)
+        try:
+            shutil.move(src, dst)
+            staged.append(name)
+            logger.debug("Staged '%s' for update safety", name)
+        except OSError:
+            # ``shutil.move`` may fail on Windows if a file handle inside
+            # the directory is still open (e.g. a SQLite WAL file). Fall
+            # back to copy-then-remove.
+            logger.debug("Move failed for '%s', falling back to copy", name)
+            try:
+                if os.path.isdir(src) and not os.path.islink(src):
+                    shutil.copytree(src, dst, symlinks=True)
+                    shutil.rmtree(src, ignore_errors=True)
+                else:
+                    shutil.copy2(src, dst)
+                    os.remove(src)
+                staged.append(name)
+                logger.info("Copied (then removed) '%s' for update safety", name)
+            except Exception as exc:
+                logger.warning(
+                    "Could not stage '%s': %s (will rely on git -e / skip lists)", name, exc
+                )
+    return backup_root, staged
+
+
+def _restore_preserved_items(plugin_root: str, backup_root: str, staged: list[str]) -> None:
+    """Move staged items back from *backup_root* into *plugin_root*.
+
+    Any leftover placeholder at the destination (created by git checkout or
+    ZIP extraction) is removed before the move.
+    """
+    for name in staged:
+        src = os.path.join(backup_root, name)
+        dst = os.path.join(plugin_root, name)
+        try:
+            if os.path.lexists(dst):
+                if os.path.isdir(dst) and not os.path.islink(dst):
+                    shutil.rmtree(dst, ignore_errors=True)
+                else:
+                    os.remove(dst)
+            shutil.move(src, dst)
+            logger.debug("Restored '%s' after update", name)
+        except OSError:
+            logger.debug("Move failed restoring '%s', falling back to copy", name)
+            try:
+                if os.path.isdir(src) and not os.path.islink(src):
+                    shutil.copytree(src, dst, symlinks=True, dirs_exist_ok=True)
+                    shutil.rmtree(src, ignore_errors=True)
+                else:
+                    shutil.copy2(src, dst)
+                    os.remove(src)
+                logger.info("Copied '%s' back after update", name)
+            except Exception as exc:
+                logger.error("Failed to restore '%s': %s", name, exc)
+    shutil.rmtree(backup_root, ignore_errors=True)
+
+

 class UpdateRoutes:
    """Routes for handling plugin update checks"""
@@ -26,6 +125,7 @@ class UpdateRoutes:
        app.router.add_get('/api/lm/check-updates', UpdateRoutes.check_updates)
        app.router.add_get('/api/lm/version-info', UpdateRoutes.get_version_info)
        app.router.add_post('/api/lm/perform-update', UpdateRoutes.perform_update)
+        app.router.add_post('/api/lm/switch-channel', UpdateRoutes.switch_channel)
    
    @staticmethod
    async def check_updates(request):
@@ -44,10 +144,17 @@ class UpdateRoutes:

            # Fetch remote version from GitHub
            if nightly:
-                remote_version, changelog = await UpdateRoutes._get_nightly_version()
-                releases = None
+                local_hash = git_info.get('short_hash', '')
+                nightly_version, releases_result = await asyncio.gather(
+                    UpdateRoutes._get_nightly_version(local_hash),
+                    UpdateRoutes._get_remote_version()
+                )
+                remote_version, _, behind_by, commit_date = nightly_version
+                _, changelog, releases = releases_result
            else:
                remote_version, changelog, releases = await UpdateRoutes._get_remote_version()
+                behind_by = 0
+                commit_date = ''
            
            # Compare versions
            if nightly:
@@ -60,6 +167,10 @@ class UpdateRoutes:
                    remote_version.replace('v', '')
                )
            
+            current_dir = os.path.dirname(os.path.abspath(__file__))
+            plugin_root = os.path.dirname(os.path.dirname(current_dir))
+            has_git = os.path.exists(os.path.join(plugin_root, '.git'))
+
            response_data = {
                'success': True,
                'current_version': local_version,
@@ -67,13 +178,13 @@ class UpdateRoutes:
                'update_available': update_available,
                'changelog': changelog,
                'git_info': git_info,
-                'nightly': nightly
+                'nightly': nightly,
+                'has_git': has_git,
+                'releases': releases,
+                'behind_by': behind_by,
+                'commit_date': commit_date
            }
            
-            # Include releases list for stable mode
-            if releases is not None:
-                response_data['releases'] = releases
-            
            return web.json_response(response_data)
            
        except NETWORK_EXCEPTIONS as e:
@@ -105,9 +216,14 @@ class UpdateRoutes:
            # Format: version-short_hash
            version_string = f"{local_version}-{short_hash}"
            
+            current_dir = os.path.dirname(os.path.abspath(__file__))
+            plugin_root = os.path.dirname(os.path.dirname(current_dir))
+            has_git = os.path.exists(os.path.join(plugin_root, '.git'))
+
            return web.json_response({
                'success': True,
-                'version': version_string
+                'version': version_string,
+                'has_git': has_git
            })
            
        except Exception as e:
@@ -135,20 +251,22 @@ class UpdateRoutes:
            if os.path.exists(settings_path):
                with open(settings_path, 'r', encoding='utf-8') as f:
                    settings_backup = f.read()
-                logger.info("Backed up settings.json")
+                logger.debug("Backed up settings.json (%d bytes)", len(settings_backup))

-            git_folder = os.path.join(plugin_root, '.git')
-            if os.path.exists(git_folder):
-                # Git update
-                success, new_version = await UpdateRoutes._perform_git_update(plugin_root, nightly)
-            else:
-                # Fallback: Download ZIP and replace files
-                success, new_version = await UpdateRoutes._download_and_replace_zip(plugin_root)
+            staged_backup_dir, staged_items = _stage_preserved_items(plugin_root)
+            try:
+                git_folder = os.path.join(plugin_root, '.git')
+                if os.path.exists(git_folder):
+                    success, new_version = await UpdateRoutes._perform_git_update(plugin_root, nightly)
+                else:
+                    success, new_version = await UpdateRoutes._download_and_replace_zip(plugin_root)
+            finally:
+                _restore_preserved_items(plugin_root, staged_backup_dir, staged_items)

            if settings_backup and success:
                with open(settings_path, 'w', encoding='utf-8') as f:
                    f.write(settings_backup)
-                logger.info("Restored settings.json")
+                logger.debug("Restored settings.json content (%d bytes)", len(settings_backup))

            if success:
                return web.json_response({
@@ -169,6 +287,164 @@ class UpdateRoutes:
                'error': str(e)
            })

+    @staticmethod
+    async def switch_channel(request):
+        """
+        Switch between release and nightly update channels.
+
+        ZIP/CNR install → Nightly: git init + checkout main (one-way upgrade)
+        Git install → Release:   git checkout latest tag (.git preserved)
+        ZIP/CNR install → Release: ZIP download (no .git, stays in ZIP mode)
+        Git install → Nightly:   git checkout main + pull
+        """
+        try:
+            body = await request.json() if request.has_body else {}
+            channel = body.get('channel', '')
+
+            if channel not in ('release', 'nightly'):
+                return web.json_response({
+                    'success': False,
+                    'error': f'Invalid channel: {channel}. Must be "release" or "nightly".'
+                })
+
+            current_dir = os.path.dirname(os.path.abspath(__file__))
+            plugin_root = os.path.dirname(os.path.dirname(current_dir))
+
+            settings_path = ensure_settings_file(logger)
+            settings_backup = None
+            if os.path.exists(settings_path):
+                with open(settings_path, 'r', encoding='utf-8') as f:
+                    settings_backup = f.read()
+                logger.debug("Backed up settings.json before channel switch (%d bytes)", len(settings_backup))
+
+            staged_backup_dir, staged_items = _stage_preserved_items(plugin_root)
+            try:
+                git_folder = os.path.join(plugin_root, '.git')
+
+                if channel == 'nightly':
+                    git_backup = None
+                    if os.path.exists(git_folder):
+                        git_backup = UpdateRoutes._backup_git(git_folder, 'nightly')
+
+                    success = False
+                    new_version = ''
+                    try:
+                        if os.path.exists(git_folder):
+                            success, new_version = await UpdateRoutes._perform_git_update(
+                                plugin_root, nightly=True
+                            )
+                        else:
+                            success, new_version = UpdateRoutes._init_git_repo(plugin_root)
+                    finally:
+                        UpdateRoutes._restore_git(git_backup, git_folder, success, 'nightly')
+                else:
+                    success = False
+                    new_version = ''
+                    if os.path.exists(git_folder):
+                        success, new_version = await UpdateRoutes._perform_git_update(
+                            plugin_root, nightly=False
+                        )
+                    else:
+                        tracking_file = os.path.join(plugin_root, '.tracking')
+                        if os.path.exists(tracking_file):
+                            os.remove(tracking_file)
+                        success, new_version = await UpdateRoutes._download_and_replace_zip(plugin_root)
+            finally:
+                _restore_preserved_items(plugin_root, staged_backup_dir, staged_items)
+
+            if settings_backup and success:
+                with open(settings_path, 'w', encoding='utf-8') as f:
+                    f.write(settings_backup)
+                logger.debug("Restored settings.json content after channel switch (%d bytes)", len(settings_backup))
+
+            if success:
+                return web.json_response({
+                    'success': True,
+                    'channel': channel,
+                    'new_version': new_version,
+                    'message': f'Switched to {channel} channel'
+                })
+            else:
+                return web.json_response({
+                    'success': False,
+                    'error': f'Failed to switch to {channel} channel'
+                })
+
+        except Exception as e:
+            logger.error("Failed to switch channel: %s", e, exc_info=True)
+            return web.json_response({
+                'success': False,
+                'error': str(e)
+            })
+
+    @staticmethod
+    def _init_git_repo(plugin_root: str) -> tuple[bool, str]:
+        """
+        Initialize a Git repository in a ZIP-installed plugin folder.
+        Clones the remote history and checks out main branch.
+        """
+        try:
+            import git
+        except ImportError:
+            logger.error(
+                "GitPython is not available: cannot initialize git repo. "
+                "Install git or set $GIT_PYTHON_GIT_EXECUTABLE to the git binary path."
+            )
+            return False, ""
+
+        clean_excludes = _clean_excludes()
+
+        try:
+            repo = git.Repo.init(plugin_root)
+            origin = repo.create_remote(
+                'origin',
+                'https://github.com/willmiao/ComfyUI-Lora-Manager.git'
+            )
+            origin.fetch()
+
+            repo.create_head('main', origin.refs.main)
+            repo.git.checkout('main', '--force')
+            repo.git.reset('--hard')
+            repo.git.clean('-fd', *clean_excludes)
+
+            tracking_file = os.path.join(plugin_root, '.tracking')
+            if os.path.exists(tracking_file):
+                os.remove(tracking_file)
+                logger.info("Removed .tracking file (now in git mode)")
+
+            new_version = f"main-{repo.head.commit.hexsha[:7]}"
+            logger.info("Initialized git repo on main branch: %s", new_version)
+            return True, new_version
+
+        except Exception as e:
+            logger.error("Failed to initialize git repo: %s", e, exc_info=True)
+            return False, ""
+
+    @staticmethod
+    def _backup_git(git_folder, label):
+        try:
+            backup_dir = tempfile.mkdtemp()
+            backup = os.path.join(backup_dir, '.git')
+            shutil.copytree(git_folder, backup)
+            logger.info("Backed up .git before switching to %s", label)
+            return backup
+        except Exception as e:
+            logger.error("Failed to backup .git before %s switch: %s", label, e)
+            return None
+
+    @staticmethod
+    def _restore_git(git_backup, git_folder, success, label):
+        if git_backup and not success:
+            try:
+                if os.path.exists(git_folder):
+                    shutil.rmtree(git_folder)
+                shutil.copytree(git_backup, git_folder)
+                logger.info("Restored .git after failed %s switch", label)
+            except Exception as e:
+                logger.error("Failed to restore .git after %s switch: %s", label, e)
+        if git_backup:
+            shutil.rmtree(os.path.dirname(git_backup), ignore_errors=True)
+
    @staticmethod
    async def _download_and_replace_zip(plugin_root: str) -> tuple[bool, str]:
        """
@@ -191,9 +467,10 @@ class UpdateRoutes:
            if not success:
                logger.error(f"Failed to fetch release info: {data}")
                return False, ""
-            
-            zip_url = data.get("zipball_url")
-            version = data.get("tag_name", "unknown")
+
+            release_payload = cast(dict[str, Any], data)
+            zip_url = release_payload.get("zipball_url", "")
+            version = release_payload.get("tag_name", "unknown")

            # Download ZIP to temporary file
            with tempfile.NamedTemporaryFile(delete=False, suffix=".zip") as tmp_zip:
@@ -212,8 +489,18 @@ class UpdateRoutes:

            zip_path = tmp_zip_path

-            # Skip both settings.json, civitai and model cache folder
-            UpdateRoutes._clean_plugin_folder(plugin_root, skip_files=['settings.json', 'civitai', 'model_cache'])
+            # Close the downloaded-versions SQLite connection before cleaning,
+            # so that shutil.rmtree() does not fail on Windows (the process
+            # cannot delete a file with an outstanding open handle).
+            try:
+                history_svc = ServiceRegistry._services.get("downloaded_version_history_service")
+                if history_svc is not None:
+                    history_svc.close()
+                    logger.info("Closed downloaded-version history database connection")
+            except Exception:
+                logger.debug("Could not close downloaded-version history database", exc_info=True)
+
+            UpdateRoutes._clean_plugin_folder(plugin_root, skip_files=list(_PRESERVE_DIRS))

            # Extract ZIP to temp dir
            with tempfile.TemporaryDirectory() as tmp_dir:
@@ -222,16 +509,17 @@ class UpdateRoutes:
                    # Find extracted folder (GitHub ZIP contains a root folder)
                    extracted_root = next(os.scandir(tmp_dir)).path

-                    # Copy files, skipping settings.json and civitai folder
+                    # Copy files, skipping user data that should be preserved
+                    skip_items = set(_PRESERVE_DIRS)
                    for item in os.listdir(extracted_root):
-                        if item == 'settings.json' or item == 'civitai':
+                        if item in skip_items:
                            continue
                        src = os.path.join(extracted_root, item)
                        dst = os.path.join(plugin_root, item)
                        if os.path.isdir(src):
                            if os.path.exists(dst):
                                shutil.rmtree(dst)
-                            shutil.copytree(src, dst, ignore=shutil.ignore_patterns('settings.json', 'civitai'))
+                            shutil.copytree(src, dst, ignore=shutil.ignore_patterns(*skip_items))
                        else:
                            shutil.copy2(src, dst)

@@ -239,15 +527,17 @@ class UpdateRoutes:
                    # for ComfyUI Manager to work properly
                    tracking_info_file = os.path.join(plugin_root, '.tracking')
                    tracking_files = []
+                    skip_tracked = set(_PRESERVE_DIRS) - {'settings.json'}
                    for root, dirs, files in os.walk(extracted_root):
-                        # Skip civitai folder and its contents
+                        # Skip user data directories and their contents
                        rel_root = os.path.relpath(root, extracted_root)
-                        if rel_root == 'civitai' or rel_root.startswith('civitai' + os.sep):
+                        top_dir = rel_root.split(os.sep)[0] if rel_root != '.' else ''
+                        if top_dir in skip_tracked:
                            continue
                        for file in files:
                            rel_path = os.path.relpath(os.path.join(root, file), extracted_root)
-                            # Skip settings.json and any file under civitai
-                            if rel_path == 'settings.json' or rel_path.startswith('civitai' + os.sep):
+                            # Skip settings.json and any file under user data dirs
+                            if rel_path == 'settings.json' or rel_path.split(os.sep)[0] in skip_tracked:
                                continue
                            tracking_files.append(rel_path.replace("\\", "/"))
                    with open(tracking_info_file, "w", encoding='utf-8') as file:
@@ -260,7 +550,8 @@ class UpdateRoutes:
        except Exception as e:
            logger.error(f"ZIP update failed: {e}", exc_info=True)
            return False, ""
-        
+
+    @staticmethod
    def _clean_plugin_folder(plugin_root, skip_files=None):
        skip_files = skip_files or []
        for item in os.listdir(plugin_root):
@@ -273,41 +564,56 @@ class UpdateRoutes:
                os.remove(path)
    
    @staticmethod
-    async def _get_nightly_version() -> tuple[str, List[str]]:
-        """
-        Fetch latest commit from main branch
-        """
+    async def _get_nightly_version(local_hash: str = "") -> tuple[str, List[str], int, str]:
        repo_owner = "willmiao"
        repo_name = "ComfyUI-Lora-Manager"
-        
-        # Use GitHub API to fetch the latest commit from main branch
+
        github_url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/commits/main"
-        
+
        try:
            downloader = await get_downloader()
-            success, data = await downloader.make_request('GET', github_url, custom_headers={'Accept': 'application/vnd.github+json'})
-            
+            success, data = await downloader.make_request(
+                'GET', github_url,
+                custom_headers={'Accept': 'application/vnd.github+json'}
+            )
+
            if not success:
-                logger.warning(f"Failed to fetch GitHub commit: {data}")
-                return "main", []
-            
-            commit_sha = data.get('sha', '')[:7]  # Short hash
-            commit_message = data.get('commit', {}).get('message', '')
-            
-            # Format as "main-{short_hash}"
+                logger.warning("Failed to fetch GitHub commit: %s", data)
+                return "main", [], 0, ""
+
+            commit_payload = cast(dict[str, Any], data)
+            commit_sha = commit_payload.get('sha', '')[:7]
+            commit_message = commit_payload.get('commit', {}).get('message', '')
+            commit_date = commit_payload.get('commit', {}).get('committer', {}).get('date', '')[:10]
+
            version = f"main-{commit_sha}"
-            
-            # Use commit message as changelog
            changelog = [commit_message] if commit_message else []
-            
-            return version, changelog
-        
+
+            behind_by = 0
+            if local_hash and local_hash not in ('unknown', 'stable'):
+                compare_url = (
+                    f"https://api.github.com/repos/{repo_owner}/{repo_name}"
+                    f"/compare/{local_hash}...main"
+                )
+                c_ok, c_data = await downloader.make_request(
+                    'GET', compare_url,
+                    custom_headers={'Accept': 'application/vnd.github+json'}
+                )
+                if c_ok:
+                    compare_payload = cast(dict[str, Any], c_data)
+                    if compare_payload.get('status') in ('ahead', 'diverged'):
+                        behind_by = compare_payload.get('ahead_by', 0)
+                    else:
+                        behind_by = compare_payload.get('behind_by', 0)
+
+            return version, changelog, behind_by, commit_date
+
        except NETWORK_EXCEPTIONS as e:
            logger.warning("Unable to reach GitHub for nightly version: %s", e)
-            return "main", []
+            return "main", [], 0, ""
        except Exception as e:
-            logger.error(f"Error fetching nightly version: {e}", exc_info=True)
-            return "main", []
+            logger.error("Error fetching nightly version: %s", e, exc_info=True)
+            return "main", [], 0, ""
    
    @staticmethod
    def _compare_nightly_versions(local_git_info: Dict[str, str], remote_version: str) -> bool:
@@ -342,6 +648,17 @@ class UpdateRoutes:
        Returns:
            tuple: (success, new_version)
        """
+        try:
+            import git
+        except ImportError:
+            logger.error(
+                "GitPython is not available: the git executable was not found in PATH. "
+                "Install git or set $GIT_PYTHON_GIT_EXECUTABLE to the git binary path."
+            )
+            return False, ""
+
+        clean_excludes = _clean_excludes()
+
        try:
            # Open the Git repository
            repo = git.Repo(plugin_root)
@@ -353,8 +670,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'
@@ -371,8 +689,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)
@@ -390,7 +709,7 @@ class UpdateRoutes:
            logger.info(f"Successfully updated to {new_version}")
            return True, new_version
            
-        except git.exc.GitError as e:
+        except git.exc.GitError as e:  # pyright: ignore[reportAttributeAccessIssue]
            logger.error(f"Git error during update: {e}")
            return False, ""
        except Exception as e:
@@ -438,6 +757,7 @@ class UpdateRoutes:
            if not os.path.exists(os.path.join(plugin_root, '.git')):
                return git_info

+            import git
            repo = git.Repo(plugin_root)
            commit = repo.head.commit
            git_info['commit_hash'] = commit.hexsha
@@ -450,7 +770,7 @@ class UpdateRoutes:
        return git_info
    
    @staticmethod
-    async def _get_remote_version() -> tuple[str, List[str], List[Dict]]:
+    async def _get_remote_version() -> tuple[str, List[str], List[Dict[str, Any]]]:
        """
        Fetch remote version from GitHub
        Returns:
@@ -472,7 +792,7 @@ class UpdateRoutes:
            
            # Parse releases
            releases = []
-            for i, release in enumerate(data):
+            for i, release in enumerate(cast(list[dict[str, Any]], data)):
                version = release.get('tag_name', '')
                if not version.startswith('v'):
                    version = f"v{version}"
@@ -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",
+]
@@ -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]) -> 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)
@@ -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[str] = 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 ""
@@ -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
@@ -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, Any], 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
@@ -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/Show More
+++ b/Show More