Mermaid diagrams · LLM semantics · verifiable logic

Turn source reality into a logic map agents can trust.

Mermaid Engine treats every diagram as an abstraction of source data, links nodes and edges back to evidence, and compiles the result into deterministic forms with honest verification manifests that logic tools and AI agents can review and traverse.

Update commandmdd update

Current CLI version v0.1.3

Read white paper

Prompt for your coding agent

The copied text installs from https://mermaidengine.com/install.sh, asks the agent to inspect mdd-engine --help, mdd-agent --help, and mdd --help, tells the agent to use mdd update for a future website re-install, prefers deterministic replay when no Ollama/Qwen is configured, mentions extract-targets, obligations, eval-run, and learn failure, and tells the agent not to claim proof unless verification.json records a deterministic backend run.

Why use it?

Prose hides contradictions. Diagrams expose the logic.

Specs, prompts, issues, source code, logs, policies, and architecture notes often describe the same system in conflicting ways. Mermaid Engine refines domain knowledge into one reviewable graph whose parts can be checked back against linked source evidence, then compiled into a portable bundle for deterministic agent traversal.

Grounding

Every edge is a source claim.

Nodes, transitions, guards, and refinements can link back to requirements, code, tests, logs, policies, or upstream diagrams for review.

Deployment

Ship the compiled knowledge, not the toolchain.

Run heavyweight refinement and concrete checks once, then distribute the lightweight mdd CLI with compiled .mddbundle diagrams and their verification manifests.

Verification

Logic tools check the traversal.

Compiled artifacts make legal paths deterministic, so agents can evaluate complex systems without inventing unsupported moves.

Replayable source-to-target loop

Autoform-inspired lifecycle, MDD-native artifacts.

Mermaid Engine now includes an Autoform-inspired source-to-target workflow without copying Autoform Bot code, prompts, docs, or data. Autoform Bot is non-commercial prior art; MDD keeps the product boundary in deterministic CLI artifacts and replayable evidence.

01extract-targetsChunk source corpora and emit mdd-targets/v0 plus source-map drafts

02obligationsPersist typed mdd-obligation-dag/v0 work items

03eval-runFail closed on missing IR, stale source checks, overclaims, or bundle gaps

04learn failureTurn failed traces into advisory guides that cannot override guardrails

Opt-in ingest integration

Default behavior stays compatible.

Add --extract-targets, --obligation-dag, and --eval-report when a run needs the target/DAG/evaluation loop. Live LLM extraction remains replayable through saved files for deterministic tests.

mdd-agent ingest docs/requirements/auth.md \
  --task-type generic_domain_ingest \
  --extract-targets \
  --llm-extractions-file fixtures/extractions.json \
  --obligation-dag build/run/obligations.json \
  --eval-report \
  --out-dir build/run \
  --llm-diagrams-file fixtures/diagrams.md

How it works

Source data → refined knowledge graph → compiled runtime artifact.

Use it to link requirements, code, tests, logs, or policies to a Mermaid diagram, then either run the deterministic commands directly or let mdd-agent process --source-map perform source-link, source-check, Qwen source-review, source-grounded bundling, and runtime traversal as one replayable lane. Gold edge approval still requires supported current mdd-source-review/v0 evidence, and deployed mdd runtimes expose evidence status per operation. If source evidence goes stale, the lifecycle model drops the diagram below Bronze/Silver/Gold until remapped, re-reviewed, and re-approved.

01SourceRequirements, code, tests, logs, policies

02DiagramMermaid abstraction with source links

03ReviewQwen checks abstraction against evidence

04DeployShip mdd CLI + compiled bundles

Current parser subset

Use transition IDs on edges.

The fail-closed compiler currently accepts deterministic event syntax like Draft -- all_edges_approved --> Gold. Common Mermaid pipe labels such as Draft -->|all edges approved| Gold are valid Mermaid, but not accepted by the current MDD compiler yet.

flowchart TD
Draft[Draft]
Gold[Gold]
Draft -- all_edges_approved --> Gold

Built for general users and developers: describe the source reality, refine it into an auditable diagram, compile a bundle, then give agents a reviewed map they can follow with only the lightweight runtime.

View install script