diagonaldiagrams 0.9.0__tar.gz

diagonaldiagrams-0.9.0/.agents/skills/diagonaldiagrams-install/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: diagonaldiagrams-install
+description: >
+  Install diagonaldiagrams, the graphing library for agents. Clones
+  https://github.com/lucas19919/diagonaldiagrams, checks that graph.py runs, and
+  copies the graph-engine drawing skill into the user skills folder.
+  Use when the user says install diagonaldiagrams, set up diagonaldiagrams, add the
+  graphing library, or runs /diagonaldiagrams-install.
+license: MIT
+compatibility: Requires git and Python 3
+metadata:
+  short-description: Install the diagonaldiagrams agent graphing library
+---
+
+# Install diagonaldiagrams
+
+diagonaldiagrams is a graphing library for agents. This skill installs it as a clone plus a check, because the clone also carries the drawing skill. `pip install git+https://github.com/lucas19919/diagonaldiagrams` is the other route: it puts a `diagonaldiagrams` command on PATH, but no skill.
+
+The drawing contract is the `graph-engine` skill in the clone. This skill only puts that library on the machine.
+
+## Steps
+
+1. Find Python 3. On Windows run `py -3 --version`. Elsewhere run `python3 --version`. Stop if Python 3 is missing, and say so. Do not install Python unless the user asks.
+
+2. Pick a stable directory outside the current project.
+   - Windows: `$env:USERPROFILE\.diagonaldiagrams`
+   - Elsewhere: `$HOME/.diagonaldiagrams`
+   If `<dir>/graph.py` is already there, keep that checkout. Do not clone a second copy.
+
+3. If the directory is missing, clone it.
+
+   ```bash
+   git clone https://github.com/lucas19919/diagonaldiagrams.git <dir>
+   ```
+
+   If the directory exists and has no `graph.py`, stop. Tell the user what is in it.
+
+4. Check the library. Run `<python> <dir>/graph.py describe`. Require exit 0. The JSON's `types` list must include `flow`, `arch`, `seq`, `schema`, `bar`, `line`, `scatter`, `geo`, `heatmap`, and `sankey`.
+   Then run `<python> -m compileall -q <dir>/diagonaldiagrams`, so every later call starts from compiled code even where `PYTHONDONTWRITEBYTECODE` is set. Run it again after each update.
+
+5. Copy `<dir>/.agents/skills/graph-engine` to the user skills folder of the agent you are, so later sessions can draw.
+   - Claude Code: `~/.claude/skills/graph-engine`
+   - Grok: `~/.grok/skills/graph-engine`
+   - Another agent: its user skills folder, if it has one. Otherwise skip this step and say so.
+   - If a `graph-engine` skill is already there, leave it. Tell the user both paths.
+
+6. Optional, only if the user wants diagonaldiagrams as tools instead of shell commands: register the MCP server.
+   Claude Code: `claude mcp add --scope user diagonaldiagrams -- <python> <dir>/graph.py mcp`, where `<python>` is `py -3` on Windows and `python3` elsewhere.
+
+7. Report the absolute path of `<dir>/graph.py`. Later draws use that path: `py -3 <path>` on Windows, `python3 <path>` elsewhere. Point the user at the `graph-engine` skill for the draw loop.
+
+To update later: `git -C <dir> pull`, then the `compileall` line from step 4.
+
+Run `<python> <dir>/tests_smoke.py` only when the user asks for a full check.
+
+## Leave alone
+
+Do not edit `graph.py` or the `diagonaldiagrams/` package next to it. Do not hand-edit an SVG the library wrote. Do not run `sync --commit` as part of install.

