# Diagram Lint

> Paste a Markdown document with embedded Mermaid diagrams. The browser lints it against the
> markdown and mermaid style guides of the agent skill @k-dense-ai/markdown-mermaid-writing and
> applies safe fixes, free. A metered run (model gpt-terra) reviews the document, returns a fixed
> copy that the browser re-lints and compares with the original, or drafts a new Mermaid diagram
> from a prose passage and lints it before insertion.

URL: https://diagram-lint.skillsafe.ai/
API tutorial: https://diagram-lint.skillsafe.ai/api.html
Independent tool: not affiliated with or endorsed by Mermaid Chart Inc. or the Mermaid project; Mermaid is named only as the diagram syntax it checks.
Source skill: https://skillsafe.ai/skill/@k-dense-ai/markdown-mermaid-writing (k-dense-ai/scientific-agent-skills, MIT; style guides Apache-2.0, Clayton Young / Superior Byte Works LLC)

## What the free lint checks

- Mermaid: accTitle (3-8 words) and single-line accDescr on every diagram that supports them; an
  italic description paragraph above mindmap, timeline, quadrant, sankey, xychart, block, kanban,
  packet, architecture, radar and treemap diagrams instead; no %%{init} or theme directives; no
  inline style (classDef + class, each classDef with color:, at most 4 classes, the guide's palette);
  snake_case node ids that match their labels; labels of 3-6 words and edge labels of 1-4; one emoji
  per node at the start, no decorative emoji; at most two bold terms per node; subgraphs past 10
  nodes, a split past 30; at most 3 decisions per subgraph; parser traps: an `end` node id, an
  unclosed subgraph, `radar` without -beta, x-axis in a radar chart, emoji in sankey, architecture
  or C4 labels, hyphens in architecture labels, dashed requirement ids, capitalised risk values;
  unknown diagram keywords and unclosed fences.
- Markdown: exactly one H1 first; no skipped heading levels; no H5+; one emoji at the start of each
  H2 and none in H1/H3/H4; sentence case (note); descriptive headings (note); at most 3 bold terms
  per paragraph, no bold sentences, no bold italic; footnotes defined, used, cited in order, with a
  full https URL, grouped at the bottom; meaningful link text; https links; fenced code with a
  language; <details> with a <summary>, a blank line after it, and --- after </details>; tables with
  a header row and at most 5 columns; lists nested at most 2 levels; no nested blockquotes;
  whitespace (trailing spaces, double blank lines, blank lines around headings and code, final
  newline); a --- that silently turns a paragraph into a setext heading.
- Severities: error = will not render, or a diagram without accTitle/accDescr; warning = a stated
  rule; note = a heuristic. This is the page's reading of the guides, not Mermaid's parser.

## Run contract

Input (every field a string): task ("review" | "fix" | "diagram"), markdown, facts (JSON string
from the lint: summary, hint, findings F1.., diagrams D1.., outline, footnotes), title, context,
question, review (fix only), passage (diagram only), retry_note.

Output: one JSON object. Envelope: lane, verdict (blocked | needs_work | ready), headline,
finding_responses [{ref, action fix|accept|dispute, note}], next_steps. review adds diagram_notes,
prose_to_diagram, citation_gaps, priority_fixes. fix adds changes, markdown, open_questions.
diagram adds diagram_type, why_this_type, source_quote, placement, mermaid, caption, open_questions.

The browser reconciles every reply: each finding answered once, errors always fixed, verdict no
looser than the lint, quotes found verbatim, a fixed document re-linted and checked for lost or new
URLs, changed code blocks and dropped diagrams, a drafted diagram linted and its labels checked
against the passage.