docs: dedicated Getting Started page (own the onboarding query) + HowTo schema

docs/faq.md

@@ -19,6 +19,11 @@ MegaDetector is the [Microsoft AI for Good Lab](https://www.microsoft.com/en-us/
 It is a **detector**, not a classifier. It tells you *something is there*, not which species. That is a deliberate choice: one detector generalizes across ecosystems far better than a species classifier, which is usually region-specific. For species identification, pair MegaDetector with a downstream classifier.
 
 
+## How do I get started with MegaDetector?
+
+Start with the [Getting Started](getting-started.md) guide, which takes you from a folder of images to your first detections in four steps: decide whether the model fits, pick how to run it, process a small batch, and read the output. If you would rather not write code, run it through [SPARROW Studio](https://github.com/microsoft/SPARROW), [AddaxAI](https://addaxdatascience.com/addaxai/), or the [Hugging Face demo](https://huggingface.co/spaces/ai-for-good-lab/pytorch-wildlife). For the three-line Python version, see [How do I run MegaDetector?](#how-do-i-run-megadetector) below.
+
+
 ## What does MegaDetector detect?
 
 MegaDetector detects three categories:

docs/getting-started.md

@@ -0,0 +1,94 @@
+---
+title: "Getting Started with MegaDetector: First Steps for Camera-Trap AI"
+description: "Getting started with MegaDetector: decide whether it fits, pick a no-code or pip path, run your first camera-trap batch, and read the detection output."
+slug: getting-started
+tags:
+  - getting started
+  - MegaDetector
+  - camera trap AI
+  - quickstart
+  - run MegaDetector
+---
+
+# Getting Started with MegaDetector
+
+New to MegaDetector? This page is the short path from "I have a folder of camera-trap images" to "I have detections I can act on." It walks four steps: decide whether the model fits your project, choose how you want to run it, process a first small batch, and read the results. Each step links to the deeper reference page when you are ready for detail.
+
+If you only want the three-line code snippet, the [Overview](index.md#quick-start) has it. If you are weighing whether to adopt the model at all, the rest of this page is written for you.
+
+## Is MegaDetector right for my project?
+
+MegaDetector finds animals, people, and vehicles in camera-trap photos and draws a scored box around each one. It is a detector, so it tells you that something is present, not which species it is. Pairing it with a classifier adds species identity later (see Step 4). Because a single detector travels across habitats far better than any region-specific species model, the same weights work whether your cameras sit in savanna, boreal forest, or rainforest.
+
+It is a strong fit when:
+
+- A large image backlog where most frames are empty is the thing slowing your research down.
+- Your project spans several regions or ecosystems and you want one model for all of them.
+- You need a quick, dependable first pass before expert reviewers spend time on the images.
+- You are deploying on low-power field hardware such as a [SPARROW](https://github.com/microsoft/SPARROW) unit.
+
+Some inputs need a different tool in the family rather than MegaDetector itself: underwater or sonar imagery, overhead and aerial views, and audio recordings each have a dedicated sibling project linked from the [Camera-Trap AI](camera-trap-ai.md#when-to-use-megadetector) guide. Very small, well-camouflaged, or under-represented species can also score low, so test on a labeled sample before you trust the model at scale. The [FAQ](faq.md#what-species-does-megadetector-support) covers these caveats in one place.
+
+## Step 1: Pick how you want to run it
+
+There is no single "correct" entry point. Choose the one that matches how much code you want to write and what hardware you have.
+
+- **No code, graphical app.** [SPARROW Studio](https://github.com/microsoft/SPARROW), the AI for Good Lab desktop application, and [AddaxAI](https://addaxdatascience.com/addaxai/) (formerly EcoAssist) both run MegaDetector through a point-and-click interface with batch processing and visualization. The [Hugging Face Space](https://huggingface.co/spaces/ai-for-good-lab/pytorch-wildlife) runs it in a browser tab with nothing to install.
+- **Python or the command line.** Install the package and call it from a few lines of Python, or use the `megadetector` command. This is the most flexible path and the rest of this page assumes it.
+- **Free cloud GPU.** The [Google Colab notebook](https://colab.research.google.com/drive/1rjqHrTMzEHkMualr4vB55dQWCsCKMNXi?usp=sharing) gives you a hosted GPU when your own machine has none.
+
+For a fuller side-by-side of the surrounding tools, see [Camera-Trap Software and Tools](camera-trap-software.md).
+
+## Step 2: Run a first small batch
+
+Start small. Run the model on a handful of images first and check that the results look sane before you scale up. Install the framework:
+
+```bash
+pip install PytorchWildlife
+```
+
+Then run the current release, MegaDetectorV6, over a folder. The weights download themselves the first time:
+
+```python
+from PytorchWildlife.models import detection as pw_detection
+
+model = pw_detection.MegaDetectorV6()
+results = model.batch_image_detection("path/to/a_few_images/")
+```
+
+A laptop CPU handles roughly two to five images per second with the compact variant, which is plenty for a trial run of a few hundred frames. No GPU is required to begin. If you prefer to stay out of Python entirely, the same job runs from the terminal:
+
+```bash
+megadetector detect --input ./a_few_images/ --output results.json --model MDV6-yolov10-e
+```
+
+The [Installation](installation.md) page covers conda environments and GPU setup, and the [CLI reference](cli.md) lists every flag.
+
+## Step 3: Read the output
+
+MegaDetector writes one record per image. Each record holds the file path and a list of detections, and every detection carries three things:
+
+- `category`: `animal`, `person`, or `vehicle`.
+- `confidence`: a score from 0 to 1.
+- `bbox`: the box as `[x1, y1, x2, y2]` pixel coordinates.
+
+You apply a confidence threshold to decide what counts. A value between 0.15 and 0.3 on the animal category suits most datasets: it keeps almost every real animal while letting through a few false hits on swaying vegetation or odd lighting. Anything under your threshold is, in effect, a blank you can set aside, which is what makes the first pass clear so much of the review queue. The [Output Format](output_format.md) reference documents the full schema, and the [Camera-Trap AI](camera-trap-ai.md#filtering-blank-camera-trap-images) guide explains the blank-filtering workflow.
+
+## Step 4: Scale up and add species
+
+Once a trial batch looks right, the same code scales to a full deployment. A GPU changes the economics: at around fifty images per second, a million-image set finishes in roughly five and a half hours, against several days on CPU. Pick a heavier variant for accuracy or a compact one for speed using the guidance in the [Model Zoo](model_zoo.md).
+
+Two common next steps:
+
+- **Identify species.** Feed each MegaDetector box into a downstream classifier. PyTorch-Wildlife ships several, and [MegaDetector-Classifier](https://github.com/microsoft/MegaDetector-Classifier) lets you fine-tune one for your own region. The [Overview](index.md#species-classification) shows the two-stage pipeline in code.
+- **Fine-tune the detector.** If your species or habitats are thin in the base model, the [fine-tuning guide](training_guide.md) walks through preparing data and running `megadetector train`.
+
+Downstream review and analysis tools read MegaDetector results directly, including Timelapse, Wildlife Insights, and CamtrapR; the [software guide](camera-trap-software.md) shows where each one fits.
+
+## Get help
+
+- **GitHub Issues:** [microsoft/MegaDetector/issues](https://github.com/microsoft/MegaDetector/issues) for bugs and feature requests.
+- **Discord:** [the PyTorch-Wildlife community server](https://discord.gg/TeEVxzaYtm).
+- **Email:** [zhongqimiao@microsoft.com](mailto:zhongqimiao@microsoft.com).
+
+Still deciding? The [FAQ](faq.md) answers the most common questions about accuracy, GPU needs, licensing, and the difference between V5 and V6.

docs/index.md

@@ -23,7 +23,7 @@ MegaDetector is an **animal detector**, not a species classifier. For species re
 > [!TIP]
 > MegaDetector is part of the [microsoft/Biodiversity](https://github.com/microsoft/Biodiversity) umbrella, the hub for all AI for Good Lab wildlife tools. The full PyTorch-Wildlife framework and model zoo live at [microsoft/Pytorch-Wildlife](https://github.com/microsoft/Pytorch-Wildlife).
 
-This page is the practical user guide for the current release, **MegaDetectorV6**. If you want a one-screen reference, jump to [Quick start](#quick-start); if you're evaluating whether MegaDetector fits your project, the [FAQ](faq.md) answers the most common questions.
+This page is the practical user guide for the current release, **MegaDetectorV6**. New here? The [Getting Started](getting-started.md) guide walks you from a folder of images to your first detections step by step. If you want a one-screen reference, jump to [Quick start](#quick-start); if you're evaluating whether MegaDetector fits your project, the [FAQ](faq.md) answers the most common questions.
 
 
 ## Quick start

mkdocs.yml

@@ -72,6 +72,7 @@ theme:
 nav:
   - MegaDetector:
     - Overview: index.md
+    - Getting Started: getting-started.md
     - Installation: installation.md
     - Model Zoo: model_zoo.md
     - CLI: cli.md

overrides/main.html

@@ -93,6 +93,14 @@
           "text": "MegaDetector is the Microsoft AI for Good Lab's open-source model for finding animals, people, and vehicles in camera-trap images. It draws a bounding box around each detected object and gives it a confidence score between 0 and 1. It is a detector, not a classifier: it tells you something is there, not which species. One detector generalizes across ecosystems far better than a region-specific species classifier. For species identification, pair MegaDetector with a downstream classifier."
         }
       },
+      {
+        "@type": "Question",
+        "name": "How do I get started with MegaDetector?",
+        "acceptedAnswer": {
+          "@type": "Answer",
+          "text": "Start with the Getting Started guide, which takes you from a folder of images to your first detections in four steps: decide whether the model fits, pick how to run it, process a small batch, and read the output. If you would rather not write code, run it through SPARROW Studio, AddaxAI, or the Hugging Face demo. For the three-line Python version, see How do I run MegaDetector."
+        }
+      },
       {
         "@type": "Question",
         "name": "What does MegaDetector detect?",
@@ -218,6 +226,44 @@
   </script>
   {%- endif %}
 
+  {%- if page and page.file and page.file.src_path == "getting-started.md" and page.canonical_url %}
+  {#- Getting Started page only: HowTo. Steps mirror the visible getting-started.md headings. -#}
+  <script type="application/ld+json">
+  {{- {
+    "@context": "https://schema.org",
+    "@type": "HowTo",
+    "name": "Getting Started with MegaDetector",
+    "description": "How to get started with MegaDetector: decide whether it fits your project, pick how to run it, process a first small batch of camera-trap images, and read the detection output.",
+    "step": [
+      {
+        "@type": "HowToStep",
+        "name": "Pick how you want to run it",
+        "text": "Choose an entry point that matches how much code you want to write: a graphical app such as SPARROW Studio or AddaxAI, the Python package or the megadetector command line, or a free cloud GPU through the Google Colab notebook.",
+        "url": page.canonical_url ~ "#step-1-pick-how-you-want-to-run-it"
+      },
+      {
+        "@type": "HowToStep",
+        "name": "Run a first small batch",
+        "text": "Install PytorchWildlife with pip, load MegaDetectorV6, and run batch_image_detection on a small folder. The weights download on first use and a laptop CPU handles a trial run with no GPU required.",
+        "url": page.canonical_url ~ "#step-2-run-a-first-small-batch"
+      },
+      {
+        "@type": "HowToStep",
+        "name": "Read the output",
+        "text": "MegaDetector returns one record per image with a list of detections, each holding a category (animal, person, or vehicle), a confidence score from 0 to 1, and a bounding box. Apply a confidence threshold of about 0.15 to 0.3 on the animal category to separate detections from blanks.",
+        "url": page.canonical_url ~ "#step-3-read-the-output"
+      },
+      {
+        "@type": "HowToStep",
+        "name": "Scale up and add species",
+        "text": "Run the same code on a full deployment, using a GPU for speed, then add a downstream classifier for species identity or fine-tune the detector on your own labeled images.",
+        "url": page.canonical_url ~ "#step-4-scale-up-and-add-species"
+      }
+    ]
+  } | tojson -}}
+  </script>
+  {%- endif %}
+
   {%- if page and page.file and page.file.src_path != "index.md" and page.canonical_url %}
   {#- Interior pages only: BreadcrumbList (no breadcrumb on the homepage) -#}
   <script type="application/ld+json">