Drawings

A .draw file is an Excalidraw scene stored as a file in your workspace. You can sketch one by hand, or give Monofile mermaid and get back an editable diagram with shapes and arrows you can drag.

What a `.draw` file is

It is a normal text file whose contents are an Excalidraw scene in JSON. Create one the way you create any file, by naming it with a .draw extension, and it opens in a full Excalidraw whiteboard: rectangles, ellipses, diamonds, arrows, freehand, text, colours and layers.

It is a file like any other: every write captures a version, you can share it by link, it shows up in backlinks when a note points at it, and an agent can read or rewrite it.

Saving is automatic. The board writes shortly after you stop drawing, and each write captures a version.

Generating a drawing from mermaid

Nobody has to write Excalidraw JSON by hand. Give Monofile mermaid, piped in or read from a file you already have, and the server converts it:

bash

echo "graph TD
  Client[Web client] --> API[API gateway]
  API --> Svc[Ingest service]
  Svc --> Q[(Queue)]
  Q --> W[Worker]
  W --> DB[(Postgres)]" | monofile diagram /design/ingest.draw

bash

monofile diagram /design/arch.draw --from ./arch.mmd

Agents get the same conversion as the create_diagram tool, and the built-in assistant uses it when you ask for a diagram. The path must end in .draw.

What comes back is not an image. Every box becomes an Excalidraw rectangle, every arrow an Excalidraw arrow, every label a text element bound to its shape. Open the result and you can move a node, recolour a group, add an annotation by hand, and delete the one box that was wrong, all without touching the mermaid.

The five diagram types that convert

Type	Write it as	Use it for
Flowchart	`graph TD` or `graph LR`	Architectures, data flows, pipelines, decision paths
Sequence	`sequenceDiagram`	Interactions over time
Class	`classDiagram`	Types and entities with fields and relationships
Entity relationship	`erDiagram`	Database schemas and cardinality
State	`stateDiagram-v2`	Lifecycles with named transitions

Flowcharts take the full dialect, including subgraph ... end blocks for grouping and classDef for colouring. Anything outside these five, such as gantt, pie, mindmap or timeline, fails with an UNSUPPORTED_TYPE error.

A parse failure reports the line number. Source is capped at 50 KB.

The mermaid stays with the file

A generated drawing records the mermaid it came from, and the diagram type, inside the file. Two things follow:

Regeneration. An agent can read the source back, change three lines, and regenerate the drawing.
Divergence is recorded. When a person edits the board by hand, Monofile re-serialises the file from the shapes, and the file no longer claims that the recorded source describes it.

Reviewing a change to a drawing

A text diff of a diagram is useless. The JSON is machine-generated and every conversion mints new element ids, so a one-box change diffs as the entire file.

When an agent changes a .draw file, the review shows you a picture instead, in three views:

View	Shows
Diagram	The rendered board, with an After and Before flip so you spot the difference by toggling
Source	The mermaid that produced it, as a small readable diff
Raw	The underlying JSON diff, as an escape hatch

Keep and revert sit on the same card, so accepting or rejecting a diagram change is one click.

Next steps

DiagramsMermaid in markdown, and turning mermaid into an editable drawing.
Canvas BoardsSpatial boards of live file nodes, notes, links, groups and labelled edges.
Reviewing ChangesThe diff view and the changeset card: keep or revert everything an agent touched.
Supported File TypesThe full extension to editor map, and what each editor can do.