> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://onepin.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://onepin.ai/docs/_mcp/server.

# General rules

> The rules an Onepin workflow definition must satisfy — required nodes, port compatibility, connectedness, validator routing, and retry loops.

A definition is checked when you save it and again when a run starts. These are the rules a graph must satisfy. Get them right and a run just works; break one and Onepin rejects the graph with a message pointing at what to fix.

## Every workflow needs three things

At minimum: **one Source, one Generator, and one Export.** The smallest working graph is `Script → Generator → Export`.

```
Script ──▶ Generator ──▶ Export
(source)   (operator)     (sink)
```

Export needs audio, and only the Generator produces it — so a Generator is required in every runnable workflow. A graph with no source or no export won't run.

## Nodes connect through compatible ports

Lines flow along edges from an output port to an input port. A port only accepts a line that already carries what the next node needs — Onepin compares what the upstream port **provides** against what the downstream port **requires**, and rejects a connection that would arrive missing data.

You don't track this by hand: the canvas only lets you draw connections that fit, and a hand-authored definition is checked on save. A translator, for example, can't feed Export directly — Export needs audio, which only the Generator adds in between.

## Every node must be connected

An orphaned node — one nothing flows into or out of — fails validation. If a node is on the canvas, wire it in or remove it.

## Validators route pass and fail

A [validator](/docs/workflow/validators) has two outputs. Its **`pass`** output must reach Export, or lines that cleared the check would be silently dropped. Its **`fail`** output is optional: wire it back to the Generator to retry, or leave it unwired to drop failing lines. `pass` and `fail` can't feed the same downstream port.

## Loops are only for retries

A cycle is legal only when it is a retry loop. There are two:

* A validator's `fail` wired back to the [Generator](/docs/workflow/generator) — the regenerate-the-line loop.
* A [Pronunciation Corrector](/docs/workflow/pronunciation-corrector) on a [Pronunciation validator](/docs/workflow/pronunciation-validator)'s `fail` port, wired back to that same check to re-grade the corrected take.

Any other loop is rejected.

```
        ┌───────────────── fail ─────────────────┐
        ▼                                         │
   Generator ──▶ Accuracy validator ──▶ pass ──▶ Export
```

## The pronunciation chain has its own placement rules

The three pronunciation nodes are constrained more tightly than the rest of the graph, and the validator enforces this on save:

* A [Phoneme Injector](/docs/workflow/phoneme-injector) must sit **immediately before** a [Pronunciation validator](/docs/workflow/pronunciation-validator) — every outgoing edge goes there and nowhere else. Its input must already carry generated audio, so it cannot sit before the Generator.
* A [Pronunciation Corrector](/docs/workflow/pronunciation-corrector) may sit **only** on a Pronunciation validator's `fail` or `pass` port, and must have at least one outgoing edge. A `pass`-fed Corrector must send its output forward, never back onto an earlier node.
* The [Pronunciation validator](/docs/workflow/pronunciation-validator) goes **last** among a branch's validators.
* The whole chain is `en-us` / `en-gb` only. A Generator branch in another language is rejected, and the built-in pronunciation reference additionally has no Korean, Japanese, or Chinese data.

## Saved isn't the same as runnable

Save-time checks are lenient so you can keep a draft — for example, a cloned template with an empty script saves fine. Run-start is stricter: running a workflow whose required configs are empty fails with `422`. Fix the flagged nodes and run again.

## Related

* [Overview](/docs/workflow/overview) — the node families and how lines flow
* [Validators](/docs/workflow/validators) — pass/fail routing and retry in depth
* [Run a workflow](/docs/guides/run-a-workflow) — build and run a graph end to end
* [Fix pronunciations](/docs/guides/fix-pronunciations) — the pronunciation chain end to end