Variables and typed values

Annotation turns a raw catalog into a reusable product. Two tools drive that transformation: per-field typed values (defaults, choices, and a strict/suggestion flag) and head variables (catalog-level {{name}} placeholders interpolated once at submit).

Per-field defaults and choice lists

Every field in the Variables view of the template workspace can carry:

Default value — the text (or ref sentinel like @icon:starter/star) used when a caller omits that field from the fill. Explicit values always win; hidden fields never receive a default.
Choices — an ordered list of allowed values. Up to 50 choices, each non-empty and unique. When a caller sends a string value outside the list, the build is rejected with a validation error that names the field and its allowed values.
Strict vs suggestion — a field with choices either enforces the list strictly or treats it as a suggestion set for the fill builder UI.

In the fill builder, a choices-bearing field renders as a <select>. The first option is “use default” (or “keep template content”) with an empty value; omitting the field is equivalent to selecting the default. A text field with a default shows it as a placeholder.

Defaults can themselves contain {{variable}} references — they are interpolated before values reach the build engine.

Head variables

Head variables are catalog-level named slots, defined once and usable in any field value or default across all slides. You edit them in the Variables view.

Each variable has a name (lowercase letters, digits, and underscores), a human-readable label, an optional description (shown in the agent brief), and an optional default.

The `{{name}}` interpolation rule

In a fill.json, the top-level variables block binds names to values:

{
  "variables": { "company": "ACME Corp", "quarter": "Q3 2025" },
  "slides": { ... }
}

Bindings = catalog defaults overlaid with the document’s variables block. Interpolation replaces every {{name}} occurrence (pattern {{ name }} with optional whitespace) in string fill values and in paragraph text items, after field defaults have been injected.

Strict: a {{name}} reference in any value that has no binding — neither a submitted binding nor a catalog default — causes a validation error listing the known variable names. There is no escape syntax for a literal {{ in v1 (an unmatched sequence passes through verbatim).

How agents see variables

The compact catalog (accessible via GET /api/v1/catalogs/{id}/compact and the MCP get_catalog tool) includes a top-level variables section. Each entry exposes name, label, description, and default. The get_fill_schema MCP tool describes the interpolation contract. This is what makes an agent-written fill accurate without requiring the agent to guess what {{company}} means.

Where to edit

Open the template workspace at /templates/{id} and select the Variables tab. The page shows two cards:

Head variables — editable rows (name, label, default, description); an empty-name row is dropped on save.
Field annotations — per-field blocks with “Default value” and “Choices” inputs.