improve review-plan preview output and docs

README.md

@@ -2,25 +2,28 @@
 
 ## Documentation Status
 
-- Last synchronized: **2026-02-16**
-- CLI command refactor landed (`parse`, `enrich`, `execute`, `rollback` logic moved to `src/vlm/commands/`).
-- Unified JSON I/O interfaces are available in `src/vlm/io.py`.
-- Full test baseline after refactor: **477 passed**.
+- Last synchronized: **2026-04-02**
+- Human-in-the-loop workflow includes `vlm apply-review` for syncing manual plan edits from CSV back into `plan.json`.
+- Scanner now detects `ffprobe` availability and degrades gracefully.
+- JSON artifacts (`identities.json`, `analysis.json`, `plan.json`) are schema-validated on load/save.
+- Plan generation separates logical intent from environment-derived validation snapshots, improving reproducibility.
 
 A Python-based CLI tool for managing personal video collections with a safety-first, human-in-the-loop approach.
 
 ## Features
 
 - **Safety-First Design**: All file operations are reversible with rollback support
-- **Human-in-the-Loop**: Explicit confirmation required before making any changes
+- **Human-in-the-Loop**: Explicit confirmation required before making any changes. **New: Full review-apply cycle for manual plan adjustments via CSV.**
 - **Comprehensive Analysis**: Detect episode gaps and duplicate files
-- **Rich Metadata**: Extract video resolution, codec, duration, and bitrate
+- **Rich Metadata**: Extract video resolution, codec, duration, and bitrate (with graceful fallback if `ffprobe` is missing)
 - **Flexible Organization**: Customizable directory structure and naming templates
 - **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 (reports can include plan content summary via `--plan`)
-- **Plan–Analysis Integration**: `vlm plan --analysis` applies duplicate resolution (keep by reputation, quarantine rest) and adds a Chinese human summary to the plan for quick review
+- **Detailed Reporting**: Generate inventory, completeness, and duplicate reports
+- **Plan–Analysis Integration**: `vlm plan --analysis` applies duplicate resolution and adds a Chinese human summary
+- **Artifact Validation**: JSON artifacts are validated early to catch malformed inputs before later stages run
+- **Deterministic Planning**: Plan generation records live filesystem checks as validation snapshots instead of mixing them into core plan facts
 
 ## Installation
 
@@ -159,7 +162,12 @@ 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 `artifacts/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** in one of three ways:
+- Open `artifacts/plan.json` in your editor
+- Run `vlm review-plan` to get a terminal preview (summary + high-risk operation preview)
+- Run `vlm execute` to see the same plan summary in dry-run mode
+
+You can still edit `plan.json` directly when needed.
 
 ### 7. Execute (Dry-Run First)
 
@@ -220,13 +228,20 @@ vlm analyze
 vlm plan --analysis artifacts/analysis.json
 # Output: artifacts/plan.json with operations, human summary, and duplicate quarantine decisions
 
-# 7. Review the plan
-cat artifacts/plan.json | less
-# or open in your editor
+# 7. Review the plan in terminal (summary + high-risk preview)
+vlm review-plan
+# Optional: control preview size
+vlm review-plan --preview-limit 20
+# Optional: show every high-risk operation in terminal
+vlm review-plan --show-all
+# Edit artifacts/plan_manual_review.csv in Excel/Numbers
+# Sync your manual decisions back to artifacts/plan.json
+vlm apply-review
+# Output: Successfully updated plan saved to: artifacts/plan.json
 
 # 8. Dry-run to preview
 vlm execute
-# Shows what would happen without making changes
+# Shows what would happen without making changes (respecting your manual edits)
 
 # 9. Execute with confirmation
 vlm execute --confirm
@@ -331,6 +346,22 @@ vlm plan --input my_identities.json --output my_plan.json
 vlm plan --input my_identities.json --analysis my_analysis.json --output my_plan.json
 ```
 
+### Manual Plan Review
+
+```bash
+# Export high-risk operations and preview them in terminal
+vlm review-plan
+
+# Preview first N high-risk operations in terminal (default: 10)
+vlm review-plan --preview-limit 20
+
+# Show all high-risk operations in terminal preview
+vlm review-plan --show-all
+
+# Apply edited CSV decisions back to plan.json
+vlm apply-review
+```
+
 ### Execution
 
 ```bash