Enhance project structure and add new files for enrichment and analysis

- Updated AGENTS.md to reflect changes in CLI commands and module organization, including the addition of an enrichment step and new functional modules.
- Introduced analysis.json, identities.json, inventory.csv, and plan.json to support enriched metadata and execution planning.
- Added CODE_IMPROVEMENTS.md to document identified code issues and proposed solutions for future enhancements.
- Updated README.md to include new enrichment features and configuration options.
- Removed unused dependency on ffmpeg-python from pyproject.toml.

These changes improve the overall functionality and maintainability of the Video Library Manager project.

README.md

@@ -9,7 +9,7 @@ A Python-based CLI tool for managing personal video collections with a safety-fi
 - **Comprehensive Analysis**: Detect episode gaps and duplicate files
 - **Rich Metadata**: Extract video resolution, codec, duration, and bitrate
 - **Flexible Organization**: Customizable directory structure and naming templates
-- **Metadata Enrichment**: Add bilingual titles and reputation signals (TMDB + optional Douban + optional AI fallback)
+- **Metadata Enrichment**: Add bilingual titles and reputation signals (TMDB + optional AI fallback)
 - **Incremental Performance**: SQLite-backed cache avoids repeated metadata lookups
 - **State Tracking**: Track file status throughout the workflow
 - **Detailed Reporting**: Generate inventory, completeness, and duplicate reports
@@ -86,6 +86,7 @@ This updates `identities.json` in place and adds fields like:
 - `title_zh`, `title_en`, `display_title`
 - `reputation_score`, `reputation_votes`, `reputation_source`
 - `review_status`, `enrichment_confidence`
+- summary metrics including `api_calls`, `cache_hits`, and `skip_reasons`
 
 To refresh all records instead of using incremental cache:
 
@@ -93,6 +94,12 @@ To refresh all records instead of using incremental cache:
 vlm enrich --refresh-all
 ```
 
+If enrichment cannot run for some records, CLI shows grouped reasons, for example:
+
+```text
+Skip reasons: no_key=4632
+```
+
 ### 5. Analyze Your Library
 
 Detect episode gaps and duplicates:
@@ -382,7 +389,7 @@ categories:
   series: [series, tv, shows]
   anime: [anime]
 
-# Enrichment settings
+# Enrichment settings (`enrich` alias is also supported)
 enrichment:
   enabled: true
   incremental: true
@@ -395,8 +402,15 @@ enrichment:
     mode: "bidirectional"
     fallback_machine: true
   api_keys:
+    # Preferred: TMDB v4 Bearer token
+    tmdb_bearer: null
+    # Backward-compatible fallback (legacy query api_key)
     tmdb: null
     openai: null
+  tmdb:
+    language: "zh-CN"
+    region: null
+    include_adult: false
   reputation:
     min_votes: 50
     low_score_threshold: 6.0
@@ -405,6 +419,39 @@ enrichment:
     title_format: "{title_zh} {title_en}"
 ```
 
+### TMDB Enrichment Setup
+
+`vlm enrich` works best with TMDB Bearer auth (recommended by TMDB). Legacy `tmdb` api key is still supported for compatibility.
+
+Minimal config:
+
+```yaml
+enrichment:
+  providers: [tmdb]
+  api_keys:
+    tmdb_bearer: "YOUR_TMDB_BEARER_TOKEN"
+```
+
+Optional TMDB query tuning:
+
+```yaml
+enrichment:
+  tmdb:
+    language: "zh-CN"   # localized title language
+    region: "US"        # affects regional release/search behavior
+    include_adult: false
+```
+
+Validation flow:
+
+```bash
+# 1) run small incremental pass
+vlm enrich --input identities.json --refresh-changed-only
+
+# 2) then full refresh if output looks correct
+vlm enrich --input identities.json --refresh-all
+```
+
 ### Template Variables
 
 **Movies:**
@@ -576,6 +623,26 @@ vlm config init
 vlm config validate
 ```
 
+### TMDB Auth / Rate Limit / Zero Enriched
+
+Common enrichment outcomes:
+
+- `Error during enrichment: TMDB authentication failed (401/403)`  
+  Cause: invalid/missing `tmdb_bearer` (or `tmdb`) key.  
+  Action: update `~/.vlm/config.yaml` and rerun.
+
+- `Skip reasons: no_key=...`  
+  Cause: no TMDB credentials configured for provider.  
+  Action: set `enrichment.api_keys.tmdb_bearer` (recommended) or `tmdb`.
+
+- `Skip reasons: rate_limited=...`  
+  Cause: TMDB rate limit hit (`429`).  
+  Action: retry later; VLM already applies bounded retry/backoff.
+
+- `Enriched now: 0` with non-zero records  
+  Cause: often `no_key`, `no_match`, or provider errors.  
+  Action: check `Skip reasons` and `Failure sample` in CLI output.
+
 ### Permission Errors
 
 If you can't access certain files:
@@ -646,12 +713,21 @@ pytest --cov=vlm tests/
 
 ```
 src/vlm/
-├── cli.py              # Click-based CLI interface
+├── cli.py              # Click-based CLI interface, global options
+├── context.py          # CLIContext and pass_context for commands
+├── commands/           # Command implementations
+│   ├── scan.py         # Scan command
+│   ├── analyze.py      # Analyze command
+│   └── plan.py         # Plan command
 ├── scanner.py          # File discovery and metadata extraction
 ├── parser.py           # Filename parsing (titles, years, episodes)
 ├── enrichment.py       # Title/reputation enrichment pipeline
 ├── cache.py            # SQLite cache for incremental enrichment
-├── providers/          # External metadata providers (TMDB/Douban)
+├── providers/          # External metadata providers (TMDB, etc.)
+│   ├── base.py         # Provider interface
+│   └── tmdb.py         # TMDB API client
+├── io.py               # JSON/CSV load/save and plan/analysis input helpers
+├── utils.py            # UTC time, format_size, etc.
 ├── analysis.py         # Completeness and duplicate detection
 ├── planner.py          # Execution plan generation
 ├── executor.py         # File operations and rollback