refactor default artifacts workspace and path compatibility

README.md

@@ -48,6 +48,7 @@ This creates `~/.vlm/config.yaml`. Edit it to set your library root:
 
 ```yaml
 library_root: "/mnt/Downloads"  # Change this to your video library path
+workspace_dir: "artifacts"      # Default workspace for generated files
 ```
 
 ### 2. Scan Your Library
@@ -58,14 +59,14 @@ Discover all video files in your library:
 vlm scan
 ```
 
-This creates `inventory.csv` with all discovered files and their metadata.
+This creates `artifacts/inventory.csv` with all discovered files and their metadata.
 
 **What happens:**
 - Discovers video files using the system `find` command
 - Extracts file metadata (size, modification time)
 - Categorizes files based on directory structure (movie/series/anime/other)
 - Extracts video metadata using ffprobe (if available)
-- Saves results to `inventory.csv`
+- Saves results to `artifacts/inventory.csv`
 
 ### 3. Parse Filenames
 
@@ -78,10 +79,10 @@ vlm parse
 **For accurate duplicate resolution by quality, embed video metadata:**
 
 ```bash
-vlm parse --inventory inventory.csv
+vlm parse --inventory artifacts/inventory.csv
 ```
 
-This creates `identities.json` with parsed information. When using `--inventory`, video metadata (size, resolution, codec) is embedded, enabling accurate quality comparison during duplicate analysis.
+This creates `artifacts/identities.json` with parsed information. When using `--inventory`, video metadata (size, resolution, codec) is embedded, enabling accurate quality comparison during duplicate analysis.
 
 **What it extracts:**
 - **Movies**: Title and year (e.g., "Inception (2010)")
@@ -91,13 +92,13 @@ This creates `identities.json` with parsed information. When using `--inventory`
 
 ### 4. Enrich Titles and Reputation (Optional but Recommended)
 
-Add translation and reputation metadata to `identities.json`:
+Add translation and reputation metadata to `artifacts/identities.json`:
 
 ```bash
 vlm enrich
 ```
 
-This updates `identities.json` in place and adds fields like:
+This updates `artifacts/identities.json` in place and adds fields like:
 - `title_zh`, `title_en`, `display_title`
 - `reputation_score`, `reputation_votes`, `reputation_source`
 - `review_status`, `enrichment_confidence`
@@ -123,7 +124,7 @@ Detect episode gaps and duplicates:
 vlm analyze
 ```
 
-This creates `analysis.json` with:
+This creates `artifacts/analysis.json` with:
 - Series with missing episodes
 - Duplicate files with quality comparison
 
@@ -138,10 +139,10 @@ vlm plan
 To let the plan automatically resolve duplicate groups (keep one file per group by reputation, quarantine the rest), pass the analysis file:
 
 ```bash
-vlm plan --analysis analysis.json
+vlm plan --analysis artifacts/analysis.json
 ```
 
-This creates `plan.json` with:
+This creates `artifacts/plan.json` with:
 - Proposed operations (move, rename, quarantine, no-op)
 - **Summary**: counts by operation type and by reason
 - **Human summary** (中文): short narrative for quick review
@@ -158,7 +159,7 @@ Duplicate keep strategy is configurable in `~/.vlm/config.yaml` under `plan.dupl
 - `first_seen` - Keep the first file in each duplicate group.
 - `manual` - Do not generate quarantine operations; duplicates are listed in analysis only.
 
-**Review the plan** by opening `plan.json` in your editor, or read the human summary when you run `vlm execute`. You can edit the plan JSON if needed.
+**Review the plan** by opening `artifacts/plan.json` in your editor, or read the human summary when you run `vlm execute`. You can edit the plan JSON if needed.
 
 ### 7. Execute (Dry-Run First)
 
@@ -177,7 +178,7 @@ 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`
+- Even if a manually edited `artifacts/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)
@@ -201,26 +202,26 @@ vlm config init
 
 # 2. Scan your library
 vlm scan
-# Output: inventory.csv with 1234 files discovered
+# Output: artifacts/inventory.csv with 1234 files discovered
 
 # 3. Parse filenames with metadata embedding (recommended for duplicate resolution)
-vlm parse --inventory inventory.csv
-# Output: identities.json with parsed titles, episodes, and embedded video metadata (v2 schema)
+vlm parse --inventory artifacts/inventory.csv
+# Output: artifacts/identities.json with parsed titles, episodes, and embedded video metadata (v2 schema)
 
 # 4. Enrich identities (translation + reputation)
 vlm enrich
-# Output: identities.json updated in place (incremental cache enabled)
+# Output: artifacts/identities.json updated in place (incremental cache enabled)
 
 # 5. Analyze for gaps and duplicates
 vlm analyze
-# Output: analysis.json with 5 series with gaps, 12 duplicate groups (accurate quality comparison)
+# Output: artifacts/analysis.json with 5 series with gaps, 12 duplicate groups (accurate quality comparison)
 
 # 6. Generate execution plan (optionally use analysis for duplicate handling)
-vlm plan --analysis analysis.json
-# Output: plan.json with operations, human summary, and duplicate quarantine decisions
+vlm plan --analysis artifacts/analysis.json
+# Output: artifacts/plan.json with operations, human summary, and duplicate quarantine decisions
 
 # 7. Review the plan
-cat plan.json | less
+cat artifacts/plan.json | less
 # or open in your editor
 
 # 8. Dry-run to preview
@@ -253,7 +254,7 @@ vlm config validate
 ### Scanning
 
 ```bash
