From 2ba04bb1bd506e8018dd18d150f96ec894fd5619 Mon Sep 17 00:00:00 2001
From: Will Miao <willmiao.dev@gmail.com>
Date: Thu, 27 Aug 2026 17:14:40 +0800
Subject: [PATCH] docs: merge CLAUDE.md content into AGENTS.md and remove
 CLAUDE.md

---
 AGENTS.md | 150 +++++++++++++++++++++++++++++++------------
 CLAUDE.md | 189 ------------------------------------------------------
 2 files changed, 109 insertions(+), 230 deletions(-)
 delete mode 100644 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
index 480bee6c..783981c3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,6 +2,10 @@
 
 This file provides guidance for agentic coding assistants working in this repository.
 
+## Overview
+
+ComfyUI LoRA Manager is a comprehensive LoRA management system for ComfyUI that combines a Python backend with browser-based widgets. It provides model organization, downloading from CivitAI/CivArchive, recipe management, and one-click workflow integration.
+
 ## Development Commands
 
 ### Backend Development
@@ -28,16 +32,21 @@ COVERAGE_FILE=coverage/backend/.coverage pytest \
   --cov=py --cov=standalone \
   --cov-report=term-missing \
   --cov-report=html:coverage/backend/html \
-  --cov-report=xml:coverage/backend/coverage.xml
+  --cov-report=xml:coverage/backend/coverage.xml \
+  --cov-report=json:coverage/backend/coverage.json
 ```
 
 ### Frontend Development (LoRA Manager Web UI)
 
 ```bash
+# Install dependencies (root and Vue widgets)
 npm install
+cd vue-widgets && npm install && cd ..
+
 npm test                    # Run all tests (JS + Vue)
 npm run test:js             # Run JS tests only
-npm run test:watch          # Watch mode
+npm run test:vue            # Run Vue widget tests only
+npm run test:watch          # Watch mode (JS tests only)
 npm run test:coverage       # Generate coverage report
 ```
 
@@ -54,88 +63,159 @@ npm run test:watch          # Watch mode
 npm run test:coverage       # Generate coverage report
 ```
 
-## Python Code Style
+### Localization
 
-### Imports & Formatting
+```bash
+# Sync translation keys after UI string updates
+python scripts/sync_translation_keys.py
+```
+
+Locale files are in `locales/` (en, zh-CN, zh-TW, ja, ko, fr, de, es, ru, he).
+
+## Code Style
+
+### Python
+
+#### Imports & Formatting
 
 - Use `from __future__ import annotations` for forward references
 - Group imports: standard library, third-party, local (blank line separated)
+- Use `TYPE_CHECKING` guard for type-checking-only imports
 - Absolute imports within `py/`: `from ..services import X`
 - PEP 8 with 4-space indentation, type hints required
 
-### Naming Conventions
+#### Naming Conventions
 
 - Files: `snake_case.py`, Classes: `PascalCase`, Functions/vars: `snake_case`
 - Constants: `UPPER_SNAKE_CASE`, Private: `_protected`, `__mangled`
 
-### Error Handling & Async
+#### Error Handling & Async
 
 - Use `logging.getLogger(__name__)`, define custom exceptions in `py/services/errors.py`
 - `async def` for I/O, `@pytest.mark.asyncio` for async tests
 - Singleton with `asyncio.Lock`: see `ModelScanner.get_instance()`
 - Return `aiohttp.web.json_response` or `web.Response`
 
-### Testing
+### JavaScript/TypeScript
 
-- `pytest` with `--import-mode=importlib`
-- Fixtures in `tests/conftest.py`, use `tmp_path_factory` for isolation
-- Mark tests needing real paths: `@pytest.mark.no_settings_dir_isolation`
-- Mock ComfyUI dependencies via conftest patterns
-
-## JavaScript/TypeScript Code Style
-
-### Imports & Modules
+#### Imports & Modules
 
 - ES modules: `import { app } from "../../scripts/app.js"` for ComfyUI
 - Vue: `import { ref, computed } from 'vue'`, type imports: `import type { Foo }`
 - Export named functions: `export function foo() {}`
 
