Concepts

Short mental models for writing Digitorn apps in YAML. For field-by-field detail, use Language and Module reference.

Page	Why it helps
What you can use in app YAML	Inventory of modules, tools, and non-features.
Glossary	Terms you will see in the YAML docs.
Client UI (ui:)	Themes, workspace pane, widgets, slash commands.

Patterns that keep showing up

One tool, several modes

Some capabilities are one tool with parameters (for example background_run, or agent for sub-agents). Prefer the params documented on that tool; do not invent sibling tool names.

Unknown keys fail compile

Typos in YAML field names are compile errors. Fix the path the compiler reports, then re-lint.

Compile time vs run time

Templates like {{env.X}}, {{secret.X}}, and {{prompt.X}} resolve when the app is compiled. Live model replies, tool results, and triggers happen when the app runs.

Names the model sees vs names in YAML

The chat model often sees short names (Bash, Write). In YAML capabilities and constraints, use module ids and actions (bash + run, filesystem + write). Prefer the module reference.