-# Scan with default output (inventory.csv)
+# Scan with default output (artifacts/inventory.csv)
 vlm scan
 
 # Scan with custom output file
@@ -274,7 +275,7 @@ vlm scan --output my_library.csv
 vlm parse
 
 # Parse with metadata embedding (v2 schema - enables quality comparison)
-vlm parse --inventory inventory.csv
+vlm parse --inventory artifacts/inventory.csv
 
 # Parse with custom input/output
 vlm parse --input my_inventory.csv --output my_identities.json
@@ -290,7 +291,7 @@ vlm parse --input my_inventory.csv --output my_identities.json --inventory my_in
 ### Enrichment
 
 ```bash
-# Enrich identities in place (default: identities.json)
+# Enrich identities in place (default: artifacts/identities.json)
 vlm enrich
 
 # Enrich custom file and write to another file
@@ -323,7 +324,7 @@ vlm analyze --input my_identities.json --output my_analysis.json
 vlm plan
 
 # Use analysis so duplicate groups become "keep one + quarantine rest" (by_reputation by default)
-vlm plan --analysis analysis.json
+vlm plan --analysis artifacts/analysis.json
 
 # Custom input/output
 vlm plan --input my_identities.json --output my_plan.json
@@ -382,12 +383,12 @@ vlm report inventory --format json --output inventory_report.json
 # Generate completeness report (series with gaps)
 vlm report completeness
 
-# Include plan content summary in the report (human_summary from plan.json)
-vlm report completeness --plan plan.json
+# Include plan content summary in the report (human_summary from artifacts/plan.json)
+vlm report completeness --plan artifacts/plan.json
 
 # Generate duplicates report
 vlm report duplicates
-vlm report duplicates --plan plan.json
+vlm report duplicates --plan artifacts/plan.json
 
 # Generate summary statistics
 vlm report summary
@@ -418,6 +419,9 @@ The configuration file (`~/.vlm/config.yaml`) controls VLM's behavior:
 # Required: Root directory of your video library
 library_root: "/mnt/nas/videos"
 
+# Workspace directory for generated artifacts
+workspace_dir: "artifacts"
+
 # Video file extensions to recognize
 video_extensions:
   - .mp4
@@ -512,10 +516,10 @@ Validation flow:
 
 ```bash
 # 1) run small incremental pass
-vlm enrich --input identities.json --refresh-changed-only
+vlm enrich --input artifacts/identities.json --refresh-changed-only
 
 # 2) then full refresh if output looks correct
-vlm enrich --input identities.json --refresh-all
+vlm enrich --input artifacts/identities.json --refresh-all
 ```
 
 ### Template Variables
@@ -592,7 +596,7 @@ vlm report summary
 ```bash
 # 1. Scan and parse
 vlm scan
-vlm parse --inventory inventory.csv
+vlm parse --inventory artifacts/inventory.csv
 vlm enrich
 
 # 2. Analyze completeness
@@ -600,7 +604,7 @@ vlm analyze
 
 # 3. View report (optionally include plan summary if you have a plan)
 vlm report completeness
-vlm report completeness --plan plan.json
+vlm report completeness --plan artifacts/plan.json
 ```
 
 ### Scenario 3: Finding and Removing Duplicates
@@ -608,7 +612,7 @@ vlm report completeness --plan plan.json
 ```bash
 # 1. Scan and parse (with --inventory for accurate quality comparison)
 vlm scan
-vlm parse --inventory inventory.csv
+vlm parse --inventory artifacts/inventory.csv
 vlm enrich
 
 # 2. Analyze for duplicates
@@ -618,9 +622,9 @@ vlm analyze
 vlm report duplicates
 
 # 4. Generate plan with analysis: VLM keeps one file per duplicate group (by reputation) and quarantines the rest
-vlm plan --analysis analysis.json
+vlm plan --analysis artifacts/analysis.json
 
-# 5. Review plan (human summary in plan.json and when you run execute)
+# 5. Review plan (human summary in artifacts/plan.json and when you run execute)
 vlm execute
 vlm execute --confirm
 
@@ -628,7 +632,7 @@ vlm execute --confirm
 vlm quarantine add /path/to/lower/quality/file.mkv --reason "duplicate - lower quality"
 
 # Report with plan context
-vlm report duplicates --plan plan.json
+vlm report duplicates --plan artifacts/plan.json
 ```
 
 ### Scenario 4: Reorganizing Your Library
@@ -639,13 +643,13 @@ vlm report duplicates --plan plan.json
 
 # 2. Scan and parse
 vlm scan
-vlm parse --inventory inventory.csv
+vlm parse --inventory artifacts/inventory.csv
 vlm enrich
 
 # 3. Generate plan
 vlm plan
 
-# 4. Review plan.json carefully
+# 4. Review artifacts/plan.json carefully
 
 # 5. Dry-run to preview
 vlm execute