D2 diagrams

The user's instructions win over this skill when they differ.

Files

• A diagram is D2 source in a .d2 file, such as diagrams/sign-in.d2.
  Write only that file. When someone opens it in the app, the app lays it out
  and saves two files next to it: the canvas (sign-in.excalidraw), which
  keeps shapes people moved and anything drawn by hand, and a layout record
  (sign-in.d2.json). Don't write or edit those two.
• To change a diagram, read its .d2 file and save the new source with
  write_file and its base_version. Changes made by hand on the canvas
  survive the next layout.
• To move, rename or delete a diagram, do the same to each of its three files
  that exists (see list_files) in one save_files call, so they stay
  together.
• Embed it in a note with <Diagram src="diagrams/sign-in.d2" />. The file
  must exist, so create it first or in the same save_files call.
• show_file draws a diagram from its canvas. A new diagram has no canvas
  until it is opened in the app, and after a source change the card may say
  it is out of date. Give the user the link to open it.
• Comments on a diagram's shapes are on its canvas: to add one, use the
  .excalidraw path and the shape's element_id with add_comment.

Writing D2

• Layout is automatic, so don't give positions. Set direction: right or
  direction: down at the top.
• These shapes are drawn as themselves: rectangle (the default), square, oval,
  circle, diamond, text and sql_table. A container (api: { web; worker })
  becomes a frame. Other shapes, such as cylinder or person, are drawn as
  boxes.
• Keep labels short and put the detail in the note around the diagram.

direction: right
start: Start {shape: oval}
check: Approved? {shape: diamond}
ship: Ship it
fix: Fix issues
start -> check: submit
check -> ship: yes
check -> fix: no
fix -> check: revise

A table diagram:

users: {
  shape: sql_table
  id: int {constraint: primary_key}
  email: varchar {constraint: unique}
}
orders: {
  shape: sql_table
  id: int {constraint: primary_key}
  user_id: int {constraint: foreign_key}
}
users.id <-> orders.user_id: places