chore: snapshot current project updates

README.md

@@ -140,9 +140,14 @@ This creates `plan.json` with:
 - **Human summary** (中文): short narrative for quick review
 - **Metadata**: when using `--analysis`, duplicate groups considered and completeness gaps
 
+Safety guards in planning:
+- Titles used in path templates are sanitized (path separators/control chars/`..` stripped)
+- Any destination outside `library_root` is rejected as `no-op`
+
 Duplicate keep strategy is configurable in `~/.vlm/config.yaml` under `plan.duplicate_keep`:
 - `by_quality` - Prefer highest quality (resolution > source > codec > file size). Best for automatic duplicate resolution.
-- `by_reputation` - Prefer external rating (TMDB); fallback to first-seen. Default.
+- `by_reputation` - Prefer external rating (TMDB); when rating ties/missing, fallback to quality (source-first: BluRay > WEB-DL), then first-seen. Default.
+- `by_reputation_quality_time` - Prefer external rating first, then quality, then newer modified time.
 - `first_seen` - Keep the first file in each duplicate group.
 - `manual` - Do not generate quarantine operations; duplicates are listed in analysis only.
 
@@ -164,6 +169,10 @@ vlm execute --confirm
 
 **Important**: This creates a rollback log in `~/.vlm/rollback/` for reverting changes.
 
+Execution safeguards:
+- Even if a manually edited `plan.json` contains an unsafe destination, execution rejects paths outside `library_root`
+- Summary counters treat conflict skips separately from real failures (`failed`/`skipped` are mutually exclusive)
+
 ### 8. Rollback (If Needed)
 
 If you need to undo the operations:
@@ -248,6 +257,7 @@ vlm scan --output my_library.csv
 - Hidden paths are skipped (any component starting with `.`)
 - File matching uses configured `video_extensions` (default: `.mp4`, `.mkv`, `.avi`, `.mov`, `.wmv`, `.flv`, `.webm`, `.m4v`)
 - If `ffprobe` is available, resolution/codec/duration/bitrate are included
+- ffprobe extraction uses controlled concurrency (`enrichment.max_concurrency`)
 - Timestamps stored in UTC format (`YYYY-MM-DDTHH:MM:SS`)
 
 ### Parsing
@@ -427,7 +437,8 @@ log_level: "INFO"
 
 # Plan behavior (e.g. when using vlm plan --analysis)
 plan:
-  # Duplicate keep strategy: "by_quality", "by_reputation" (default), "first_seen", or "manual"
+  # Duplicate keep strategy: "by_quality", "by_reputation" (default),
+  # "by_reputation_quality_time", "first_seen", or "manual"
   # by_quality: resolution > source (BluRay > WEB-DL) > codec (x265 > x264) > file size
   duplicate_keep: "by_reputation"
 
@@ -444,7 +455,7 @@ enrichment:
   refresh_mode: "manual"
   providers: [tmdb]
   cache_db: "~/.vlm/enrichment_cache.db"
-  max_concurrency: 6
+  max_concurrency: 6  # used by enrichment requests and scan-time ffprobe workers
   min_match_score: 0.75
   translation:
     mode: "bidirectional"
@@ -739,6 +750,29 @@ Always keep backups of important files!
 - **Local files only**: Designed for local or mounted network storage
 - **Best-effort rollback**: Rollback may not succeed if files have been modified
 
+## Gemini CLI Agent Skills
+
+This project includes built-in expert guidance for the Gemini CLI. These skills co-locate project knowledge with the source code.
+
+### Activation
+
+To activate the expert guidance in Gemini CLI, use:
+
+```bash
+# General expert guidance and knowledge base
+activate_skill vlm-expert
+
+# Step-by-step library organization workflow
+activate_skill vlm-library-workflow
+```
+
+### Features
+
+- **Context-Aware Guidance**: The Agent understands the VLM safety-first workflow and configuration.
+- **Risk Warnings**: Automatic alerts if a plan contains high-risk operations (>20% quarantine).
+- **Command Recipes**: Instant access to complex command sequences and troubleshooting steps.
+- **Developer Verification**: Built-in test execution recipes for verifying core logic changes.
+
 ## Development
 
 ### Running Tests
@@ -784,7 +818,7 @@ src/vlm/
 ├── io.py               # JSON/CSV load/save, load_analysis_json, plan/analysis input helpers
 ├── utils.py            # UTC time, format_size, etc.
 ├── analysis.py         # Completeness and duplicate detection
-├── duplicate_resolve.py # Duplicate group keep-index (by_quality, by_reputation, first_seen, manual)
+├── duplicate_resolve.py # Duplicate group keep-index (by_quality, by_reputation, by_reputation_quality_time, first_seen, manual)
 ├── planner.py          # Execution plan generation (optionally consumes analysis)
 ├── executor.py         # File operations and rollback
 ├── quarantine.py       # Quarantine management