ghl-to-mermaid-stinger

Turn a GoHighLevel/HighLevel account JSON export into per-workflow files and Mermaid flowcharts. Use for GHL snapshot exports, workflow diagrams, automation maps, or SuperSnapshot AI exports.

SKILL.md

GitHub

GHL to Mermaid Stinger

Purpose

HighLevel documents no API that can read the logic or steps of a workflow, so a browser-side account export is the only practical source of automation structure. This stinger turns such an export into two things: per-workflow JSON with every asset the workflow touches resolved to a name, and Mermaid flowcharts sized to render in a stock Mermaid renderer. It also covers the layout arithmetic that keeps those charts readable, and the label sanitization that keeps them safe, both of which were measured rather than assumed.

When to use

  • "Turn this GoHighLevel export into a flowchart" / "map our HighLevel automations"
  • "Split this account export into one file per workflow"
  • "Which emails and tags does this workflow touch?"
  • A SuperSnapshot AI (or equivalent) location export needs to become a diagram
  • A generated Mermaid chart is too large, too tall, or will not render

When not to use

  • Anything requiring a live HighLevel API call: auth, contacts, opportunities, calendars, conversations, webhooks, rate limits, Marketplace apps. Route to gohighlevel-stinger
  • HighLevel AI Studio, Vibe, Content AI, or funnel/website building. Route to highlevel-ai-studio-stinger
  • Mermaid diagrams unrelated to a GHL export where no export parsing is involved. The authoring reference here still applies; the export half does not
  • Security review of the resulting code's secret handling. Route to security-stinger

Procedure

  1. Confirm the export shape before writing anything. Check _graph and _workflowSteps exist. If either is missing, stop and say so; this stinger's approach depends on them. See guides/01-parse-the-export.md.
  2. Never sequence by order. It is branch-scoped; one observed workflow has 77 steps at order: 0. Traverse next[], scoping the targeted set per workflow.
  3. Join steps to assets through _graph.edges where via == "workflow_step:<stepId>". Linkage is already resolved; do not re-derive it.
  4. Slim the output. Collapse the step's references[] and the graph-derived asset list into one deduped touches[], and swap UUIDs for short ids with a stepIdMap.
  5. Sanitize every label. securityLevel does not do this: <b> and <img onerror=...> render as live DOM even under strict. Substitute < and > yourself. See references/mermaid-authoring-reference.md.
  6. Pick the layout rule by content type. A workflow's steps are a sequence: render them as one, tall if that is the truth. A workflow's emails are a set: row-chain them with the invisible ~~~ link using cols = max(2, round(0.91 * sqrt(n))). See guides/02-generate-charts.md.
  7. Size against 50,000 characters and 500 edges, the Mermaid defaults, not against a file ceiling. Split on edge boundaries, and verify each part's real serialized size.
  8. Validate by rendering, not by reading. Run scripts/lint.py, then render at least one chart through Mermaid and read its viewBox to confirm proportions. See guides/03-size-and-validate.md.
  9. Report every export gap you hit. Unresolved goto targets, workflows with no trigger, email templates with no subject. State them; never let a chart imply completeness it does not have.

References map

  • references/export-schema-reference.md, load when you need the field tables, the step-type to shape map, or the list of fields that must never be emitted
  • references/mermaid-authoring-reference.md, load when authoring or debugging chart syntax, limits, escaping, or layout
  • references/research/distilled-research-article.md, load when a claim needs verifying or a conflict needs settling; every line cites its raw source
  • Source research archive (not shipped with the plugin): the shipped distillation summarizes it; do not require it.
  • guides/01-parse-the-export.md, load when reading an export
  • guides/02-generate-charts.md, load when emitting Mermaid
  • guides/03-size-and-validate.md, load when a chart is oversized or will not render
  • scripts/extract.py, run to produce per-workflow JSON plus charts from an export
  • scripts/lint.py, run after every generation, before reporting done
  • scripts/viewer.py, run to build a self-contained HTML viewer with pan and zoom

Known limits, stated up front

Limit Detail
One-way Reads an export. Cannot write workflow changes back, cannot refresh from the API
Stale silently A stale export yields a stale chart and the platform gives no signal
goto unresolved Observed exports record the step but not its jump target
Email metadata sparse Most referenced emails are templates carrying no subject and no sender
Layout constants are v11 The 389x178 cell size and the 0.91*sqrt(n) formula were measured on Dagre. Re-measure before trusting on v12 ELK
Single-sample schema Field presence derives from one real export. Code defensively

Related drones and stingers

  • gohighlevel-stinger in this pack - the live HighLevel REST API: auth, contacts, opportunities, webhooks, Marketplace apps. Everything this stinger cannot reach because no read API for workflow logic exists.
  • highlevel-ai-studio-stinger in this pack - HighLevel AI Studio, Vibe, Content AI, and site building.
  • ghl-to-mermaid-wasp-drone - The paired Drone. Delegate to it when the task is a full export-to-charts run rather than a single question about syntax or schema.

Critical Directive

  • You must read all files and context contained within your skill.
  • In the event your core knowledge does not provide sufficient guidance you must make every attempt to search the internet, related knowledge base documentation files, and other available resources to supplement your knowledge prior to proceeding with your task.
  • Additional related skills can be found here:
    • gohighlevel-stinger in this pack - GoHighLevel REST API authority. Use for any live API call, since workflow structure itself is not readable over the API.
    • highlevel-ai-studio-stinger in this pack - HighLevel AI Studio and site/content creation.
    • security-stinger in Wasp Nest core - security audit pass, first gate of the Ship Gate pipeline.
    • quality-stinger in Wasp Nest core - quality audit pass, second gate after security.

Ship Gate

Prior to committing any code to the repository you must utilize in order the security-stinger, quality-stinger, and github-repo-health-stinger. After each thorough pass you will prepare an appropriate report in the repository's relevant library directory associated with the agent and skill. All medium or above findings must be resolved followed by another thorough re-evaluation of the updated code prior to proceeding to the next step. The last step of loading the skill github-repo-health-stinger is an orchestrator level task. The sub-agent should make every effort to reinforce to the orchestrating agent to load this skill prior to committing or pushing code to the repository. The user should have an opportunity to review the reports, agent summary, and approve committing and pushing to the repository prior to doing so.