diagonaldiagrams-0.9.0/.agents/skills/graph-engine/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: graph-engine
+description: Draw charts, flowcharts, sequence diagrams, architecture maps, database schemas, maps, and math plots as SVG with diagonaldiagrams. One command checks the spec, draws, and audits the layout for collisions. Use for any request to chart, plot, diagram, or visualize data, logic, a codebase, or a schema.
+---
+
+# Draw with diagonaldiagrams
+
+Run `diagonaldiagrams`, or `py -3 <path>/graph.py` (Windows) / `python3 <path>/graph.py`. Not installed:
+run the `diagonaldiagrams-install` skill.
+
+## One call
+
+Write the input and render it in the same shell call. Flowcharts, sequence diagrams, and ER diagrams
+are plain Mermaid, piped in with `-`:
+
+```bash
+diagonaldiagrams mermaid - -o flow.svg <<'EOF'
+flowchart TD
+  A([Ticket arrives]) --> B{Sev1?}
+  B -->|yes| C[Page on-call]
+  B -->|no| D[Queue it]
+EOF
+```
+
+It prints one JSON line:
+
+- `"ok": true`: done. The figure is at `svg`. `layout` lists what was drawn: each row's boxes left to
+  right and each frame's members (a long flow that wraps says which rows stand in which column), a
+  schema's columns of tables, a sequence's messages in order, or a chart's axes and series. Check the
+  content against it.
+- `"ok": false`: each error has a `fix`. Change the input and run again. Never edit the SVG.
+- `warnings`: the figure is drawn; act on one only if it matters.
+
+`"ok": true` means no text overlaps, nothing spills its box or the canvas, no boxes overlap, and no
+arrow crosses a box or a label. Do not screenshot, open, or grep the SVG to check: answer from the
+verdict. Each extra look costs a full round trip.
+
+## Where it goes
+
+Pick `--fit` for where the figure will be read, so its text stays full size there:
+
+- `--fit column` for a README, docs page, wiki, notes app or chat: a column about 700 px wide, read by
+  scrolling. A long flow stays one tall strip, a wide row splits into rows where that takes less room
+  than shrinking the figure, schema tables stack, and the figure is about 640 px wide.
+- `--fit slide` (the default) for a deck or a full-width screen: a long flow wraps into columns.
+- `--fit page` for a printed or PDF page: a long flow wraps toward portrait.
+
+In Mermaid, a front matter line does the same (`---`, `fit: column`, `---` above `flowchart TD`); in a
+JSON spec, `"size": {"fit": "column"}`. Sequence diagrams draw the same in every fit.
+
+## Mermaid
+
+`([x])` start or end, `[x]` step, `{x}` decision, `[(x)]` store. `-->|label|`, `-.->` dashed,
+`==>` or `:::focal` coral. `subgraph id [Name] ... end` draws a frame. `fa:fa-database` adds an icon.
+An arrow back to an earlier step draws up the outside. Flows draw top-down; arrow labels draw in capitals.
+`sequenceDiagram` (`participant G as Gateway`, `A->>B: call`, `B-->>A: reply`, `A-)B: event`) and
+`erDiagram` (`A ||--o{ B : has`) work too. Not drawn: style and classDef colors, notes, loop or alt
+blocks. A parse error names the line.
+
+## JSON specs and data
+
+`flow`, `arch`, `seq`, and `schema` also take a JSON spec: `diagonaldiagrams arch spec.json -o arch.svg`.
+`describe <type>` prints the shape. Use `arch` for services in rows (`layer`), with blue HTTP arrows.
+
+`iso` draws a layer stack in isometric 3D: `{"columns", "layers": [{"id", "name", "sub", "items": [{"id", "name",
+"sub", "focal", "col", "row"}]}], "links": [{"from", "to", "label", "async", "focal"}]}`, top layer first. A long
+layer wraps into rows. A link may join any two layers, passing those between through a port; an item stands under
+what it links to above, or in its `col` and `row` (0 at the front). `--style`, `--font` and `--fit` work as on other
+diagrams: a layer is `group`, an item `node`, a link `edge`. The verdict's `layout` lists each layer's items left to
+right. Errors read depth: `hidden` (behind a nearer layer), `spill` (off its block), `through` (a link crossing a
+block): line the linked items up in one `col`. Validate with `validate SPEC.json --type iso`.
+
+CSV with a header row:
+
+| type | flags |
+| --- | --- |
+| `bar` | `--cat COL --val COL [--group COL --sort desc --unit ms]` |
+| `line` | `--x COL --y COL [--group COL]` |
+| `scatter` | `--x COL --y COL [--group COL]` |
+| `geo` | `--lat COL --lon COL [--label COL]` |
+
+All take `--title`, `--subtitle` (state the finding), `--xlabel`, `--ylabel`, and `--highlight VALUE`
+(one series or bar in coral). Line charts name each series at its end; that is the legend.
+`bar` and `line` take `--ref VALUE=label` for a dashed reference line (a target, or 50%); `--unit %` ends a
+bar axis at 100.
+`chart <type> INPUT` draws about 60 more (sankey, gantt, heatmap, treemap, pie, radar, math, ...);
+`describe` lists them.
+
+## Files
+
+`-o PATH/NAME.svg` is the file you get (folders are created), with `NAME.html` and
+`NAME.graph.json` beside it. Input given with `-` or `-s TEXT` is saved as `NAME.spec.mmd` or `NAME.spec.json`.
+`export DIR/NAME --to png|pdf|drawio|excalidraw` redraws from the receipt.
+
+## Stories
+
+To walk someone through a figure, write a story: the figure, then views that `focus`, `dim`, `hide`,
+`highlight` or `reveal` parts of it by selector, each with a `title`, `text` and `notes`.
+`diagonaldiagrams story STORY.json -o out/story.html` draws every view into one page that animates
+between them. `describe story` has the format; a warning means a selector matched nothing.
+
+## Edits as patches
+
+To move, rename or recolor boxes, write a patch: a JSON list like
+`[{"op": "place", "id": "fix", "row": ["review", "fix"]}]` (`place` puts a box in a row, in that order). Write it
+into the spec and draw again at the same `-o` path:
+
+```bash
+diagonaldiagrams apply SPEC.json patch.json
+diagonaldiagrams flow SPEC.json -o out/x.svg
+```
+
+The verdict's `changed` lists what moved, so you can say it in a sentence; the page animates the change.
+Keep edits when you regenerate the spec: `place` writes `rank`, `order` and `same-rank`, which you should
+leave as they are. Keep the patch too: after regenerating, apply it again. Edits that still fit are written in
+(applying twice changes nothing); a `patch-conflict` names an edit the new spec contradicts.
+`diff OLD NEW` compares any two drawings.
+
+Titles state the finding. Blue is HTTP, dashed is async, coral marks at most two focal items.

