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

# Flows

> Define simulation flows as config (improv and scripted)

A simulation flow. Both types share `kind: flow` and are discriminated by `type`. Flows reference agents, a persona, and an environment by name.

## Improv (`type: improv`)

An improvised simulation with a happy path and edge-case variants.

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# yaml-language-server: $schema=https://schema.roark.ai/roark-config.schema.json
kind: flow
type: improv
name: frustrated-rebooking
agents: [frontdesk]
happyPath:
  persona: frustrated-caller
  environment: Quiet line
  prompt: You call to rebook the cleaning that was cancelled on you.
edgeCases:
  - name: escalates-to-manager
    prompt: file://prompts/escalates-to-manager.md
    expectations:
      - Agent offers to escalate rather than arguing
```

* `happyPath` requires a `persona` and `environment` (by name); `prompt` and `expectations` are optional.
* Each `edgeCases[]` entry inherits the happy path unless it overrides `persona` / `environment` / `prompt`, and can add its own `expectations`.

## Scripted (`type: scripted`)

A step-by-step conversation graph (branches, merges, DTMF, voicemail, scenario links). Each apply replaces the whole graph.

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# yaml-language-server: $schema=https://schema.roark.ai/roark-config.schema.json
kind: flow
type: scripted
name: booking-scripted
agents: [frontdesk]
branchingMode: ADAPTIVE
graph:
  - ref: greeting
    type: AGENT_TURN
    content: Thanks for calling, how can I help?
    steps:
      - ref: request
        type: CUSTOMER_TURN
        content: I'd like to book a cleaning.
```

* Each node has a `type` and an optional `ref` label so other nodes can rejoin it via `mergeInto` (DAG merge edges). `steps` are a node's successors (more than one = a branch).
* No UUIDs: identity is the `ref`, and each apply replaces the whole graph.
* The environment is referenced by its display name and must already exist in Roark.

<Note>
  For the full field reference of every kind, see the [Config DSL reference](https://schema.roark.ai/roark-config.schema.json) schema.
</Note>