-### Naming & Formatting
+#### Naming & Formatting
 
 - camelCase for functions/vars/props, PascalCase for classes
 - Constants: `UPPER_SNAKE_CASE`, Files: `snake_case.js` or `kebab-case.js`
 - 2-space indentation preferred (follow existing file conventions)
 - Vue Single File Components: `<script setup lang="ts">` preferred
 
-### Widget Development
+#### Widget Development
 
+- Prefer vanilla JS for `web/comfyui/` widgets; avoid framework dependencies (except the Vue widgets in `vue-widgets/`)
 - 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
+#### Vue Composables Pattern
 
 - Use composition API: `useXxxState(widget)`, return reactive refs and methods
 - Guard restoration loops with flag: `let isRestoring = false`
 - Build config from state: `const buildConfig = (): Config => { ... }`
 
-## Architecture Patterns
+## Architecture
+
+### Dual Mode Operation
+
+The system runs in two modes:
+- **ComfyUI plugin mode**: Integrates with ComfyUI's PromptServer, uses `folder_paths` for model discovery
+- **Standalone mode**: `standalone.py` mocks ComfyUI dependencies, reads paths from `settings.json`
+- Detection: `os.environ.get("LORA_MANAGER_STANDALONE", "0") == "1"`
+
+### Backend Entry Points
+
+- `__init__.py` — ComfyUI plugin entry: registers nodes via `NODE_CLASS_MAPPINGS`, sets `WEB_DIRECTORY`, calls `LoraManager.add_routes()`
+- `standalone.py` — Standalone server: mocks `folder_paths` and node modules, starts aiohttp server
+- `py/lora_manager.py` — Main `LoraManager` class that registers all HTTP routes
 
 ### Service Layer
 
 - `ServiceRegistry` singleton for DI, services use `get_instance()` classmethod
+- `BaseModelService` abstract base → `LoraService`, `CheckpointService`, `EmbeddingService`
+- `ModelScanner` base → `LoraScanner`, `CheckpointScanner`, `EmbeddingScanner` for file discovery with hash-based deduplication
+- `PersistentModelCache` (SQLite) for metadata persistence
+- `MetadataSyncService` — background sync from CivitAI/CivArchive APIs
+- `SettingsManager` — settings with schema migration support
+- `WebSocketManager` — real-time progress broadcasting
+- `ModelServiceFactory` — creates the right service for each model type
+- Use cases in `py/services/use_cases/` orchestrate complex business logic (auto-organize, bulk refresh, downloads)
 - Separate scanners (discovery) from services (business logic)
 - Handlers in `py/routes/handlers/` are pure functions with deps as params
 
 ### Model Types & Routes
 
-- `BaseModelService` base for LoRA, Checkpoint, Embedding
-- `ModelScanner` for file discovery, hash deduplication
-- `PersistentModelCache` (SQLite) for persistence
-- Route registrars: `ModelRouteRegistrar`, endpoints: `/loras/*`, `/checkpoints/*`, `/embeddings/*`
-- WebSocket via `WebSocketManager` for real-time updates
+- API endpoints follow `/loras/*`, `/checkpoints/*`, `/embeddings/*` patterns
+- Route registrars organize endpoints by domain: `ModelRouteRegistrar`, `RecipeRouteRegistrar`, etc.
+- Request handlers in `py/routes/handlers/` implement route logic
+- All routes use aiohttp, return `web.json_response` or `web.Response`
 
 ### Recipe System
 
