# YAML And Execution

YAML is the bridge between the docs navigator and runtime execution. A selected tree path should be serializable, inspectable, editable, and executable.

## Generate YAML

```bash
macroforecast-navigate replications synthetic-replication-roundtrip \
  --write-yaml /tmp/synthetic-replication.yaml
```

In the Navigator App, the YAML preview can also be copied or downloaded after
editing a path. The app can import package recipe YAML generated by the
navigator so the same route can be inspected again in the tree.

## Resolve YAML

```bash
macroforecast-navigate resolve /tmp/synthetic-replication.yaml
```

Run only when `execution_status` is `executable`.

The browser app is a path editor and YAML generator. It does not replace
`macroforecast-navigate resolve`, which remains the authoritative preflight before
execution.

## Run YAML

```bash
macroforecast-navigate run /tmp/synthetic-replication.yaml \
  --local-raw-source tests/fixtures/fred_md_ar_sample.csv \
  --output-root /tmp/macroforecast-synthetic
```

The command returns:

```json
{
  "execution_status": "executed",
  "artifact_dir": "/tmp/macroforecast-synthetic/runs/...",
  "run_id": "..."
}
```

## Notebook Pattern

```python
from pathlib import Path
import yaml

from macroforecast.navigator import replication_recipe_yaml
from macroforecast import compile_recipe_dict, run_compiled_recipe

recipe = yaml.safe_load(replication_recipe_yaml("synthetic-replication-roundtrip"))
compiled = compile_recipe_dict(recipe)

result = run_compiled_recipe(
    compiled.compiled,
    output_root="/tmp/macroforecast-synthetic",
    local_raw_source=Path("tests/fixtures/fred_md_ar_sample.csv"),
)
```

## Expected Outputs

The exact set depends on the selected path, but ordinary executable runs should write:

- `manifest.json`;
- `predictions.csv`;
- `metrics.json`;
- `comparison_summary.json`;
- `evaluation_summary.json`;
- optional evaluation reports such as `evaluation_report.md` or
  `evaluation_report.tex` when Layer 4 `report_style` requests them;
- optional payload files such as `forecast_payloads.jsonl`;
- optional Layer 6 inference artifacts such as `stat_tests.json` and
  compatibility sidecars such as `stat_test_dm_modified.json`.

## When To Use API Docs

Use API docs after YAML execution works and you need function signatures, extension hooks, or custom plugin internals. For choosing a path, use the navigator pages first.