Draw from a document

Not every diagram starts from code. A design doc, a pattern on a docs site or an engineering article describes a system in words. The archgram skill can draw what such a document says, each part backed by the sentence that states it.

Name the document#

The agent draws from a document only when you name one. Otherwise it draws from the code.

Draw the design in docs/design.md with archgram.

The document must be a file in your project. Save an article you want to draw as a Markdown or text file first.

What it draws#

• A part only where a sentence states it, and a line only where a sentence says one part calls, sends to or reads from another.
• The document's own words. Each part and line is labelled as the document names it, never paraphrased, so a reader who goes from the drawing to the text finds the same names.
• Nothing the text does not state, however likely. What is missing is listed in the report as a gap.

If a diagram already sits beside the document and the two disagree, the agent says where and asks which is right.

Each part points to its sentence#

Each part and line takes as its source the document's path and a few words from the sentence that states it. Here the document is docs/design.md, which says "The worker takes each job from the queue and writes it to Postgres."

archgram: 1
title: jobs
description: The worker takes each job from the queue and writes it to Postgres.
nodes:
  - { id: worker, kind: service, label: worker, source: "../design.md#The worker takes each job" }
  - { id: db, kind: database, label: Postgres, source: "../design.md#writes it to Postgres" }
edges:
  - { from: worker, to: db, source: "../design.md#writes it to Postgres" }

archgram check holds the drawing to the text as it does to code. When someone edits the document to say the worker "stores it in MySQL", the sentence Postgres stands on is gone, and check names what lost it.

docs/diagrams/design.archgram.yaml:6:56: node db: `../design.md` does not hold `writes it to Postgres`
docs/diagrams/design.archgram.yaml:8:37: edge worker → db: `../design.md` does not hold `writes it to Postgres`
2 problems in docs/diagrams/design.archgram.yaml

Keep a diagram true shows how to run the check in CI.

Limits#

• The words sit on one line of the file. A paragraph wrapped across lines splits a sentence, so the agent quotes from within one line.
• The words must match exactly. A rewording that keeps the meaning fails the check, and the source needs the new words. A rewording that changes the meaning but keeps the words passes.
• A phrase the document repeats is found wherever it is, so a change to one copy can go unnoticed.