-- Base: `py/recipes/base.py`, Enrichment: `RecipeEnrichmentService`
-- Parsers: `py/recipes/parsers/`
+- Base: `py/recipes/base.py`, Enrichment: `RecipeEnrichmentService` in `py/recipes/enrichment.py`
+- Parsers: `py/recipes/parsers/` for PNG metadata, JSON, and workflow formats
+
+### Custom Nodes
+
+- Location: `py/nodes/`, all nodes registered in `__init__.py`
+- Each node class has a `NAME` class attribute used as key in `NODE_CLASS_MAPPINGS`
+- Standard ComfyUI node pattern: `INPUT_TYPES()` classmethod, `RETURN_TYPES`, `FUNCTION`
+
+### Configuration
+
+- `py/config.py` manages folder paths for models and handles symlink mappings
+- Auto-saves paths to `settings.json` in ComfyUI mode
+
+### Frontend UI Architecture
+
+#### 1. LoRA Manager Web UI
+- Location: `./static/` (JS/CSS) and `./templates/` (HTML)
+- Tech: Vanilla JS + CSS, served by the hosting server (ComfyUI app in plugin mode, `standalone.py` in standalone mode)
+- Tests: `tests/frontend/**/*.test.js` (vitest + jsdom)
+
+#### 2. ComfyUI Custom Node Widgets
+- Location: `./web/comfyui/` (Vanilla JS) + `./vue-widgets/` (Vue)
+- Primary styles: `./web/comfyui/lm_styles.css` (NOT `./static/css/`)
+- Vue widgets: Vue 3 + TypeScript + PrimeVue + vue-i18n, e.g. `LoraPoolWidget`, `LoraRandomizerWidget`, `LoraCyclerWidget`, `AutocompleteTextWidget`
+- Vue builds to `./web/comfyui/vue-widgets/`; auto-built on ComfyUI startup via `py/vue_widget_builder.py`, typecheck via `vue-tsc`
+- Widget registration: `app.registerExtension()` and `getCustomWidgets` hooks; `node.addDOMWidget(...)` embeds HTML in LiteGraph nodes
+- See `docs/dom_widget_dev_guide.md` for the DOMWidget development guide
+
+## Testing
+
+### Backend (pytest)
+
+- Config in `pytest.ini`: `--import-mode=importlib`, testpaths=`tests`
+- Fixtures in `tests/conftest.py` mock ComfyUI dependencies; use `tmp_path_factory` for isolation
+- Markers: `@pytest.mark.asyncio`, `@pytest.mark.no_settings_dir_isolation` (tests needing real settings paths)
+
+### Frontend (vitest)
+
+- Vanilla JS tests: `tests/frontend/**/*.test.js` with jsdom; setup in `tests/frontend/setup.js`
+- Vue widget tests: `vue-widgets/tests/**/*.test.ts` with jsdom + `@vue/test-utils`
+
+## Key Integration Points
+
+- **Settings:** Stored in the user config directory (via `platformdirs`) or portable mode (`"use_portable_settings": true`)
+- **CivitAI/CivArchive:** API clients for metadata sync and model downloads; CivitAI API key stored in settings
+- **Symlinks:** Config scans symlinks to map virtual→physical paths; fingerprinting prevents redundant rescans
+- **WebSocket:** Broadcasts real-time progress for downloads, scans, and metadata sync
+- **Model scanning flow:** Walk folders → compute hashes → deduplicate → extract safetensors metadata → cache in SQLite → background CivitAI sync → WebSocket broadcast
 
 ## Important Notes
 
 - ALWAYS use English for comments (per copilot-instructions.md)
-- 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.
   **Business paths vs real paths**: All stored paths and operation routing use the
@@ -150,16 +230,4 @@ npm run test:coverage       # Generate coverage report
 - Follow the style of recent repository commits when writing commit messages
 - Prefer the repo's existing `feat(...)`, `fix(...)`, `chore:` style where applicable
 - If the user has provided a GitHub issue link or issue ID for the task, mention that issue in the commit message, for example `(#871)`
