I did an incognito chat so that Claude would only have access to the prompt that is pasted in the parent document.

—

This is one of those cases where the agent use case and the human use case point in the same direction, but for slightly different reasons. Here's my reasoning.

LLMs produce errors and need room to recover. An agent performing a complex edit — say, restructuring a section — will likely issue a sequence of commands: create blocks, move blocks, update references. If each command publishes immediately, and the agent makes a mistake on step 3 of 7, you now have a broken intermediate state permanently recorded in the document history and visible to collaborators. With a draft, the agent can make mistakes, correct them, and only publish the coherent final result.

Complex edits are inherently multi-step. You noted that a single logical edit may touch many blocks at different levels of the hierarchy. This is a transactional unit of work. Publishing each step individually violates the atomicity that both humans and collaborators expect. When someone sees a change appear, they reasonably assume it represents a complete thought — not step 4 of 12 in an in-progress restructuring.

Strict schema validation amplifies the risk. Because malformed blocks are rejected, an agent performing a multi-step edit may need to create blocks in a specific order to satisfy validation constraints (e.g., creating a parent before its children). Intermediate states that are structurally valid but semantically incomplete would pollute the document history. A draft lets the agent build up the full valid state before it faces the publish-time validation gauntlet.

Agents benefit from preview/verify loops. A well-designed agent workflow would look like: create draft → make changes → preview the result → verify it meets the goal → publish (or discard and retry). Without drafts, there's no natural checkpoint for self-verification before changes go live.

Immediate publish is genuinely useful for simple, atomic operations — fixing a typo, updating a single field. For a human doing quick edits, the ceremony of creating and publishing a draft for a one-liner is friction. So you should support it, but think of it as a convenience shortcut, not the primary model.

A clean way to do this: every mutating command publishes immediately by default but accepts a --draft <draft-id> flag to accumulate into an existing draft instead. Then provide draft create, draft publish, draft discard, and draft diff/draft preview commands. This way simple edits are frictionless and complex edits are safe.

History quality. Since published changes are immutable and form permanent history, you want that history to be meaningful. A history full of "agent created block," "agent moved block," "agent fixed mistake," "agent moved block again" is noise. A single "agent restructured introduction" entry is a useful historical record.

Network efficiency. In a peer-to-peer system, every publish propagates to other nodes. Batching changes into a single publish reduces network chatter significantly, especially for agent-driven workflows that might issue dozens of commands in rapid succession.

Conflict surface. If an agent is making a complex edit across 15 commands and each one publishes immediately, there are 15 windows where a concurrent collaborator could make a conflicting change. A draft that publishes atomically has one conflict resolution point.

A few things worth getting right in the draft implementation:

The draft should be identified by a stable ID so that an agent can reference it across multiple commands in a script or tool-use chain without parsing output. Something like draft create returns an ID, and all subsequent commands use --draft <id>. Consider also supporting a "current draft" concept (like a git branch checkout) so agents don't have to thread the ID through every call.

draft diff and draft preview are critical for the agent verify step. diff should support machine-readable output (JSON) so agents can programmatically check their work, not just human-readable formatting.

draft publish should be the only point where full validation runs against the complete resulting document state. Intermediate draft states can be more permissive — this gives agents (and humans) room to work without fighting the validator at every step.

Consider a --dry-run flag on draft publish that runs validation and shows what would be published without actually publishing. This gives agents a low-cost way to test before committing.

Build drafts first because they make complex edits safe, keep document history clean, reduce network load, and — critically — give AI agents the error-correction loop they need to operate reliably. Then add immediate publish as a convenience mode for trivial edits. The cost of building drafts first is slightly more upfront implementation work, but the cost of not having them is agents publishing broken intermediate states into your immutable, peer-to-peer document history, which is a much harder problem to fix after the fact.