# Core concepts

This page is a glossary. The terms below show up everywhere else in the docs
and in the UI. Skim it once, then come back when something is unclear. Each
entry links out to the page with the full story.

## Workflow

A **workflow** is a YAML file describing a finite state machine: a set of steps
and the rules for moving between them. It declares those steps and the
transitions between them, plus a single `initial` state where execution starts.
Workflows are pure data on disk. Roscoe reads them at runtime, so you can edit a
file and re-run without rebuilding.

See [YAML structure](/docs/authoring/yaml-structure) for the full schema.

## State / Node

A **state** (also called a **node**) is a single executable step inside a
workflow. The two terms are interchangeable: the YAML calls them states, and the
web editor draws them as nodes on a graph. The node types are:

- [`script`](/docs/nodes/script) — run JavaScript or TypeScript on Bun (shell
  commands too, via `Bun.$`).
- [`ai_agent`](/docs/nodes/ai-agent) — call a model with a prompt.
- [`ai_judge`](/docs/nodes/ai-judge) — call a model with a rubric and parse a
  verdict.
- [`consensus`](/docs/nodes/consensus) — fan out to several sub-runs and vote.
- [`round_robin`](/docs/nodes/round-robin) — judge candidates head-to-head and
  pick a winner.
- [`map`](/docs/nodes/map) — run the same step over a list and collect the
  results.
- [`condition`](/docs/nodes/condition) — branch on context variables without
  calling out to anything.
- [`human`](/docs/nodes/human) — pause until a person approves or rejects.
- [`subworkflow`](/docs/nodes/subworkflow) — run another workflow as one step.
- [`end`](/docs/nodes/end) — terminate the run with an outcome.

## Transition / Edge

A **transition** is a named outgoing path from a state, declared under that
state's `on:` map. When a node finishes, its validator returns a transition key,
a string like `'true'`, `'pass'`, or `'high'`. Roscoe looks up that key in `on:`
and runs the state it points to. If the key isn't present, the run fails.

Transition keys come from the node's [validator](/docs/authoring/validators),
where you define which keys a node can emit.

## Run

A **run** is one execution of a workflow. Every run has a unique id, a
start/end timestamp, and an outcome. Its per-node trace records every state
visited, the inputs and outputs, and the transition taken. Runs are persisted
to SQLite and visible in the web UI indefinitely.

## Context / Variables

**Context** is the key-value bag that flows through a run. Initial values come
from the CLI's `--var key=value` flags or the API's `context` field on
`POST /api/runs`. Each node can read context variables in its prompt or script.
Each node's outputs merge back into context, so downstream nodes can use them.

See [output chaining](/docs/authoring/output-chaining) for how to thread one
node's output into the next.

## Validator

A **validator** turns a node's output into a transition key. The output can be
a returned value, stdout, or an AI response. The common kinds are:

- `boolean` — emits `'true'` or `'false'`. The default for script nodes (a
  truthy vs falsy return value) and yes/no judges.
- `enum` — picks from a fixed list of strings, e.g. `['pass', 'fail',
'needs-review']`, for multi-way branching.
- `confidence` — buckets a numeric score into named tiers such as `high`,
  `medium`, and `low`.

Consensus nodes add two of their own, `answer` and `most_consistent`, for
tallying votes across the panel. See [validators](/docs/authoring/validators)
for the full reference.

## Outcome

The **outcome** is the terminal status of a run, set by whichever `end` node
the workflow reaches. Three values: `success`, `failure`, `cancelled`. The
outcome drives the colour of the run row in the UI and the exit code of
`roscoe run`.

## Workflow source

Workflows live in one of two places. **Global** workflows sit in
`~/.roscoe/workflows/` and are available everywhere you run `roscoe`. **Project**
workflows sit in `<repo>/.roscoe/workflows/` and are scoped to that repo.

When both define a workflow with the same name, project shadows global. This
lets you check workflow definitions into a repo and override anything that
conflicts with a global one.

See [workflow sources](/docs/configuration/workflow-sources) for resolution
rules.

## Execution mode

Roscoe runs in one of two modes, depending on who orchestrates the AI calls. In
**standalone** mode the runner calls AI executors directly. This needs an
`ANTHROPIC_API_KEY` or a working `claude` CLI on the PATH, and it's the default
for `roscoe run` and the web UI. In **MCP** (Model Context Protocol) mode Claude
Code is the orchestrator. Roscoe runs as an MCP server, and Claude Code reads
each AI node's prompt, calls the model, and feeds the response back. Roscoe needs
no API key of its own.

See [MCP integration](/docs/running/mcp).

## LLM backend

In standalone mode, Roscoe picks one of two **LLM backends** for its AI calls.
The **SDK** backend uses the Anthropic SDK with an API key from the environment;
it's faster and supports streaming and tool use. The **CLI** backend shells out
to `claude -p` as a subprocess, which needs no API key if you're already signed
in to Claude Code.

The backend is auto-detected: SDK if `ANTHROPIC_API_KEY` is set, CLI
otherwise. You can pin it explicitly in `roscoe.yaml`.

See [LLM backends](/docs/configuration/llm-backends).

## Where to next

- [Write your first workflow](/docs/getting-started/first-workflow) — build and
  run one end to end.
- [YAML structure](/docs/authoring/yaml-structure) — the full schema behind
  these terms.