Agent skill that turns natural language, code, Terraform/K8s, SQL, OpenAPI, AsyncAPI, Protobuf and GraphQL sources into editable, tested draw.io architecture diagrams: incremental sync, multi-view projection, drift diff, CI architecture tests, whiteboard derasterize, interactive HTML/PPTX/Mermaid exports.
Python agent-skillsarchitecturearchitecture-diagramasyncapibpmnc4-modelclaude-codediagramdiagrams-as-codedrawioflowchartgithub-actionsgraphqlimage-to-diagramkubernetesmcp-serverprotobufsysmlterraformuml
docs: restore LF line endings, correct the diamond-exit pitfall
Agents365-ai45aa31165362
diff --git a/skills/drawio-skill/SKILL.md b/skills/drawio-skill/SKILL.mdindex 30ded44..081685d 100644--- a/skills/drawio-skill/SKILL.md+++ b/skills/drawio-skill/SKILL.md@@ -1,147 +1,147 @@-----name: drawio-skill-description: Create, edit, synchronize, inspect, test, and publish editable draw.io diagrams. Use when the user explicitly requests draw.io/diagrams.net, needs a polished architecture, ERD, UML, sequence, C4, SysML, BPMN, network, swimlane, ML, or infrastructure diagram, wants code/IaC/SQL/OpenAPI/AsyncAPI/Protobuf/GraphQL converted into a diagram, or wants an existing diagram queried, reviewed, diffed, restyled, kept in sync, or made interactive. Prefer Mermaid/PlantUML elsewhere when the requested artifact is diagrams-as-code rather than an editable draw.io file.-license: MIT-allowed-tools: [Bash, Read, Write, WebFetch]-metadata: {"openclaw":{"requires":{"anyBins":["python3"]},"emoji":"📐","os":["darwin","linux","win32"],"install":[{"id":"brew-drawio","kind":"brew","formula":"drawio","bins":["drawio"],"label":"Install draw.io for native exports","os":["darwin"],"optional":true},{"id":"brew-graphviz","kind":"brew","formula":"graphviz","bins":["dot"],"label":"Install Graphviz for automatic layout","os":["darwin"],"optional":true}]},"hermes":{"tags":["drawio","diagram","architecture","visualization","uml"],"category":"design","requires_tools":["python3"],"related_skills":["mermaid","excalidraw","plantuml"]},"author":"Agents365-ai","version":"3.3.0","homepage":"https://github.com/Agents365-ai/drawio-skill","compatibility":"Core IR, XML, sync, query, test, review, and Story workflows need Python 3 only; native export needs draw.io; Graphviz is optional.","platforms":["macos","linux","windows"]}------# Draw.io Architecture Studio--Produce editable `.drawio` artifacts, not flattened pictures. The preferred-entrypoint is `scripts/diagramctl.py`, which unifies generation, incremental-sync, multi-view projection, semantic queries/tests/reviews, failure analysis,-and accessible publishing over a shared Diagram IR.--## Choose the workflow--| Request | Route |-| --- | --- |-| Natural-language diagram with precise styling | Read `references/diagram-types.md`, then `references/xml-authoring.md` and author XML |-| Standard flowchart/mindmap/gantt/timeline/etc. with no special styling | If draw.io >=30, read `references/mermaid-authoring.md` and convert Mermaid to native `.drawio` |-| Large graph (~15+ nodes) that needs automatic layout | Use `autolayout.py`; read `references/autolayout.md` before passing any `--layout` value |-| Code, Terraform, K8s, compose, SQL, OpenAPI, AsyncAPI, or CI source | Use `diagramctl.py build`; read `references/diagram-ir.md` |-| Protocol Buffers schema (.proto) | Use `protoimports.py` or `diagramctl.py build`; read `references/toolbox.md` |-| GraphQL SDL schema (.graphql/.gql) or introspection JSON | Use `graphqlerd.py` or `diagramctl.py build`; read `references/toolbox.md` |-| Running cluster/stack/cloud (actual state, not declared config) | Read `references/live-infra.md`, then use `tfstate.py`, `dockerimports.py`, or `k8simports.py -` |-| Update a generated diagram without losing manual layout | Use `diagramctl.py sync`; read `references/diagram-ir.md` |-| Executive/system/deployment/data-flow/security views | Use `diagramctl.py views`; read `references/diagram-ir.md` |-| Query, architecture policy, review, what-if, or guided walkthrough | Read `references/semantic-workflows.md` |-| MCP host (Claude Desktop, Cursor, VS Code, Codex) should call these workflows | Register `scripts/diagramctl_mcp.py`; read `references/mcp.md` |-| Prompt phrasing for a diagram type or semantic workflow | Read `references/cookbook.md` |-| Enforce architecture rules or visual diffs in GitHub Actions CI | Read `references/ci-gate.md` |-| Rendered before/after/diff images as a PR review comment | Use `prdiff.py`; read `references/pr-bot.md` |-| Existing `.drawio` to HTML/PPTX/Mermaid/Markdown/animation/runbook | Read `references/toolbox.md`; `diagramctl.py transform` exposes the existing tools |-| Pipeline, journey, or subsystem map drawn as a metro/subway map | Use `tubemap.py`; read `references/tubemap.md` |-| Shape, cloud/vendor, AI, or Databricks icon | Read `references/shapes.md` or `references/databricks.md`; never guess shape names |-| Learn/apply/manage a visual style | Read `references/style-presets.md` |-| Extract a reusable style from an existing diagram or theme | Read `references/style-extraction.md` |-| Existing image to editable diagram (screenshot, whiteboard photo, legacy PNG) | Read `references/derasterize.md` |-| Export/platform problem | Read `references/troubleshooting.md`; for access/network questions read `references/security.md` |--## Unified CLI--Run from this skill directory, or replace `scripts/` with the absolute path to-this skill's scripts directory:--```bash-python3 scripts/diagramctl.py doctor-python3 scripts/diagramctl.py build model.json --from ir -o architecture.drawio-python3 scripts/diagramctl.py build ./infra --from terraform --group \- --ir-output architecture.ir.json -o architecture.drawio-python3 scripts/diagramctl.py sync architecture.drawio ./infra --from terraform \- -o architecture.next.drawio-python3 scripts/diagramctl.py views architecture.ir.json \- --views executive,system,deployment,dataflow,security -o views.drawio-python3 scripts/diagramctl.py test architecture.drawio --rules policy.yml-python3 scripts/diagramctl.py review architecture.drawio -o review.md-python3 scripts/diagramctl.py query architecture.drawio --from internet --to orders-db-python3 scripts/diagramctl.py whatif architecture.ir.json --fail kafka \- --drawio kafka-failure.drawio -o impact.json-python3 scripts/diagramctl.py story architecture.ir.json -o walkthrough.html-```--`doctor` does not launch GUI tools unless `--probe` is passed. Core semantic-commands are offline and stdlib-only.--## Creation workflow--1. Infer the diagram type, audience, scope, output format, and location from the- request. Ask only when a missing choice materially changes the result;- default to PNG plus `.drawio` in the working directory.-2. Select the authoring route from the table above. For a data-backed diagram,- prefer Diagram IR and preserve provenance. For a large graph, use an importer- or `autolayout.py`; do not hand-place more than roughly fifteen nodes.-3. Resolve an explicitly named style preset, or the user's default preset, as- documented in `references/style-presets.md`. Structural diagram conventions- and visual presets compose; they do not replace each other.-4. Generate the `.drawio`, then run structural validation:-- ```bash- python3 scripts/validate.py diagram.drawio --score- ```-- When semantic metadata or an architecture policy is in scope, also run- `diagramctl.py test`. Do not present inferred semantic findings as verified- runtime facts.-5. Export a draft PNG without embedded XML and inspect it visually. Fix obvious- overlap, clipping, disconnected edges, edge-through-node routing, stacked- edges, and unreadable labels. Stop automatic vision repair after two rounds.- When the drawio binary is unavailable or a visual check is inconclusive,- verify the renderer's own DOM instead (`--dump-dom` on the viewer URL, see- `references/troubleshooting.md`): read each edge's `<path>` segments and- label anchor coordinates directly — vision alone both misses geometry- defects and hallucinates new ones.-6. Show the draft and apply targeted edits. Preserve existing geometry for- local changes. Use `sync` for source-backed changes and write a reviewable- output; use `--prune` only when deletion was requested.-7. After approval, create final requested formats and report both editable- source and export paths.--## Export invariants--Resolve the available binary once (`drawio`, `draw.io`, the macOS app path, or-the Windows executable) and use that exact binary for the run.--```bash-# Draft for visual inspection: never use -e here-drawio -x -f png --width 2000 -o diagram.png diagram.drawio--# Final editable PNG-drawio -x -f png -e -s 2 -o diagram.drawio.png diagram.drawio-python3 scripts/repair_png.py diagram.drawio.png--# Final editable SVG/PDF-drawio -x -f svg -e --embed-svg-images -o diagram.svg diagram.drawio-drawio -x -f pdf -e -o diagram.pdf diagram.drawio-```--Do not combine `--width` and `-s`. Embedded PNG exports require-`repair_png.py`; draft PNGs used by vision must not use `-e`. On Linux headless,-follow `references/troubleshooting.md` rather than improvising Electron flags.-If the CLI crashes in a macOS sandbox, try one permitted escalated run, then use-`encode_drawio_url.py` or deliver XML; do not repeatedly launch it.--## Editing and identity--- Use stable semantic IDs and never reuse reserved IDs `0` or `1`.-- Every edge requires `<mxGeometry relative="1" as="geometry"/>`.-- For a local edit, change the matching cell only; for a global direction- change, regenerate/re-layout the page.-- Keep provenance, `data-model-id`, semantic properties, manual geometry, and- manual styles intact unless the user requests otherwise.-- When reconciling, retain removals as reviewable faded elements by default.-- For edges stacked at a boundary, run `edgeports.py`; add waypoints when an- edge still crosses an unrelated shape. There is no CLI-only edge rerouter- that preserves node positions.--## Quality and trust--An attractive diagram can still be wrong. Prefer source-backed relationships,-show provenance where useful, distinguish exact extraction from AI inference,-and keep architecture review findings framed as prompts. Story HTML must remain-self-contained, keyboard usable, and include a text alternative. Never include-secrets in node properties or provenance because they are embedded in outputs.--For all focused scripts and composition patterns, read `references/toolbox.md`;-load only the task-specific reference needed for the current request.+---+name: drawio-skill+description: Create, edit, synchronize, inspect, test, and publish editable draw.io diagrams. Use when the user explicitly requests draw.io/diagrams.net, needs a polished architecture, ERD, UML, sequence, C4, SysML, BPMN, network, swimlane, ML, or infrastructure diagram, wants code/IaC/SQL/OpenAPI/AsyncAPI/Protobuf/GraphQL converted into a diagram, or wants an existing diagram queried, reviewed, diffed, restyled, kept in sync, or made interactive. Prefer Mermaid/PlantUML elsewhere when the requested artifact is diagrams-as-code rather than an editable draw.io file.+license: MIT+allowed-tools: [Bash, Read, Write, WebFetch]+metadata: {"openclaw":{"requires":{"anyBins":["python3"]},"emoji":"📐","os":["darwin","linux","win32"],"install":[{"id":"brew-drawio","kind":"brew","formula":"drawio","bins":["drawio"],"label":"Install draw.io for native exports","os":["darwin"],"optional":true},{"id":"brew-graphviz","kind":"brew","formula":"graphviz","bins":["dot"],"label":"Install Graphviz for automatic layout","os":["darwin"],"optional":true}]},"hermes":{"tags":["drawio","diagram","architecture","visualization","uml"],"category":"design","requires_tools":["python3"],"related_skills":["mermaid","excalidraw","plantuml"]},"author":"Agents365-ai","version":"3.3.0","homepage":"https://github.com/Agents365-ai/drawio-skill","compatibility":"Core IR, XML, sync, query, test, review, and Story workflows need Python 3 only; native export needs draw.io; Graphviz is optional.","platforms":["macos","linux","windows"]}+---++# Draw.io Architecture Studio++Produce editable `.drawio` artifacts, not flattened pictures. The preferred+entrypoint is `scripts/diagramctl.py`, which unifies generation, incremental+sync, multi-view projection, semantic queries/tests/reviews, failure analysis,+and accessible publishing over a shared Diagram IR.++## Choose the workflow++| Request | Route |+| --- | --- |+| Natural-language diagram with precise styling | Read `references/diagram-types.md`, then `references/xml-authoring.md` and author XML |+| Standard flowchart/mindmap/gantt/timeline/etc. with no special styling | If draw.io >=30, read `references/mermaid-authoring.md` and convert Mermaid to native `.drawio` |+| Large graph (~15+ nodes) that needs automatic layout | Use `autolayout.py`; read `references/autolayout.md` before passing any `--layout` value |+| Code, Terraform, K8s, compose, SQL, OpenAPI, AsyncAPI, or CI source | Use `diagramctl.py build`; read `references/diagram-ir.md` |+| Protocol Buffers schema (.proto) | Use `protoimports.py` or `diagramctl.py build`; read `references/toolbox.md` |+| GraphQL SDL schema (.graphql/.gql) or introspection JSON | Use `graphqlerd.py` or `diagramctl.py build`; read `references/toolbox.md` |+| Running cluster/stack/cloud (actual state, not declared config) | Read `references/live-infra.md`, then use `tfstate.py`, `dockerimports.py`, or `k8simports.py -` |+| Update a generated diagram without losing manual layout | Use `diagramctl.py sync`; read `references/diagram-ir.md` |+| Executive/system/deployment/data-flow/security views | Use `diagramctl.py views`; read `references/diagram-ir.md` |+| Query, architecture policy, review, what-if, or guided walkthrough | Read `references/semantic-workflows.md` |+| MCP host (Claude Desktop, Cursor, VS Code, Codex) should call these workflows | Register `scripts/diagramctl_mcp.py`; read `references/mcp.md` |+| Prompt phrasing for a diagram type or semantic workflow | Read `references/cookbook.md` |+| Enforce architecture rules or visual diffs in GitHub Actions CI | Read `references/ci-gate.md` |+| Rendered before/after/diff images as a PR review comment | Use `prdiff.py`; read `references/pr-bot.md` |+| Existing `.drawio` to HTML/PPTX/Mermaid/Markdown/animation/runbook | Read `references/toolbox.md`; `diagramctl.py transform` exposes the existing tools |+| Pipeline, journey, or subsystem map drawn as a metro/subway map | Use `tubemap.py`; read `references/tubemap.md` |+| Shape, cloud/vendor, AI, or Databricks icon | Read `references/shapes.md` or `references/databricks.md`; never guess shape names |+| Learn/apply/manage a visual style | Read `references/style-presets.md` |+| Extract a reusable style from an existing diagram or theme | Read `references/style-extraction.md` |+| Existing image to editable diagram (screenshot, whiteboard photo, legacy PNG) | Read `references/derasterize.md` |+| Export/platform problem | Read `references/troubleshooting.md`; for access/network questions read `references/security.md` |++## Unified CLI++Run from this skill directory, or replace `scripts/` with the absolute path to+this skill's scripts directory:++```bash+python3 scripts/diagramctl.py doctor+python3 scripts/diagramctl.py build model.json --from ir -o architecture.drawio+python3 scripts/diagramctl.py build ./infra --from terraform --group \+ --ir-output architecture.ir.json -o architecture.drawio+python3 scripts/diagramctl.py sync architecture.drawio ./infra --from terraform \+ -o architecture.next.drawio+python3 scripts/diagramctl.py views architecture.ir.json \+ --views executive,system,deployment,dataflow,security -o views.drawio+python3 scripts/diagramctl.py test architecture.drawio --rules policy.yml+python3 scripts/diagramctl.py review architecture.drawio -o review.md+python3 scripts/diagramctl.py query architecture.drawio --from internet --to orders-db+python3 scripts/diagramctl.py whatif architecture.ir.json --fail kafka \+ --drawio kafka-failure.drawio -o impact.json+python3 scripts/diagramctl.py story architecture.ir.json -o walkthrough.html+```++`doctor` does not launch GUI tools unless `--probe` is passed. Core semantic+commands are offline and stdlib-only.++## Creation workflow++1. Infer the diagram type, audience, scope, output format, and location from the+ request. Ask only when a missing choice materially changes the result;+ default to PNG plus `.drawio` in the working directory.+2. Select the authoring route from the table above. For a data-backed diagram,+ prefer Diagram IR and preserve provenance. For a large graph, use an importer+ or `autolayout.py`; do not hand-place more than roughly fifteen nodes.+3. Resolve an explicitly named style preset, or the user's default preset, as+ documented in `references/style-presets.md`. Structural diagram conventions+ and visual presets compose; they do not replace each other.+4. Generate the `.drawio`, then run structural validation:++ ```bash+ python3 scripts/validate.py diagram.drawio --score+ ```++ When semantic metadata or an architecture policy is in scope, also run+ `diagramctl.py test`. Do not present inferred semantic findings as verified+ runtime facts.+5. Export a draft PNG without embedded XML and inspect it visually. Fix obvious+ overlap, clipping, disconnected edges, edge-through-node routing, stacked+ edges, and unreadable labels. Stop automatic vision repair after two rounds.+ When the drawio binary is unavailable or a visual check is inconclusive,+ verify the renderer's own DOM instead (`--dump-dom` on the viewer URL, see+ `references/troubleshooting.md`): read each edge's `<path>` segments and+ label anchor coordinates directly — vision alone both misses geometry+ defects and hallucinates new ones.+6. Show the draft and apply targeted edits. Preserve existing geometry for+ local changes. Use `sync` for source-backed changes and write a reviewable+ output; use `--prune` only when deletion was requested.+7. After approval, create final requested formats and report both editable+ source and export paths.++## Export invariants++Resolve the available binary once (`drawio`, `draw.io`, the macOS app path, or+the Windows executable) and use that exact binary for the run.++```bash+# Draft for visual inspection: never use -e here+drawio -x -f png --width 2000 -o diagram.png diagram.drawio++# Final editable PNG+drawio -x -f png -e -s 2 -o diagram.drawio.png diagram.drawio+python3 scripts/repair_png.py diagram.drawio.png++# Final editable SVG/PDF+drawio -x -f svg -e --embed-svg-images -o diagram.svg diagram.drawio+drawio -x -f pdf -e -o diagram.pdf diagram.drawio+```++Do not combine `--width` and `-s`. Embedded PNG exports require+`repair_png.py`; draft PNGs used by vision must not use `-e`. On Linux headless,+follow `references/troubleshooting.md` rather than improvising Electron flags.+If the CLI crashes in a macOS sandbox, try one permitted escalated run, then use+`encode_drawio_url.py` or deliver XML; do not repeatedly launch it.++## Editing and identity++- Use stable semantic IDs and never reuse reserved IDs `0` or `1`.+- Every edge requires `<mxGeometry relative="1" as="geometry"/>`.+- For a local edit, change the matching cell only; for a global direction+ change, regenerate/re-layout the page.+- Keep provenance, `data-model-id`, semantic properties, manual geometry, and+ manual styles intact unless the user requests otherwise.+- When reconciling, retain removals as reviewable faded elements by default.+- For edges stacked at a boundary, run `edgeports.py`; add waypoints when an+ edge still crosses an unrelated shape. There is no CLI-only edge rerouter+ that preserves node positions.++## Quality and trust++An attractive diagram can still be wrong. Prefer source-backed relationships,+show provenance where useful, distinguish exact extraction from AI inference,+and keep architecture review findings framed as prompts. Story HTML must remain+self-contained, keyboard usable, and include a text alternative. Never include+secrets in node properties or provenance because they are embedded in outputs.++For all focused scripts and composition patterns, read `references/toolbox.md`;+load only the task-specific reference needed for the current request.diff --git a/skills/drawio-skill/references/troubleshooting.md b/skills/drawio-skill/references/troubleshooting.mdindex 572a5fa..d166388 100644--- a/skills/drawio-skill/references/troubleshooting.md+++ b/skills/drawio-skill/references/troubleshooting.md@@ -1,92 +1,92 @@-# Troubleshooting — Common Mistakes--Read this when something looks wrong in the output (rendering, export, layout, edges) or when a CLI invocation fails. Most rows have a one-line fix.--| Mistake | Fix |-|---------|-----|-| Missing `id="0"` and `id="1"` root cells | Always include both at the top of `<root>` |-| Shapes not connected | `source` and `target` on edge must match existing shape `id` values |-| Self-closing edge `mxCell` (`<mxCell ... edge="1" />`) | Use the expanded form with `<mxGeometry relative="1" as="geometry" />` child — self-closing edges won't render |-| `--` inside XML comments | Illegal per XML spec — use single hyphens or rephrase |-| Special characters in `value` | Use XML entities: `&` `<` `>` `"` |-| Literal `\n` in label text | Use `
` for line breaks in `value` attributes |-| Overlapping shapes | Scale spacing with complexity (200–350px); leave routing corridors |-| Edges crossing through shapes | Add waypoints, distribute entry/exit points, or increase spacing |-| Arrowhead overlaps bend | Final edge segment before target must be ≥20px — increase spacing or add waypoints |-| Iteration loop never ends | After 5 rounds, suggest user open .drawio in draw.io desktop for fine-tuning |-| `command not found: draw.io` after `brew install --cask drawio` | Homebrew installs the binary as `drawio` (no dot). Use `drawio --version`, not `draw.io --version`. The dot-name only exists inside the `.app` bundle (`/Applications/draw.io.app/Contents/MacOS/draw.io`) and on Windows (`draw.io.exe`). |-| Export command not found on macOS | Try full path `/Applications/draw.io.app/Contents/MacOS/draw.io` |-| Vision returns "Unable to resize image — dimensions exceed the 2576x2576px limit" | The preview PNG is too large for Claude's vision API. Re-export with `--width 2000` instead of `-s 2` (the flag is `--width`; there is no short `-w` — passing `-w 2000` silently breaks input-file parsing and drawio errors with "input file/directory not found"). For very tall-narrow diagrams that still overshoot, use `--height 2000` instead. |-| Linux: blank/error output headlessly | Prefix command with `xvfb-run -a` |-| Linux: `--no-sandbox` placed before input file (parsed as filename) | Move `--no-sandbox` to the very end of the command (drawio-desktop#249, #1056) |-| Linux: `Failed to get 'appData' path` / `Home directory not accessible` | `export HOME=/tmp` before invoking drawio (drawio-desktop#127) |-| Linux server: segfault / EGL / MESA `failed to load driver` errors | Add `--disable-gpu` (suppresses Chromium GL init when no GPU available) |-| PDF export fails | Ensure Chromium is available (draw.io bundles it on desktop) |-| Background color wrong in CLI export | Known CLI bug; add `--transparent` flag or set background via style |-| Vision returns 400 "Could not process image" on draft PNG | Re-export the preview without `-e` (issue #8). Root cause is a truncated IEND chunk in `-e` PNGs, not the `zTXt` chunk itself — but skipping `-e` for the preview is the simplest fix. |-| Final `-e` PNG won't open in image viewers / vision APIs | Run `python3 <this-skill-dir>/scripts/repair_png.py <path>`. draw.io CLI emits `-e` PNGs with an 8-byte truncation at IEND. SVG/PDF unaffected. |-| WSL2: `drawio` / `draw.io` not found | The CLI lives on the Windows side. Use the Windows desktop exe via `/mnt/c`: `"/mnt/c/Program Files/draw.io/draw.io.exe"` (or per-user `"/mnt/c/Users/<you>/AppData/Local/Programs/draw.io/draw.io.exe"`). |-| WSL2: opening an exported file fails with a `/mnt/c/...`-style path | `cmd.exe` can't resolve WSL paths — convert first: `cmd.exe /c start "" "$(wslpath -w diagram.drawio.png)"`. The empty `""` after `start` is the (required) window title. |-| Browser URL opens to a blank/empty diagram (Windows/WSL2) | `cmd.exe`'s `start` treats `&` as a separator and drops everything after `#` — so the `#R…`/`#create=…` fragment (the whole diagram) is lost. Never pass the URL straight to `start`. Write a `.url` shortcut file and open *that* (see "WSL2 / Windows" below). |-| `viewer.diagrams.net` intermittently drops connections (`ERR_CONNECTION_CLOSED`) during headless draft rendering | Retry in a loop with a fresh `--user-data-dir` per attempt, and gate each screenshot on a palette check: count pixels of a known fill color (e.g. the blue `#dae8fc`) and require thousands — an error page also "has colors", so a naive size/variance check passes it. |-| Vision review approves a broken render (or hallucinates routing such as "the arrow wraps around the box") | Never let vision be the only gate for edge geometry. Verify the DOM: `--dump-dom` on the viewer URL, then parse `<path d="…">` per edge (straight? single intended segments? tip before the target border?) and `foreignObject` `padding-top/margin-left` for label anchors — see "Verifying the rendered output" below. |--## WSL2 / Windows specifics--**Locate the CLI.** Detect WSL2 with `grep -qi microsoft /proc/version`. On WSL2 the-export CLI is the Windows desktop exe, reached through `/mnt/c` (quote the path —-it contains a space):--```bash-"/mnt/c/Program Files/draw.io/draw.io.exe" --version-# per-user install fallback:-"/mnt/c/Users/$USER/AppData/Local/Programs/draw.io/draw.io.exe" --version-```--**Open a file.** Convert the WSL path to a Windows path first; `cmd.exe` cannot-follow `/mnt/c/...`:--```bash-cmd.exe /c start "" "$(wslpath -w diagram.drawio.png)"-```--**Open a browser-fallback URL.** `cmd.exe /c start` strips the URL fragment-(`&` ends the command, `#…` is dropped) — and the fragment carries the entire-diagram. Write a `.url` shortcut and open it instead, so the URL survives intact:--```bash-URL=$(python3 <this-skill-dir>/scripts/encode_drawio_url.py --edit diagram.drawio)-TMP=$(mktemp --suffix=.url)-printf '[InternetShortcut]\r\nURL=%s\r\n' "$URL" > "$TMP"-cmd.exe /c start "" "$(wslpath -w "$TMP")"-```--On native Windows the same `.url`-file trick applies (`start "" "%TEMP%\d.url"`).-On macOS/Linux just `open "$URL"` / `xdg-open "$URL"` — no workaround needed.--## Verifying the rendered output (viewer.diagrams.net)--When the drawio binary is unavailable (or the render pipeline is flaky), verify-geometry from the viewer's own output instead of eyeballing a screenshot:--```bash-URL=$(python3 <this-skill-dir>/scripts/encode_drawio_url.py diagram.drawio)-msedge --headless=new --disable-gpu --user-data-dir="$(mktemp -d)" \- --virtual-time-budget=25000 --dump-dom "$URL" > dom.html-# any recent Chromium works: `msedge` / `chromium` / `google-chrome`,-# or the macOS app binary-```--Then check with a script, not by eye:--- **Edge paths**: every stroke `<path d="M …">` should contain only the segments- you intended. A segment crossing a shape it does not terminate at, an- unexpected `Q` pair mid-segment (the 1–2 px S-wiggle from a misaligned- `entryX`), or an arrow tip past the target border are XML defects — fix the- file, don't re-route by hand.-- **Label anchors**: label `foreignObject`s expose `padding-top: <y>px;- margin-left: <x>px`; assert each label box lands in empty space (no edge- segment, no shape boundary, no second label).-- **Screenshot gating**: when a PNG is required, retry `ERR_CONNECTION_CLOSED`- with a fresh `--user-data-dir` and accept the file only after counting pixels- of a known palette fill — error pages pass naive "has content" checks.+# Troubleshooting — Common Mistakes++Read this when something looks wrong in the output (rendering, export, layout, edges) or when a CLI invocation fails. Most rows have a one-line fix.++| Mistake | Fix |+|---------|-----|+| Missing `id="0"` and `id="1"` root cells | Always include both at the top of `<root>` |+| Shapes not connected | `source` and `target` on edge must match existing shape `id` values |+| Self-closing edge `mxCell` (`<mxCell ... edge="1" />`) | Use the expanded form with `<mxGeometry relative="1" as="geometry" />` child — self-closing edges won't render |+| `--` inside XML comments | Illegal per XML spec — use single hyphens or rephrase |+| Special characters in `value` | Use XML entities: `&` `<` `>` `"` |+| Literal `\n` in label text | Use `
` for line breaks in `value` attributes |+| Overlapping shapes | Scale spacing with complexity (200–350px); leave routing corridors |+| Edges crossing through shapes | Add waypoints, distribute entry/exit points, or increase spacing |+| Arrowhead overlaps bend | Final edge segment before target must be ≥20px — increase spacing or add waypoints |+| Iteration loop never ends | After 5 rounds, suggest user open .drawio in draw.io desktop for fine-tuning |+| `command not found: draw.io` after `brew install --cask drawio` | Homebrew installs the binary as `drawio` (no dot). Use `drawio --version`, not `draw.io --version`. The dot-name only exists inside the `.app` bundle (`/Applications/draw.io.app/Contents/MacOS/draw.io`) and on Windows (`draw.io.exe`). |+| Export command not found on macOS | Try full path `/Applications/draw.io.app/Contents/MacOS/draw.io` |+| Vision returns "Unable to resize image — dimensions exceed the 2576x2576px limit" | The preview PNG is too large for Claude's vision API. Re-export with `--width 2000` instead of `-s 2` (the flag is `--width`; there is no short `-w` — passing `-w 2000` silently breaks input-file parsing and drawio errors with "input file/directory not found"). For very tall-narrow diagrams that still overshoot, use `--height 2000` instead. |+| Linux: blank/error output headlessly | Prefix command with `xvfb-run -a` |+| Linux: `--no-sandbox` placed before input file (parsed as filename) | Move `--no-sandbox` to the very end of the command (drawio-desktop#249, #1056) |+| Linux: `Failed to get 'appData' path` / `Home directory not accessible` | `export HOME=/tmp` before invoking drawio (drawio-desktop#127) |+| Linux server: segfault / EGL / MESA `failed to load driver` errors | Add `--disable-gpu` (suppresses Chromium GL init when no GPU available) |+| PDF export fails | Ensure Chromium is available (draw.io bundles it on desktop) |+| Background color wrong in CLI export | Known CLI bug; add `--transparent` flag or set background via style |+| Vision returns 400 "Could not process image" on draft PNG | Re-export the preview without `-e` (issue #8). Root cause is a truncated IEND chunk in `-e` PNGs, not the `zTXt` chunk itself — but skipping `-e` for the preview is the simplest fix. |+| Final `-e` PNG won't open in image viewers / vision APIs | Run `python3 <this-skill-dir>/scripts/repair_png.py <path>`. draw.io CLI emits `-e` PNGs with an 8-byte truncation at IEND. SVG/PDF unaffected. |+| WSL2: `drawio` / `draw.io` not found | The CLI lives on the Windows side. Use the Windows desktop exe via `/mnt/c`: `"/mnt/c/Program Files/draw.io/draw.io.exe"` (or per-user `"/mnt/c/Users/<you>/AppData/Local/Programs/draw.io/draw.io.exe"`). |+| WSL2: opening an exported file fails with a `/mnt/c/...`-style path | `cmd.exe` can't resolve WSL paths — convert first: `cmd.exe /c start "" "$(wslpath -w diagram.drawio.png)"`. The empty `""` after `start` is the (required) window title. |+| Browser URL opens to a blank/empty diagram (Windows/WSL2) | `cmd.exe`'s `start` treats `&` as a separator and drops everything after `#` — so the `#R…`/`#create=…` fragment (the whole diagram) is lost. Never pass the URL straight to `start`. Write a `.url` shortcut file and open *that* (see "WSL2 / Windows" below). |+| `viewer.diagrams.net` intermittently drops connections (`ERR_CONNECTION_CLOSED`) during headless draft rendering | Retry in a loop with a fresh `--user-data-dir` per attempt, and gate each screenshot on a palette check: count pixels of a known fill color (e.g. the blue `#dae8fc`) and require thousands — an error page also "has colors", so a naive size/variance check passes it. |+| Vision review approves a broken render (or hallucinates routing such as "the arrow wraps around the box") | Never let vision be the only gate for edge geometry. Verify the DOM: `--dump-dom` on the viewer URL, then parse `<path d="…">` per edge (straight? single intended segments? tip before the target border?) and `foreignObject` `padding-top/margin-left` for label anchors — see "Verifying the rendered output" below. |++## WSL2 / Windows specifics++**Locate the CLI.** Detect WSL2 with `grep -qi microsoft /proc/version`. On WSL2 the+export CLI is the Windows desktop exe, reached through `/mnt/c` (quote the path —+it contains a space):++```bash+"/mnt/c/Program Files/draw.io/draw.io.exe" --version+# per-user install fallback:+"/mnt/c/Users/$USER/AppData/Local/Programs/draw.io/draw.io.exe" --version+```++**Open a file.** Convert the WSL path to a Windows path first; `cmd.exe` cannot+follow `/mnt/c/...`:++```bash+cmd.exe /c start "" "$(wslpath -w diagram.drawio.png)"+```++**Open a browser-fallback URL.** `cmd.exe /c start` strips the URL fragment+(`&` ends the command, `#…` is dropped) — and the fragment carries the entire+diagram. Write a `.url` shortcut and open it instead, so the URL survives intact:++```bash+URL=$(python3 <this-skill-dir>/scripts/encode_drawio_url.py --edit diagram.drawio)+TMP=$(mktemp --suffix=.url)+printf '[InternetShortcut]\r\nURL=%s\r\n' "$URL" > "$TMP"+cmd.exe /c start "" "$(wslpath -w "$TMP")"+```++On native Windows the same `.url`-file trick applies (`start "" "%TEMP%\d.url"`).+On macOS/Linux just `open "$URL"` / `xdg-open "$URL"` — no workaround needed.++## Verifying the rendered output (viewer.diagrams.net)++When the drawio binary is unavailable (or the render pipeline is flaky), verify+geometry from the viewer's own output instead of eyeballing a screenshot:++```bash+URL=$(python3 <this-skill-dir>/scripts/encode_drawio_url.py diagram.drawio)+msedge --headless=new --disable-gpu --user-data-dir="$(mktemp -d)" \+ --virtual-time-budget=25000 --dump-dom "$URL" > dom.html+# any recent Chromium works: `msedge` / `chromium` / `google-chrome`,+# or the macOS app binary+```++Then check with a script, not by eye:++- **Edge paths**: every stroke `<path d="M …">` should contain only the segments+ you intended. A segment crossing a shape it does not terminate at, an+ unexpected `Q` pair mid-segment (the 1–2 px S-wiggle from a misaligned+ `entryX`), or an arrow tip past the target border are XML defects — fix the+ file, don't re-route by hand.+- **Label anchors**: label `foreignObject`s expose `padding-top: <y>px;+ margin-left: <x>px`; assert each label box lands in empty space (no edge+ segment, no shape boundary, no second label).+- **Screenshot gating**: when a PNG is required, retry `ERR_CONNECTION_CLOSED`+ with a fresh `--user-data-dir` and accept the file only after counting pixels+ of a known palette fill — error pages pass naive "has content" checks.diff --git a/skills/drawio-skill/references/xml-authoring.md b/skills/drawio-skill/references/xml-authoring.mdindex 3071c87..07aa238 100644--- a/skills/drawio-skill/references/xml-authoring.md+++ b/skills/drawio-skill/references/xml-authoring.md@@ -1,220 +1,220 @@-# Authoring .drawio XML--Read this **before hand-writing any `.drawio` XML** (workflow step 3). Skip it when a bundled generator writes the XML for you (`autolayout.py` + importers, `seqlayout.py`).--### File skeleton--```xml-<?xml version="1.0" encoding="UTF-8"?>-<mxfile host="drawio" version="26.0.0">- <diagram name="Page-1">- <mxGraphModel>- <root>- <mxCell id="0" />- <mxCell id="1" parent="0" />- <!-- user shapes start at id="2" -->- </root>- </mxGraphModel>- </diagram>-</mxfile>-```--**Rules:**--- `id="0"` and `id="1"` are required root cells — never omit them-- User shapes start at `id="2"` and increment sequentially-- All shapes have `parent="1"` (unless inside a container — then use container's id)-- All text uses `html=1` in style for proper rendering-- **Never use `--` inside XML comments** — it's illegal per XML spec and causes parse errors-- Escape special characters in attribute values: `&`, `<`, `>`, `"`-- **Multi-line text in labels:** use `
` for line breaks inside `value` attributes (not literal `\n`). Example: `value="Line 1
Line 2"`--### Shape types (vertex)--| Style keyword | Use for |-| -------------- | --------- |-| `rounded=0` | plain rectangle (default) |-| `rounded=1` | rounded rectangle — services, modules |-| `ellipse;` | circles/ovals — start/end, databases |-| `rhombus;` | diamond — decision points |-| `shape=mxgraph.aws4.resourceIcon;` | AWS icons |-| `shape=cylinder3;` | cylinder — databases |-| `swimlane;` | group/container with title bar |--For **vendor/branded icons** (AWS/Azure/GCP/Cisco/Kubernetes) and any non-trivial shape, don't guess the `shape=mxgraph.*` name — a wrong name renders as a blank box. Run `python3 <this-skill-dir>/scripts/shapesearch.py "<keywords>"` to get the exact official style + size, or see `references/shapes.md` for the hand-writable cheatsheet. For **AI/LLM brand logos** (OpenAI, Claude, Gemini, …), which draw.io has none of, use `python3 <this-skill-dir>/scripts/aiicons.py "<brand>"`.--### Required properties--```xml-<!-- Rectangle / rounded box -->-<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">- <mxGeometry x="100" y="100" width="160" height="60" as="geometry" />-</mxCell>--<!-- Cylinder (database) -->-<mxCell id="3" value="DB" style="shape=cylinder3;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;" vertex="1" parent="1">- <mxGeometry x="350" y="100" width="120" height="80" as="geometry" />-</mxCell>--<!-- Diamond (decision) -->-<mxCell id="4" value="Check?" style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">- <mxGeometry x="100" y="220" width="160" height="80" as="geometry" />-</mxCell>-```--### Containers and groups--For architecture diagrams with nested elements, use draw.io's parent-child containment — do **not** just place shapes on top of larger shapes.--| Type | Style | When to use |-| ------ | ------- | ------------- |-| **Group** (invisible) | `group;pointerEvents=0;` | No visual border needed, container has no connections |-| **Swimlane** (titled) | `swimlane;startSize=30;` | Container needs a visible title bar, or container itself has connections |-| **Custom container** | Add `container=1;pointerEvents=0;` to any shape | Any shape acting as a container without its own connections |--**Key rules:**--- Add `pointerEvents=0;` to container styles that should not capture connections between children-- Children set `parent="containerId"` and use coordinates **relative to the container**--```xml-<!-- Swimlane container -->-<mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">- <mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>-</mxCell>-<!-- Child inside container — coordinates relative to parent -->-<mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">- <mxGeometry x="20" y="40" width="120" height="60" as="geometry"/>-</mxCell>-<mxCell id="db1" value="Database" style="shape=cylinder3;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">- <mxGeometry x="160" y="40" width="120" height="60" as="geometry"/>-</mxCell>-```--### Connector (edge)--**CRITICAL:** Every edge `mxCell` must contain a `<mxGeometry relative="1" as="geometry" />` child element. Self-closing edge cells (`<mxCell ... edge="1" ... />`) are **invalid** and will not render. Always use the expanded form.--```xml-<!-- Directed arrow — always include rounded, orthogonalLoop, jettySize for clean routing -->-<mxCell id="10" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="2" target="3">- <mxGeometry relative="1" as="geometry" />-</mxCell>--<!-- Arrow with label + explicit entry/exit points to control direction -->-<mxCell id="11" value="HTTP/REST" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="2" target="4">- <mxGeometry relative="1" as="geometry" />-</mxCell>--<!-- Arrow with waypoints — use when edge must route around other shapes -->-<mxCell id="12" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="3" target="5">- <mxGeometry relative="1" as="geometry">- <Array as="points">- <mxPoint x="500" y="50" />- </Array>- </mxGeometry>-</mxCell>-```--**Edge style rules:**--- **Animated connectors:** add `flowAnimation=1;` to any edge style to show a moving dot animation along the arrow. Works in SVG export and draw.io desktop — ideal for data-flow and pipeline diagrams. Example: `style="edgeStyle=orthogonalEdgeStyle;flowAnimation=1;rounded=1;..."`-- **Always** include `rounded=1;orthogonalLoop=1;jettySize=auto` — these enable smart routing that avoids overlaps-- Pin `exitX/exitY/entryX/entryY` on every edge when a node has 2+ connections — distributes lines across the shape perimeter. `scripts/edgeports.py <file>` does this for a whole diagram: it picks the side facing each peer and spreads that side's edges over even slots ordered by the far endpoint, so they don't stack or cross at the boundary. It skips ends you pinned by hand and is idempotent-- Add `<Array as="points">` waypoints when an edge must detour around an intermediate shape-- **Leave room for arrowheads:** the final straight segment between the last bend and the target shape must be ≥20px long. If too short, the arrowhead overlaps the bend and looks broken. Fix by increasing node spacing or adding explicit waypoints-- **libavoid obstacle-avoiding routing (editor-side, draw.io ≥ 30):** draw.io has a newer connector router that recomputes edge paths to run *around* shapes (fanning out parallel edges) without moving any node. It runs interactively in the draw.io desktop editor (or via jgraph's MCP app-server `routing:"libavoid"`) — it is **not** a headless CLI flag. Passing `--layout libavoid` opens a modal `Unknown layout:` error dialog and hangs the run (jgraph's own drawio-mcp plugin docs claim the CLI flag works — verified hang on 30.2.6, don't trust it); the CLI `--layout` values are ELK *node* layout presets, a different thing (see `mermaid-authoring.md`). For CLI-authored files keep the orthogonal rules above; if a dense diagram still has crossings after export, open the `.drawio` in draw.io desktop once and let libavoid re-route. Don't stack it on an ELK `--layout` pass — pick one router, not both.--### Distributing connections on a shape--When multiple edges connect to the same shape, assign different entry/exit points to prevent stacking:--| Position | exitX/entryX | exitY/entryY | Use when |-| ---------- | ------------- | ------------- | ---------- |-| Top center | 0.5 | 0 | connecting to node above |-| Top-left | 0.25 | 0 | 2nd connection from top |-| Top-right | 0.75 | 0 | 3rd connection from top |-| Right center | 1 | 0.5 | connecting to node on right |-| Bottom center | 0.5 | 1 | connecting to node below |-| Left center | 0 | 0.5 | connecting to node on left |--**Rule:** if a shape has N connections on one side, space them evenly (e.g., 3 connections on bottom → exitX = 0.25, 0.5, 0.75)--### Color palette (fillColor / strokeColor)--*Used only when no user style preset is active (see `references/style-presets.md` → "Applying a preset").*--| Color name | fillColor | strokeColor | Use for |-| ----------- | ----------- | ------------- | --------- |-| Blue | `#dae8fc` | `#6c8ebf` | services, clients |-| Green | `#d5e8d4` | `#82b366` | success, databases |-| Yellow | `#fff2cc` | `#d6b656` | queues, decisions |-| Orange | `#ffe6cc` | `#d79b00` | gateways, APIs |-| Red/Pink | `#f8cecc` | `#b85450` | errors, alerts |-| Grey | `#f5f5f5` | `#666666` | external/neutral |-| Purple | `#e1d5e7` | `#9673a6` | security, auth |--### Legend (auto-generate from the palette)--When a diagram uses 3+ semantic colors, add a legend so the color coding is self-explanatory. Generate it mechanically from the roles actually present — never invent legend entries that aren't in the diagram:--```xml-<!-- Legend container: place in a corner clear of the diagram (e.g. below-left) -->-<mxCell id="legend" value="Legend" style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#666666;verticalAlign=top;fontStyle=1;" vertex="1" parent="1">- <mxGeometry x="40" y="720" width="180" height="110" as="geometry"/>-</mxCell>-<!-- One swatch + label pair per used role, 24px row pitch, children of the legend -->-<mxCell id="leg1" value="" style="rounded=0;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="legend">- <mxGeometry x="10" y="30" width="30" height="16" as="geometry"/>-</mxCell>-<mxCell id="leg1t" value="Service" style="text;html=1;align=left;verticalAlign=middle;" vertex="1" parent="legend">- <mxGeometry x="50" y="28" width="120" height="20" as="geometry"/>-</mxCell>-```--Rules: swatch colors come from the active palette (preset or the table above) with the **role name** as the label (Service, Database, Queue, …); height = `30 + 24 × rows`; the legend is a container (`parent="legend"`, relative coordinates); skip it entirely for single-color diagrams.--### Layout tips--**Spacing — scale with complexity:**--| Diagram complexity | Nodes | Horizontal gap | Vertical gap |-| ------------------- | ------- | ---------------- | -------------- |-| Simple | ≤5 | 200px | 150px |-| Medium | 6–10 | 280px | 200px |-| Complex | >10 | 350px | 250px |--**Routing corridors:** between shape rows/columns, leave an extra ~80px empty corridor where edges can route without crossing shapes. Never place a shape in a gap that edges need to traverse.--**Grid alignment:** snap all `x`, `y`, `width`, `height` values to **multiples of 10** — this ensures shapes align cleanly on draw.io's default grid and makes manual editing easier.--**General rules:**--- Plan a grid before assigning x/y coordinates — sketch node positions on paper/mentally first-- Group related nodes in the same horizontal or vertical band-- Use `swimlane` cells for logical grouping with visible borders-- Place heavily-connected "hub" nodes centrally so edges radiate outward instead of crossing-- To force straight vertical connections, pin entry/exit points explicitly on edges:- `exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0`-- Always center-align a child node under its parent (same center x) to avoid diagonal routing-- **Event bus pattern**: place Kafka/bus nodes in the **center of the service row**, not below — services on either side can reach it with short horizontal arrows (`exitX=1` left side, `exitX=0` right side), eliminating all line crossings-- Horizontal connections (`exitX=1` or `exitX=0`) never cross vertical nodes in the same row; use them for peer-to-peer and publish connections--**Avoiding edge-shape overlap:**--- Before finalizing coordinates, trace each edge path mentally — if it must cross an unrelated shape, either move the shape or add waypoints-- For tree/hierarchical layouts: assign nodes to layers (rows), connect only between adjacent layers to minimize crossings-- For star/hub layouts: place the hub center, satellites around it — edges stay short and radial-- When an edge must span multiple rows/columns, route it along the outer corridor, not through the middle of the diagram--### Decision-diamond branches, pixel-exact pins, and labels--Pitfalls verified from rendered output. `validate.py` does not catch any of them, and vision review both misses them and hallucinates new ones (it once described a clean diamond exit as "wrapping around the box" and approved a screenshot that was actually the browser error page).--| Pitfall | Rule |-| ------- | ---- |-| Edge exits a rhombus **vertex** with its first segment heading *inward* — e.g. out of the left vertex going right — so the elbow's horizontal run crosses the diamond's own interior | Vertex exits must head outward (left vertex → left, right → right, top → up, bottom → down). When both branch targets sit *below* the decision (left and right), skip the elbow entirely: draw one straight line per branch with `edgeStyle=none` from the lower-left / lower-right **edge midpoint** (`exitX=0.25;exitY=0.75` / `exitX=0.75;exitY=0.75` — both points lie on the rhombus outline) to each target's top center. Symmetric, no right angle, nothing to cross. |-| Vertical edge whose `entryX` is 1–2 px off the source's exit x (easy to hit when boxes snap to a 10 px grid) | Compute the pin with full precision: `entryX = (sourceCenterX − target.x) / target.width`, e.g. `0.0652`, `0.2027`. Style values accept more than two decimals. A 1–2 px mismatch renders as an S-shaped double curve (two `Q` bends) just before the arrowhead. |-| `blockThin` arrowheads (~5×7 px) flush against the target border | Reviewers read the tip as "piercing the box". Use `endArrow=block;endSize=8` for main flow edges. |-| Long labels auto-centered on their own edge | The white label chip visually severs the edge, and near a corner it can cut both segments. Keep only micro-labels (`Yes` / `No`) on the line; offset longer labels (`<mxPoint as="offset" x="…" y="…"/>`) into verified empty space, and shorten any label wider than the corridor it annotates. |-| Trusting "it looks fine" | Confirm with renderer ground truth: render the viewer URL and `--dump-dom`, then read `<path d="…">` segments and label `foreignObject` `padding-top/margin-left` anchors (see `references/troubleshooting.md` → "Verifying the rendered output"). |+# Authoring .drawio XML++Read this **before hand-writing any `.drawio` XML** (workflow step 3). Skip it when a bundled generator writes the XML for you (`autolayout.py` + importers, `seqlayout.py`).++### File skeleton++```xml+<?xml version="1.0" encoding="UTF-8"?>+<mxfile host="drawio" version="26.0.0">+ <diagram name="Page-1">+ <mxGraphModel>+ <root>+ <mxCell id="0" />+ <mxCell id="1" parent="0" />+ <!-- user shapes start at id="2" -->+ </root>+ </mxGraphModel>+ </diagram>+</mxfile>+```++**Rules:**++- `id="0"` and `id="1"` are required root cells — never omit them+- User shapes start at `id="2"` and increment sequentially+- All shapes have `parent="1"` (unless inside a container — then use container's id)+- All text uses `html=1` in style for proper rendering+- **Never use `--` inside XML comments** — it's illegal per XML spec and causes parse errors+- Escape special characters in attribute values: `&`, `<`, `>`, `"`+- **Multi-line text in labels:** use `
` for line breaks inside `value` attributes (not literal `\n`). Example: `value="Line 1
Line 2"`++### Shape types (vertex)++| Style keyword | Use for |+| -------------- | --------- |+| `rounded=0` | plain rectangle (default) |+| `rounded=1` | rounded rectangle — services, modules |+| `ellipse;` | circles/ovals — start/end, databases |+| `rhombus;` | diamond — decision points |+| `shape=mxgraph.aws4.resourceIcon;` | AWS icons |+| `shape=cylinder3;` | cylinder — databases |+| `swimlane;` | group/container with title bar |++For **vendor/branded icons** (AWS/Azure/GCP/Cisco/Kubernetes) and any non-trivial shape, don't guess the `shape=mxgraph.*` name — a wrong name renders as a blank box. Run `python3 <this-skill-dir>/scripts/shapesearch.py "<keywords>"` to get the exact official style + size, or see `references/shapes.md` for the hand-writable cheatsheet. For **AI/LLM brand logos** (OpenAI, Claude, Gemini, …), which draw.io has none of, use `python3 <this-skill-dir>/scripts/aiicons.py "<brand>"`.++### Required properties++```xml+<!-- Rectangle / rounded box -->+<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">+ <mxGeometry x="100" y="100" width="160" height="60" as="geometry" />+</mxCell>++<!-- Cylinder (database) -->+<mxCell id="3" value="DB" style="shape=cylinder3;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;" vertex="1" parent="1">+ <mxGeometry x="350" y="100" width="120" height="80" as="geometry" />+</mxCell>++<!-- Diamond (decision) -->+<mxCell id="4" value="Check?" style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">+ <mxGeometry x="100" y="220" width="160" height="80" as="geometry" />+</mxCell>+```++### Containers and groups++For architecture diagrams with nested elements, use draw.io's parent-child containment — do **not** just place shapes on top of larger shapes.++| Type | Style | When to use |+| ------ | ------- | ------------- |+| **Group** (invisible) | `group;pointerEvents=0;` | No visual border needed, container has no connections |+| **Swimlane** (titled) | `swimlane;startSize=30;` | Container needs a visible title bar, or container itself has connections |+| **Custom container** | Add `container=1;pointerEvents=0;` to any shape | Any shape acting as a container without its own connections |++**Key rules:**++- Add `pointerEvents=0;` to container styles that should not capture connections between children+- Children set `parent="containerId"` and use coordinates **relative to the container**++```xml+<!-- Swimlane container -->+<mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">+ <mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>+</mxCell>+<!-- Child inside container — coordinates relative to parent -->+<mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">+ <mxGeometry x="20" y="40" width="120" height="60" as="geometry"/>+</mxCell>+<mxCell id="db1" value="Database" style="shape=cylinder3;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">+ <mxGeometry x="160" y="40" width="120" height="60" as="geometry"/>+</mxCell>+```++### Connector (edge)++**CRITICAL:** Every edge `mxCell` must contain a `<mxGeometry relative="1" as="geometry" />` child element. Self-closing edge cells (`<mxCell ... edge="1" ... />`) are **invalid** and will not render. Always use the expanded form.++```xml+<!-- Directed arrow — always include rounded, orthogonalLoop, jettySize for clean routing -->+<mxCell id="10" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="2" target="3">+ <mxGeometry relative="1" as="geometry" />+</mxCell>++<!-- Arrow with label + explicit entry/exit points to control direction -->+<mxCell id="11" value="HTTP/REST" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="2" target="4">+ <mxGeometry relative="1" as="geometry" />+</mxCell>++<!-- Arrow with waypoints — use when edge must route around other shapes -->+<mxCell id="12" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="3" target="5">+ <mxGeometry relative="1" as="geometry">+ <Array as="points">+ <mxPoint x="500" y="50" />+ </Array>+ </mxGeometry>+</mxCell>+```++**Edge style rules:**++- **Animated connectors:** add `flowAnimation=1;` to any edge style to show a moving dot animation along the arrow. Works in SVG export and draw.io desktop — ideal for data-flow and pipeline diagrams. Example: `style="edgeStyle=orthogonalEdgeStyle;flowAnimation=1;rounded=1;..."`+- **Always** include `rounded=1;orthogonalLoop=1;jettySize=auto` — these enable smart routing that avoids overlaps+- Pin `exitX/exitY/entryX/entryY` on every edge when a node has 2+ connections — distributes lines across the shape perimeter. `scripts/edgeports.py <file>` does this for a whole diagram: it picks the side facing each peer and spreads that side's edges over even slots ordered by the far endpoint, so they don't stack or cross at the boundary. It skips ends you pinned by hand and is idempotent+- Add `<Array as="points">` waypoints when an edge must detour around an intermediate shape+- **Leave room for arrowheads:** the final straight segment between the last bend and the target shape must be ≥20px long. If too short, the arrowhead overlaps the bend and looks broken. Fix by increasing node spacing or adding explicit waypoints+- **libavoid obstacle-avoiding routing (editor-side, draw.io ≥ 30):** draw.io has a newer connector router that recomputes edge paths to run *around* shapes (fanning out parallel edges) without moving any node. It runs interactively in the draw.io desktop editor (or via jgraph's MCP app-server `routing:"libavoid"`) — it is **not** a headless CLI flag. Passing `--layout libavoid` opens a modal `Unknown layout:` error dialog and hangs the run (jgraph's own drawio-mcp plugin docs claim the CLI flag works — verified hang on 30.2.6, don't trust it); the CLI `--layout` values are ELK *node* layout presets, a different thing (see `mermaid-authoring.md`). For CLI-authored files keep the orthogonal rules above; if a dense diagram still has crossings after export, open the `.drawio` in draw.io desktop once and let libavoid re-route. Don't stack it on an ELK `--layout` pass — pick one router, not both.++### Distributing connections on a shape++When multiple edges connect to the same shape, assign different entry/exit points to prevent stacking:++| Position | exitX/entryX | exitY/entryY | Use when |+| ---------- | ------------- | ------------- | ---------- |+| Top center | 0.5 | 0 | connecting to node above |+| Top-left | 0.25 | 0 | 2nd connection from top |+| Top-right | 0.75 | 0 | 3rd connection from top |+| Right center | 1 | 0.5 | connecting to node on right |+| Bottom center | 0.5 | 1 | connecting to node below |+| Left center | 0 | 0.5 | connecting to node on left |++**Rule:** if a shape has N connections on one side, space them evenly (e.g., 3 connections on bottom → exitX = 0.25, 0.5, 0.75)++### Color palette (fillColor / strokeColor)++*Used only when no user style preset is active (see `references/style-presets.md` → "Applying a preset").*++| Color name | fillColor | strokeColor | Use for |+| ----------- | ----------- | ------------- | --------- |+| Blue | `#dae8fc` | `#6c8ebf` | services, clients |+| Green | `#d5e8d4` | `#82b366` | success, databases |+| Yellow | `#fff2cc` | `#d6b656` | queues, decisions |+| Orange | `#ffe6cc` | `#d79b00` | gateways, APIs |+| Red/Pink | `#f8cecc` | `#b85450` | errors, alerts |+| Grey | `#f5f5f5` | `#666666` | external/neutral |+| Purple | `#e1d5e7` | `#9673a6` | security, auth |++### Legend (auto-generate from the palette)++When a diagram uses 3+ semantic colors, add a legend so the color coding is self-explanatory. Generate it mechanically from the roles actually present — never invent legend entries that aren't in the diagram:++```xml+<!-- Legend container: place in a corner clear of the diagram (e.g. below-left) -->+<mxCell id="legend" value="Legend" style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#666666;verticalAlign=top;fontStyle=1;" vertex="1" parent="1">+ <mxGeometry x="40" y="720" width="180" height="110" as="geometry"/>+</mxCell>+<!-- One swatch + label pair per used role, 24px row pitch, children of the legend -->+<mxCell id="leg1" value="" style="rounded=0;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="legend">+ <mxGeometry x="10" y="30" width="30" height="16" as="geometry"/>+</mxCell>+<mxCell id="leg1t" value="Service" style="text;html=1;align=left;verticalAlign=middle;" vertex="1" parent="legend">+ <mxGeometry x="50" y="28" width="120" height="20" as="geometry"/>+</mxCell>+```++Rules: swatch colors come from the active palette (preset or the table above) with the **role name** as the label (Service, Database, Queue, …); height = `30 + 24 × rows`; the legend is a container (`parent="legend"`, relative coordinates); skip it entirely for single-color diagrams.++### Layout tips++**Spacing — scale with complexity:**++| Diagram complexity | Nodes | Horizontal gap | Vertical gap |+| ------------------- | ------- | ---------------- | -------------- |+| Simple | ≤5 | 200px | 150px |+| Medium | 6–10 | 280px | 200px |+| Complex | >10 | 350px | 250px |++**Routing corridors:** between shape rows/columns, leave an extra ~80px empty corridor where edges can route without crossing shapes. Never place a shape in a gap that edges need to traverse.++**Grid alignment:** snap all `x`, `y`, `width`, `height` values to **multiples of 10** — this ensures shapes align cleanly on draw.io's default grid and makes manual editing easier.++**General rules:**++- Plan a grid before assigning x/y coordinates — sketch node positions on paper/mentally first+- Group related nodes in the same horizontal or vertical band+- Use `swimlane` cells for logical grouping with visible borders+- Place heavily-connected "hub" nodes centrally so edges radiate outward instead of crossing+- To force straight vertical connections, pin entry/exit points explicitly on edges:+ `exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0`+- Always center-align a child node under its parent (same center x) to avoid diagonal routing+- **Event bus pattern**: place Kafka/bus nodes in the **center of the service row**, not below — services on either side can reach it with short horizontal arrows (`exitX=1` left side, `exitX=0` right side), eliminating all line crossings+- Horizontal connections (`exitX=1` or `exitX=0`) never cross vertical nodes in the same row; use them for peer-to-peer and publish connections++**Avoiding edge-shape overlap:**++- Before finalizing coordinates, trace each edge path mentally — if it must cross an unrelated shape, either move the shape or add waypoints+- For tree/hierarchical layouts: assign nodes to layers (rows), connect only between adjacent layers to minimize crossings+- For star/hub layouts: place the hub center, satellites around it — edges stay short and radial+- When an edge must span multiple rows/columns, route it along the outer corridor, not through the middle of the diagram++### Decision-diamond branches, pixel-exact pins, and labels++Pitfalls verified from rendered output. `validate.py` does not catch any of them, and vision review both misses them and hallucinates new ones (it once described a clean diamond exit as "wrapping around the box" and approved a screenshot that was actually the browser error page).++| Pitfall | Rule |+| ------- | ---- |+| Edge exits the rhombus's left/right side with its first segment heading *inward* (`exitX=0;exitY=0.25` with its target to the right at the same height): the elbow's horizontal run crosses the diamond's own interior. At the exact vertex (`exitY=0.5`) the router instead detours around the whole shape, which reads no better | Vertex exits must head outward (left vertex → left, right → right, top → up, bottom → down). When both branch targets sit *below* the decision (left and right), skip the elbow entirely: draw one straight line per branch with `edgeStyle=none` from the lower-left / lower-right **edge midpoint** (`exitX=0.25;exitY=0.75` / `exitX=0.75;exitY=0.75` — both points lie on the rhombus outline) to each target's top center. Symmetric, no right angle, nothing to cross. |+| Vertical edge whose `entryX` is 1–2 px off the source's exit x (easy to hit when boxes snap to a 10 px grid) | Compute the pin with full precision: `entryX = (sourceCenterX − target.x) / target.width`, e.g. `0.0652`, `0.2027`. Style values accept more than two decimals. A 1–2 px mismatch renders as an S-shaped double curve (two `Q` bends) just before the arrowhead. |+| `blockThin` arrowheads (~5×7 px) flush against the target border | Reviewers read the tip as "piercing the box". Use `endArrow=block;endSize=8` for main flow edges. |+| Long labels auto-centered on their own edge | The white label chip visually severs the edge, and near a corner it can cut both segments. Keep only micro-labels (`Yes` / `No`) on the line; offset longer labels (`<mxPoint as="offset" x="…" y="…"/>`) into verified empty space, and shorten any label wider than the corridor it annotates. |+| Trusting "it looks fine" | Confirm with renderer ground truth: render the viewer URL and `--dump-dom`, then read `<path d="…">` segments and label `foreignObject` `padding-top/margin-left` anchors (see `references/troubleshooting.md` → "Verifying the rendered output"). |