# diagonaldiagrams

> diagonaldiagrams is a Python library and MCP server that lets an AI agent draw diagrams and charts as SVG, and check them for overlapping text, arrows through boxes and text that spills, before showing them. One command checks a spec, draws the SVG, and audits the drawing. Do not hand-edit the SVG, and do not screenshot it to check it: the JSON line is the check.

## Draw

```bash
diagonaldiagrams mermaid - -o out/flow.svg <<'EOF'
flowchart TD
  A([Start]) --> B{Ready?}
  B -->|yes| C([Done])
  B -->|no| A
EOF
```

From a checkout the same arguments work as `py -3 graph.py` (Windows) or `python3 graph.py`.

It prints one JSON line.

- `"ok": true`. The figure is at `svg`. `layout` lists what was drawn. Answer from that.
- `"ok": false`. Each error has a `fix`. Change the input and run again.
- `warnings`. The figure is drawn. Act on one only if it matters.

`--fit` says where it will be read. `column` for a README, docs page, or chat (about 640 px wide, read by scrolling). `slide` is the default, for a deck. `page` is for print. In Mermaid, put `fit: column` in the front matter. In JSON, `"size": {"fit": "column"}`.

| Command | Input |
| --- | --- |
| `mermaid` | `flowchart`, `sequenceDiagram`, `erDiagram` |
| `flow`, `arch`, `seq`, `schema` | JSON. `describe <type>` prints the shape |
| `iso` | JSON layers (top first), their items in rows, and links between layers: an isometric layer stack |
| `bar`, `line`, `scatter` | CSV. `--cat`/`--val`, or `--x`/`--y`, and optional `--group` |
| `geo` | CSV or GeoJSON, on a built-in coastline |
| `chart <kind>` | About 60 more. `describe` lists them |
| `story` | One figure, several views. `--gif` films a view when ffmpeg is installed |
| `apply` | A JSON patch into a spec, then draw again at the same `-o` path |
| `export` | `png`, `pdf`, `drawio`, `excalidraw` from the receipt |

Titles state the finding. Blue is HTTP. Dashed is async. Coral marks at most two focal items.

## Install

- [Install skill](.agents/skills/diagonaldiagrams-install/SKILL.md): clone, check `describe`, copy the drawing skill.
- [Drawing skill](.agents/skills/graph-engine/SKILL.md): the full contract. This file is the short version of it.
- Plugin: `/plugin marketplace add lucas19919/diagonaldiagrams` then `/plugin install diagonaldiagrams@diagonaldiagrams`.
- Command only: `pip install diagonaldiagrams`.
- MCP: `diagonaldiagrams mcp`.

## Read next

- [README](README.md): what it is, three filmed figures, and the Pele and Mermaid numbers.
- [Architecture](docs/ARCHITECTURE.md): where the code lives, for contributors.
