Get started

Editing an existing diagram

How an agent, or you, changes a diagram that already exists as a Plotwork picture: a hosted link, an .svg file in a repository, or a diagram fence in a Markdown file. The picture can give its diagram source back only if it was saved with the source inside it, so this guide also says when to save it that way.

TL;DR

Question	Answer
How do I edit a picture I only have as a link or a file?	Call `read_diagram` with its link as `url` or its text as `svg`, edit the source it returns, call `draw_diagram`, then write the file again or call `publish_diagram`.
When can a picture give its source back?	When it was saved with `embedSource` set to true, or written by `sync_markdown`. A picture without the source says so and returns its title, outline, and labels to rebuild it from.
When should I set `embedSource`?	Whenever you save an SVG into a repository, or publish a link someone may want to edit later. It is off by default.
Is the embedded source private?	No. The source is part of the picture, so anyone who has the file or the link can read it. For a diagram in an organisation, every member who can open it can.
Does an edit keep the same link?	No. A hosted link is one drawing. An edited diagram is a new picture with a new link, so replace the old link where it is used.
Does reading use the network?	Only when you give `read_diagram` a link. Reading the text of a file touches no network, and the local server still makes no network requests by default.
Which links can it read?	Pictures on `cdn.plotwork.dev` and `cdn-preview.plotwork.dev`, over https, at a path like `/d/<22 characters>.svg`. Nothing else is fetched.
Can I read one without an agent?	Yes, over HTTP. `POST /v1/diagrams/read` takes the text of a picture or the link of a hosted one and answers with its source. Calling it directly needs the Pro plan and an API key.

1. How a picture carries its source

A Plotwork picture is an SVG file. When it is drawn with the source embedded, the source sits in one <metadata data-format="buun-diagram"> element of the file, written as XML text: &, <, and > are escaped, so any source fits, and a plain fetch of the file shows it. read_diagram reads that element back and returns the exact text that was written, down to its quotes, blank lines, and line endings.

How the picture was made	Source inside?
`sync_markdown` on a Markdown file	Yes. It always writes it.
`draw_diagram`, `draw_from_pattern`, `convert_mermaid`, or `render_diagram`	Only with `embedSource` set to true, or with `detail` set to `full` where the tool has it.
`publish_diagram` or `POST /v1/diagrams/publish`	Only with `embedSource` set to true.
A picture drawn before this existed, or saved by another tool	No.

A hosted picture also carries a stored diagram id, in data-plotwork-id on its root element. read_diagram returns it as id, so you know which stored diagram the file came from.

2. Edit a hosted link

You have https://cdn.plotwork.dev/d/<22 characters>.svg in a README, a ticket, or a chat, and a request to change it.

Step	What to do
1	Call `read_diagram` with `url` set to the link. It returns `source`, `kind`, `id`, and the check of the source, with every error's line, column, and hint.
2	Edit `source`. Keep what the person did not ask you to change.
3	Call `draw_diagram` with the edited source and `embedSource` set to true. Fix every error it returns, then read the outline to check the diagram says what was meant.
4	Call `publish_diagram` with the same source and `embedSource` set to true, and the same `folder` and `name` as before if there were any. Tell the person that the source is part of the picture.
5	Replace the old link with the new one wherever it is used, such as the README or the ticket. The answer carries a Markdown image to paste.

If the picture has expired or was deleted, read_diagram returns status unreachable and says so. Then you need the source from somewhere else, such as a diagram fence or a .diagram file.

3. Edit an `.svg` file in a repository

You have a file such as docs/assets/login-flow.svg and a request to change it.

Step	What to do
1	Read the file, then call `read_diagram` with its text as `svg`.
2	Edit the source.
3	Call `draw_diagram` with the edited source and `embedSource` set to true.
4	Write the returned `svg` over the file. Draw the dark theme too if the repository has a dark file next to it.
5	Show the person the change, or the new picture.

If you keep the edited source in a .diagram file next to the picture, the next edit starts from the file, not from the picture.

4. Edit a `diagram` fence in Markdown

If the picture sits under a diagram fence in a Markdown file, the fence is the source and nothing needs reading back. Edit the fence, then call sync_markdown with the document. It returns the rewritten pictures and the block between the markers, and it embeds the source in each picture. See Diagrams in Markdown and on GitHub.

When a repository has both a fence and a picture, edit the fence. The next sync rewrites the picture from it.

5. When the picture has no source

A picture saved without embedSource has nothing to read back. read_diagram does not fail. It answers with status no-source, and:

Field	What it holds
`message` and `next`	What happened, and what to look for next.
`picture.title`	The title of the diagram.
`picture.outline`	The plain-language outline the picture carries, one entry for each line: its groups, nodes, and connections.
`picture.labels`	The text painted on the picture, each label once, in painted order.

Use them in this order:

Look for the source where the picture came from: a diagram fence in the Markdown file that shows it, or a .diagram file next to it.
If there is none, rebuild the diagram from the title, outline, and labels, call draw_diagram, and compare the new outline with the old one.
Save the result with embedSource set to true, so the next edit starts from the source.

The same answer shape covers a text that is not an SVG (not-a-picture), a source that was changed by hand after it was written (damaged), a link on another host (refused), and a link that does not answer (unreachable). Each is a result with a reason and a next step, never an exception.

6. Privacy

The embedded source is stored in the picture, so it is stored wherever the picture is. This is the one case in which Plotwork keeps diagram source, and it happens only when embedSource is set to true.

Where the picture goes	Who can read the source
A file in your repository	Everyone who can read the repository, and everyone who can fetch the file.
A hosted link	Anyone who has the link. Deleting the diagram deletes the source with the picture, and a cached copy can stay visible for up to an hour.
An organisation's private library	Every member who can open the diagram.
A diagram only drawn, never saved	Only you. `draw_diagram` returns the picture and stores nothing, even with `embedSource` set to true.

Nothing sets embedSource for you. An agent should set it when the person is likely to edit the diagram later, and should say so when it publishes. Leave it off for a diagram whose labels are fine to show but whose source you want to keep to yourself. See the privacy policy.

7. A new link on every edit

A hosted link is one drawing and it never changes in place. Publishing the same diagram again returns the same link. Publishing an edited diagram stores a new picture, so it gets a new link, and the old link keeps showing the old drawing until it expires. The same diagram published with embedSource and without it is also two pictures with two links.

So an edit is two steps: publish, then replace. An agent that edits a README should replace every use of the old link in the same change.

On GitHub

GitHub fetches each image through its own proxy and caches it by address. A new link is a new address, so the new drawing shows at once. A README that still holds the old link keeps showing the old drawing, and that is why the old link has to be replaced. The CDN tells caches to keep a picture for up to an hour, which only matters for an address that changes in place, and a Plotwork link does not.

8. For agents

Both servers tell a model these steps, in their instructions, in the overview that get_diagram_syntax returns (under editing), and in the tool descriptions:

To change an existing Plotwork SVG, call read_diagram with its url or its text first.
Edit the source it returns, then call draw_diagram.
Write the file again, or call publish_diagram again. The link changes, so replace the old link.
Set embedSource to true whenever you save an SVG into a repository or publish a link someone may want to edit later.

Doc	Why
Hosted diagrams	Publishing, links, folders, plans, and how long a link lasts
Diagrams in Markdown and on GitHub	The `diagram` fence, `sync`, and the pictures GitHub shows
Writing diagrams with an agent	The loop an agent follows to write a diagram
Privacy policy	What is stored when you publish, and what embedding the source changes
read_diagram	The tool as the server describes it