This document covers all field types available in Pour's config.toml schema, their config keys, validation rules, default output targets, and TUI rendering behavior.

Every module defined in [modules.<name>] supports these keys:

Every field in a module's [[modules.<name>.fields]] array supports these keys:

Any field can override its default via target = "frontmatter" or target = "body".

Any field can be conditionally shown using a show_when block. Hidden fields are skipped during rendering and navigation.

Or using one_of to match multiple values:

Visibility rules:

Submit behavior:

Navigation behavior:

Config validation rules:

Limitations (v1):

Single-line free text input.

TUI: Inline text input with cursor. Accepts any characters.
Output: Value written as-is to frontmatter (or body if overridden). If wikilink = true, the value is wrapped in [[...]] before output.

Multi-line text input with an editor overlay.

TUI: Opens a bordered overlay editor on Enter. Supports multi-line editing. Escape closes the overlay.
Output: Defaults to Markdown body. Can be overridden to frontmatter.
Callout wrapping: When callout = "note" (or any Obsidian callout type) is set, the body output is automatically wrapped in blockquote callout syntax. This applies in both create mode (partition_fields) and append mode (template {{field}} substitution).

Produces:

Runtime cycling: When a textarea field has callout configured, Left/Right arrow keys cycle through callout types while the editor overlay is closed. The [!type] label is shown on the field row. The selected type overrides the config default for that entry only.

Available callout types: note, info, todo, tip, success, question, warning, failure, danger, bug, example, quote.

Numeric input. Restricts keyboard input to digits, ., and -.

TUI: Inline text input, filtered to numeric characters only.
Output: Written to frontmatter as an unquoted YAML number (if parseable as integer or float). Falls back to quoted string if the value contains non-numeric content.
Validation: Non-numeric characters are rejected at input time, not at submit time.

Dropdown with hardcoded options defined in config.

TUI: Enter toggles a dropdown overlay. Up/Down cycles options while open. Enter again confirms selection. The selected value is shown inline when the dropdown is closed.
Output: Selected string written to frontmatter. If wikilink = true, the value is wrapped in [[...]] before output (e.g. roaster: "[[Onyx]]"), creating an Obsidian backlink to the named note.
Extensible options: With allow_create = true, a novel value typed into the open dropdown is accepted on Enter, appended to the in-memory options list, and persisted back to the field's options array in config.toml. Fields without allow_create remain locked to the configured options.
Validation: options must be present and non-empty. Config load fails otherwise. allow_create is only valid on static_select and dynamic_select fields.

Dropdown populated from vault directory contents at runtime via the 3-tier fallback pipeline. With allow_create = true, novel values trigger inline note creation back into the vault.

TUI: Same dropdown interaction as static_select. Options are populated via the 3-tier fallback: API directory listing, filesystem scan, JSON cache (~/.pour/cache/state.json), then freetext input if all fail.

When allow_create = true, the user can type characters directly into the field to filter the dropdown options (case-insensitive substring match). If typing produces no matching options, Enter accepts the typed text as a novel value. Backspace trims the typed text. Esc clears the search buffer before closing the dropdown. Navigating away (Tab/Shift-Tab) discards any unsaved search text.

Output: Selected (or typed) string written to frontmatter. If wikilink = true, the value is wrapped in [[...]] before output.
Validation: source must be present and must be a vault-relative path (no absolute, drive-qualified, UNC, or .. traversal paths). Config load fails otherwise. allow_create is only valid on dynamic_select; using it on any other field type fails config validation.
Source path: Relative to the vault root. Example: "Coffee/Beans" resolves to <vault_base_path>/Coffee/Beans/.

When allow_create = true and the submitted value is not in the existing options list (case-insensitive), Pour automatically creates a note at {source}/{sanitized_value}.md before writing the module output.

Without create_template — a bare stub note is created:

With create_template — a sub-form overlay appears in the TUI, prompting the user to fill in the template's fields. The created note gets full frontmatter from the template. See Template-Driven Creation below.

