# Mov Renamarr CLI - Project Plan

## Goal
Build a Linux CLI that scans a directory of movie files, queries online metadata (OMDb/TMDb), and writes Radarr-compatible folder and file names to an output directory. Project name: Mov Renamarr.

## Core Requirements
- Input: directory tree containing video files.
- Output: `Movie Title (Year)/Movie Title (Year) [Quality] [id].ext`.
- Uses `ffprobe` for media info and filename parsing for hints.
- Queries OMDb/TMDb, with caching to avoid repeat lookups.
- Non-interactive by default: skip ambiguous/unmatched files, report them at end.
- Optional `--interactive` to confirm matches.
- Linux support only (for now).

## Non-Goals (for MVP)
- No Radarr API integration.
- No TV/series handling.
- No transcoding or media repair.

## Decisions to Lock In
- Default action: copy (safe default).
- Optional flags: `--move` and `--rename-in-place`.
- Config file support (XDG by default) + CLI overrides. Config format: TOML.
- Provider selection: auto based on available API keys, with optional user preference. Default auto priority: TMDb.
- Match scoring and minimum confidence threshold.
- Cache storage format (SQLite vs JSON) + TTL + `--refresh-cache`.
- Quality tags default to resolution only; configurable via CLI/config.
- Optional local LLM integration (Ollama) for filename parsing and lookup assist, disabled by default.
- Default report format: text.
- Sidecar notes: off by default; opt-in only.
- Include top-3 candidates in unresolved items by default.
- Emphasize performance, broad Linux compatibility, and robust error handling.
- UX: per-file status line (file/provider/result/new name), progress counts, color when TTY, `--verbose` for debug details.
- Collision policy: default skip if destination exists; optional `--overwrite` or `--suffix` to avoid data loss.
- Sidecar files: optionally move/copy all sidecar files with `--sidecars` flag (off by default).
- Concurrency: default jobs = min(4, max(1, floor(cores/2))); default net-jobs = min(2, jobs); allow overrides.
- ffprobe required (no native parsing fallback).
- Reports: stdout by default; optional report file name pattern `mov-renamarr-report-YYYYMMDD-HHMMSS.txt` when `--report` is set without a path.
- Config precedence: defaults -> config TOML -> env -> CLI flags.
- Config path: `$XDG_CONFIG_HOME/mov-renamarr/config.toml` (fallback `~/.config/mov-renamarr/config.toml`).
- Cache path: `$XDG_CACHE_HOME/mov-renamarr/cache.db` (fallback `~/.cache/mov-renamarr/cache.db`).
- Report file default location: current working directory when `--report` is set without a path.
- Provider base URLs configurable in config/env to support testing/mocking.
- Create a commented default config file on first run and notify the user.

## Proposed CLI (Draft)
- `mov-renamarr --input <dir> --output <dir>`
- `--config <path>` (default: XDG config)
- `--provider auto|omdb|tmdb|both`
- `--api-key-omdb <key>` / `--api-key-tmdb <key>` (override config/env)
- `--cache <path>` (default: `~/.cache/mov-renamarr.db`)
- `--refresh-cache` (bypass cache)
- `--dry-run`
- `--move` / `--rename-in-place`
- `--interactive`
- `--report <path>` + `--report-format text|json|csv`
- `--sidecar-notes` (write per-file skip notes)
- `--min-score <0-100>`
- `--include-id` (tmdb/omdb/imdb if available)
- `--quality-tags resolution|resolution,codec,source`
- `--color auto|always|never`
- `--jobs <n|auto>`
- `--net-jobs <n|auto>`
- `--no-lookup` (skip external providers; use filename/LLM only)
- `--llm-mode off|parse|assist` (default: off)
- `--llm-endpoint <url>` (Ollama, default `http://localhost:11434`)
- `--llm-model <name>` (Ollama model name)
- `--llm-timeout <seconds>` / `--llm-max-tokens <n>`

## Matching Heuristics (Draft)
- Parse filename for title/year hints; strip extra release metadata.
- Use `ffprobe` for duration and resolution.
- Prefer exact year match; allow +/- 1 year when missing.
- Use string similarity + runtime delta to choose best match.

## Pipeline (Draft)
1. Load config (XDG) + merge CLI overrides.
2. Discover files and filter by extension; skip output subtree when output != input to avoid reprocessing.
3. Parse filename hints (title/year) and strip release metadata (optionally via LLM parse).
4. Run `ffprobe` for duration/resolution/codec.
5. Select provider(s) based on available API keys and user preference.
6. Query provider(s) with hints (LLM assist may propose candidates but must be verified).
7. Score and select match; if below threshold, mark as unresolved.
8. Build Radarr-compatible output path.
9. Copy/move/rename-in-place file to output directory.
10. Write summary report of successes and unresolved items.

## Milestones
- M0: Project scaffold and plan (done).
- M1: CLI skeleton and config parsing.
- M2: `ffprobe` integration and media metadata model.
- M3: OMDb/TMDb client + caching.
- M4: Matching, naming, and file move/copy.
- M5: Reporting, tests, and polish.
- M6: Automated test harness and fixtures.
- M7: Performance pass and profiling.