feat(cli): switch default draft format to JSON with --markdown option

[horacioh]

Summary

• Switch default draft format: CLI now creates drafts as JSON (matching desktop app format) instead of Markdown
• Add --markdown flag: Users can opt into the legacy Markdown format with --markdown option
• Update draft filenames: JSON drafts use <nanoid>.json instead of <slug>_<nanoid>.md for consistency with desktop
• Update draft removal: draft rm --all now properly handles both .md and .json draft files
• Comprehensive test updates: Tests updated to reflect new default behavior and add coverage for --markdown option

Breaking Changes

• draft create now outputs JSON format by default instead of Markdown. Users who need Markdown format must pass the --markdown flag.
• Draft filenames changed from <slug>_<nanoid>.md to <nanoid>.json for JSON drafts.

[juligasa]

What's reason behind changing the default draft format in the cli? Right now everything we produce with the cli is markdown first, since it's llm's format of choice. Also, markdown can be further ammended and updated manually by the user. Or even created by the user entirely. The drawback is that markdown is not as rich as json so not all block types can be represented in .MD files unless we do nastier things with html tagging. But the cli currently only supports basic blocks. So I wonder if you plan to add more blocks to the cli or what was the purpose

[ericvicenti]

I agree that the JSON is a better format for saving. But the markdown CLI behavior by default is part of our design principles

https://seedteamtalks.hyper.media/human-interface-library/cli-design-principles?v=bafy2bzacebjovh3m6cywisgve2nxz2pauhpvlt2jiv4pcegqpor7bo555skl2#s6-DtObp+

[juligasa]

I agree that the JSON is a better format for saving. But the markdown CLI behavior by default is part of our design principles

https://seedteamtalks.hyper.media/human-interface-library/cli-design-principles?v=bafy2bzacebjovh3m6cywisgve2nxz2pauhpvlt2jiv4pcegqpor7bo555skl2#s6-DtObp+

💯 Yeah, the problem is, how do reconcile those two? Right now the cli saves it in .md AND also writes the index json so that the app can see this too (internally the desktop app parses it using the parser in the client SDK). The desktop app still saves them in json because only the desktop app can generate rich documents only supported by json format

[horacioh]

@juligasa the problem is that now If I create a draft with the CLI and I want to open it in the app, its not possible. the screen gets blank when I click the draft in the drafts list.

I guess the solution here is either store the file in both formats, or store the markdown file in another place. and I believe a CLI should store file where they are runned, or you can pass an output flag or something.

What we can't have is what we have currently, that we are storing markdown files in the drafts folder. because drafts made in the app are not stored in markdown.

[ericvicenti]

I'm not sure its a good idea for the CLI to work with the same drafts folder as the desktop app. Helpful for us I think, but I think its generally a bad practice to use the same signing keys and drafts between CLI and desktop because usually the desktop is operated by a human and the CLI is operated by a bot or a script, who should have a different identity.

I guess it would be good to use the same draft saving format and code. Then maybe there is a CLI flag which allows you to specify the drafts folder, in case the user really does want to use the same one as desktop.

[horacioh]

yes, this is exactly what I was proposing in the previous comment:

• the CLI can create markdown by default
• the CLI should save files in the same working directory is running (have a special flag to change the location like --out <PATH>)
• the CLI should have a flag to store the draft as JSON in the app's drafts folder

wdyt @juligasa ?

[ericvicenti]

I don't agree that the CLI should have two formats of draft saving. What is the benefit of saving the drafts as markdown? I believe that the CLI should output markdown to the user (following our design principle), but it can use the "proper" data format underneath.

I am not sure about using the CWD for drafts. Maybe it is the best option, and the user will reference drafts via path name. Or maybe the CLI should choose a location for the user's drafts, something like ~/.seed/cli/drafts .. Not sure about this, lets see what @juligasa thinks

[juligasa]

Actually we currently accept a path override via flag. But the default path is the seed path. I wanted to have a global place for drafts since i did not want drafts scattered among directories depending on where you invoked the cli from.
What @horacioh described (blank draft seen on the desktop app) is clearly a bug not an architectural issue IMO.
On the other hand, @ericvicenti, imposing limitations on the tooling about what keys to use and all of that i don't think its a very robust solution. I don't even know what the problem is. Allowing the tools to use any keys the user wants to use on them?.
This separation between cli (bot) and desktop(human) is greyer than one may anticipate. I can perfectly use the cli myself (just like I use curl manually), and I can also use the chatbot in the app to generate drafts totally in automatic mode (without looking at the text generated). So I don't see a clear bot/human separation. Maybe we need to step back and think about our broader policy on this matter..
If you want to co-sign a document with a bot, your flow of creating the first draft with a bot key and then iterate over with a human key could work. But that's a user's decision. Let's take the git commit comment in claude as an example. Claude wants to add this annoying note co-authored with claude code or something like that and I don't like it at all, i want to receive full credit (and responsability) of what goes there, even if i did not look at any single line of code that was commited. If git forced me to use a different bot key i would be quite annoyed

[ericvicenti]

I believe the major benefit of Seed with agents is that we can use changes to track attribution between agent and human. So, when the agent completes their change, it gets signed (no longer in draft mode). Then when the human makes improvements on the agent's work, you can see exactly what was changed.

Of course I should be able to see that an agent was "steered" by a certain human, and ideally I would also see the prompts that were used to create the agents output. So that way I can see how the humans on my team are using AI. In 2026 hate wondering "is this team member really thinking this way, or is this just a LLM hallucination"

And, I think that if you really do want to use your personal keys to sign LLM-generated content, that should be possible (but discouraged with the default UX)

[horacioh]

is clearly a bug not an architectural issue IMO

the error is that the desktop app tries to open a file that it does not know how to handle or interact with (markdown).
The desktop app knows how to interact with drafts stored in JSON format. so if the CLi stores Markdown, then it must use another location.

[juligasa]

the error is that the desktop app tries to open a file that it does not know how to handle or interact with (markdown).

It does know hoe to handle it, there was a bug, I already pushed the fix. The Desktop app should now see the drafts created by the CLI. Is still failing for you @horacioh ?

So, when the agent completes their change, it gets signed (no longer in draft mode)

Then, to what extend drafts in the CLI are useful? because there are two conflicting flows.

1. The human iterates in a code session along with a model, the content of a seed document. The output of the session is a draft that can be further visualized, amended or processed. Then, when the user is happy, it signs the first version with a "human key"
2. Agent creates a first signed version of the document. A human can "steer" as many times as it wants, creating new version every times. At this point, the document is being handled in the desktop app. I would add. If inside the app changes come from the chatbot agent (one of the next features) we should again use a "bot key" according to your reasoning @ericvicenti ? if changes are manually input in the editor by a human, then use regular keys.

The thing is, in case 1, we should instruct (via skill) the llm to create a draft instead of a document while the opposite is true for case 2.
If we believe we should encourage case 2 for users, that's fine. But why did we push so hard to have CLI drafts, then? They won't be used at all by llm's...

[horacioh]

@juligasa this is the error I get when I try to edit the draft created by the CLI

This is because we need to add locationUid and locationPath data to the index.json file for that draft.

I confirm I can open drafts created by the CLI!

[juligasa]

This is because we need to add locationUid and locationPath data to the index.json file for that draft.

I know. The fix was supposed to handle that. You just needed to pull the code and open the drafts again