{ "markdown": "

\n \n \n \"Mirofy\n \n

\n\n

\n Diagrams of your system that cite their sources — and say what they could not see.\n

\n\n

\n \"mirofy-cli\n \"MIT\n \"Zero\n \"85\n \"Output\n

\n\n

\n \n \n \n \"A\n \n \n

\n\n

\n This is the whole product: one HTML file, open in a browser. Every colour\n in it is the system’s own vocabulary — backend, database, cloud,\n security, message bus, external — and nothing else. Colour never marks\n where an arrow goes, only what a thing is.\n
\n Open this exact file ↗ —\n click any node for its evidence, trace what reaches it, search it, present it.\n

\n\n---\n\n## What it is\n\nPoint Mirofy at a repository. It reads the code into an **evidence graph**,\nbuilds a **model** from that graph, and compiles the model into **one HTML\nfile** you can open, search, share and check.\n\nEvery relationship it draws can answer one question: *what is the evidence for\nthis?* Each carries the file, the line range and the commit it came from. Where\nnothing is known, the diagram **says so** instead of filling the gap.\n\n

\n \"scan\n

\n\nRun it against this repository and you get this — not a mock-up, and not drawn\nby hand:\n\n

\n \"Mirofy's\n

\n\n

\n Every box is the same colour here, and that is the point. All twelve of\n these are the same thing — a package, derived from a manifest — so there is\n nothing for colour to say, and it says nothing. The picture at the top is\n colourful because that system genuinely has six kinds in it. A tool that\n tinted these boxes to look livelier would be inventing a distinction it had\n not found.\n
\n Open the live one ↗ — click any\n node for the file, line range and commit behind it.\n

\n\n## Install\n\n**Nothing to install** — one command, and a diagram opens:\n\n```bash\nnpx mirofy-cli map . # YOUR repository, mapped, in one command\nnpx mirofy-cli demo # a finished artifact, to see what this produces\nnpx mirofy-cli init # a starter document of your own to edit\nnpx mirofy-cli render architecture architecture.json\n```\n\n**Give it to your agent instead** — one line, and the skill installs for Claude\nCode, Cursor, Gemini CLI, Amp and a dozen others:\n\n```bash\nnpx skills add Hasan-Laraib/Mirofy\n```\n\nThen ask: *map this repository's architecture*. Your agent reads\n[`SKILL.md`](packages/core/SKILL.md) and drives the same CLI.\n\n**In Claude Code**, the plugin carries both the skill and the MCP server:\n\n```\n/plugin marketplace add Hasan-Laraib/Mirofy\n/plugin install mirofy@mirofy\n```\n\nEvery one of these routes is the same package. The agent never draws the\ndiagram — it runs the CLI you would have run, which is why nothing it reports\ncan drift from what the CLI reports.\n\n`map` runs the whole pipeline in the directory you point it at — scan, model,\ncompile, layout, render — and writes `architecture.html` next to your code.\n`map --out ` sends the diagram and the intermediates there instead, so\nnothing lands in your repository; without it the intermediates go to\n`/scan`. Naming an output path still wins over both. It works on a repository that declares no\nworkspaces: where there are no packages to draw, it models the **source\ndirectories** and the imports between them.\n\n### What it reads\n\n**JavaScript and TypeScript** imports · **Python** imports · **Go** imports ·\n**Java** imports · **Rust** imports · **Kotlin** imports ·\n`package.json` workspaces · Express and Next routes · `docker-compose`.\n\nThat is the whole list, and the list is the point. Everything else is\n**reported, not skipped**: `coverage.md` names every file no adapter opened,\ngrouped by type, and `map` says so on its way out when the unread files\noutnumber the read ones. Point it at a Ruby repository and you get an honest\nempty answer naming every unread `.rb` file — not a confident small one drawn\nfrom the two JavaScript files in an `examples/` folder.\n\nPython resolves by **file existence**, not by convention: relative imports\nagainst the importing file's directory, absolute ones against the repository\nroot and any directory that actually holds a package. A specifier that matches\ntwo source roots is a gap naming both, because which one wins depends on\n`sys.path`, which is configuration and not in the source.\n\nGo resolves against the module path `go.mod` **declares**, and decides the\nstandard library the way the toolchain does — a first path segment containing a\ndot is a domain, and a domain means a module fetched from somewhere. Java\nbuilds its index from the `package` statements files **declare**, not from\ndirectory layout: Maven convention puts `com.acme.store` under\n`src/main/java/com/acme/store` and convention is not always, but the\ndeclaration is what the compiler reads.\n\nRust peels a `use` from the right until a real file appears, because\n`use crate::a::b::C` does not say which of a, b or C is the file. It reads the\ncrate name and the source root from `Cargo.toml` — including a declared\n`[lib] path`, since `src/` is only the default — and knows that Cargo compiles\nevery direct child of `tests`, `benches` and `examples` as its own crate.\n\nKotlin reads its type index from the declarations themselves — `class`, `interface`,\n`object`, `typealias` and `fun interface` among them — rather than from file\nnames, because a Kotlin file need not be named after the type\nit holds and may declare several. It shares that index with Java: the two\ncompile to one namespace and import each other freely, so an index of one\nextension reports a real edge to the other as a missing type.\n\nIn every one of them, an import that names something inside this repository\nwhich is not there is a gap — never a dependency on a published copy of\nyourself.\n\n`npx mirofy-cli guide \"show an API request with a cache miss\"` picks the\ndiagram type for you if you are not sure which one you want.\n\n**As a CLI you keep** — `npm install -g mirofy-cli`. The command it installs is\n**`mirofy`**; the package carries the `-cli` suffix because npm refused the bare\nname as too close to the existing `minify`.\n\n**From source** — no install at all, because there is nothing to install:\n\n```bash\ngit clone https://github.com/Hasan-Laraib/Mirofy.git\nnode Mirofy/packages/core/bin/mirofy.mjs demo\n```\n\nThat works on a bare checkout with no `npm install`, because every package here\nhas zero runtime dependencies.\n\n**As an agent skill** — build the bundle and copy it where your agent looks:\n\n```bash\ngit clone https://github.com/Hasan-Laraib/Mirofy.git\ncd Mirofy && npm install && npm run build:skill\n\ncp -r dist/mirofy ~/.claude/skills/ # Claude Code\ncp -r dist/mirofy ~/.agents/skills/ # Codex CLI, opencode\n```\n\nThen ask: `Use mirofy to map this repository's runtime architecture.`\n\nThe bundle is 2.8 MB and named for the skill inside it — copying `packages/core`\ninstead installs a skill called `core` that says in its own frontmatter it is\ncalled `mirofy`, and drags the test suite along with it. Before writing the\nbundle, `build:skill` copies it somewhere with no repository around it and\nrenders a diagram: a bundle that only works inside its own checkout is not a\nbundle.\n\nNothing is downloaded at runtime and nothing phones home — there is no update\ncheck, because a tool that reaches the network to tell you about itself is a\ntool that reaches the network.\n\n## The pipeline, one step at a time\n\n`mirofy map` is these five steps in order. Run them yourself when you want to\nkeep an intermediate, or point a step somewhere else:\n\n```bash\nnpm run scan # repository → evidence graph\nnpm run model -- --from-graph --graph scan/evidence-graph.json\nnpm run compile # model → a bounded view\nnpm run layout # view → positioned document\nnode packages/core/bin/mirofy.mjs render architecture scan/diagram.json out.html --repo-root .\n```\n\nAgainst **this repository** it records **1,220 facts** across **221 files**,\nwith **15 gaps** it could not read; derives **18 components and 20\nrelationships** — every one citing the file and line it came from — and draws\n**twelve**, recording what it left out and why.\n\nThose figures are checked, not remembered — see\n[the numbers on this page](#what-is-proved) below.\n\nThose commands reproduce the diagram at the top of this page. It is checked in\nunder `assets/` as documentation; the interactive artifacts are built, never\nstored.\n\nNo repository? Author a JSON document, or convert a Mermaid diagram:\n\n```bash\nnode packages/core/bin/mirofy.mjs import mermaid design.mmd\nnode packages/core/bin/mirofy.mjs render architecture design.json out.html\nnode packages/core/bin/mirofy.mjs validate architecture design.json --json\n```\n\n## What you get\n\n

\n \"One\n

\n\n

\n Open any edge and it tells you why it is on the page: the relation, its\n provenance class, the file and line it came from, and the commit it was\n checked against. Underneath is the half most tools leave out — what the\n scanner could not determine, written down instead of guessed.\n
\n That record is real, and taken from this repository. So is the gap.\n

\n\nThree claims about the pictures below, each with the thing that keeps it honest.\n\n\n\n\n\n\n
\n\"An\n

Colour tells you what a node is, never where an arrow goes.\nSix presets, light and dark. meridian holds every arrow at graphite\nso hue is never doing two jobs at once.\n
\nProved by conformance row 4.16 · open this exact artifact ↗

\n		\n\"A\n

Five diagram types, one schema, one validator.\narchitecture · workflow · sequence · dataflow · lifecycle — the same typed IR\nbehind all of them.\n
\nProved by conformance row 1.1, which renders all five from their baseline\nfixtures in one pass · open this exact artifact ↗

\n
\n\n

\n \"The\n

\n\n

\n One file. No server — and nothing it needs from the network.\n
\n The diagram, the evidence, the search and every interaction are in the\n file. The one thing it ever asks the internet for is a webfont\n it does not wait for and does not need, and it falls back to\n your system monospace without it.\n
\n Checked on every run by scripts/check-readme-claims.mjs,\n which fails the build the moment a reference appears that could block first\n paint or change what the diagram says — and which fails just as loudly if this\n sentence ever overstates what the artifact actually fetches.\n

\n\n

\n All thirty are live ↗ — five types × six\n presets, rebuilt from every commit.\n

\n\n### The viewer, actually being used\n\nNot mock-ups. Every frame below is a capture of the shipped viewer, driven\nthrough real clicks by `scripts/build-screenshots.mjs` — which fails rather than\nreuse an old picture if a control is renamed or a panel stops opening, and\nrefuses to save a shot of a feature that did nothing.\n\n\n\n\n\n\n\n\n\n\n
\n\"The\n

Find anything. Typing api narrows ten nodes to\ntwo. The capture asserts the list actually shrank — a screenshot of an unfiltered\nlist is not a screenshot of search.

\n		\n\"A\n

Ask a node where it came from. conformance,\nsource-backed, cited to packages/conformance/package.json\nat a pinned commit. This one is captured from this repository, because\nthe authored example has no citations and a passport with the evidence missing\nwould illustrate the claim by not showing it.

\n
\n\"Authored\n

Follow what reaches what. Upstream of Worker:\nsix nodes, six links, five hops — lit, with everything off the path dimmed. The\ncapture picks the node with the deepest reach, so the picture is of a\npath and not of one arrow.

\n		\n\"The\n

Compare roles across the whole system. The Semantic Lens\nanswers provenance and kind for every node at once, rather than one node at a\ntime.

\n
\n\n---\n\n## What it does that a diagram tool doesn't\n\n### It refuses to guess\n\nA file the scanner cannot parse becomes a recorded **gap**, never a silent\nomission. Every fact is labelled with one of six provenance classes, so\n`source-backed` and `inferred` never look alike.\n\nThe same rule holds where a decision has to be made that evidence cannot\nsettle. A derived component's kind is `package` — the scanner knows a manifest\nexists, not whether something is a \"backend\". 784 imports of Node builtins are\n*counted and named*, not drawn and not dropped in silence. In Python a computed\n`importlib.import_module(name)` is a gap with its line, and docstrings are\nblanked before parsing — a docstring full of example imports would otherwise\nbecome edges the code does not have, cited to prose. A citation with no\npinned commit to verify against is discarded rather than shown, because a\ncitation nobody can check is worse than none — `map` reads the commit from\nyour `origin` remote, or takes `--repo-url` and `--revision` when there is no\nremote to read.\n\nA passport lists at most three sources, because forty-three links is not a\npassport. It says **“Showing 3 of 43 cited sources”** when it does, so a bound on the\ndrawing is never mistaken for a claim about the evidence.\n\n### It answers questions about your system\n\n```bash\nnpm run explain -- callers api # what points at api\nnpm run explain -- impact api # what is downstream of it\nnpm run explain -- find payment # id, label, kind or metadata match\nnpm run explain -- gaps # what the scan could not read\n```\n\nEvery answer names the unread files that could change it. *\"Nothing calls\nPaymentService\"* is useful if the scanner read everything and reckless if six\nfiles failed to parse — so an empty result means **not found**, never **does not\nexist**.\n\n`impact` answers as *reachability* and refuses to be more. What is connected is\na fact about the graph; whether a change breaks it is a judgement about a\nrunning system, and Mirofy has no evidence for that.\n\n### Your agent can ask too\n\nThe same queries over MCP — nine tools, the same engine, not a second\nimplementation that could disagree with the CLI:\n\n```json\n{ \"mcpServers\": { \"mirofy\": { \"command\": \"npx\", \"args\": [\"-y\", \"mirofy-cli\", \"mcp\"] } } }\n```\n\nPoint any MCP client at that. It reads `./scan` — whatever `map --out ./scan`\nlast wrote — relative to the directory the client starts it in; `--model` and\n`--graph` override. No clone, and nothing to install first.\n\nThe incompleteness warning is in the **prose** an agent reads, not only the\nJSON. Most clients feed the text to the model and drop the rest.\n\n### It checks architecture rules — with three outcomes, not two\n\n```bash\nnpm run assert # reads architecture-rules.json\n```\n\n`pass`, `fail`, and **`unproven`**. A rule that found no violation over a scan\nwith unread files has not been *shown* to hold, so it never counts as passing.\nTurning a gap into a green check is the one failure this project exists to\navoid.\n\nSome gaps are permanent — a dynamic import whose base path is a variable cannot\nbe resolved without guessing. Those can be **acknowledged**, one path at a\ntime, quoting the gap's reason and carrying a written argument. An\nacknowledgement written for a dynamic import stops applying the day that file\nfails to parse instead. And a rule that passes on the strength of one says so:\n\n```\n[ok ] no-cycles — No violation. 8 unread file(s) are acknowledged as unable\n to hide one; this rests on that judgement, not on a complete scan.\n\n2 passed, 0 failed, 0 unproven of 2\n2 of those rule(s) rest on acknowledged gaps, not on evidence.\n```\n\n### It tells you what is moving\n\n```bash\nnpm run timeline # cited-file churn, newest first\nnpm run drift -- --base a.json --head b.json # what two scans say differently\n```\n\nDrift reports changed facts and nothing else — no score, no risk label, no merge\nrecommendation. It runs on every pull request and can never fail one.\n\n---\n\n## The number we would rather not publish\n\nA benchmark asks one question: hand a model a written brief, and how often does\nthe diagram it writes come out **usable on the first attempt**?\n\nRight now, over eight briefs authored by Claude Code: **2 of 8**.\n\n```bash\nnode scripts/benchmark.mjs --author \"\" --model \"\" --keep benchmarks/corpus/mine\nnode scripts/benchmark.mjs --replay benchmarks/corpus/mine\n```\n\nThat is not a good number and it is the real one. Three things make it worth\nprinting anyway.\n\n**Usable means clean, not accepted.** A warning is the diagram telling you it\nneeds a second look, which is exactly what a first-pass rate is supposed to\nexclude. Two more documents in that set validate with zero errors and are still\nnot counted.\n\n**It is measured against a saved corpus, not a fresh one.** `--keep` stores what\nthe model produced; `--replay` re-runs the tool over those exact documents\nwithout calling the model again. Without that split, every re-run changes both\nthe documents and the tool, and any movement can be attributed to either — which\nis why the rate sat at zero for weeks without anyone being able to say what was\nwrong. A replay cannot even claim a different author: the model is read from the\nsaved manifest, and `--model` is refused if it disagrees.\n\n**It moves for reasons you can name.** The last change to the layout engine took\nthe same eight documents from 0 of 8 to 2 of 8, and total composition errors\nfrom 121 to 34, because a diagnostic that said *\"shorten the label or widen\nsize\"* was asking an author to rename part of their system to fit a box the\nrenderer had picked. The renderer now widens the box.\n\nIf you compare this to a number published elsewhere, check what was measured.\nA rate for an agent that can call a validator and repair its own output, reviewed\nby a person at the end, is a different measurement from a blind single-shot\nmodel — not a worse one, a different one. Ours is the second kind.\n\n---\n\n## Inside the artifact\n\n- **Node Finder**, **Semantic Lens**, **Semantic Radar** — search, filter and\n overview a diagram too large to read at once\n- **Route Probe** — resolve a directed path and see it traced, hop by hop\n- **Semantic Passport** — click a node for its type, tags and cited evidence,\n with a **Verified Source Beacon** on anything backed by a pinned commit\n- **Your code, drawn apart from everyone else’s** — a module you wrote is\n solid, a third-party package is dashed. Not a colour: the colour-blind-safe\n preset already spends all seven of its hues on the seven semantic roles, so\n an eighth would be a distinction only some readers could see\n- **Guided views**, presentation mode, motion governor, and `?embed=1`\n- Three exports, copied straight to the clipboard:\n - **Export → Share Card** — a 1200×630 PNG in the current theme and preset\n - **Export → Route Share Card** — the exact route a Route Probe resolved\n - **Export → Reach Share Card** — the set a reachability query returned\n\nA card shows what the reader actually did. None of them claim validation, and\nnone are produced from a query that returned nothing.\n\n```bash\nnpm run gallery # every type in every preset → preview/index.html\nnpm run build:site # the same, plus this repo's self-model → site/\n```\n\nThe second is what CI publishes to\n**[hasan-laraib.github.io/Mirofy](https://hasan-laraib.github.io/Mirofy/)** on every commit. Nothing\nis committed: the site is built from the code at the commit it describes, so it\ncannot go on quietly describing an older one.\n\n## Taking it elsewhere\n\nThe interactive file is ~720 KB and earns it. None of that survives a README, a\npull request or a Notion page, though — all of them strip scripts. So:\n\n```bash\n# 19 KB standalone SVG: no scripts, no stylesheet needed\nnode packages/core/bin/mirofy.mjs render architecture in.json out.svg --format svg-static\n\n# or open it in an editor you already own\nnpm run export -- drawio architecture in.json\nnpm run export -- excalidraw architecture in.json\n```\n\n| where it goes | how |\n|---|---|\n| README, pull request, Notion, Confluence | `svg-static` |\n| Figma, Canva, Illustrator, Sketch | `svg-static` — styling is written as attributes, so it arrives with its colours |\n| diagrams.net · draw.io VS Code extension | `drawio` — real shapes and connectors |\n| Excalidraw · Obsidian · VS Code | `excalidraw` — bound arrows, movable boxes |\n\nThe SVG carries its styling **twice**: in a stylesheet and on the elements. In\nSVG a stylesheet outranks an attribute, so a browser renders from the CSS, and\nthe attributes speak only where the CSS is ignored — which is exactly what\nFigma, Canva and Illustrator do. Without them the diagram imports shape-correct\nand colour-dead.\n\nBoth editor exports say exactly what they lost, computed from *your* document\nrather than recited as a disclaimer. A diagram you can only edit in the tool\nthat made it is a diagram held hostage.\n\n## What is proved\n\nThe conformance matrix has **105 rows**. **85 are proved without a browser**;\n19 more need headless Chrome (`MIROFY_CHROME`), bringing the total to 104.\n\n```bash\nnpm run check # lint, types, 1,000+ tests, golden parity, conformance, size, audit\n```\n\nEvery row names a test, and the title must match character-for-character — a row\nwhose proof file passes while its own test was renamed counts as **unproven**,\nnever as passing. One row (6.10, deterministic ZIP packaging) is UNPROVEN and\ncounted as such rather than quietly dropped.\n\n**Skipped is not passed.** Browser rows never count toward the proved total\nunless a browser actually ran them.\n\nAnd the numbers on this page are checked too:\n\n```bash\nnode scripts/check-readme-claims.mjs\n```\n\nIt counts the matrix, reads the tool list the MCP server serves, renders an\nartifact to measure it, and re-runs the benchmark. This exists because a review\nfound three numbers here wrong at once — none of them dishonest, all of them\ntrue when written and left behind by the repository. A page that argues for\nchecking claims has no business making unchecked ones.\n\n## Evidence and provenance\n\nSix classes, never blurred:\n\n| class | means |\n|---|---|\n| `authored` | a human wrote it |\n| `source-backed` | read out of a cited file and line range |\n| `statically-derived` | computed from code without running it |\n| `config-derived` | read from a manifest — configuration, not code |\n| `runtime-observed` | seen in a real run |\n| `inferred` | a guess, and labelled as one |\n\nSource citations verify against a pinned 40-character commit in a real local\ncheckout before they render. A path that does not exist at that revision is an\nerror, not a broken link.\n\nSeveral repositories can be declared at once, and a citation names which one it\nbelongs to. Verifying against *a* repository rather than *the right one* is how\na path from a sibling repo passes as evidence for this one.\n\n## Packages\n\n| package | does |\n|---|---|\n| `scanner` | adapters that read a repository into facts and gaps |\n| `evidence` | append-only evidence graph, query, honest coverage |\n| `model` | the system model: stable ids, evidence refs, human overrides |\n| `compile` | view compiler and the planner seam |\n| `explain` | graph queries, architecture rules, drift, timeline |\n| `mcp` | the model as agent context |\n| `import` | Mermaid into typed documents |\n| `export` | draw.io and Excalidraw escape hatches |\n| `layout` | constraint layout: intent to coordinates (dev-time) |\n| `core` | renderers, schemas, validators, CLI |\n| `viewer` | the interactive viewer, built into one template |\n| `benchmark` | first-pass usable rate, over a saved corpus |\n| `conformance` | the matrix, and the tests every row names |\n\n**Zero runtime dependencies** in every package. The artifact ships nothing but\nitself.\n\n`packages/core/assets/template.html` is **generated** from `packages/viewer/`.\nNever edit it directly — edit the source and run `npm run build:template`.\n`npm run check:template` rebuilds from source and fails if the committed file\nhas drifted.\n\n## Attribution\n\nEvery artifact says what made it. The viewer footer is **dismissible** — the\ndiagram is yours, and a banner you cannot close is an imposition on someone\nelse's document. Share Cards carry a **permanent** one, because a card travels\nwithout its context and lands where nothing says where it came from.\n\nIt names the tool and claims nothing about the diagram, and carries no URL: a\nlink baked into every shared artifact outlives the address it points at.\n\nMIT. `packages/core/LICENSE` retains, verbatim, the required third-party\ncopyright notice for the imported rendering core; the root `LICENSE` covers this\nproject's own work.\n", "bytes": 28188, "sha": "c4087595e483deb07cfadaa18be969a1dff1ce9fff451edeae9d467b2ac520a2", "repo_slug": "hasan-laraib/mirofy", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_hasan_laraib_mirofy_f71af32a/readme" }