---
description: Why MatMelt is built the way it is — the what-vs-where split, the stage contract, the funnel, scheduling and restart, remote execution, and the science.
---

# Explanation

Understanding-oriented pages. They answer *why* rather than *how*: what each
design decision buys, what it costs, and which failure it was chosen to prevent.
Nothing here is needed to use the tool — {doc}`../how-to/index` and
{doc}`../reference/index` are for that — but it is what makes the tool's
behaviour predictable instead of surprising.

```{toctree}
:maxdepth: 1

what-vs-where
stage-contract
funnel-and-stop-after
scheduling-and-restart
remote-execution
the-science
```

| Page | The question it answers |
|---|---|
| {doc}`what-vs-where` | Why moving a stage to a cluster is config and not code |
| {doc}`stage-contract` | Why a stage can refuse, and why a non-zero exit is not an error |
| {doc}`funnel-and-stop-after` | Why the pipeline fans out then narrows, and what "stopping" means |
| {doc}`scheduling-and-restart` | Why an interrupted run resumes instead of starting over |
| {doc}`remote-execution` | Why a remote machine holds none of MatMelt's code |
| {doc}`the-science` | What each stage actually computes, and how far to trust it |

One idea runs through all six: **the tool decides what to compute and never
decides where; it judges results and never invents them; and everything it
learns is written down before it is acted on.** Each page below is that idea
applied to one part of the system.
