> ## Documentation Index
> Fetch the complete documentation index at: https://songbird.studiocollective.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# songbird-scenarios

# songbird-scenarios

JSON-defined workflows that drive Songbird into a starting state by issuing
sync engine commands sequentially.

## What it owns

* The scenario file format (`scenarios/**/*.json`).
* The resolver that flattens `include:` chains into a single step list.
* The `${name.field}` reference substitution.
* The runner that walks the step list and calls
  `songbird_sync::dispatch::dispatch()` on each step.

## Public API

* `find_scenario(name, root)` — locate a scenario JSON file by bare name
  (recursive search) or path-qualified name.
* `resolve(name, root) -> ResolvedScenario` — parse, recursively flatten
  `include:`s (dedup + cycle detection), return an ordered `Vec<Step>`.
* `run(&ResolvedScenario, &RunOptions) -> RunReport` — execute the steps,
  substituting refs and dispatching each one. Requires
  `songbird_sync::dispatch::init` to have already been called.

## How it fits

The Tauri app (`songbird-app`) calls into this crate from its `setup()`
flow when the `SONGBIRD_SCENARIO` env var is set, after the sync engine
context is initialized. `./utils/build-rs -s <name>` is the dev-loop
entry point that sets the env var.

This crate does **not** know about Tauri, the audio engine, or files
beyond JSON parsing — it only knows about `songbird-sync::dispatch`.

## Tests

```
cargo test -p songbird-scenarios
```

Tests cover parsing, finding, resolving (including cycle detection), and
ref substitution. The runner is integration-tested via the Tauri app
because it depends on the global dispatch context.