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

# VLM Command Recipes

## Baseline

Run from repository root unless user specifies otherwise.

```bash
vlm --help
vlm config show
vlm config validate
```

If `vlm` is not on PATH, switch to:

```bash
uv run vlm --help
uv run vlm config show
uv run vlm config validate
```

## End-to-End Pipeline

```bash
vlm scan --output inventory.csv
vlm parse --input inventory.csv --output identities.json --inventory inventory.csv
vlm enrich
vlm analyze --input identities.json --output analysis.json --inventory inventory.csv
vlm plan --input identities.json --output plan.json --analysis analysis.json
vlm review-plan --input plan.json --output plan_manual_review.csv
vlm execute --plan plan.json
vlm execute --plan plan.json --confirm
```

## Artifact Expectations

1. `inventory.csv`: discovered video files with filesystem and optional ffprobe metadata.
2. `identities.json`: parsed identities for movie/series/anime/other, optionally with embedded quality metadata.
3. `analysis.json`: completeness gaps and duplicate groups with quality comparison context.
4. `plan.json`: planned operations (`move`, `rename`, `quarantine`, `no-op`) and summary data.
5. `plan_manual_review.csv`: high-risk operations requiring human confirmation before `--confirm`.

## Focused Workflows

```bash
# Parse only, with metadata embedding
vlm parse --inventory inventory.csv

# Analyze only
vlm analyze --input identities.json --output analysis.json --inventory inventory.csv

# Plan from analysis-assisted duplicate decisions
vlm plan --input identities.json --analysis analysis.json --output plan.json

# Roll back latest confirmed execution
vlm rollback
```

## Frequent Failure Triage

1. Missing config:
   Run `vlm config init`, then set `library_root` in `~/.vlm/config.yaml`.
2. Invalid config values:
   Run `vlm config validate` and fix reported keys.
3. Missing input artifact:
   Run the prerequisite stage (`scan` before `parse`, `parse` before `analyze`, `analyze` before analysis-driven `plan`).
4. Unexpected duplicate decisions:
   Check `plan.duplicate_keep` in config and rerun `vlm plan --analysis analysis.json`.
5. Unsafe or undesired execution results:
   Run `vlm rollback` and inspect plan before re-running `execute --confirm`.
6. `vlm` command not found:
   Use `uv run vlm ...` fallback for the same subcommands.