diff --git a/docs/source/reference/cli/index.md b/docs/source/reference/cli/index.md
index ac738f0..e52c828 100644
--- a/docs/source/reference/cli/index.md
+++ b/docs/source/reference/cli/index.md
@@ -1,18 +1,51 @@
 # CLI reference
 
-Use this section like this:
+Use this section to find the right command quickly, then open the command page
+for full options and argument details.
 
-1. Check `base` for global options shared by all commands.
-2. Pick the command page you need (`predict`, `data`, `train`, or `evaluate`).
-3. Use `detect_legacy` only if you are maintaining old workflows.
+## How to use this section
+
+1. Start with {doc}`base` for options shared across the CLI.
+2. Pick the command group or command you need from the command map below.
+3. Open the linked page for complete autogenerated option reference.
+
+## Command map
+
+| Command | Use it for | Required positional args |
+| --- | --- | --- |
+| `batdetect2 predict` | Run inference on audio | Depends on subcommand (`directory`, `file_list`, `dataset`) |
+| `batdetect2 data` | Inspect and convert dataset configs | Depends on subcommand (`summary`, `convert`) |
+| `batdetect2 train` | Train or fine-tune models | `TRAIN_DATASET` |
+| `batdetect2 evaluate` | Evaluate a checkpoint on a test dataset | `MODEL_PATH`, `TEST_DATASET` |
+| `batdetect2 detect` | Legacy compatibility workflow | `AUDIO_DIR`, `ANN_DIR`, `DETECTION_THRESHOLD` |
+
+## Global options and conventions
+
+- Global CLI options are documented in {doc}`base`.
+- Paths with spaces should be wrapped in quotes.
+- Input audio is expected to be mono.
+- Legacy `detect` uses a required threshold argument, while `predict` uses
+  the optional `--detection-threshold` override.
+
+```{warning}
+`batdetect2 detect` is a legacy command.
+Prefer `batdetect2 predict directory` for new workflows.
+```
+
+## Related pages
+
+- {doc}`../../tutorials/run-inference-on-folder`
+- {doc}`../../how_to/run-batch-predictions`
+- {doc}`../../how_to/tune-detection-threshold`
+- {doc}`../configs`
 
 ```{toctree}
 :maxdepth: 1
 
-base
-predict
-data
-train
-evaluate
-detect_legacy
+Base command and global options <base>
+Predict command group <predict>
+Data command group <data>
+Train command <train>
+Evaluate command <evaluate>
+Legacy detect command <detect_legacy>
 ```