michal-niedzwiedzki/visimark

A document integrity layer for Markdown: it checks that every number in a document still matches the formula that produced it, so an agent's correct formula can't ship with a wrong total.
VisiMark checks the numbers in Markdown documents, especially ones an agent wrote. Every computed value carries its formula, a machine proves the two still agree, and CI fails when they don't. The document stays plain Markdown.
This matters most when the Markdown is written or edited by an AI agent.
Agents are reliable at writing formulas and unreliable at the arithmetic those
formulas describe: Net = Price Qty is something an agent gets right,
50.00 is something it guesses. Write the formula instead of the number and
the number stops being a claim and becomes a derivation — reviewable in a
diff, re-runnable, enforceable in CI. The agent writes, VisiMark verifies, Git
records the result.
A VisiMark document is an ordinary Markdown file. It renders correctly on
GitHub, in VS Code preview, and through pandoc to both HTML and Word, today,
with no plugin — verified, not assumed. What VisiMark adds is that every
computed number in it carries the formula that produced it, that a machine can
prove the two still agree, and that a change to either shows up as a small,
readable diff.
## Who it's for
Six audiences so far, each with a specific entry point. Kept short on
purpose — it grows when one of these gets a real user, not before.
Agents and reviewers verifying a document a model just wrote — the
MCP server and the agent skill.
Analysts, founders, capacity planners who want a what-if without a
second tab or a copy of the file — eval --scenario, worked through on a
headcount model in docs/tutorial/runway.md.
Anyone who already lints Markdown — the
pre-commit hook,
remark-lint-visimark,
markdownlint-rule-visimark,
and the composite GitHub Action.
Engineers, scientists, anyone with a unit — declare it in a bracket after
a name, Rate [PLN] or speed [m/s] = Distance / Duration, and check
refuses kg + m and derives km/h (see
What it refuses to do).
Obsidian users with a vault of numbers — the
Obsidian plugin, which marks every computed
value in reading mode and Live Preview.
Finance — NPV, IRR, PMT, and the decimal precision the three of
them force you to declare, worked through in
a loan and an investment appraisal.
## A wrong invoice that renders clean
docs/example-invoice-drift.md is a real B2B
invoice after someone raised the on-call hours from 12 to 20 and updated
nothing that depends on it. It renders as a clean, plausible invoice on
GitHub, in a Markdown preview, anywhere — which is the entire argument for
this project. Every number in it carries the formula that produced it; the
syntax follows further down. Here is visimark check reading the same file a
reviewer just skimmed and approved:
console
$ visimark check docs/example-invoice-drift.md
docs/example-invoice-drift.md
STALE lines.Net · On-call support 3120.00 ≠ 5200.00 Qty Rate
STALE lines.VAT · On-call support 717.60 ≠ 1196.00 Net vat
STALE lines.Gross · On-call support 3837.60 ≠ 6396.00 Net + VAT
STALE lines.Gross · Discovery workshop 4428.50 ≠ 4428.00 Net + VAT
STALE lines.nettotal 23300.00 ≠ 25380.00 SUM(Net)