Update the diagram after a merge: three calls, and how to pick one

A repository at a normal pace produces dozens of commits a week and a handful of architectural changes a quarter. A README fix, a test, a dependency bump, a comment: none of them change what the picture shows. A loop that redraws on every merge spends time and tokens producing a diagram identical to the one it replaced, or worse, subtly different because the model made different choices the second time around.

Datadef settles that question before drawing anything. A sync first resolves the head commit of the tracked ref and stops there if it has not moved. If it has, it computes a structure fingerprint, a truncated SHA-256 over what actually feeds the diagram: the parsed Terraform draw plan for a Terraform repository, the assembled file corpus for everything else. A commit that touches a README, a test or a comment moves the commit sha and not the fingerprint, and a sync whose fingerprint has not moved skips generation outright. No model call, no redraw, no new version.

That changes what a sensible default looks like. An agent can call the refresh after every merge without paying for the merges that did not matter. The no-op answer comes back in a couple of seconds and is literal about it: already up to date, the repository and ref it checked, and the commit it is still sitting on.

edit_diagram takes one plain-language instruction against one diagram, applies it, and returns a PNG of the result. It is the right call when the change is small and you already know exactly what it is: one new service, one rewired arrow, one renamed table. It spends a generation credit, and when the model concludes that nothing needed to change, the credit is refunded and you get a note saying so instead of a redraw.

repo_refresh takes a project id and re-syncs the linked repository. It is the right call when the branch has moved and you want the picture to follow the source rather than your description of it. It is also the destructive one: a real sync regenerates the diagram from the repository and replaces manual canvas edits. The call waits about ten seconds for the fast path, then reports that the sync is running and points the agent at repo_status. Refreshes are rate limited to ten in ten minutes per account, so an agent looping over twenty projects queues instead of starting twenty generations at once.

The third call is no call. Daily sync already runs about once a day per linked diagram while it is enabled. If the merge was not urgent, the loop is covered and the correct agent behaviour is to say that rather than to burn a generation proving it.

> we merged the events consumer, is the platform diagram current?

repo_status(project_id: "prj_8fd2")
  "Platform" tracks github acme/platform (branch main).
  Sync: synced 20 hours ago, status ok, at commit 4f1c9a2b1d.
  Daily sync is on.

repo_refresh(project_id: "prj_8fd2")
  Sync started. The diagram is being regenerated from acme/platform
  (branch main); this usually takes 1 to 3 minutes.

The reason teams stop trusting automatic regeneration is rarely accuracy. It is that the second version looks like a different diagram: new names, new zones, everything in a new place, and the one node someone had dragged somewhere meaningful is back in the middle of the canvas.

Three mechanisms hold the picture still. On a re-sync the previous diagram is handed back to the model as grounding: its zones, and up to 60 of its nodes as id, label, type and zone, under rules that say anything still present in the source keeps all four, and that zones are not to be renamed, re-split or rearranged. Node identity travels as a source id recorded on each node rather than being reconstructed from the label, so a rename stays a relabel instead of becoming a new node. And nodes a person dragged are pinned: the sync records where it left every node, and anything sitting more than 12 pixels from that spot at the next run is treated as a deliberate move and put back.

The threshold is what makes that safe to leave on. A node still sitting where the layout engine put it is not pinned, so an untouched diagram stays free to re-lay out as it grows, while a hand-arranged one holds still. The grounding block is also appended only on a re-sync of an existing diagram: a first generation, a scratch canvas, a dashboard prompt and a plain MCP call all draw freely. Each sync then logs what share of the previous node ids survived, which is the number to look at when a small source change produced a large diagram change.

A merge tells you what the code now does. It does not tell you that the old path is deprecated but still serving traffic, that the new queue is temporary until the migration finishes, or that a service exists for one customer and comes out in November. Those are the sentences a reader actually needs, and no amount of reading the diff produces them.

So the division of work is stable: the agent handles the structural half, which is mechanical and verifiable against source, and a person writes the annotations that carry intent. Annotations survive a sync when they are notes on the canvas rather than the shape of the drawing itself. Nodes added by hand are counted separately in the grounding handed to the next generation, with an explicit instruction to keep them, because they are the reader's own work and nothing in the source will ever justify them.

• Repo to diagram: how repository sync works
• MCP and agents: setup and the full tool list
• When to regenerate an architecture diagram
• Letting an agent update docs after a merge
• Repository connections documentation