Authoring documents as YAML in the app

Document YAML panel

A "Edit document as YAML" toolbar button (top right of the architecture-doc editor, also reachable from the Shift+N command palette under "Document") opens a side panel with:

• The document's YAML source. For a code-backed document this is the stored source; for a hand-drawn document it is decompiled from the current canvas.
• A "Code-backed" badge when the document already has a YAML source, or a "Not code-backed yet" badge otherwise.
• Live validation as you type (errors block Apply; warnings do not). Validation runs against the same compiler the canvas uses.
• An Apply button that recompiles the document from the YAML.

When the document is not yet code-backed, Apply requires an explicit confirmation because it replaces the current canvas with the compiled document. When the document is already code-backed, Apply recompiles in place; manual canvas placements that were not pinned may be repositioned by the layout engine.

Import from Mermaid

An "Import from Mermaid" toolbar button, also in the Shift+N command palette under "Document", opens a panel that accepts pasted Mermaid source or an uploaded .mmd, .mermaid, .md, or .txt file. A README section containing a fenced mermaid block works directly: the first block is extracted automatically.

Converting shows the generated document YAML plus a diagnostics list. Errors block Apply; fidelity notes do not. Applying replaces the current canvas after the same confirmation used for the YAML panel.

Export as Mermaid

An "Export as Mermaid" toolbar button, also in the Shift+N command palette under "Document", emits Mermaid for the current canvas. It returns one block for the ERD group, one per sequence diagram, and one for the flowchart group when those groups are present. Each block has its own copy button plus a "Copy all as Markdown" action. Export notes identify skipped element kinds and supported fidelity losses. See Mermaid import and export for the supported subset and limits.

Edit a single element as YAML

Select one ERD entity, API endpoint, or sequence diagram that came from the compiler (it carries a stable DSL key), and an "Edit selected element as YAML" button appears. It opens just that node's YAML slice. Editing and applying it splices the node back into the document and recompiles. The node id is fixed, so editing the slice cannot rename or detach the node.

Live reload

When a document is recompiled, by this editor, another collaborator, or an MCP agent, every open editor reloads the canvas automatically (via the doc:recompiled realtime event).