*: add --yaml-doc-header flag for YAML document separator

[eb4x]

Add an optional --yaml-doc-header flag that prepends the standard YAML document separator (---) to MachineConfig YAML output.

[gemini-code-assist]

Code Review

This pull request introduces a new YAMLDocumentHeader option (exposed via the --yaml-doc-header CLI flag) to prepend a YAML document separator (---) to the generated YAML output. The reviewer suggested writing the # Generated by Butane; do not edit header comment before the --- document separator, as placing file-level comments at the very top of the file is more standard in YAML.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Placing the # Generated by Butane; do not edit header comment at the very top of the file (before the --- document separator) is more standard for file-level comments in YAML. This ensures that the header is always on line 1, making it immediately visible to anyone opening the file.

Suggested change

	if options.YAMLDocumentHeader {
	yamlCfgBuf.WriteString("---\n")
	}
	yamlCfgBuf.WriteString("# Generated by Butane; do not edit\n")
	yamlCfgBuf.WriteString("# Generated by Butane; do not edit\n")
	if options.YAMLDocumentHeader {
	yamlCfgBuf.WriteString("---\n")
	}

[eb4x]

They're both easily seen at the top, and if you're concatenating multiple yaml files, the comment is in the document it belongs in, not in the preceding one.