diff --git a/.gitignore b/.gitignore
index 4d7420e..b9e17d3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -128,6 +128,7 @@ notebooks/tmp
 /notebooks
 /AGENTS.md
 /scripts
+/todo.md
 
 # Assets
 !assets/*
diff --git a/docs/source/how_to/tune-detection-threshold.md b/docs/source/how_to/tune-detection-threshold.md
index b668ec0..da21d3e 100644
--- a/docs/source/how_to/tune-detection-threshold.md
+++ b/docs/source/how_to/tune-detection-threshold.md
@@ -8,10 +8,18 @@ Run an initial prediction workflow and keep outputs in a dedicated folder.
 
 ## 2) Sweep threshold values
 
-If you use the legacy `detect` command, run multiple thresholds (for example,
-`0.1`, `0.3`, `0.5`) and compare output counts and quality on a validation
+Run `predict` multiple times with different thresholds (for example `0.1`,
+`0.3`, `0.5`) and compare output counts and quality on the same validation
 subset.
 
+```bash
+batdetect2 predict directory \
+  path/to/model.ckpt \
+  path/to/audio_dir \
+  path/to/outputs_thr_03 \
+  --detection-threshold 0.3
+```
+
 ## 3) Validate against known calls
 
 Use files with trusted annotations or expert review to select a threshold that
diff --git a/docs/source/reference/cli/detect_legacy.rst b/docs/source/reference/cli/detect_legacy.rst
index e1a4002..c3d15de 100644
--- a/docs/source/reference/cli/detect_legacy.rst
+++ b/docs/source/reference/cli/detect_legacy.rst
@@ -11,6 +11,7 @@ Migration at a glance
 
 - Legacy: ``batdetect2 detect AUDIO_DIR ANN_DIR DETECTION_THRESHOLD``
 - Current: ``batdetect2 predict directory MODEL_PATH AUDIO_DIR OUTPUT_PATH``
+  with optional ``--detection-threshold``
 
 .. click:: batdetect2.cli.compat:detect
    :prog: batdetect2 detect
diff --git a/docs/source/reference/cli/predict.rst b/docs/source/reference/cli/predict.rst
index 7ff6359..8acf20f 100644
--- a/docs/source/reference/cli/predict.rst
+++ b/docs/source/reference/cli/predict.rst
@@ -2,6 +2,7 @@ Predict command
 ===============
 
 Run model inference from a directory, a file list, or a dataset.
+Use ``--detection-threshold`` to override the model default per run.
 
 .. click:: batdetect2.cli.inference:predict
    :prog: batdetect2 predict