# Documentation Status
- Synced with artifacts/ baseline on 2026-06-01.

# 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` and optionally `workspace_dir: artifacts`.

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

## 2. Identification

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

### Metadata Enrichment
```bash
vlm enrich
```
- **Goal**: Update `artifacts/identities.json` with TMDB data.
- **Troubleshooting**: Check `enrichment.api_keys` in config; never commit `~/.vlm/config.yaml`.

## 3. Analysis and Planning

### Detect Issues
```bash
vlm analyze
```
- **Goal**: Create `artifacts/analysis.json`.
- **Outputs**: Episode gaps and duplicate groups.

### Create Execution Plan
```bash
vlm plan --analysis artifacts/analysis.json
```
- **Goal**: Create `artifacts/plan.json`.
- **Strategy**: Uses `plan.duplicate_keep` (default: `by_reputation`) for duplicate decisions.

## 4. Review and Execution

### Human review
```bash
vlm review-plan
# Optional: vlm review-plan --tui  (requires textual extra)
vlm apply-review   # after editing artifacts/plan_manual_review.csv
```

### Execute Changes
```bash
vlm execute           # Dry-run
vlm execute --confirm # Actual operations (explicit confirmation)
```

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