# Tutorials

Tutorials are paced learning sessions. They assume you have already read
Quickstart so that installation and stage names are familiar. Start with the
short bake-off path, then read the report, then open the detailed notebooks when
you need stage-level logs and debugging patterns.

Complete Tutorials after Quickstart. Use Guides when you later have a specific
job such as bringing your own traces or building a custom classifier. Use the
API Reference when you need exact names.

```{toctree}
:maxdepth: 1
:caption: Getting started

first_zoo_run
read_the_report
```

```{toctree}
:maxdepth: 1
:caption: Detailed notebooks

stage_data
stage_classify
stage_hardware_report
debugging_pipeline
```

<ul class="arcade-pipeline">
  <li><strong>1. First zoo run</strong><span>Install, link data, launch the public bake-off</span></li>
  <li><strong>2. Read the report</strong><span>Turn the table into a decision</span></li>
  <li><strong>3. Stage notebooks</strong><span>Data, classify, hardware, report</span></li>
  <li class="optional"><strong>4. Debug</strong><span>Logs, isolation, common failures</span></li>
</ul>

## Getting started

1. **First zoo run** installs the extras used by the public multi-method
   benchmark, links the paper data the bundled configs expect, and launches
   ``configs/paper_all_methods_benchmark.yaml`` from the command line or from
   Python.
2. **Read the report** opens the summary PDF or HTML and the companion JSON,
   then explains joint accuracy, F5Q, PQ min, analytical hardware columns, and
   the recommendation box so you can defend a ranking in a lab meeting.

## Detailed notebooks

These Jupyter notebooks live under ``doc/tutorials/`` and are rendered in the
HTML manual without re-executing during the docs build. Run them locally from
the repository root when you want live logs.

| Notebook | Focus |
|----------|-------|
| {doc}`stage_data` | Stage 1 data load, demodulation, splits, caches, and data-stage log lines |
| {doc}`stage_classify` | Feature kinds, Stage 2 classify banners, isolating one method |
| {doc}`stage_hardware_report` | Analytical hardware estimation and summary report outputs |
| {doc}`debugging_pipeline` | Log levels, validation, minimal reproductions, symptom → fix map |

If a tutorial step fails because an optional dependency is missing, return to
{doc}`../quickstart/installation` and install the matching extra before
retrying.