# Repository Guidelines

This repository owns local file inventory and matching behavior. It does not own the WCX reference database, its schema, metadata, OCR, history, or aliases.

Always treat the reference database as an external dependency and open it strictly read-only with SQLite `mode=ro`. Store any future local paths, collection state, or matching decisions separately.

Use `movie.id` as the stable external identity when referring to a reference-database movie. The initial implementation must require an explicit `--database` argument; do not add an implicit reference-database path.

`scripts/match_filenames.py` performs filename matching. `scripts/diagnose_duration_match.py` is a manual duration diagnostic that identifies the reference movie by stable `movie.id`; it is not an automated test. Both scripts require an explicit `--database` argument and must open the reference database strictly read-only with SQLite `mode=ro`.

Keep file operations conservative. Operations that rename, move, or remove files must normally support or require a dry run before applying changes.

Do not commit databases, video files, generated reports, credentials, or Python caches.