YAML configuration

YAML is everywhere in Zod. Providers, memory, custom tools, and MCP servers are all edited as live, syntax-highlighted YAML — formatted by a hand-rolled aligned formatter and edited in the "Socratic editor", with an "ask AI to edit" button on every section.

Aligned YAML formatter

Zod's formatter parses YAML with js-yaml and re-emits it with all mapping colons aligned to a single global column. It chooses inline vs. block layout based on a max-line budget that is re-measured live from the editor width, and it wraps long scalar values across lines at the value column — so a long API key wraps cleanly:

providers:
  - name        : OpenRouter
    baseUrl     : https://openrouter.ai/api/v1
    apiKey      : sk-or-v1-REPLACE-ME-00000000000000
                  0000000000000000000000000000000000
    model       : openrouter/free
    enabled     : true

Used by the providers, memory, tools, and MCP editors, and by the yaml_format tool.
Inline vs. block layout adapts to your editor width in real time.
Long values wrap at the aligned value column for readability.

The Socratic editor

Each YAML line is rendered with syntax-aware highlighting and live affordances:

Syntax highlighting

Keys, quoted strings, numbers, and booleans are each rendered in their own color.

Secret masking

Secret keys are masked with •••••••• until you toggle "show API keys".

Clickable toggles

Booleans render as clickable toggles — click to flip true / false.

URLs & $ENV vars

URLs become links, and $ENV variables are highlighted so you can spot placeholders instantly.

Line-by-line editing

Click to edit a line, Enter to split with smart indent, Backspace to merge, Tab to indent — a fast, tactile editing model instead of a raw text area.

Ask AI to edit this YAML

Every config section has an "Ask AI" input. It sends the current YAML to your provider and asks it to return a complete, valid replacement document — so you can describe a change in plain language and get back correctly formatted, aligned YAML.

Orchestrator: line format ⇄ YAML

The orchestrator is a second, similar editor — but for workflow text. The friendly line format converts to and from strict YAML:

Line format

# Research brief
## @step:gather
@tool:memory
@skill:research
→ @goto:summarize
## @step:summarize
@tool:todo

Strict YAML

title: Research brief
steps:
  - name : gather
    tools: [memory]
    skills: [research]
    gotos:
      - goto: summarize
  - name : summarize
    tools: [todo]

The YAML form has title plus a steps[] array, each step carrying tools, skills, and gotos — see the Orchestrator page for how these run.