docs: align docs entry points with current workflows

README.md

@@ -1,11 +1,40 @@
 # BatDetect2
 <img style="display: block-inline;" width="64" height="64" src="assets/bat_icon.png"> Code for detecting and classifying bat echolocation calls in high frequency audio recordings.
 
-## Getting started
+## What BatDetect2 is useful for
-### Python Environment
 
-We recommend using an isolated Python environment to avoid dependency issues. Choose one
+BatDetect2 can help you screen recordings for bat calls,
-of the following options:
+find recordings that need expert review,
+and compare model outputs across sites or projects with appropriate caution.
+
+It is best used as a tool to support ecological work,
+not as a replacement for validation or expert interpretation.
+
+## Start here
+
+If you want the simplest current workflow,
+use the documentation site and start with:
+
+- getting started: `docs/source/getting_started.md`
+- first tutorial: `docs/source/tutorials/run-inference-on-folder.md`
+
+The current docs default to:
+
+- the current command-line workflow: `batdetect2 predict`
+- the current Python workflow: `batdetect2.api_v2.BatDetect2API`
+
+If you need the previous workflow based on `batdetect2 detect` or `batdetect2.api`,
+use the legacy docs section and migration guide in the docs site.
+
+## Install BatDetect2
+
+If you already use Python,
+activate the environment where you want BatDetect2 to live.
+
+If not,
+create a fresh one first so BatDetect2 stays separate from other software on your machine.
+
+Two common options are:
 
 * Install the Anaconda Python 3.10 distribution for your operating system from [here](https://www.continuum.io/downloads). Create a new environment and activate it:
 
@@ -14,7 +43,7 @@ conda create -y --name batdetect2 python==3.10
 conda activate batdetect2
 ```
 
-* If you already have Python installed (version >= 3.8,< 3.11) and prefer using virtual environments then:
+* If you already have Python installed (version >= 3.10,< 3.14), you can create a fresh environment with:
 
 ```bash
 python -m venv .venv
@@ -37,6 +66,43 @@ pip install .
 
 Make sure you have the environment activated before installing `batdetect2`.
 
+## Run BatDetect2 on a folder of recordings
+
+Once installed,
+the simplest current workflow is to run BatDetect2 on a folder of `.wav` files.
+
+If you are working from this repository checkout,
+you can use this example checkpoint path:
+
+```text
+src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar
+```
+
+Example command:
+
+```bash
+batdetect2 predict directory \
+  src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar \
+  example_data/audio \
+  outputs
+```
+
+This will scan the audio files in `example_data/audio`
+and save model outputs to `outputs`.
+
+For the full beginner walkthrough,
+use `docs/source/tutorials/run-inference-on-folder.md`.
+
+## Legacy workflow
+
+The sections below are kept only for people maintaining older BatDetect2 scripts and analysis pipelines.
+
+If you are new to BatDetect2,
+stop here and use the current docs and command above.
+
+If you really do need the older workflow,
+the reference material is below.
+
 
 ## Try the model
 1) You can try a demo of the model (for UK species) on [huggingface](https://huggingface.co/spaces/macaodha/batdetect2).
@@ -48,9 +114,15 @@ Make sure you have the environment activated before installing `batdetect2`.
 
 After following the above steps to install the code you can run the model on your own data.
 
+The remainder of this section is legacy reference material.
+
 
 ### Using the command line
 
+The commands below describe the legacy CLI workflow.
+
+For new work, prefer the current docs and `batdetect2 predict`.
+
 You can run the model by opening the command line and typing:
 ```bash
 batdetect2 detect AUDIO_DIR ANN_DIR DETECTION_THRESHOLD
@@ -73,6 +145,10 @@ You can also specify which model to use by setting the `--model_path` argument.
 
 ### Using the Python API
 
+The examples below describe the legacy Python API.
+
+For new work, prefer `batdetect2.api_v2.BatDetect2API` and the current docs site.
+
 If you prefer to process your data within a Python script then you can use the `batdetect2` Python API.
 
 ```python
@@ -98,7 +174,10 @@ You can integrate the detections or the extracted features to your custom analys
 
 
 ## Training the model on your own data
-Take a look at the steps outlined in finetuning readme [here](batdetect2/finetune/readme.md) for a description of how to train your own model.
+Take a look at the training tutorial in the docs site first.
+
+If you are working from this repository checkout,
+start with `docs/source/tutorials/train-a-custom-model.md`.
 
 
 ## Data and annotations

docs/source/explanation/index.md

@@ -1,14 +1,19 @@
-# Explanation
+# Understanding
 
-Explanation pages describe why BatDetect2 behaves as it does and how to reason
+Understanding pages explain how BatDetect2 works, what its outputs mean, and how to reason about trade-offs.
-about trade-offs.
+
+Use this section when you want help interpreting the tool, not just running it.
 
 ```{toctree}
 :maxdepth: 1
 
+what-batdetect2-predicts
+interpreting-formatted-outputs
+extracted-features-and-embeddings
 model-output-and-validation
 postprocessing-and-thresholds
 pipeline-overview
 preprocessing-consistency
 target-encoding-and-decoding
+evaluation-concepts-and-matching
 ```

docs/source/getting_started.md

@@ -1,22 +1,41 @@
 # Getting started
 
-BatDetect2 is both a command line tool (CLI) and a Python library.
+If you want to run BatDetect2 on your recordings,
+start with the command-line route below.
 
-- Use the CLI if you want to run existing models or train your own models from
+You do not need to write Python code for a standard first run.
-  the terminal.
+
-- Use the Python package if you want to integrate BatDetect2 into your own
+BatDetect2 also has a Python interface,
-  scripts, notebooks, or analysis pipeline.
+but that is mainly for users writing their own analysis scripts.
+
+- Use the command-line route if you want to run an existing model or train your own model by typing commands in a terminal window.
+- Use the Python route only if you already want to work in scripts or notebooks.
+
+```{note}
+If you are looking for the previous BatDetect2 workflow based on `batdetect2 detect` or `batdetect2.api`, go to {doc}`legacy/index`.
+New docs default to the current `predict` CLI and `BatDetect2API` workflow.
+```
 
 If you want to try BatDetect2 before installing anything locally:
 
 - [Hugging Face demo (UK species)](https://huggingface.co/spaces/macaodha/batdetect2)
 - [Google Colab notebook](https://colab.research.google.com/github/macaodha/batdetect2/blob/master/batdetect2_notebook.ipynb)
 
-## Prerequisites
+## The simplest route for most users
+
+1. Install BatDetect2.
+2. Use a model checkpoint.
+3. Run the first tutorial on a folder of recordings.
+
+If that is what you want,
+you can ignore the Python sections for now.
+
+## Install BatDetect2
 
 We recommend `uv` for both workflows.
-`uv` is a fast Python package and environment manager that keeps installs
+
-isolated and reproducible.
+`uv` is a tool that helps install Python software cleanly,
+without mixing it into the rest of your machine.
 
 - Use `uv tool` to install the CLI.
 - Use `uv add` to add `batdetect2` as a dependency in a Python project.
@@ -26,8 +45,8 @@ Install `uv` first by following their
 
 ## Install the CLI
 
-The following installs `batdetect2` in an isolated tool environment and exposes
+The following installs `batdetect2` in its own small environment and makes the
-the `batdetect2` command on your machine.
+`batdetect2` command available on your machine.
 
 ```bash
 uv tool install batdetect2
@@ -49,16 +68,34 @@ Run your first workflow:
 
 Go to {doc}`tutorials/run-inference-on-folder` for a complete first run.
 
-## Integrate with your Python project
+## Choose a model checkpoint
 
-If you are using BatDetect2 from Python code, add it to your project
+The current command-line and Python workflows expect an explicit checkpoint path.
-dependencies:
+
+A checkpoint is the saved model file that BatDetect2 will use for prediction.
+
+You can use:
+
+- a checkpoint you trained yourself, or
+- a checkpoint distributed with your installation or repository checkout.
+
+In this repository checkout, an example pretrained checkpoint is available at:
+
+```text
+src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar
+```
+
+Use that path in the tutorial commands if you want a concrete starting point from this source tree.
+
+## Python route for users writing code
+
+If you are using BatDetect2 from Python code, add it to your Python project:
 
 ```bash
 uv add batdetect2
 ```
 
-This keeps dependency metadata and the environment in sync.
+This keeps your project settings and installed packages in sync.
 
 ### Alternative with `pip`
 
@@ -77,7 +114,10 @@ pip install batdetect2
 
 ## What's next
 
-- Run your first detection workflow:
+- Run your first workflow on a folder of recordings:
   {doc}`tutorials/run-inference-on-folder`
-- For practical task recipes, go to {doc}`how_to/index`
+- If you write code and want the Python route:
-- For command and option details, go to {doc}`reference/cli/index`
+  {doc}`tutorials/integrate-with-a-python-pipeline`
+- For common practical tasks, go to {doc}`how_to/index`
+- For detailed command help, go to {doc}`reference/cli/index`
+- To understand outputs and trade-offs, go to {doc}`explanation/index`

docs/source/how_to/index.md

@@ -1,12 +1,22 @@
 # How-to Guides
 
-How-to guides help you complete specific tasks while working.
+How-to guides help you answer practical questions once you are past the first tutorial.
+
+Use this section when you already know the basic workflow and want help with one specific task.
 
 ```{toctree}
 :maxdepth: 1
 
+choose-an-inference-input-mode
 run-batch-predictions
+tune-inference-clipping
 tune-detection-threshold
+inspect-class-scores-in-python
+inspect-detection-features-in-python
+save-predictions-in-different-output-formats
+fine-tune-from-a-checkpoint
+choose-and-configure-evaluation-tasks
+interpret-evaluation-outputs
 configure-aoef-dataset
 import-legacy-batdetect2-annotations
 configure-audio-preprocessing

docs/source/index.md

@@ -1,63 +1,87 @@
 # Home
 
-Welcome to the batdetect2 docs.
+Welcome to the BatDetect2 documentation.
 
-## What is batdetect2?
+## What is BatDetect2?
 
-`batdetect2` is a bat echolocation detection model.
+`batdetect2` detects bat echolocation calls in audio recordings.
-It detects each individual echolocation call in an input spectrogram, draws a
-box around each call event, and predicts the most likely species for that call.
-A recording can contain many calls from different species.
 
-The current default model is trained for 17 UK species but you can also train
+It can help you screen large collections of recordings,
-new models from your own annotated data.
+find files that need expert review,
+and support ecology and conservation work where manual review alone would be slow.
 
-For details on the approach please read our pre-print:
+In practice,
-[Towards a General Approach for Bat Echolocation Detection and Classification](https://www.biorxiv.org/content/10.1101/2022.12.14.520490v1)
+BatDetect2 takes recordings,
+looks for likely bat calls,
+draws a box around each detected event,
+and scores the most likely class for that event.
 
-## What you can do
+The current default model is trained for 17 UK species.
 
-- Run inference on your recordings and export predictions for downstream
+The library also supports custom training,
-  analysis:
+fine-tuning,
+evaluation,
+and more advanced use from Python.
+
+For details on the underlying approach, see the pre-print:
+[Towards a General Approach for Bat Echolocation Detection and Classification](https://www.biorxiv.org/content/10.1101/2022.12.14.520490v1)
+
+## A good first use for BatDetect2
+
+BatDetect2 is a good fit when you want to:
+
+- scan many recordings for likely bat activity,
+- prioritize files for expert review,
+- compare outputs across projects with appropriate caution,
+- build reviewed local datasets for later model improvement.
+
+It is not a substitute for validation.
+
+## Main user journeys
+
+- I want to run the model on my recordings:
   {doc}`tutorials/run-inference-on-folder`
-- Train a custom model on your own annotated data:
+- I write code and want to use Python:
-  {doc}`tutorials/train-a-custom-model`
-- Evaluate model performance on a held-out test set:
-  {doc}`tutorials/evaluate-on-a-test-set`
-- Integrate batdetect2 into Python scripts and notebooks:
   {doc}`tutorials/integrate-with-a-python-pipeline`
+- I want to train or fine-tune a custom model:
+  {doc}`tutorials/train-a-custom-model`
+- I want to evaluate a trained model on held-out data:
+  {doc}`tutorials/evaluate-on-a-test-set`
 
 ```{warning}
 Treat outputs as model predictions, not ground truth.
-Always validate on reviewed local data before using results for ecological
+Always validate on reviewed local data before using results for ecological inference.
-inference.
 ```
 
-## Where to start
+```{note}
+Looking for the previous BatDetect2 workflow?
+See {doc}`legacy/index`.
+The legacy docs are still available, but new workflows should use `batdetect2 predict` and `BatDetect2API`.
+```
 
-If you are new, start with {doc}`getting_started`.
+## How to use this site
 
-For a low-code path, go to {doc}`tutorials/index`.
+Start with {doc}`getting_started` if you are new.
-If you are Python-savvy and want more control, go to {doc}`how_to/index` and
-{doc}`reference/index`.
 
-Each section has a different purpose:
+Then choose the section that matches what you need.
-some pages teach by example, some focus on practical tasks, some are lookup
+
-material, and some explain trade-offs.
+If you are here mainly to run the model on recordings,
+start with Tutorials.
 
 | Section | Best for | Start here |
-| ------------- | ------------------------------------------- | ------------------------ |
+| --- | --- | --- |
-| Tutorials     | Learning by doing                           | {doc}`tutorials/index`   |
+| Tutorials | Step-by-step routes for the most common tasks | {doc}`tutorials/index` |
-| How-to guides | Solving practical tasks                     | {doc}`how_to/index`      |
+| How-to guides | Answers to specific practical questions | {doc}`how_to/index` |
-| Reference     | Looking up commands, configs, and APIs      | {doc}`reference/index`   |
+| Reference | Detailed command and settings help | {doc}`reference/index` |
-| Explanation   | Understanding design choices and trade-offs | {doc}`explanation/index` |
+| Understanding | Concepts, interpretation, and trade-offs | {doc}`explanation/index` |
+| Legacy | Previous workflow and migration guidance | {doc}`legacy/index` |
 
 ## Get in touch
 
 - GitHub repository:
   [macaodha/batdetect2](https://github.com/macaodha/batdetect2)
 - Questions, bug reports, and feature requests:
-  [GitHub Issues](https://github.com/macaodha/batdetect2/issues)
+  [GitHub Issues](https://github.com/macaodha/batdetect2/issues)
 - Common questions:
   {doc}`faq`
 - Want to contribute?
@@ -65,7 +89,7 @@ material, and some explain trade-offs.
 
 ## Cite this work
 
-If you use batdetect2 in research, please cite:
+If you use BatDetect2 in research, please cite:
 
 Mac Aodha, O., Martinez Balvanera, S., Damstra, E., et al.
 (2022).
@@ -82,6 +106,7 @@ tutorials/index
 how_to/index
 reference/index
 explanation/index
+legacy/index
 ```
 
 ```{toctree}

docs/source/reference/index.md

@@ -1,12 +1,20 @@
 # Reference documentation
 
-Reference pages provide factual, complete descriptions of commands,
+Reference pages are the detailed lookup pages.
-configuration, and data structures.
+
+Use this section when you need exact command options, setting names, output details, or Python API entries.
 
 ```{toctree}
 :maxdepth: 1
 
 cli/index
+api
+app-config
+inference-config
+evaluation-config
+outputs-config
+output-formats
+output-transforms
 data-sources
 preprocessing-config
 postprocess-config

docs/source/tutorials/index.md

@@ -1,7 +1,12 @@
 # Tutorials
 
-Tutorials are for learning by doing. They provide a single, reproducible path
+Tutorials are the default learning path.
-to a concrete outcome.
+
+Each tutorial follows one recommended route from start to finish.
+
+Use tutorials when you want the simplest route to a concrete outcome.
+
+Use {doc}`../how_to/index` when you need to customize a workflow.
 
 ```{toctree}
 :maxdepth: 1