Discussion extracted from PR #377: feat(cli): switch default draft format to JSON with --markdown option. cc hm://z6Mkvz9TgGtv9zsGsdrksfNk1ajbFancgHREJEz3Y2HsAVdk/:profile?v=bafy2bzaceaf5y2554kmdly7yz55fowqum4546bpa2gmi5gntflhlf4gaomdg6&l hm://z6MkgisVMELvqnsCo3dYmtVpy8PiqPGMVwfAyBWFn84vebq4/:profile hm://z6MkgYR76i3w2Xc2fcvgFJWfYjsop6YwUonDhQx3AdLmQ4BQ/:profile hm://z6MkrbYsRzKb1VABdvhsDSAk6JK8fAszKsyHhcaZigYeWCou/:profile?v=bafy2bzacecoevvu2ebpntbrhm552uqp3ag5vrxvukpk7a4vvfmhazkk7smu5y&l

CLI Draft Format

Julio: 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 amended 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.

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

Julio: The problem is, how do we 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.

Shared Drafts Folder

Eric: I'm not sure it's 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 it's 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.

Eric: 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.

Julio: 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 was described (blank draft seen on the desktop app) is clearly a bug not an architectural issue IMO.

Agent Attribution & Key Separation

Julio: On the other hand, Eric, imposing limitations on the tooling about what keys to use and all of that I don't think it's 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 responsibility) of what goes there, even if I did not look at any single line of code that was committed. If git forced me to use a different bot key I would be quite annoyed.

Eric: 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 agent's output. So that way I can see how the humans on my team are using AI. In 2026 I 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).

Julio: There is a practical angle to key separation that makes it harder than it looks. Today the human is the one registered as official member of the sites — capabilities are issued to my key. If I try to delegate to a separate bot key, either the bot cannot write on the same sites my "master" key can, or I have to re-issue capabilities to the bot on every site I am part of. That is painful enough that the easy route is to just hand the bot my own key and impersonate. Even if a users initial intent is to keep personas separate, after feeling that pain they will default to impersonation. Unless we build a full capability clone — a way to say "this bot key inherits every capability my key has" — the rational outcome is: whatever I can access as a real human should be available to my bots, because they are effectively controlled by me anyway.

Draft Workflows: When Are Drafts Useful?

Julio: Then, to what extent drafts in the CLI are useful? Because there are two conflicting flows:

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."

Agent creates a first signed version of the document. A human can "steer" as many times as it wants, creating new versions every time. 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 Eric? 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 LLMs.