[readitalready]

This flow is really for LLM consumption, since Markdown spec documents are for LLMs anyways. And you can always write a JSON-to-markdown converter for human use (actually, LLMs remember Markdown content better than JSON, so you should use that in your flow a well).

The real change is in generation side, and now the spec docs are LLM generated JSON based on other spec docs or human prompts. LLMs seem to write JSON better than Markdown or YAML, if you tell it to follow a schema.

[ehsanu1]

For my schemas, I found LLMs really wanted to just use markdown embedded in the strings, so I've been considering doing away with the schema. I also figure that embedding markdown in a string may make it perform worse as it has to juggle nested formats, and thus escaping and such (wanted: eval for this). By replacing the json tool call with basic markdown extraction, I'd lose some structured data but gain flexibility (html would be even more flexible).

Wondering if you are referring to adherence to required data in a schema when you say LLMs do better with json vs markdown, or something else? Or perhaps to tool calls and/or strict json output being more reliably formatted for clean extraction?