-- When unrelated local changes exist, stage and commit only the files relevant to the requested task
-
-## Frontend UI Architecture
-
-### 1. LoRA Manager Web UI
-- Location: `./static/` and `./templates/`
-- 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
-- Location: `./web/comfyui/` (Vanilla JS) + `./vue-widgets/` (Vue)
-- Primary styles: `./web/comfyui/lm_styles.css` (NOT `./static/css/`)
-- Vue builds to `./web/comfyui/vue-widgets/`, typecheck via `vue-tsc`
+- When unrelated local changes exist, stage and commit only the files relevant to the requested task
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index e3af65a4..00000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,189 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Overview
-
-ComfyUI LoRA Manager is a comprehensive LoRA management system for ComfyUI that combines a Python backend with browser-based widgets. It provides model organization, downloading from CivitAI/CivArchive, recipe management, and one-click workflow integration.
-
-## Development Commands
-
-### Backend
-
-```bash
-pip install -r requirements.txt
-pip install -r requirements-dev.txt
-
-# Run standalone server (port 8188 by default)
-python standalone.py --port 8188
-
-# Run all backend tests
-pytest
-
-# Run specific test file or function
-pytest tests/test_recipes.py
-pytest tests/test_recipes.py::test_function_name
-
-# Run backend tests with coverage
-COVERAGE_FILE=coverage/backend/.coverage pytest \
-  --cov=py \
-  --cov=standalone \
-  --cov-report=term-missing \
-  --cov-report=html:coverage/backend/html \
-  --cov-report=xml:coverage/backend/coverage.xml \
-  --cov-report=json:coverage/backend/coverage.json
-```
-
-### Frontend
-
-There are three test suites run by `npm test`: vanilla JS tests (vitest at root) and Vue widget tests (`vue-widgets/` vitest).
-
-```bash
-npm install
-cd vue-widgets && npm install && cd ..
-
-# Run all frontend tests (JS + Vue)
-npm test
-
-# Run only vanilla JS tests
-npm run test:js
-
-# Run only Vue widget tests
-npm run test:vue
-
-# Watch mode (JS tests only)
-npm run test:watch
-
-# Frontend coverage
-npm run test:coverage
-
-# Build Vue widgets (output to web/comfyui/vue-widgets/)
-cd vue-widgets && npm run build
-
-# Vue widget dev mode (watch + rebuild)
-cd vue-widgets && npm run dev
-
-# Typecheck Vue widgets
-cd vue-widgets && npm run typecheck
-```
-
-### Localization
-
-```bash
-# Sync translation keys after UI string updates
-python scripts/sync_translation_keys.py
-```
-
-Locale files are in `locales/` (en, zh-CN, zh-TW, ja, ko, fr, de, es, ru, he).
-
-## Architecture
-
-### Dual Mode Operation
-
-The system runs in two modes:
-- **ComfyUI plugin mode**: Integrates with ComfyUI's PromptServer, uses `folder_paths` for model discovery
-- **Standalone mode**: `standalone.py` mocks ComfyUI dependencies, reads paths from `settings.json`
-- Detection: `os.environ.get("LORA_MANAGER_STANDALONE", "0") == "1"`
-
-### Backend (Python)
-
-**Entry points:**
-- `__init__.py` — ComfyUI plugin entry: registers nodes via `NODE_CLASS_MAPPINGS`, sets `WEB_DIRECTORY`, calls `LoraManager.add_routes()`
-- `standalone.py` — Standalone server: mocks `folder_paths` and node modules, starts aiohttp server
-- `py/lora_manager.py` — Main `LoraManager` class that registers all HTTP routes
-
-**Service layer** (`py/services/`):
-- `ServiceRegistry` singleton for dependency injection; services follow `get_instance()` singleton pattern
-- `BaseModelService` abstract base → `LoraService`, `CheckpointService`, `EmbeddingService`
-- `ModelScanner` base → `LoraScanner`, `CheckpointScanner`, `EmbeddingScanner` for file discovery with hash-based deduplication
-- `PersistentModelCache` — SQLite-based metadata cache
-- `MetadataSyncService` — Background sync from CivitAI/CivArchive APIs
-- `SettingsManager` — Settings with schema migration support
-- `WebSocketManager` — Real-time progress broadcasting
-- `ModelServiceFactory` — Creates the right service for each model type
-- Use cases in `py/services/use_cases/` orchestrate complex business logic (auto-organize, bulk refresh, downloads)
-
-**Routes** (`py/routes/`):
-- Route registrars organize endpoints by domain: `ModelRouteRegistrar`, `RecipeRouteRegistrar`, etc.
-- Request handlers in `py/routes/handlers/` implement route logic
-- API endpoints follow `/loras/*`, `/checkpoints/*`, `/embeddings/*` patterns
-- All routes use aiohttp, return `web.json_response` or `web.Response`
-
-**Recipe system** (`py/recipes/`):
-- `base.py` — Recipe metadata structure
-- `enrichment.py` — Enriches recipes with model metadata
-- `parsers/` — Parsers for PNG metadata, JSON, and workflow formats
-
-**Custom nodes** (`py/nodes/`):
-- Each node class has a `NAME` class attribute used as key in `NODE_CLASS_MAPPINGS`
-- Standard ComfyUI node pattern: `INPUT_TYPES()` classmethod, `RETURN_TYPES`, `FUNCTION`
-- All nodes registered in `__init__.py`
-
-**Configuration** (`py/config.py`):
-- Manages folder paths for models, handles symlink mappings
-- Auto-saves paths to settings.json in ComfyUI mode
-
-### Frontend — Two Distinct UI Systems
-
-#### 1. Standalone Manager Web UI
-- **Location:** `static/` (JS/CSS) and `templates/` (HTML)
-- **Tech:** Vanilla JS + CSS, served by standalone server
-- **Structure:** `static/js/core.js` (shared), `loras.js`, `checkpoints.js`, `embeddings.js`, `recipes.js`, `statistics.js`
-- **Tests:** `tests/frontend/**/*.test.js` (vitest + jsdom)
-
-#### 2. ComfyUI Custom Node Widgets
-- **Vanilla JS widgets:** `web/comfyui/*.js` — ES modules extending ComfyUI's LiteGraph UI
-  - `loras_widget.js` / `loras_widget_events.js` — Main LoRA selection widget
-  - `autocomplete.js` — Trigger word and embedding autocomplete
-  - `preview_tooltip.js` — Model card preview tooltips
-  - `top_menu_extension.js` — "Launch LoRA Manager" menu item
-  - `utils.js` — Shared utilities and API helpers
-  - Widget styling in `web/comfyui/lm_styles.css` (NOT `static/css/`)
-- **Vue widgets:** `vue-widgets/src/` → built to `web/comfyui/vue-widgets/`
-  - Vue 3 + TypeScript + PrimeVue + vue-i18n
-  - Vite build with CSS-injected-by-JS plugin
-  - Components: `LoraPoolWidget`, `LoraRandomizerWidget`, `LoraCyclerWidget`, `AutocompleteTextWidget`
-  - Auto-built on ComfyUI startup via `py/vue_widget_builder.py`
-  - Tests: `vue-widgets/tests/**/*.test.ts` (vitest)
-
-**Widget registration pattern:**
-- Widgets use `app.registerExtension()` and `getCustomWidgets` hooks
-- `node.addDOMWidget(name, type, element, options)` embeds HTML in LiteGraph nodes
-- See `docs/dom_widget_dev_guide.md` for DOMWidget development guide
-
-## Code Style
-
-**Python:**
-- PEP 8, 4-space indentation, English comments only
-- Use `from __future__ import annotations` for forward references
-- Use `TYPE_CHECKING` guard for type-checking-only imports
-- Loggers via `logging.getLogger(__name__)`
-- Custom exceptions in `py/services/errors.py`
-- Async patterns: `async def` for I/O, `@pytest.mark.asyncio` for async tests
-- Singleton pattern with class-level `asyncio.Lock` (see `ModelScanner.get_instance()`)
-
-**JavaScript:**
-- ES modules, camelCase functions/variables, PascalCase classes
-- Widget files use `*_widget.js` suffix
-- Prefer vanilla JS for `web/comfyui/` widgets, avoid framework dependencies (except Vue widgets)
-
-## Testing
-
-**Backend (pytest):**
-- Config in `pytest.ini`: `--import-mode=importlib`, testpaths=`tests`
-- Fixtures in `tests/conftest.py` handle ComfyUI dependency mocking
-- Markers: `@pytest.mark.asyncio`, `@pytest.mark.no_settings_dir_isolation`
-- Uses `tmp_path_factory` for directory isolation
-
-**Frontend (vitest):**
-- Vanilla JS tests: `tests/frontend/**/*.test.js` with jsdom
-- Vue widget tests: `vue-widgets/tests/**/*.test.ts` with jsdom + @vue/test-utils
-- Setup in `tests/frontend/setup.js`
-
-## Key Integration Points
-
-- **Settings:** Stored in user directory (via `platformdirs`) or portable mode (`"use_portable_settings": true`)
-- **CivitAI/CivArchive:** API clients for metadata sync and model downloads; CivitAI API key in settings
-- **Symlink handling:** Config scans symlinks to map virtual→physical paths; fingerprinting prevents redundant rescans
-- **WebSocket:** Broadcasts real-time progress for downloads, scans, and metadata sync
-- **Model scanning flow:** Walk folders → compute hashes → deduplicate → extract safetensors metadata → cache in SQLite → background CivitAI sync → WebSocket broadcast