Your first governed flow

This tutorial takes you from nothing to a completed governed run, and explains why each step exists. By the end you'll have run a real vertical, watched it park at a human gate, signed that gate, and understood how the whole thing stays defensible.

Unlike the Quickstart (which is the fastest path) or the Cookbook (copy-paste recipes), this is a learning walk-through: we stop at each step to explain the idea behind it.

Why governance, not just automation

Automating a regulated process usually forces a bad trade: either a human touches every step (slow, expensive) or agents run unsupervised (fast, uninsurable). Minctrl splits the difference. Agents do the work; a risk model decides, per step, whether the run can proceed on its own or must park for a human verdict. Everything that happens is written to a tamper-evident audit trail. Keep that shape in mind — the steps below are that idea made concrete.

Step 1 — Register (and get a company for free)

TOKEN=$(curl -s -X POST "$API/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@acme.com","password":"<your-password>","company_name":"Acme Ops"}' \
  | jq -r .token)

Why it matters. Registration auto-creates a company and makes you its owner. The company is the isolation boundary: from now on your token identifies both you and your company, and you only ever see your own data. There's no tenant parameter to get wrong.

Step 2 — Pick a flow and read its governance

curl -s "$API/process-templates/" -H "Authorization: Bearer $TOKEN"

Choose a vertical — we'll use prior-auth. Before running it, look at its governance-decorated canvas:

curl -s "$API/process-templates/prior-auth/canvas" -H "Authorization: Bearer $TOKEN"

Why it matters. The same canvas graph that drives execution also encodes the governance: each step carries a risk tier, and some steps are gates. Reading the canvas tells you, before you run anything, where a human will be required and which step-ids those gates are. This is the design step — you're confirming the flow is governed the way you expect.

Step 3 — Understand validation (why a flow can't be silently ungoverned)

If you were authoring your own flow, you'd validate the graph as you edit:

curl -s -X POST "$API/process-templates/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      { "id": "screen", "kind": "agent", "tier": "medium" },
      { "id": "signoff", "kind": "gate" }
    ],
    "edges": [{ "source": "screen", "target": "signoff" }]
  }'

Why it matters. Validation enforces the invariants that make governance real: an irreversible step must have a human gate in front of it, gates must carry their human/gate-id, and blast radius must be sane. If you removed a gate that protected an irreversible step, validation would report that the irreversible step is now reachable without a human — so you can't ship an ungoverned flow by accident. (See Design on the canvas.)

Step 4 — Run it (the autopilot does the reversible work)

RUN=$(curl -s -X POST "$API/process-runs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "prior-auth",
    "inputs": { "member_id": "M-10293", "procedure_code": "27447", "diagnosis": "M17.0" },
    "auto_resolve": true
  }')
RUN_ID=$(echo "$RUN" | jq -r .id)
echo "$RUN" | jq '{id, status, parked_at}'

Why it matters. With auto_resolve: true, the resolver auto-executes the steps it can clear — reads, enrichments, reversible calls — and drives the run forward on its own. It only stops when it hits something that needs a human. The reversible work you'd otherwise pay a person to do just happens.

Step 5 — The gate: why the run parks

Your run's status came back awaiting_human. Read it in full:

curl -s "$API/process-runs/$RUN_ID" -H "Authorization: Bearer $TOKEN" | jq '{status, parked_at}'

Why it matters. The run reached a gate — the medical-director sign-off — whose risk tier requires a human verdict. Rather than guess, the run parks: its full state is persisted and it waits. Parking is durable, so it can wait minutes or days without holding a request open. This is what lets a governed process span a real person's working schedule instead of a timeout.

Step 6 — Resume: the human signs the gate step-id

The trace names the step the run parked on — for prior-auth that's signoff. Resume with that step-id (not a display label) and a decision:

curl -s -X POST "$API/process-runs/$RUN_ID/resume" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "gate": "signoff", "decision": "approved" }' | jq '{status, parked_at}'

Why it matters. The verdict is recorded against the gate step-id and the run continues from exactly where it stopped — nothing is recomputed, no context is lost. If the flow has another gate, it parks again and you repeat this step. The single most common mistake is passing the gate's display name instead of its step-id; if the id doesn't match the parked gate you get a 409, so re-read the run and use the id from its trace.

Step 7 — The audit trail: why it's all defensible

Read the completed run once more and look at its trace of events:

curl -s "$API/process-runs/$RUN_ID" -H "Authorization: Bearer $TOKEN" | jq '.trace.events'

Why it matters. Every decision — each auto-proceed, each park, and your human verdict — is written to a tamper-evident audit trail. Entries are chained so a later edit to a past entry is detectable. This is the record you hand a regulator: what ran, what parked, who signed which gate step-id, and why. Governance isn't just "a human clicked approve" — it's a reconstructable account of the whole run.

What you built

You ran a regulated flow where agents did the reversible work, a human signed exactly the step that carried real risk, and the whole thing left a defensible trail. That's the Minctrl loop:

design → validate → run → gate → park → resume → audit

Where to go next

• Connect a step to your API — point a step's tool-id at your real system, and keep irreversible tools shadowed.
• Configure gates and autonomy — tune what auto-clears and what always waits for a human.
• Cookbook — the same loop on AML, collections, and chargeback flows.