diagonaldiagrams-0.9.0/.agents/skills/graph-engine/references/schemas.md

@@ -0,0 +1,364 @@
+# schemas.md — generated from `diagonaldiagrams describe <type>`
+Source of truth: DESCRIBE in diagonaldiagrams/describe.py. Regenerate with `py -3 scripts/schemas_ref.py`; `describe` lists every other type.
+
+## scatter
+```json
+{
+  "input": "CSV with header row. Two numeric columns minimum.",
+  "writes": "diagonaldiagrams scatter DATA.csv --x X --y Y -o OUT.svg  (+ OUT.html and the OUT.graph.json receipt beside it)",
+  "required": [
+    "--x",
+    "--y"
+  ],
+  "options": {
+    "--title": "finding, not description",
+    "--subtitle": "one sentence takeaway",
+    "--figure": "Fig. number",
+    "--xlabel/--xunit/--ylabel/--yunit": "axis + unit in parens",
+    "--group": "categorical col, Okabe-Ito legend",
+    "--yerr": "numeric SD/CI col, capped bars",
+    "--facet": "categorical col, small multiples A/B (+col layout via export --layout social)",
+    "--source": "provenance, n auto-appended",
+    "--caption": "kept on the receipt",
+    "--corners": "sharp|rounded|editorial",
+    "--grid/--no-grid": "tick rules, on by default",
+    "--markers/--no-markers": "point dots, on by default",
+    "--highlight": "group or x value, repeatable, drawn larger in accent"
+  },
+  "budgets": {
+    "points_rendered": 400,
+    "groups": 8,
+    "facets": 4,
+    "series": "focal rule: 1 accent max"
+  },
+  "rules": [
+    "non-negative data never shows a negative axis",
+    "domain includes error bars",
+    "ticks are nice numbers aligned to grid",
+    "title and subtitle are drawn on the figure; the HTML page and the .svg are the same drawing"
+  ],
+  "example": "diagonaldiagrams scatter examples/scatter_groups.csv --x dose --y expr --yerr expr_err --group tissue --facet cohort --xlabel Dose --xunit mg --ylabel Expression --yunit 'log2 counts' -o out/s.html"
+}
+```
+
+## flow
+```json
+{
+  "input": "JSON spec {title, sub, nodes[], edges[], groups[]}",
+  "writes": "diagonaldiagrams flow SPEC.json -o OUT.svg",
+  "size": "{\"fit\": \"slide|page|column\"}, or --fit. slide (default): a long flow wraps into columns near 4:3. page: a document page, wraps toward portrait. column: a docs or notes column, read by scrolling: no wrap, about 640 px wide (a wide layer splits into rows where that takes less room than shrinking the figure; schema tables stack)",
+  "node": {
+    "id": "unique",
+    "shape": "oval=start/end | rect=step | diamond=decision | dot=merge",
+    "name": "2-4 words",
+    "tag": "optional kind, e.g. MANUAL (not STEP/START/END: the shape says it)",
+    "sub": "mono sublabel",
+    "rank": "row, 0 at the top (default: automatic)",
+    "lane": "-1 left|0 center|1 right (default 0)",
+    "focal": "bool, max 2 per diagram"
+  },
+  "edge": {
+    "from": "id",
+    "to": "id",
+    "label": "ALWAYS label decision exits",
+    "focal": "happy-path bool"
+  },
+  "rules": [
+    "top-down; a decision's branches sit side by side, loops draw back up the outside",
+    "diamond ≤3 exits (nest for more)",
+    "orthogonal elbows only",
+    "labels masked with 6px gap",
+    "shape carries type, never color",
+    "no ranks needed: longest-path auto-layering + barycenter uncrossing (--auto forces it)"
+  ],
+  "budgets": {
+    "nodes": 9,
+    "edges": 12,
+    "focal": 2,
+    "over": "a warning, not an error; split if it reads badly, or budget false hides it"
+  },
+  "example": "{\"title\":\"Deploy approval\",\"nodes\":[{\"id\":\"a\",\"shape\":\"oval\",\"name\":\"Push\"},{\"id\":\"d\",\"shape\":\"diamond\",\"name\":\"Risky?\",\"rank\":1,\"focal\":true}],\"edges\":[{\"from\":\"a\",\"to\":\"d\",\"label\":\"pass\"}]}"
+}
+```
+
+## arch
+```json
+{
+  "input": "JSON spec {title, sub, nodes[], edges[]}",
+  "writes": "diagonaldiagrams arch SPEC.json -o OUT.svg",
+  "size": "{\"fit\": \"slide|page|column\"}, or --fit. slide (default): a long flow wraps into columns near 4:3. page: a document page, wraps toward portrait. column: a docs or notes column, read by scrolling: no wrap, about 640 px wide (a wide layer splits into rows where that takes less room than shrinking the figure; schema tables stack)",
+  "node": {
+    "id": "unique",
+    "layer": "row int (default 0)",
+    "name": "service",
+    "sub": "Lang:port e.g. Go:8080",
+    "tag": "UI|API|SVC|STORE",
+    "focal": "bool, max 2"
+  },
+  "edge": {
+    "from": "id",
+    "to": "id",
+    "label": "VERB",
+    "proto": "https=blue arrow",
+    "async": "dashed bool",
+    "focal": "bool"
+  },
+  "rules": [
+    "blue=HTTP/API, dashed=async, coral=focal",
+    "tech sublabels in mono, names in sans",
+    "a wide layer spreads the canvas so boxes do not overlap",
+    "set budget false to draw past 9 nodes and 12 edges; focal stays at 2"
+  ],
+  "budgets": {
+    "nodes": 9,
+    "edges": 12,
+    "over": "a warning, not an error; one view per C4 level, or budget false hides it"
+  }
+}
+```
+
+## seq
+```json
+{
+  "input": "JSON spec {title, sub, actors[], messages[]}",
+  "writes": "diagonaldiagrams seq SPEC.json -o OUT.svg",
+  "actor": {
+    "id": "unique",
+    "name": "label",
+    "sub": "tech/mono sub",
+    "tag": "USER|UI|GATEWAY|SVC|STORE",
+    "focal": "bool, max 2"
+  },
+  "message": {
+    "from": "id",
+    "to": "id",
+    "label": "Call name/payload",
+    "proto": "https/grpc",
+    "reply": "bool dashed",
+    "async": "bool dashed",
+    "focal": "bool"
+  },
+  "rules": [
+    "solid=sync, dashed=reply/async, blue=http, coral=focal",
+    "top-down sequence order",
+    "max 6 lifelines"
+  ],
+  "budgets": {
+    "actors": 6,
+    "messages": 16,
+    "focal": 2,
+    "over": "a warning, not an error; split into sub-sequences, or budget false hides it"
+  },
+  "example": "{\"title\":\"Auth handshake\",\"actors\":[{\"id\":\"u\",\"name\":\"User\"},{\"id\":\"api\",\"name\":\"API\",\"focal\":true}],\"messages\":[{\"from\":\"u\",\"to\":\"api\",\"label\":\"login\"}]}"
+}
+```
+
+## schema
+```json
+{
+  "input": "JSON spec {title, sub, tables[], relations[]}",
+  "writes": "diagonaldiagrams schema SPEC.json -o OUT.svg",
+  "size": "{\"fit\": \"slide|page|column\"}, or --fit. slide (default): a long flow wraps into columns near 4:3. page: a document page, wraps toward portrait. column: a docs or notes column, read by scrolling: no wrap, about 640 px wide (a wide layer splits into rows where that takes less room than shrinking the figure; schema tables stack)",
+  "table": {
+    "id": "unique",
+    "name": "table_name",
+    "tag": "AUTH|CORE|AUDIT",
+    "focal": "bool, max 2",
+    "columns": [
+      {
+        "name": "col",
+        "type": "data_type",
+        "pk": "bool",
+        "fk": "bool",
+        "unique": "bool"
+      }
+    ]
+  },
+  "relation": {
+    "from": "id",
+    "from_col": "col",
+    "to": "id",
+    "to_col": "col",
+    "label": "1:N|1:1|M:N",
+    "focal": "bool"
+  },
+  "rules": [
+    "PK coral badge, FK blue badge, columns in mono, types muted",
+    "orthogonal elbow routing",
+    "max 6 tables per view"
+  ],
+  "budgets": {
+    "tables": 6,
+    "columns_per_table": 12,
+    "over": "a warning, not an error; split by bounded context, or budget false hides it"
+  },
+  "example": "{\"title\":\"Users & Teams\",\"tables\":[{\"id\":\"u\",\"name\":\"users\",\"columns\":[{\"name\":\"id\",\"type\":\"uuid\",\"pk\":true}]}],\"relations\":[]}"
+}
+```
+
+## mermaid
+```json
+{
+  "input": "Mermaid text (.mmd): flowchart/graph, sequenceDiagram, or erDiagram",
+  "writes": "diagonaldiagrams mermaid DIAGRAM.mmd -o OUT.svg   (flow, seq, or schema; checked and audited like a JSON spec)",
+  "flowchart": {
+    "nodes": "A[step]  A(step)  A([start or end])  A((start or end))  A{decision?}  A[(store)]",
+    "arrows": "A --> B   A -->|label| B   A -- label --> B   A -.-> B (dashed)   A ==> B (focal)   A & B --> C",
+    "groups": "subgraph id [Title] ... end",
+    "focal": "A:::focal",
+    "icons": "fa:fa-user, fa:fa-database, fa:fa-server, fa:fa-cloud ... in a label draw that glyph in the box"
+  },
+  "sequenceDiagram": "participant A as Name | actor U as User | A->>B: call | B-->>A: reply | A-)B: async event",
+  "erDiagram": "A ||--o{ B : verb | A { type name PK }",
+  "fit": "where the figure goes, as --fit: a line fit: column (or slide, page) in the front matter between --- lines",
+  "not drawn": "classDef/style colors, notes, loop/alt blocks, LR direction (flows draw top-down)",
+  "example": "flowchart TD\n  A([Push]) --> B{Risky?}\n  B -->|yes| C[Review]\n  B -->|no| D([Ship])\n  C --> D"
+}
+```
+
+## bar
+```json
+{
+  "input": "CSV with header row. One categorical column and one numeric column.",
+  "writes": "diagonaldiagrams bar DATA.csv --cat CAT --val VAL -o OUT.svg",
+  "options": {
+    "--cat": "category column",
+    "--val": "numeric value column",
+    "--group": "subgroup column",
+    "--sort": "none|asc|desc",
+    "--orientation": "v|h",
+    "--unit": "unit string",
+    "--title/--subtitle": "drawn on the figure",
+    "--grid/--no-grid": "tick rules, on by default",
+    "--markers/--no-markers": "value labels, on by default",
+    "--highlight": "category or group, repeatable, drawn in accent",
+    "--ref": "VALUE or VALUE=label, repeatable: a dashed reference line, such as a target or 50%"
+  },
+  "budgets": {
+    "bars": 24,
+    "categories": 12,
+    "over": "sort top-N + other"
+  },
+  "rules": [
+    "bar charts must start at zero",
+    "value labels sit on the bars",
+    "gridlines follow the ticks",
+    "--unit % ends the axis at 100 and writes 85%"
+  ],
+  "example": "diagonaldiagrams bar examples/bar_latency.csv --cat service --val p99_latency_ms --unit ms -o out/bar.html"
+}
+```
+
+## line
+```json
+{
+  "input": "CSV with header row. Continuous/temporal X column and numeric Y column.",
+  "writes": "diagonaldiagrams line DATA.csv --x X --y Y -o OUT.svg",
+  "options": {
+    "--x": "x column (numeric or timestamp)",
+    "--y": "y column (numeric)",
+    "--group": "series column",
+    "--xlabel/--xunit/--ylabel/--yunit": "axis labels",
+    "--title/--subtitle": "drawn on the figure",
+    "--grid/--no-grid": "tick rules, on by default",
+    "--markers/--no-markers": "point dots, on by default",
+    "--highlight": "x value or group, repeatable, drawn larger in accent",
+    "--ref": "VALUE or VALUE=label, repeatable: a dashed reference line"
+  },
+  "budgets": {
+    "series": 6,
+    "rows": 400,
+    "over": "a warning, not an error; a series past 600 points is thinned for drawing"
+  },
+  "rules": [
+    "non-negative data floors at 0",
+    "Okabe-Ito series colors",
+    "area fill only on a single series"
+  ],
+  "example": "diagonaldiagrams line examples/line_throughput.csv --x timestamp --y rps --group service -o out/line.html"
+}
+```
+
+## geo
+```json
+{
+  "input": "CSV with lat/lon columns, or a GeoJSON FeatureCollection of Points and Polygons.",
+  "writes": "diagonaldiagrams geo DATA.csv --lat lat --lon lon --label name --val pop -o OUT.svg",
+  "options": {
+    "--lat/--lon": "column names (guessed from lat/lon/lng when omitted)",
+    "--label": "place name",
+    "--val": "numeric size",
+    "--title/--subtitle": "drawn on the figure",
+    "--source": "footer provenance",
+    "--grid/--no-grid": "graticule lines, on by default",
+    "--markers/--no-markers": "place dots, on by default",
+    "--highlight": "place name, repeatable, drawn larger in accent"
+  },
+  "budgets": {
+    "points": 400,
+    "over": "crop to the region you mean"
+  },
+  "rules": [
+    "Web Mercator figure with a built-in coastline, not a tiled basemap",
+    "GeoJSON polygons are drawn on top of the coastline",
+    "graticule, kilometre scale bar, north arrow",
+    "dot size follows --val"
+  ],
+  "example": "diagonaldiagrams geo examples/geo_cities.csv --lat lat --lon lon --label city --val people_m -o out/geo.html"
+}
+```
+
+## export
+```json
+{
+  "input": "Receipt OUT.graph.json written beside every render.",
+  "writes": "diagonaldiagrams export OUT --to png|pdf|svg [--layout figure|wide|slide|social] [--width 1600] [-o FILE]",
+  "rules": [
+    "svg works everywhere, zero deps (re-render from receipt)",
+    "layouts figure/wide/slide/social apply to scatter; other types export single layout",
+    "png and pdf use cairosvg when it imports, otherwise headless Edge or Chrome",
+    "the HTML page has Export PNG, which saves the figure from the browser"
+  ],
+  "budgets": {
+    "png_width_default": 1600
+  },
+  "example": "diagonaldiagrams export out/scatter --to svg --layout social"
+}
+```
+
+## doc
+```json
+{
+  "input": "Markdown document containing ```graph:<type> fenced blocks.",
+  "writes": "diagonaldiagrams doc DOC.md [--out-dir assets] [--check]",
+  "behavior": "Parses and compiles embedded diagram specs into standalone SVGs in assets/, updates doc links"
+}
+```
+
+## monitor
+```json
+{
+  "input": "Repository working tree or git history.",
+  "writes": "diagonaldiagrams monitor [--base <ref>] [--ci] [--map graph.monitor.json]",
+  "behavior": "Scans code changes for data models, routes, and migrations without corresponding diagram updates; outputs JSON drift report. With --map, extracts each changed file and semantically diffs against its spec (no diff = no drift, even if files changed).",
+  "map_format": "{\"mappings\": [{\"code\": \"models/*.py\", \"spec\": \"docs/schema.graph.json\", \"kind\": \"schema\", \"domain\": \"database\"}]}"
+}
+```
+
+## extract
+```json
+{
+  "input": "Code source file (.sql DDL, Python ORM model, FastAPI routes).",
+  "writes": "diagonaldiagrams extract schema|routes SOURCE_FILE -o SPEC.json",
+  "behavior": "Reverse-extracts architecture or database schema diagram specs directly from source code using AST/token parsing"
+}
+```
+
+## sync
+```json
+{
+  "input": "Same inputs as monitor (--path, --base, --map).",
+  "writes": "diagonaldiagrams sync --map graph.monitor.json [--docs ARCH.md] [--commit]",
+  "behavior": "Auto-fix bot: for each mapping-backed drift entry runs extract -o spec, validates, recompiles --docs, audits emitted SVGs. Default touches only the working tree; --commit creates a LOCAL commit (never pushes). Exit 1 if anything is left undone. Heartbeat: cron `0 6 * * * cd repo && diagonaldiagrams sync --map graph.monitor.json --commit`, Windows Task Scheduler, or an Antigravity cron//goal task."
+}
+```

diagonaldiagrams-0.9.0/.agents/skills/graph-engine/references/taxonomy.md

@@ -0,0 +1,108 @@
+# Graph Taxonomy — CLI Graphing Tool
+Source: session 2026-10-02. Canonical list for `graph/` CLI.
+
+## A. Statistical / Data Plots — from data files
+| # | Type | Shows | Use case | Domain | CLI needs |
+|---|------|-------|----------|--------|-----------|
+| 1 | Scatter plot | 2 vars correlation | dose vs expression | science, ML | title, x/y labels, ticks, marker shape/color/size, legend, trendline, log scales, error bars |
+| 2 | Bubble chart | 3 vars (size=3rd) | pop vs GDP sized by CO2 | economics | size legend, alpha |
+| 3 | Beeswarm | 1 var dot per item | test scores per class | stats, bio | jitter, grouping |
+| 4 | Line chart | trend over continuous x | latency over time | ops, finance | multi-series, markers, fill, log-y |
+| 5 | Step chart | piecewise-constant | feature flag state | infra | sharp/smooth corners |
+| 6 | Slopegraph | change between 2 states | before/after coverage | consulting | label both ends |
+| 7 | Bump chart | rank movement | framework popularity | tech radar | rank inversion |
+| 8 | Ridgeline | distributions per series | latency per service | SRE | overlap, bandwidth |
+| 9 | Bar chart (V/H) | categorical comparison | requests per endpoint | general | grouped/stacked, thickness, padding, sort, value labels |
+| 10 | Grouped + Stacked bar | sub-categories | errors by service x type | ops | totals, legend |
+| 11 | Dumbbell / Lollipop | delta between 2 points | p50 vs p99 | performance | connector line |
+| 12 | Waterfall / Bridge | start->end via contributions | budget bridge | finance | subtotals, +/- colors |
+| 13 | Histogram | binned distribution | request sizes | stats | bins, KDE overlay |
+| 14 | Box plot | quartiles + outliers | build time per runner | QA | grouping, outliers |
+| 15 | Violin plot | KDE + box | response shape | stats | split violins |
+| 16 | Strip / Jitter | raw points per category | flaky tests | testing | alpha |
+| 17 | Pie / Donut | part-of-whole few slices | language share | exec | % labels |
+| 18 | Waffle | proportion 10x10 grid | coverage 87% | dashboards | grid icons |
+| 19 | Treemap | hierarchical sizes | disk/bundle size | infra | nesting, 2nd metric color |
+| 20 | Sunburst / Icicle | hierarchical part-of-whole | dep size tree | packaging | drill-down |
+| 21 | Heatmap / Matrix | 2D values by color | correlation matrix | ML | diverging map, annotations |
+| 22 | Calendar heatmap | day intensity | deploys per day | devprod | year layout |
+| 23 | Contour / Surface / 3D | z(x,y) | loss landscape | ML, geo-science | levels, palette |
+| 24 | Radar / Spider | 3-5 criteria | service scores | arch review | 5 axes max, 1 focal |
+| 25 | Polar cyclic | cyclic categories | traffic by hour | ops | angle=category |
+| 26 | Candlestick / OHLC | open/high/low/close | prices, batch timings | finance | bull/bear colors |
+| 27 | Status grid | health cells | host x check | dashboards | key->color map |
+| 28 | Errorbar / Forest | estimate + CI | benchmarks | science | CI level |
+| 29 | QQ / Residual | model diagnostics | normality check | ML | reference line |
+| 30 | Volcano plot | -log10(p) vs log2FC | diff expression | bio | top-N labels |
+| 31 | Sankey | flow width=amount | CDN->service->DB | data-eng | 3 stages max |
+| 32 | Streamgraph | stacked flows over time | traffic share | analytics | baseline |
+| 33 | Funnel / Pyramid | conversion drop-off | signup->paid | product | % remaining |
+
+## B. Network / Relationship — from code or data
+| # | Type | Shows | Use case | Domain |
+|---|------|-------|----------|--------|
+| 34 | Dependency graph (DAG) | depends-on, cycles | imports, terraform graph | software |
+| 35 | Force-directed / community | Louvain clusters | microservice coupling | architecture |
+| 36 | Radial | center=most-connected | core libs | review |
+| 37 | Tree / Dendrogram | parent->children | file/call tree | docs |
+| 38 | Nested / Containment | containment hierarchy | monorepo map | architecture |
+| 39 | Flow / Execution-order | bootstrap order | startup seq | onboarding |
+| 40 | Knowledge / Entity graph | entities+relations | symbols | code intel |
+
+## C. Software Architecture — from codebases (hero)
+| # | Type | Shows | Use case | CLI needs |
+|---|------|-------|----------|-----------|
+| 41 | C4 L0 Context | black box + actors | stakeholder deck | person shapes |
+| 42 | C4 L1 Container | services+DBs+queues | onboarding | tech labels, async dashed |
+| 43 | C4 L2 Component | classes in container | PR review | ports |
+| 44 | C4 L3 Code/Process | runtime lifecycle | debug auth | sequence overlay |
+| 45 | UML Class | inheritance/composition | API design | 7 classes max |
+| 46 | Deployment | zones/hosts/ports | go-live | 3 zones / 6 nodes |
+| 47 | Layer stack | abstractions | OSI, medallion | 6 layers max |
+| 48 | DP Integration | sources->core->consumers | data platform | source icons |
+| 49 | High-level / IT current-state | legacy by dept | modernization before-shot | dept grouping |
+| 50 | Database schema | tables, FKs, indexes | migration | 6 tables / 8 cols shown / 8 rels (engine budgets, DESCRIBE=schema) |
+| 51 | ER / Data model | entities+relations | domain modeling | crow's foot |
+| 51 | ER / Data model | entities+relations | domain modeling | crow's foot |
+| 52 | Wardley map | value vs evolution | build-vs-buy | 9 comps / 2 moves |
+
+## D. Logic / Process / State — from logic specs
+| # | Type | Use case | Domain |
+|---|------|----------|--------|
+| 53a | Flowchart / Programmablaufplan (PAP, DIN 66001 / ISO 5807) | Oval start/end (rx=20), rect action, diamond decision ≤3 exits, dot merge; top-down, Yes=right No=down, every branch labeled | deploy approval, algorithm, support triage | informatik / ops — shape carries type not color, coral only on happy-path or key decision |
+| 53b | Flowsheet / Process flowsheet | continuous process steps with inputs/outputs per stage | ETL pipeline, chem/process, stage framework | data-eng / process — same primitives as flowchart, emphasis on handoffs |
+| 53c | Decision flowsheet / Entscheidungs-Flussdiagramm | diamond-heavy branching, nested diamonds for 4+ exits | onboarding routing, "Should I…?", access rules | informatik / product — paired policy-evaluation traces, first-divergence highlight |
+| 54 | Swimlane | handoffs dev->review->deploy | process |
+| 55 | Sequence | User->API->Auth->DB | backend — 6 actors / 16 msgs, solid=sync dashed=reply/async, blue=http |
+| 56 | State machine | new->paid->shipped | checkout |
+| 57 | BPMN | auditable process | enterprise |
+| 58 | Decision tree | ML splits | data science |
+| 59 | Fishbone | root-cause grouped | incident — 6x3 |
+| 60 | Loop / Flywheel | feeds-first + hub | growth |
+| 61 | Kanban | WIP + blocked | delivery |
+| 62 | Gantt | tasks on timeline | planning — 12 tasks |
+| 63 | Timeline | events in time | roadmap |
+| 64 | User journey | stages + feeling | product |
+| 65 | Story map | backbone->releases | agile |
+| 66 | Org chart | ownership | team — 4 deep / 12 nodes |
+
+## E. Geospatial — from GeoJSON/shapefiles
+| # | Type | Use case | Stack |
+|---|------|----------|-------|
+| 67 | Point / Cluster map | PoPs, incidents lat/lon | `graph geo` (Web Mercator figure: graticule, scale bar, sized dots; GeoJSON polygons if you pass them). kepler/deck only if you need tiles |
+| 68 | Choropleth | region by metric | geopandas + mapclassify |
+| 69 | Heat / Density | request density | deck.gl hexagon |
+| 70 | Flow / OD map | zone-to-zone traffic | deck.gl arc |
+| 71 | Raster / Terrain | DEM hillshade | GMT, QGIS headless |
+| 72 | Print layout | map+legend+scalebar PDF | qgis layout export-pdf |
+
+## F. Comparison
+| # | Type | Use case |
+|---|------|----------|
+| 73 | Quadrant 2x2 | effort vs impact |
+| 74 | Venn (max 3) | overlap |
+| 75 | Bar+Line combo | revenue + margin |
+
+## Global rules
+- If table does it, don't draw. >9 nodes => split overview+detail.
+- Stunning arch: orthogonal elbows r=8, no diagonals, 6-10px label gap + mask, >=12px fan, max 1-2 coral focal, Geist sans + Mono ports.