Add first-class TOML support with YAML feature parity

[DandyLyons]

Summary

Add TOML as a first-class metadata serialization format using mattt/swift-toml (product: TOML). TOML should reach practical feature parity with YAML throughout md-utils, especially in the frontmatter / fm command group and every applicable --format option.

This includes both TOML frontmatter in Markdown documents and TOML as an input/output format. Existing YAML behavior and defaults must remain backward compatible.

Goals

• Read and write standard +++-delimited TOML frontmatter in addition to ----delimited YAML frontmatter.
• Preserve a document's frontmatter format when an fm or document transformation command mutates it.
• Support toml anywhere an existing --format option supports yaml, when the command's data can be represented as TOML.
• Give TOML-backed documents the same in-scope fm CRUD, array, query, validation, and batch-processing capabilities as YAML-backed documents.
• Keep format-independent behavior in portable MarkdownUtilitiesCore where practical and retain supported Apple/Linux/Wasm builds.

Scope

Frontmatter parsing and writing

• Detect YAML (---) and TOML (+++) frontmatter without changing body extraction semantics.
• Represent parsed metadata through a format-neutral model or conversion layer rather than spreading TOML/YAML branches through every command.
• Preserve the original delimiter and serialization format when updating existing frontmatter.
• Provide an explicit way to select yaml or toml when a command creates a new frontmatter block; retain YAML as the default for backward compatibility.
• Produce clear diagnostics for malformed TOML, mixed/mismatched delimiters, unsupported root values, and values that cannot be represented losslessly.
• Frontmatter comments are not guaranteed to survive mutation in either TOML or YAML. Documentation should advise users not to add comments to mutable frontmatter.

md-utils fm parity

All existing operations except fm search should work against YAML- and TOML-backed frontmatter with equivalent semantics:

• get, has, list, set, remove, rename, replace, remove-frontmatter / rmfm
• dump, unique, sort-keys, and touch
• array append, array prepend, array contains, and array remove
• single files, explicit file lists, recursive directories, and supported wrapped frontmatter in non-Markdown text files
• in-scope JMESPath consumers, missing-versus-present values, JSON Schema/rules checks, mdtype assessment/fixes, and other frontmatter consumers

TOML support for fm search, including TOML-backed input and --format toml output, is explicitly out of scope. The command should reject these cases clearly. fm search may be removed separately in the future.

fm replace --format toml should parse TOML input, and output-oriented fm commands that already accept --format yaml should also accept --format toml.

Other --format surfaces

Audit the CLI for every input/output format enum and add toml wherever YAML is currently supported, including type-definition workflows and shared serialization helpers. Update help text, examples, shell completion values, and error messages consistently.

When a command currently emits a top-level scalar or array that TOML cannot represent as a document root, define and document a stable TOML envelope rather than silently changing types. Unsupported YAML-only values (notably null, non-string mapping keys, and incompatible heterogeneous values) must fail with actionable errors instead of being coerced or dropped.

Dependency and architecture

• Add https://github.com/mattt/swift-toml.git from 2.0.0 and use the TOML product.
• Confirm dependency placement does not unnecessarily pull TOML into targets that do not need it.
• Keep decoding limits appropriate for untrusted frontmatter and preserve deterministic/sorted output where current YAML output is deterministic.
• Do not manually edit Package.resolved.

Acceptance criteria

• Markdown with +++ TOML frontmatter can be parsed, queried, mutated, and serialized while preserving its body and TOML format.
• Every existing fm subcommand other than the explicitly excluded fm search has TOML-backed coverage equivalent to its YAML-backed behavior.
• Every applicable --format option that accepts yaml also accepts toml for input or output, excluding fm search as documented above.
• New frontmatter can be explicitly created as TOML; omitted format selection continues to create YAML.
• Mutations preserve the source frontmatter format and delimiter unless the user explicitly requests conversion.
• YAML ↔ TOML conversion behavior and representability failures are documented and tested, with no silent data loss of representable values. Comments are explicitly non-preserving in both formats.
• Rules, in-scope JMESPath consumers, schemas, mdtypes, document transformations, wrapped non-Markdown frontmatter, and collection/batch output work with TOML or report a documented format limitation.
• Unit and CLI integration tests cover scalars, nested tables, arrays, arrays of tables, TOML date/time values, empty frontmatter, malformed input, unsupported values, and multi-file operations.
• README, DocC command documentation, CLI help, common-use-case examples, the bundled Agent Skill, and the Project Brief are updated.
• swift build, swift test, the native Linux Core smoke test, and the existing WebAssembly validation pass (or any upstream platform limitation is isolated and documented).

Notes

TOML and YAML do not have identical data models. “Feature parity” here means equivalent user workflows and explicit, lossless behavior—not pretending every YAML value has a direct TOML representation.

TOML config-file support is tracked separately in #105.

[DandyLyons]

Implemented TOML frontmatter support in a3bfff7.

Scope and behavior:

• Added swift-toml and format-neutral frontmatter values, with +++ parsing/rendering and YAML/TOML-preserving mutations.
• Added TOML coverage across creation-capable fm commands, arrays, dump/replace output formats, wrapped frontmatter, rules, type definitions, and Markdown transformations.
• TOML comments are not guaranteed to survive mutation, matching the existing YAML limitation; documentation advises against comments in mutable frontmatter.
• TOML support for fm search is intentionally out of scope per the follow-up decision and is rejected explicitly. TOML config-file support is tracked separately in Support TOML configuration files #105.
• Added native and WebAssembly coverage, including a revision-guarded swift-toml WASI compatibility patch.

Verification:

• swift build passed.
• swift test passed all 1,134 tests in 95 suites.
• scripts/build-wasm.sh passed, including an idempotent second run and TOML smoke assertions.
• The Linux Docker build could not be run locally because the Docker daemon was unavailable.

Leaving this issue open because its original acceptance criteria still name fm search; those criteria should be reconciled with the explicit scope change before closure.

[DandyLyons]

Acceptance criteria have been reconciled with the approved scope and checked off:

• fm search TOML support is explicitly excluded and rejects TOML input/output.
• Frontmatter comments are explicitly non-preserving for both YAML and TOML.
• The stale Linux server wording now reflects the supported MarkdownUtilitiesCore Linux smoke test.
• TOML config-file support remains tracked separately in Support TOML configuration files #105.

The remaining Docker verification now passes: docker build --file Dockerfile.core-linux --tag md-utils-core-linux . built the Swift 6.2 Linux image and completed LinuxCoreSmoke successfully.

Implementation is functionally ready to close at commit a3bfff7: native build, all 1,134 tests, WebAssembly validation, and Linux Core validation pass. However, a3bfff7 currently exists only on the local codex/issue-104-toml-support branch; there is no remote branch or PR. I recommend closing #104 after the implementation is pushed and merged into the default branch, so I am leaving it open for now.

[DandyLyons]

Completed and merged in ae10b65 via PR #106. TOML is now a first-class, format-preserving frontmatter and structured-output format across the in-scope CLI workflows, with explicit diagnostics for representability limits. The approved scope exclusions are documented: fm search remains YAML-only, frontmatter comments are not guaranteed to survive mutation in either YAML or TOML, and TOML configuration-file support is tracked separately in #105. Verification passed with swift build, all 1,134 tests in 95 suites, WebAssembly validation, the GitHub WebAssembly check, and the Swift 6.2 Linux Core Docker smoke test. All acceptance criteria are checked.