# Documentation Status
- Synced with refactor baseline on 2026-02-16.

# VLM Workflow Guide

This guide details the standard end-to-end process for organizing a video library using VLM.

## 1. Setup and Discovery

### Initialize Configuration
```bash
vlm config init
```
Edit `~/.vlm/config.yaml` to set `library_root`.

### Library Scan
```bash
vlm scan
```
- **Goal**: Create `inventory.csv`.
- **Note**: Ensure `ffprobe` is installed for resolution and codec metadata.

## 2. Identification

### Filename Parsing
```bash
vlm parse --inventory inventory.csv
```
- **Goal**: Create `identities.json`.
- **Why --inventory?**: It embeds video metadata (v2 schema) required for quality-based duplicate resolution.

### Metadata Enrichment
```bash
vlm enrich
```
- **Goal**: Update `identities.json` with TMDB data.
- **Troubleshooting**: If matches are missing, check `enrichment.api_keys` in config.

## 3. Analysis and Planning

### Detect Issues
```bash
vlm analyze
```
- **Goal**: Create `analysis.json`.
- **Outputs**: Lists duplicate files and episode gaps in series.

### Create Execution Plan
```bash
vlm plan --analysis analysis.json
```
- **Goal**: Create `plan.json`.
- **Strategy**: VLM uses the `duplicate_keep` policy (default: `by_reputation`) to decide which files to keep and which to quarantine.

## 4. Execution and Safety

### Review the Plan
Open `plan.json` and check the `human_summary` field or the proposed `operations`.

### Execute Changes
```bash
vlm execute           # Dry-run
vlm execute --confirm # Actual operations
```

### Reverting Changes
```bash
vlm rollback
```
Restores files using the latest log in `~/.vlm/rollback/`.