Document WCX detection report workflow

README.md

@@ -77,3 +77,60 @@ accuracy with low complexity and reasonable runtime.
 For detailed inspection of one video, use `--diagnose-layout` together with
 the required `--output-dir`; this mode saves normalized diagnostic images
 and prints the measurements for all three timestamps.
+
+## Detection-assisted filename matching
+
+`detect_wcx_title.py` identifies files that probably belong to WCX.
+`match_filenames.py` can read its JSON report as a filter and sends only
+entries with `classification == "wcx"` to the existing name and duration
+matching.
+
+Step 1: create the detection report:
+
+```bash
+scripts/detect_wcx_title.py \
+  /storage/disk1/X \
+  --batch \
+  --ending mp4 \
+  --json-report reports/wcx-detection.json
+```
+
+Step 2: match the detected WCX files:
+
+```bash
+scripts/match_filenames.py \
+  /storage/disk1/X \
+  --database /storage/disk1/WCX/database/wcx.db \
+  --ending mp4 \
+  --detection-report reports/wcx-detection.json
+```
+
+`match_filenames.py` first performs its normal inventory using the input
+directory, `--recursive`, `--ending`, operating-system junk-file filtering,
+and `--limit`. The limit is applied before the report filter. The script then
+takes the intersection of the normally inventoried files and report entries
+classified as `wcx`.
+
+For example:
+
+```text
+detection_report: /absolute/path/to/wcx-detection.json
+inventoried_files: 5
+report_wcx_files: 41
+selected_files: 3
+```
+
+This means `--limit` selected the first five normally inventoried files and
+three of those were classified as `wcx`. Report entries classified as
+`uncertain`, `not_wcx`, or `error` are not matched. A reported `wcx`
+file outside the current inventory is also ignored. The report must use
+`schema_version: 1`.
+
+The report is read-only, video files are not changed, and the reference
+database remains strict read-only. `match_filenames.py` does not run
+`detect_wcx_title.py` automatically and performs no renames or file moves.
+
+In one verified run, the report contained 41 WCX files and
+`match_filenames.py` analyzed exactly those 41 files: 36 were matched, one
+was ambiguous, four were unmatched, and there were no ffprobe failures.
+Ambiguous and unmatched files still require separate review or handling.