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 chat UI shows vs names in YAML

The chat UI often shows a short display label (Bash, Write) for a tool call, but that's a client-side rendering choice - the model itself calls a sanitized wire name (bash__run, double underscore, not a dot) that the daemon converts back to the real module.action FQN on receipt. In YAML capabilities and constraints, use module ids and actions (bash + run, filesystem + write). Prefer the module reference.