The filename is sanitized: characters invalid on any platform (: ? * < > | " \ /) are replaced with -, consecutive dashes are collapsed, and Windows reserved device names (CON, NUL, COM1–COM9, etc.) are rejected. If the value sanitizes to an empty or reserved string, auto-creation is skipped silently.

The new entry is appended to the in-memory cache so the next dropdown opens with the value available immediately. Creation is best-effort — a transport failure is logged to stderr but does not block form submission.

With this config, selecting or typing "Ethiopia Guji" writes bean: "[[Ethiopia Guji]]" to frontmatter and, if the value is novel, creates Coffee/Beans/Ethiopia Guji.md with a date frontmatter entry.

When create_template references a [templates.<name>] section, novel values trigger a sub-form overlay instead of creating a bare stub. This lets you capture structured metadata for the new note without leaving the TUI.

Esc cancels the sub-form without creating anything. If the terminal is too small for the overlay (< 10 rows or < 30 cols), Pour falls back to bare stub creation.

Typing "Ethiopia Guji" opens the sub-form. After filling in roaster, origin, etc., Pour creates Beans/Ethiopia Guji.md:

Then post_create_command fires templater:run, which can add body content (brew log table, tasting notes section, metadata) via an Obsidian Templater template.

Tabular data entry with multiple columns (sub-fields). Renders as a YAML array of objects in frontmatter or a Markdown table in body.

TUI: Enter opens a bordered table editor overlay. Navigate cells with arrow keys. Tab advances to next cell. Enter adds a new row. Escape closes the overlay. Empty rows are stripped on output. Inside the overlay, s saves the current rows as a per-field preset, l opens a picker over saved presets, and p cycles through them in place — see "Per-field presets" below.
Output (frontmatter): Serialized as a YAML array of objects. Number sub-fields are written as unquoted YAML numbers.

Output (body): Rendered as a Markdown table.
Validation: sub_fields must be present and non-empty. Sub-field names must be unique. static_select sub-fields must have non-empty options.

Composite-array fields support saved row-set presets so high-friction inputs (recipes, pressure profiles, ingredient lists) can be replayed with a single keypress. Presets are scoped per module.field — coffee.recipe and coffee.pressure_profile have independent lists.

Storage: ~/.pour/field_presets.json (or $POUR_HOME/field_presets.json). User-curated, atomic-replaced on save, separate from module-level presets.json.

Keys (inside the composite overlay):

Apply behaviour: Always replaces all existing rows silently — no confirmation prompt. The composite overlay shows preset: <name> as a subtitle once a preset has been applied so the active selection is visible.

Schema drift: If sub_fields changed since the preset was saved (column added or removed), each saved row is right-padded with empty strings or truncated to match the current sub-field count on apply. The status line reads "preset shape adjusted to current schema" so the change is visible; the on-disk preset is not rewritten — re-save with s to clean it up.

The PWA sub-form overlay (shipped in Phase 2, closed 2026-04-27) renders template fields using the same field-type contract defined in this document. Overlay rendering does not change any field-type semantics: text and number fields render as standard inputs; static_select fields render as inline-cycling controls (◂ ▸ chevrons) instead of a <select> element (PWA-only, no <select> in overlays per UX convention). The dynamic_select and composite_array types are not permitted as template fields (§7.4 already restricts templates to text | number | static_select). Output targets, required semantics, and default-value behavior are identical to the TUI sub-form overlay.

Template fields ([[templates.<name>.fields]]) support allow_create = true on static_select fields only. When set, typing a novel value in the sub-form is accepted; after the templated note is written successfully, the new value is appended to the template field's options array in config.toml so it appears next session. Without allow_create, the sub-form static_select remains locked to the configured cycle of options.

Sub-fields support a restricted set of types — no nesting or dynamic data:

These keys are set on the module itself, not on individual fields:

date_format controls what {{date}} resolves to in path and template strings. It does not affect strftime tokens (%Y, %m, %d) — those always expand using the standard strftime rules.

Use {{date}} in a path or append template:

date_format is editable from the dashboard via vault settings (v → date_format field).

Templates define the note structure created when a dynamic_select field with create_template triggers inline creation. Each [templates.<name>] block specifies the output path and a set of fields that appear in a sub-form overlay.

Pour templates and Obsidian's Templater plugin serve complementary roles:

The post_create_command config key bridges the two: after Pour writes the note with frontmatter, it fires an Obsidian command (e.g. templater:run) via the REST API, which triggers Templater to process the file. The Templater template can read Pour's frontmatter with tp.frontmatter and use it to build the note body.

Example coordination:

This means Pour handles data capture and Templater handles presentation — each doing what it's best at. Users who don't use Templater still get a fully functional note with clean frontmatter.