Ask an LLM to "draw our architecture" and you usually get one of two disappointing results: an ASCII sketch, or a wall of brittle Canvas/JavaScript that half-runs. The problem isn't the model — it's the target format.MarkdyScript is a small, line-based, strictly-validated DSL, which makes it a great compile target for AI: easy to generate, easy to validate, and easy to revise.

Why constrained text is the right AI target

Small grammar. Nodes, groups, beats, and four flow operators — a model can learn it from one reference page.
Deterministic. The same text always renders the same diagram, so results are reproducible and diffable.
Line-numbered errors. When the model gets something wrong, the parser points at the exact line, so the agent can self-correct.
No runtime to hallucinate. There's no imperative API surface to invent — just declarative statements.

How to prompt for a Markdy diagram

Point the model at the Markdy agent guide(grammar, node kinds, examples) and describe the system in plain English:

Use the Markdy agent guide. Create a 1280×720 animated architecture diagram for a URL shortener. Use semantic node kinds, beats, labeled flow edges (->, <-, ~>), short labels, and a final glow on the hot path.

You get back a complete, runnable scene:

scene "URL Shortener" theme=paper
layout LR

browser Browser
gateway Gateway "API Gateway"
service Shortener "URL Shortener"
cache Redis "Hot URL Cache"
database UrlDB "URL Store"

group storage: Redis UrlDB

beat create:
  Browser -> Gateway "POST /shorten" -> Shortener
  Shortener -> UrlDB "store slug" & Shortener ~> Redis "warm cache"
  Browser <- Shortener "short.ly/a7"

beat finish:
  glow storage color=#22c55e

Paste it straight into the playground to verify it. If it doesn't parse, hand the line-numbered error back to the model and ask it to fix that line — the loop is fast and reliable.

Works with the tools you already use

MarkdyScript is plain text, so it works with any assistant that accepts a URL as context — Claude, ChatGPT, GitHub Copilot, Cursor, and Windsurf. Keep the diagram in your repo and the same agent can update it whenever the system changes, exactly like diagrams as code.

Validate what the AI produced

Trust, but verify. Run markdy lint scene.markdy in CI, or render the scene inAstro or MDX docs so a broken diagram fails your build instead of shipping. Deterministic output means AI-generated diagrams stay reviewable — not magic you can't audit.