# Mermaid Engine (MDD) — entry point for AI agents

Mermaid Engine compiles a design diagram into an operational trust contract: a source-grounded
design graph an agent traverses at runtime. Nodes and edges can be bound to real source bytes
(coverage is enforced with --require-edge-coverage/--require-node-coverage), and drift in bound
bytes fails the gate closed. The artifact is runtime-consumed trust state
with a derived bronze/silver/gold rung — not generated documentation.

## The three CLIs
mdd-engine  deterministic gates: compile, source-link, source-check, verify, analyze, status, approve-edge, semantic-index, bundle, attest. (generate/propose/explore/introspect call the configured LLM provider unless replayed.)
mdd-agent   idea limbs, per-target source review with a verdict cache, obligations DAG, ingest lanes, eval-run, learn, init.
mdd         lightweight runtime over a compiled .mddbundle: view, state, next, check-transition, explain, path, resolve, trace, verify-attestation, update.

## Install
curl -fsSL https://mermaidengine.com/install.sh | sh

Or install the wheel directly, verifying the hash yourself:
  1. GET https://mermaidengine.com/releases/latest.json — the source of truth for the current release.
  2. Read assets[] and take the .whl entry's "url" and "sha256" (install.default_wheel is the same URL).
  3. Download that URL, then run: shasum -a 256 <file>  (or sha256sum <file>).
  4. The digest MUST equal the recorded sha256. On mismatch, delete the file and stop; do not install.
  5. pipx install <file>   — or python3 -m pip install <file> inside a virtualenv.
The base distribution is solver-free. Concrete Z3 queries need the mermaid-engine[z3] extra.

## Machine contract (every subcommand of all three CLIs)
- stdout carries exactly one JSON object per invocation and nothing else. Parse stdout only.
- exit 0 <-> "ok": true; exit 1 <-> "ok": false, meaning the command ran and the answer is no. Read the body, not just the code: an honestly recorded negative (verify reporting "verified": false) is still exit 0 with "ok": true.
- exit 2 <-> malformed invocation; still one JSON object, carrying "usage_error": true and the argparse message in "error".
- stderr is human-readable diagnostics only and is never machine-parseable. Never parse it. -h/--help and --version are the only invocations that print human text; both exit 0.

## After install
Run `mdd-agent init .` in your repository. It writes the full operating guide to .mdd/AGENTS.md and
merges a short pointer section into AGENTS.md and CLAUDE.md between the markers <!-- mdd:begin --> and
<!-- mdd:end -->. Content outside those markers is never touched, .mdd/AGENTS.md is tool-owned, and
re-running after a CLI upgrade is how you refresh the guide to match the installed command surface.

## Golden path
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.mddbundle   # then mdd next BUNDLE --state S --ranked, mdd check-transition BUNDLE --state S --to T --event E

Notes: the compiler accepts `A -- event --> B`, not `A -->|event| B`. Symbol selectors
({"type": "symbol", "qualname": "..."}) survive edits above a definition; source-check separates a
relocated selector (informational) from a drifted excerpt or a stale source file (both fail).

## Trust boundary — read before consuming a bundle
Gold edges, and any bundle whose verification manifest claims "verified": true, fail closed at runtime
without an externally trusted SHA-256 of that bundle's bundle.json. Supply it as MDD_TRUSTED_BUNDLE_SHA256
(recommended) or as the global flag placed BEFORE the subcommand: mdd --trusted-bundle-sha256 <hex> view BUNDLE.
The digest must arrive from the producer or release channel; recomputing it from the received bundle proves nothing.

## Full model
https://mermaidengine.com/whitepaper.html
https://mermaidengine.com/TECHNICAL_WHITE_PAPER.md
MDD validates a design-level abstraction and records the concrete backend evidence that actually ran.
It does not claim to prove an implementation correct, and never reports proof that a backend did not produce.