Operational trust contracts for AI agents
Mermaid Engine compiles a diagram into a source-grounded design graph an agent consumes at runtime: nodes and edges bind to real source bytes, drift in those bytes fails the gate closed instead of degrading quietly, and the lightweight mdd runtime answers deterministically from the compiled bundle. It validates a design-level abstraction and records the backend evidence that actually ran — it does not claim to prove an implementation correct.
mdd update
The copied text points your agent at llms.txt, installs the CLI (or verifies the wheel digest from latest.json by hand), scaffolds .mdd/AGENTS.md with mdd-agent init ., states the machine contract, and warns it not to claim proof that no backend produced.
For AI agents
Every reference an agent needs is machine-readable and hosted here: llms.txt is the entry point, releases/latest.json is the source of truth for the current wheel URL and its SHA-256, install.sh is the one-line installer, and the full model is in the white paper as HTML or Markdown.
Entry point
/llms.txt states what MDD is, the three CLIs, both install routes, the machine contract, the golden path, and the runtime trust boundary. It pins no release number, so releases/latest.json stays the single source of truth.
Scaffolding
Run mdd-agent init . in your repository. It writes the full guide to .mdd/AGENTS.md and merges a pointer section into AGENTS.md and CLAUDE.md between mdd:begin/mdd:end markers. Content outside the markers is never touched; re-run it after a CLI upgrade to refresh the guide.
Machine contract
Every subcommand of all three CLIs prints one JSON object on stdout and nothing else. Exit 0 means "ok": true, exit 1 means the command ran and the answer is no, exit 2 means a malformed invocation and carries "usage_error": true. stderr is human diagnostics only and is never machine-parseable; only --help and --version print human text.
Install
The installer is the fast path. For a manual install, read releases/latest.json, download the wheel it names, and confirm its recorded SHA-256 before installing — on mismatch, stop. Later, mdd update prints the website re-install instruction for the current release.
curl -fsSL https://mermaidengine.com/install.sh | shGolden path
These five commands need no formal backend, no LLM review, no edge approval, and no trust anchor, because a draft bundle carries no trust claim and is freely inspectable. The compiler accepts Draft -- all_edges_approved --> Gold; the common pipe-label form Draft -->|all edges approved| Gold is valid Mermaid but not yet accepted here.
mdd-engine compile diagram.mmd --out diagram.ir.json
mdd-engine source-link diagram.ir.json --mapping source-map.json --out diagram.sourced.ir.json
mdd-engine source-check diagram.sourced.ir.json --out source-check.json --require-edge-coverage
mdd-engine bundle diagram.sourced.ir.json --out diagram.mddbundle --source-check source-check.json
mdd view diagram.mddbundleHow it works
Specs, prompts, issues, code, logs, and policies describe the same system in conflicting ways. Link them to one Mermaid diagram, then run the deterministic commands directly or let mdd-agent ingest --deep-review --mapping perform source-link, source-check, per-target review, source-grounded bundling, and runtime traversal as one lane, with each LLM gate pinned by a repeatable --replay GATE=PATH. Around that sits an Autoform-inspired source-to-target loop: idea init emits an obligations DAG, obligations set advances it under enforced dependencies, eval-run fails closed on missing IR, stale source checks, overclaims, or bundle gaps, and learn failure turns failed traces into advisory guides that cannot override a guardrail. Autoform Bot is non-commercial prior art; MDD copies none of its code, prompts, docs, or data.
Grounding
Links can bind a node or edge to real bytes (coverage becomes mandatory with the coverage flags on source-check) through a line span or a symbol selector that re-resolves through the Python AST, plus a hash of the exact excerpt. source-check then separates a relocated excerpt (informational) from a drifted or stale one (fails). Review runs one provider call per target with a reviewer-keyed verdict cache, so re-reviewing after a one-edge change costs one call.
Derived trust
mdd-engine status derives the bronze/silver/gold rung from the evidence you pass in rather than a stored label, and Gold is approved per edge against that edge's own current evidence. Only v1 source-review approval bindings carry Gold authority; legacy-v0 records require fresh approval and are rejected by validation, bundling, and runtime loading. Backend selection flags on verify are proposal-only unless concrete TLC, Z3 query, or Lean check flags are supplied; concrete Z3 needs the optional mermaid-engine[z3] extra. attest records an unsigned hash chain — tamper detection, not a signature.
Runtime
Install the solver-free base distribution, run refinement and any backend checks once, then ship compiled .mddbundle diagrams to the lightweight mdd command — the runtime is not independently packaged. It answers view, ranks immediate edges with next --ranked, enumerates bounded routes with path, and resolves intent with resolve. Approved forbidden edges are reported separately and never traversed.
Trust boundary: for Gold-bearing IRs, engine-side validation, verification, and bundling reread the producer's source bytes and fail closed on staleness. On the consumer side those files do not exist, so portable runtime loading validates complete embedded bindings without producer source paths and requires an externally trusted bundle.json SHA-256 — from the producer or release channel, never recomputed from the received bundle — before consuming any Gold edge or any bundle claiming verification.