dl-organizer/AGENTS.md

# Repository Guidelines

## Project Overview
Video Library Manager (VLM) - Python CLI for managing personal video collections. Safety-first, human-in-the-loop approach. All operations reversible.

## Quick Start
```bash
uv pip install -e ".[dev]"     # Install with dev deps
uv run pytest -q               # Run tests
uv run vlm --help              # Verify CLI
```

## Core Workflow
1. `vlm scan` → discover files → `artifacts/inventory.csv`
2. `vlm parse` → extract identities → `artifacts/identities.json`
3. `vlm enrich` → (optional) add TMDB metadata
4. `vlm analyze` → detect gaps/duplicates → `artifacts/analysis.json`
5. `vlm plan` → generate execution plan → `artifacts/plan.json`
6. `vlm review-plan` → preview high-risk operations
7. `vlm execute` → dry-run by default, `--confirm` to execute
8. `vlm rollback` → undo executed operations

## Project Structure
- `src/vlm/cli.py` - CLI entrypoint
- `src/vlm/commands/` - Command implementations (scan, parse, enrich, analyze, plan, execute, review_plan, report, quarantine_cmd, state_cmd, config_cmd)
- `src/vlm/scanner.py` - File discovery + ffprobe metadata
- `src/vlm/parser.py` - Filename parsing (movies: title+year, series: SxxExx)
- `src/vlm/enrichment.py` - TMDB enrichment pipeline
- `src/vlm/planner.py` - Execution plan generation
- `src/vlm/executor.py` - File operations with rollback
- `src/vlm/models.py` - Data structures (VideoFile, MovieIdentity, SeriesIdentity, etc.)
- `tests/` - Test suite mirroring source modules

## Key Concepts

### Safety Protocol
- NEVER delete files permanently - use quarantine
- All operations create rollback logs with `--confirm`
- Default mode is dry-run

### File Categorization
Based on top-level directory matching `categories` config (case-insensitive). Default: `movie`, `series`, `anime`.

### Schema Versions
- **v1** (default): Lightweight, no embedded metadata
- **v2** (with `--inventory`): Includes video metadata for quality-aware duplicate resolution

### Parsing Patterns (Hardcoded)
- Movies: `{title} ({year})` or `{title}.{year}`
- Series: `S{season:02d}E{episode:02d}` or `{season}x{episode}`

## Development Commands
```bash
uv run pytest                           # All tests
uv run pytest tests/test_scanner.py     # Specific file
uv run ruff check src tests             # Lint
uv run vlm scan                         # Discover files
uv run vlm parse --inventory artifacts/inventory.csv  # Parse with metadata
uv run vlm plan --analysis artifacts/analysis.json    # Plan with duplicates
uv run vlm review-plan --tui            # Interactive review (requires [tui])
```

## Code Style
- Python 3.10+, 4-space indent, PEP 8
- `snake_case` functions/vars, `PascalCase` classes, `UPPER_SNAKE_CASE` constants
- Type hints for public APIs
- Absolute imports: `from vlm.module import ...`
- Ruff (`E`, `F`, `I`) enforced in CI

## Testing
- pytest + hypothesis for property-based tests
- Naming: `test_*.py`, `test_*()`, `Test*`
- Add tests with behavior changes
- Prefer unit tests + targeted CLI integration via `CliRunner`

## Commit Guidelines
- Imperative subjects: `fix logging fallback for unwritable log dir`
- Keep commits focused (no mixed refactors + behavior changes)
- Include: `Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>`
- PRs: summary, rationale, test evidence, CLI output changes

## Important Notes
- Anime: discovered but not parsed in v1
- State tracking: optional, persisted to `~/.vlm/state.json`
- Quarantine: only movie/series (not anime/other)
- Timestamps: UTC ISO 8601 format
- Logging: `~/.vlm/vlm.log`, falls back to console if unwritable
- Config: `~/.vlm/config.yaml`