commit remaining modified project files

GEMINI.md

@@ -1,7 +1,7 @@
 # GEMINI.md
 
 ## Documentation Status
-- Synced with repository refactor baseline on 2026-02-16 (source of truth: `CHANGELOG.md`).
+- Synced with repository refactor baseline on 2026-02-20 (source of truth: `CHANGELOG.md`).
 
 This document provides a comprehensive overview of the Video Library Manager (VLM) project, intended to be used as instructional context for Gemini.
 
@@ -11,10 +11,12 @@ The Video Library Manager (VLM) is a Python-based CLI tool designed for managing
 
 **Core Functionality:**
 
-*   **Scanning & Parsing:** Discovers video files, extracts metadata (file info, video properties via `ffprobe`), and parses filenames to identify titles, years, seasons, and episodes.
+*   **Scanning & Parsing:** Discovers video files, extracts metadata. Proactively detects `ffprobe` for video properties with graceful fallback to file-level metadata. Parses filenames for titles, years, seasons, and episodes, with specific support for Anime-style hyphenated numbering and release group stripping.
 *   **Metadata Enrichment:** Augments local data with information from TMDB, including bilingual titles and reputation scores. It uses a local SQLite cache to improve performance.
 *   **Analysis:** Detects duplicate files (with quality comparisons) and identifies gaps in TV series episodes.
-*   **Planning & Execution:** Generates a reviewable JSON-based execution plan for file operations (move, rename, quarantine). The plan is executed only upon user confirmation.
+*   **Planning & Execution:** Generates a reviewable JSON-based execution plan for file operations (move, rename, quarantine). Supports "safe mode" and directory preservation.
+*   **Plan Review Cycle:** Exports high-risk operations to CSV for manual confirmation (`review-plan`) and synchronizes user decisions back to the master plan (`apply-review`), enabling a full human-in-the-loop workflow.
+*   **Quarantine Management:** Safely isolates files for review, with full support for listing and restoration.
 *   **Reporting:** Creates reports for inventory, duplicate files, and series completeness.
 *   **State Management:** Tracks the status of files throughout the organization workflow.
 
@@ -29,14 +31,25 @@ The Video Library Manager (VLM) is a Python-based CLI tool designed for managing
 
 **Architecture:**
 
-The project follows a modular structure located in the `src/vlm` directory. Key modules include:
+The project follows a modular structure located in the `src/vlm` directory.
 
 *   `cli.py`: The main entry point for the CLI, using Click.
-*   `commands/*.py`: Implementation of the individual CLI commands (scan, parse, enrich, etc.).
+*   `commands/*.py`: Implementation of the individual CLI commands (scan, parse, enrich, analyze, plan, execute/rollback).
 *   `scanner.py`, `parser.py`, `enrichment.py`, `analysis.py`, `planner.py`, `executor.py`: Core logic for the different stages of the workflow.
+*   `io.py`: Unified I/O layer for JSON and CSV handling.
+*   `cache.py`: Local SQLite cache for TMDB metadata.
+*   `context.py`: CLI context and state management for command execution.
+*   `duplicate_resolve.py`: Logic for resolving duplicate files based on quality and metadata.
+*   `logging_config.py`: Centralized logging configuration.
+*   `plan_review.py`: Risk analysis and manual review generation for execution plans.
+*   `quarantine.py`: Management of quarantined files (listing, adding, restoring).
+*   `reports.py`: Generation of inventory, completeness, and duplicate reports.
+*   `state.py`: File status tracking and persistence (reviewed, ignored, planned, etc.).
+*   `transaction.py`: Atomic filesystem operations and transaction logging for reliability.
 *   `providers/tmdb.py`: Client for interacting with the TMDB API.
 *   `models.py`: Defines the data structures used throughout the application.
 *   `config.py`: Manages application configuration from a YAML file.
+*   `utils.py`: General utility functions (formatting, path handling).
 
 ## Building and Running
 
@@ -57,9 +70,13 @@ The main entry point is the `vlm` command.
 *   Enrich metadata: `uv run vlm enrich`
 *   Analyze the library: `uv run vlm analyze`
 *   Generate a plan: `uv run vlm plan`
+*   Review a plan: `uv run vlm review-plan`
 *   Execute the plan (dry-run): `uv run vlm execute`
 *   Execute the plan (with confirmation): `uv run vlm execute --confirm`
 *   Rollback the last execution: `uv run vlm rollback`
+*   Generate reports: `uv run vlm report [inventory|completeness|duplicates|summary]`
+*   Manage quarantine: `uv run vlm quarantine [list|add|restore]`
+*   Manage file states: `uv run vlm state [show|set|query|clear]`
 
 **Running tests:**