# Editing an existing diagram

> Page: https://docs.plotwork.dev/editing-existing-diagrams. Index of every page: https://docs.plotwork.dev/llms.txt

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](https://docs.plotwork.dev/plans-and-billing.md) 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](https://docs.plotwork.dev/markdown-and-github.md).

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:

1. 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.
2. 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.
3. 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](https://docs.plotwork.dev/privacy-policy.md).

## 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:

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

## See also

| Doc | Why |
|---|---|
| [Hosted diagrams](https://docs.plotwork.dev/hosted-diagrams.md) | Publishing, links, folders, plans, and how long a link lasts |
| [Diagrams in Markdown and on GitHub](https://docs.plotwork.dev/markdown-and-github.md) | The `diagram` fence, `sync`, and the pictures GitHub shows |
| [Writing diagrams with an agent](https://docs.plotwork.dev/mcp/agent-loop.md) | The loop an agent follows to write a diagram |
| [Privacy policy](https://docs.plotwork.dev/privacy-policy.md) | What is stored when you publish, and what embedding the source changes |
| [read_diagram](https://docs.plotwork.dev/mcp/tools/read-diagram.md) | The tool as the server describes it |