chore: snapshot current project updates

CLAUDE.md

@@ -8,6 +8,8 @@ Video Library Manager (VLM) is a Python CLI tool for managing personal video col
 
 ## Development Commands
 
+**Important:** This project uses `uv` for Python package management. All commands should be run with `uv run` to ensure they execute in the correct project environment with proper dependencies.
+
 ### Installation
 ```bash
 # Install package in editable mode
@@ -19,51 +21,57 @@ uv pip install -e ".[dev]"
 
 ### Testing
 ```bash
-# Run all tests
-pytest
+# Run all tests (use uv run to execute in the project environment)
+uv run pytest
 
 # Run specific test file
-pytest tests/test_scanner.py
+uv run pytest tests/test_scanner.py
 
 # Run with verbose output
-pytest -v
+uv run pytest -v
+
+# Run with quiet output (summary only)
+uv run pytest -q
+
+# Count total test cases
+uv run pytest --collect-only -q
 ```
 
 ### Running the CLI
 ```bash
-# Verify CLI works
-vlm --help
+# Verify CLI works (use uv run for proper environment)
+uv run vlm --help
 
 # Initialize config
-vlm config init
+uv run vlm config init
 
 # Common workflow
-vlm scan                    # Discover files
-vlm parse                   # Extract identities (v1 schema)
-vlm parse --inventory inventory.csv  # Extract identities with embedded metadata (v2 schema, recommended)
-vlm enrich                  # (Optional) Enrich titles/reputation via TMDB
-vlm enrich --refresh-all    # Force full refresh (ignore cache)
-vlm analyze                 # Detect gaps/duplicates
-vlm plan                    # Generate execution plan
-vlm plan --analysis analysis.json  # Generate plan with duplicate resolution
-vlm execute                 # Dry-run (default)
-vlm execute --confirm       # Actually execute
-vlm rollback                # Undo executed operations
+uv run vlm scan                    # Discover files
+uv run vlm parse                   # Extract identities (v1 schema)
+uv run vlm parse --inventory inventory.csv  # Extract identities with embedded metadata (v2 schema, recommended)
+uv run vlm enrich                  # (Optional) Enrich titles/reputation via TMDB
+uv run vlm enrich --refresh-all    # Force full refresh (ignore cache)
+uv run vlm analyze                 # Detect gaps/duplicates
+uv run vlm plan                    # Generate execution plan
+uv run vlm plan --analysis analysis.json  # Generate plan with duplicate resolution
+uv run vlm execute                 # Dry-run (default)
+uv run vlm execute --confirm       # Actually execute
+uv run vlm rollback                # Undo executed operations
 
 # Reporting
-vlm report summary          # Overview statistics
-vlm report inventory        # File inventory
-vlm report completeness     # Series with missing episodes
-vlm report duplicates       # Duplicate files with quality comparison
+uv run vlm report summary          # Overview statistics
+uv run vlm report inventory        # File inventory
+uv run vlm report completeness     # Series with missing episodes
+uv run vlm report duplicates       # Duplicate files with quality comparison
 
 # Quarantine management
-vlm quarantine list         # List quarantined files
-vlm quarantine add <file> --reason "duplicate"
-vlm quarantine restore <file>
+uv run vlm quarantine list         # List quarantined files
+uv run vlm quarantine add <file> --reason "duplicate"
+uv run vlm quarantine restore <file>
 
 # State management
-vlm state show <file>
-vlm state set <file> --status reviewed
+uv run vlm state show <file>
+uv run vlm state set <file> --status reviewed
 ```
 
 ## Architecture