Terminology

This glossary provides canonical names for MDZ syntax elements. Use these terms consistently in documentation, error messages, and discussion.

Path Syntax

• Link (~/path/to/file) — Reference to another file. Type inferred from folder.
• Anchor (#section) — Reference to a section in the current file.
• Link with anchor (~/path/to/file#section) — Reference to a section in another file.

Folder Conventions

• agent/ — Contains agent definitions for delegation
• skill/ — Contains reusable skill modules
• tool/ — Contains tool integrations

Dollar Sigil

• Dollar sigil ($) — Prefix marking variables and types. $name for variables, $Name for types.

Delimiters

• Frontmatter fence (---) — YAML frontmatter delimiter (opening and closing).
• Semantic span (positional) — Content for LLM interpretation based on placement.
• Tuple ((a, b)) — Grouping of multiple values. Used in types and destructuring.
• Array literal ([a, b]) — Collection of values.
• Array suffix ($Type[]) — Type modifier indicating a collection.

Control Flow Keywords

• For loop (FOR $x IN $y ... END) — Iteration over a collection.
• While loop (WHILE cond ... END) — Conditional loop.
• Return statement (RETURN $value) — Exit and return a value.
• Async delegate (ASYNC DELEGATE task TO ~/agent/x) — Non-blocking agent delegation.
• Await (AWAIT $handle) — Wait for async operation to complete.
• Conditional (IF cond THEN ... END) — Conditional branching.
• Else clause (ELSE) — Alternative branch of a conditional.
• Logical operators (AND, OR, NOT) — Boolean logic in conditions.
• Loop control (BREAK, CONTINUE) — Early exit or skip within loops.
• Collection operator (IN) — Specifies the collection in a loop.

Composition Keywords

• USE (USE ~/skill/x TO task) — Invoke a skill to perform a task.
• EXECUTE (EXECUTE ~/tool/x TO action) — Execute a tool.
• DELEGATE (DELEGATE task TO ~/agent/x) — Delegate to an autonomous agent.
• GOTO (GOTO #section) — Jump to a section anchor.
• WITH (WITH #anchor) — Pass a template section.
• TO — Target specifier in composition statements.

Operators

• Assignment (=) — Assigns a value to a variable or defines a type.
• Type annotation (:) — Separates a variable from its type. $x: $Type
• Arrow (=>) — Defines a lambda expression. $x => expr
• Union (|) — Separates enum variants in types. "a" | "b"
• Member access (.) — Accesses a property. $item.name
• Push operator (>>) — Appends a value to a collection. $item >> $list

Comparison Operators

• Equality (=) — Tests if values are equal (in conditions).
• Inequality (!=) — Tests if values are not equal.
• Less than (<) — Numeric comparison.
• Greater than (>) — Numeric comparison.
• Less or equal (<=) — Numeric comparison.
• Greater or equal (>=) — Numeric comparison.

Document Structure

• Frontmatter — Skill metadata in YAML between --- fences: name, description.
• Section heading (##) — Markdown heading that defines a referenceable section.
• List item (-) — Markdown list marker for steps and declarations.
• Code block (```) — Fenced code block (standard markdown).

Type Forms

• Semantic type ($Task: /any executable instruction/) — Natural language type description.
• Enum type ($Status: "active" | "done") — Fixed set of string values.
• Tuple type (($Task, $Priority)) — Compound type of ordered values.
• Array type ($Task[]) — Collection of a single type.
• Function type ($fn = $x => expr) — Lambda/callable type.
• Type reference ($Task) — Reference to a defined type.

Variable Forms

• Variable declaration ($name = value) — Creates a variable with a value.
• Typed declaration ($name: $Type = value) — Declaration with type annotation.
• Required parameter ($name: $Type) — Parameter without default (required).
• Variable reference ($name) — Use of a defined variable.
• Lambda expression ($fn = $x => expr) — Anonymous function definition.

Control Flow

• Block — Indented content after : belonging to a control flow statement.
• Condition — Boolean expression in WHILE/IF (deterministic or semantic).
• Semantic condition (NOT diminishing returns) — Natural language condition interpreted by LLM.
• Deterministic condition ($x < 5) — Computable boolean expression.
• Destructuring (($a, $b) IN $tuples) — Unpacking tuple elements in iteration.

Composition

• Skill invocation (USE ~/skill/x TO task) — Invoking another skill.
• Tool execution (EXECUTE ~/tool/x TO action) — Running an external tool.
• Agent delegation (DELEGATE task TO ~/agent/x) — Spawning autonomous subagent.
• Section navigation (GOTO #section) — Jumping to a section anchor.

Operator Precedence

From highest to lowest:

1. Grouping: ( ) — parenthesized expressions
2. Member access: . — property access like $item.property
3. Function call: () — invocation like $fn($x)
4. Comparison: =, !=, <, >, <=, >=
5. Logical NOT: NOT — unary negation
6. Logical AND: AND — conjunction
7. Logical OR: OR — disjunction
8. Lambda arrow: => — binds loosest