More extensive overview of cli reference

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.
+## How to use this section
-2. Pick the command page you need (`predict`, `data`, `train`, or `evaluate`).
+
-3. Use `detect_legacy` only if you are maintaining old workflows.
+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
+Base command and global options <base>
-predict
+Predict command group <predict>
-data
+Data command group <data>
-train
+Train command <train>
-evaluate
+Evaluate command <evaluate>
-detect_legacy
+Legacy detect command <detect_legacy>
 ```