🎯 The Argument Is a Commit Hash
The diagram points at a commit hash, 9f1a1cf. Archify traced the repository mco-org/mco at that exact revision and produced a checked map, not a sketch — "a map with a receipt." 0:00
The viral framing was wrong. "AI finally learned to draw architecture diagrams" — no. What everyone actually experienced: ask a model for a diagram, get something beautiful and confident — a gateway you don't have, a queue you deleted in March. Models aren't bad at diagrams; they were asked to do two jobs at once, and only one was ever theirs.
✍️ Error 1: "The AI Draws It"
The agent's entire output is typed JSON IR — nodes, edges, roles, boundaries as structured fields. Archify then deterministically compiles that JSON into HTML and SVG. 1:01
Count the pixels the model places: zero. Count the layout decisions it makes: zero. It doesn't choose a coordinate, route a curve, size a box, or pick a color. "Think of it exactly like a compiler — the model writes source, the toolchain owns everything downstream."
Deterministic means the same input produces the same output every run on every machine. And if the JSON doesn't satisfy the type, nothing renders — you get a failure, not a confident picture of a service you don't run.
"The verdict on error one: the model got demoted. That is not a limitation of the tool — that is the feature."
🎨 Error 2: "Prettier Mermaid?"
With Mermaid, the model writes graph TD and every arrow by hand — still authoring layout in a text language, rendering a static picture in a code fence. Archify is a different class. 1:48
| Mermaid | Archify |
|---|---|
| Model authors layout by hand in text | Model emits typed JSON IR; deterministic compile |
| Static picture in a README code fence | Self-contained interactive HTML + PNG + SVG + WebM + 1200×630 share card |
| Something you read | Something you interrogate |
1200×630 is deliberate — the standard link-preview size, so the diagram survives the trip into a release note or PR description. Five diagram types: architecture, workflow, sequence, data flow, lifecycle. Four presets, dark/light themes, built-in brand marks, finite motion (motion with an end state, not an animation loop).
The interactions are the real separation: search nodes, open revision-verified source, trace upstream and downstream reach, inspect the shortest authored path, compare roles, play a named guided chapter.
✅ Error 3: "Validated Means Correct"
The error worth slowing down for — the word "validation" is doing very narrow work here. 2:57
What's actually checked is the chain from typed source to picture: the IR is typed, the compile is deterministic, and the topology is authored. That word — "authored" — appears throughout the docs and is load-bearing. Trace a route and you get the authored path; the claim is that the map matches its own declared source, which can point at revision-verified code at a specific commit. That's chain of custody.
What is not claimed: runtime. The docs say "captures that exact reading, without claiming runtime impact." No impact scores, no merge-safety opinions, no profiler numbers. A wrong fact that is correctly typed still compiles. If the agent decides your billing service talks to Redis and it doesn't, that lie is well-formed and renders beautifully.
"Determinism buys you reproducibility. It does not buy you truth. What it buys is a smaller lie surface."
Three failure modes became one. The model can no longer invent a layout, invent a route it never declared, or produce a picture that disagrees with its own type source. What remains is a fact you can read as JSON and check against the commit.
🔀 Error 4: "Compare Reviews For You"
The command is architecture compare base.json head.json — it renders before / delta / after and reports exact facts in five classes. 4:27
Five nouns: added, removed, changed, moved, rerouted. Now count the scores: zero. No risk grade, no blast-radius number, no "ship it" verdict. Almost every diff surface ships with a number attached — a coverage percentage, a severity label, a confidence score. Those numbers are "the easiest thing in the world to generate and the hardest to justify." Archify stops at the five nouns and hands the judgment back to you.
Moved and rerouted are separate classes — most diff views collapse them into "changed." Splitting them tells you whether a box drifted in the layout or an edge now takes a different path through your system. Only one of those is an architecture change.
"The proudest thing this tool does is decline to have an opinion. The refusal is the feature."
📦 What Is Actually Real
Three things, and the one number still missing. 5:29
1. The boundary is a genuine engineering split, not marketing — authorship on one side, rendering on the other, a type check at the seam. The model supplies facts, because facts are the only thing it's allowed to emit.
2. The receipts are checked in — rare. The proof lab carries 11 scenarios with JSON sources, named views, and validation receipts. The
mco-org/mco map at 9f1a1cf is public with its type source next to it. Sample artifacts are described as "generated artifacts, not product mock-ups." You can open examples/web-app.html locally before installing anything.3. The install is one line:
npx skills add tt-a1i/archify-g — targeting four hosts (Cursor, Codex, Claude Code, OpenCode), plus a no-install trial path.The missing number: there is no published accuracy benchmark — how often an agent's typed facts actually match the repository it read. "Everything else in this system is verifiable, and that one number is the only thing standing between you and a beautifully typed fiction."
"The model never needed to get better at drawing. It needed to be taken off the pen — and the pen needed a type checker. We spent a long time trying to make the model more trustworthy. This makes the model less powerful and the output more trustworthy. Those turn out to be the same move."
💡 Key Takeaways
- The model never drew the diagram — it emits typed JSON IR; a zero-dependency Node.js system compiles it deterministically into HTML/SVG.
- Pixels placed by the model: zero; layout decisions: zero — "take the pen away, and put a type checker on the pen."
- Not Mermaid with a theme — a self-contained interactive HTML artifact you interrogate, not read, with revision-verified source tracing.
- 1200×630 is deliberate — the link-preview size, so diagrams survive release notes and PRs.
- "Validated" means "matches its own typed source", not "correct" — a wrong fact that is correctly typed still compiles beautifully.
- Determinism buys reproducibility, not truth — it shrinks the lie surface from three failure modes to one.
- Compare mode reports five nouns and zero scores — added/removed/changed/moved/rerouted; the refusal to grade is the feature.
- The one missing number — no published accuracy benchmark for how often typed facts match the repo.