Archify Validates the Drawing, Not the Architecture

The agent skill topping today's trending board hashes its own output, refuses to claim checks it did not run, and still cannot tell you whether the boxes are true. That gap is the whole category.

Somewhere in Archify's documentation there is a sentence that describes the entire state of agent-generated engineering documentation, and it is written about an optional feature almost nobody will turn on. Describing the deployment-ownership profile, a fail-closed review mode for production topologies, the README says the check "validates authored facts" and not live infrastructure.

Authored facts. Meaning: things somebody wrote down. Meaning: the check confirms your claim is well-formed and internally consistent, not that it corresponds to a running system.

Sit with that, because Archify is currently the number one repository on Trendshift's daily board at roughly 21.9k stars, it is a genuinely careful piece of engineering, and every guarantee it makes is of that shape.

What it does

Archify is MIT-licensed, a rewrite of Cocoon-AI/architecture-diagram-generator v1.0, currently at development version 2.16. Install is one line, npx skills add tt-a1i/archify -g, and the agent switcher covers Cursor, Claude Code, Codex CLI and opencode.

The loop is short. Your agent reads a codebase or a description, writes typed JSON matching one of five schemas, and a Node renderer with no model in it compiles that JSON into a single self-contained HTML file. Five diagram types: architecture, workflow, sequence, data flow, lifecycle. The output has pan and zoom, node search, route probing, upstream and downstream tracing, presentation mode, and exports to PNG, SVG, WebM and a 1200 by 630 share card.

The separation is the good idea here. The model does layout judgment and semantics; a deterministic renderer does pixels. You cannot check a picture, but you can check a schema, and Archify checks a lot of them.

Nine artifact checks for a showcase pass, with zero composition errors and zero warnings required. The skill file is blunt that the weaker tier exists and should not be mistaken for the stronger one: a receipt reporting only four checks is basic validation and "never showcase acceptance." Delivery goes further. It freezes the specification bytes into a private snapshot, renders and checks that snapshot, atomically replaces the target only on a pass, and reports SHA-256 hashes plus byte counts for both the spec and the artifact.

That is a real chain of custody. On a file.

The part I did not expect

Run visual-check after delivery and it measures containment at four desktop sizes, captures light and dark screenshots, and writes a contact sheet. Then it reports visualReview: "pending". Always. The skill file explains why in a line I have not seen anywhere else in agent tooling: screenshots are evidence for inspection, never an automatic polish claim.

The instructions to the agent carry the same posture throughout. Do not claim success for a non-zero command. Do not claim visual inspection you did not perform. Never delete a meaningful relationship label just to pass validation. Once the deployment profile is enabled, do not remove it to make the diagnostics go away; repair the facts or report the failures truthfully.

Source evidence follows the same rule. You can attach repository citations to architecture components, pinned to one public commit, and Archify verifies the git origin, the commit, the blobs and the requested line ranges. It is opt-in, the docs say so plainly, and ordinary diagrams stay source-free.

I want to give the maintainer full credit here. Most projects in this space would have shipped the citation as a formatting feature and the screenshot as proof. Archify built the machinery and then wrote instructions telling the model not to overclaim what the machinery did.

Where the guarantees stop

Now line up everything that gets verified.

The JSON conforms to a schema. Boxes do not overlap. Labels do not mask routes. Nothing sits off canvas. The delivered HTML hashes to a known value. The cited commit exists. The cited file exists. The cited lines exist. The page does not overflow at 1920 by 1080.

Not on that list: whether the component labeled "Auth Service" is a service, whether it does auth, whether the arrow into it reflects a call that happens, whether the three components your agent left out are the three that page you at 2am.

Archify verifies that the citation resolves. It cannot verify that the citation supports the claim. Those are different operations, and only the second one is what a reader of an architecture diagram thinks they are getting.

Here is the position I will defend: the failure mode of agent-generated documentation is not that it looks bad. It is that it looks finished. A crooked ASCII box diagram in a README announces its own provisional status and gets read with appropriate suspicion. A four-times-rasterized diagram with semantic color coding, a legend, a route probe and a SHA-256 receipt does not. Reviewer confidence tracks polish, and Archify's entire reason for existing is that it produces more polish than anything you would draw by hand.

The receipts make it worse before they make it better, because a receipt is a strong signal that somebody checked something, and the reader is not going to ask which layer.

Putting this into practice

Four things, in the order I would actually do them.

Turn on source evidence and say so out loud. The agent will not enable it for you. Put "source-linked" or "evidence-backed" in the request. Public repositories only, architecture diagrams only, one pinned commit. Without it you have a picture with no thread back to the code at all.

Hand-check three citations the first time, then spot-check after. Follow the line ranges. Decide whether the code at src/router.ts:24-61 means what the label claims. Archify proved those lines exist; you are the only thing that can prove they mean that. Fifteen minutes, once, and you will calibrate how much your agent's reading of that repo can be trusted.

Ask for the showcase receipt, not just the file. deliver --json returns the rule codes, the subject of every diagnostic and the hashes. If your agent hands you an HTML file and a summary sentence, you have no idea which validation tier it passed.

Keep the first map under twelve nodes and make more of them. The skill file caps primary nodes at twelve for a reason. One honest bounded view per question beats one map of everything that is wrong in eleven places you cannot see.

Honest limitations

Most of Archify's discipline is prose. The deterministic parts are genuinely enforced by code: exit codes, schema validation, layout geometry, the SHA-256 receipts, the git checks. The parts that say "do not claim visual inspection you did not perform" are instructions to a language model, and a language model under pressure to look finished is exactly the actor those instructions are addressed to. Every "never claim" line in that file is a rule the system hopes will hold, sitting next to rules the system enforces. Nothing in the receipt tells you which kind you got.

The evidence feature also excludes the case where you need it most. Public GitHub repositories only, and architecture mode only. Your private production monorepo, where nobody can sanity-check the diagram from memory, is the one repository that cannot carry verified source links.

The project is moving very fast and it is one author. Version 2.16.0-dev.0, a sponsored README, 21.9k stars against roughly 1.4k forks, and a feature list that has grown share cards, route cards, reach cards, guided stories, presentation stage, semantic lens and an engineering profile in a few weeks. Feature velocity that high tends to outrun the tests, and the skill file's own instructions to the agent are now long enough that following all of them is itself a nontrivial ask.

And Mermaid is not an import path. Archify reads pasted Mermaid for topology and then authors fresh JSON; automatic parsing is explicitly out of scope. If you have a hundred existing diagrams, this is not a migration target, it is a rewrite.

The thing worth keeping

Verification has layers, and tools reliably ship the cheapest layer while borrowing the vocabulary of the most expensive one.

Archify is the rare case where you can read the documentation and see precisely which layer you bought. It checks form, it checks that citations resolve, it hashes what it hands you, and it refuses to pretend any of that amounts to a judgment about your system. The phrase is right there: authored facts.

So the next time a tool tells you its output is verified, do not ask whether it verifies. Ask which layer, ask whether that layer survives the export, and ask whether anyone has read the three boxes in the middle.

Sources: tt-a1i/archify on GitHub, with README_EN.md and archify/SKILL.md read from raw.githubusercontent.com on 28 August 2026 (cache-busted, after an earlier cached copy served materially older text). Version, license, validation tiers, delivery receipt and setup details come from the SKILL.md frontmatter and body; install commands, install-surface table and the deployment-profile wording come from README_EN.md. Star and fork figures are the counts the repository page served on that date and agree with the Trendshift daily board. Upstream project: Cocoon-AI/architecture-diagram-generator.