BLANKS.md is the master file for the blank surface: one file at the root of a config layer that configures blanks as a whole. It doesn't define any blank itself; individual blanks live in their own folders (blanks/<name>/BLANK.md). The master is the surface-wide dial.
What the frontmatter carries
Per the open standard's core spec, the file is YAML frontmatter with five fields: name and description (identifying the project, not any single blank), a spec: pin, and the two working lists:
ignore:lists_-prefixed forms that should never auto-fill. It's a content-level filter: the runtime never fills the listed forms, regardless of which blank would otherwise claim them.disable:lists blank ids excluded at this layer, e.g.disable: [stocks]. It's a source-level subtraction: the named blank stays installed in your library untouched; this layer just doesn't compose it in.
The distinction matters in practice. ignore answers "never fill this particular form"; disable answers "this whole blank shouldn't run here". Re-enabling either is deleting a line, not re-installing anything.
Where it lives, and the layering
Like everything in the config tree, the master exists per layer: ~/.cues/BLANKS.md for your user-wide defaults and <project>/.cues/BLANKS.md for one project. A repo can commit a project-level master that disables a shipped blank for everyone who works in it, which is the polite alternative to asking teammates to edit their own configs. The spec is defensive about the file's absence: a missing BLANKS.md is simply treated as one with no settings, and a 0-byte file (truncation damage) is treated as missing rather than as "disable everything".
One of the master files
Each surface has the same shape of master file: CUES.md for cues, BLANKS.md for blanks. The naming convention is deliberate: uppercase plural masters declare a surface as a whole, uppercase singular files (BLANK.md) declare one source, lowercase folders (blanks/) contain the sources. Scaffolding the masters is opencues init's job, and opencues validate lints them along with everything else (malformed master frontmatter is its own error code in the standard's lint rules).
Note what does not belong here: runtime settings. Whether the fluid blank is on, which LLM the blanks bucket uses, trigger timing, all of that lives in OPENCUES.md. The master files are part of the open standard; the runtime settings file is owned by the reference implementation. The spec is strict about this boundary: a conformant runtime must refuse to honour surface settings declared in the wrong master file, which is what keeps a disable: in CUES.md from accidentally muting a blank.
One more spec subtlety: name: on a master identifies the project, while name: on a per-source BLANK.md identifies that source, and validators scope uniqueness checks to each level separately, so a project named weather never collides with the weather blank.
Related: What is a blank? · What is CUES.md? · GitHub repo