visimark

# VisiMark

[![visimark MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/michal-niedzwiedzki/visimark/badges/score.svg)](https://glama.ai/mcp/servers/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](docs/mcp.md) and the [agent skill](skills/visimark/SKILL.md).
- **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`](docs/tutorial/runway.md).
- **Anyone who already lints Markdown** — the
  [pre-commit hook](docs/ci.md#24-git-hooks-and-pre-commit),
  [`remark-lint-visimark`](docs/ci.md#25-the-remarkunified-plugin),
  [`markdownlint-rule-visimark`](docs/ci.md#26-the-markdownlint-custom-rule),
  and the composite [GitHub Action](action.yml).
- **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](#what-it-refuses-to-do)).
- **Obsidian users with a vault of numbers** — the
  [Obsidian plugin](editors/obsidian/README.md), 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](docs/articles/howto-finance-npv-irr-pmt/howto-finance-npv-irr-pmt.md).

## A wrong invoice that renders clean

[`docs/example-invoice-drift.md`](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.net_total                          23300.00 ≠ 25380.00   SUM(Net)
  STALE   lines.vat_total                           5359.00 ≠ 5837.40    SUM(VAT)
  STALE   lines.gross_total                        28659.00 ≠ 31217.40   SUM(Gross)
  STALE   lines.gross_total                        28659.00 ≠ 31217.40   SUM(Gross)
  STALE   schedule.Amount · Signature               8597.70 ≠ 9365.22    Share * lines.gross_total
  STALE   schedule.Amount · Delivery of backend    11463.60 ≠ 12486.96   Share * lines.gross_total
  STALE   schedule.Amount · Acceptance              8597.70 ≠ 9365.22    Share * lines.gross_total
  STALE   schedule.covered                         28659.00 ≠ 31217.40   SUM(Amount)
  STALE   terms.early_pay_total                    28085.82 ≠ 30593.05
  STALE   terms.early_pay_saved                      573.18 ≠ 624.35
  STALE   8 prose anchors bound to the values above

  DATE    schedule.Due    · Delivery of backend   "15.10.2026"
          Dates must be ISO 8601 calendar dates: YYYY-MM-DD.
          Unambiguous — `visimark fmt --fix-dates` rewrites it to 2026-10-15.

  DATE    schedule.Due    · Acceptance            "11/12/2026"
          Dates must be ISO 8601 calendar dates: YYYY-MM-DD.
          Ambiguous: 2026-12-11 or 2026-11-12, 29 days apart. Fix by hand.

  NOTE    schedule.Days   · 2 rows not verified (upstream DATE errors)

  UNDEF   terms.eur_total   unknown name `fx_rate`
          did you mean `fx_eur`?

  VECTOR  recon.variance    `schedule.Amount` is a column, not a value.
          Wrap it in an aggregate: SUM(schedule.Amount)

  CYCLE   late_fees.base → late_fees.fee → late_fees.total → late_fees.base

  27 problems (22 stale, 5 errors)
$ echo $?
1
```

Twenty-seven problems: a payment date ambiguous by twenty-nine days, a cell
someone nudged by hand to make a column look right, a circular reference — all
invisible on the rendered page, all caught before a human had to notice.

## Why this matters now

More and more of the documents that carry numbers are written as text and kept
in Git: reports and research notes, estimates and budgets, quotes and
invoices, project plans, financial summaries. Text is excellent for
collaboration, review and version control. But ordinary Markdown has no way to
say *this number came from these inputs, and it must still agree with them* —
so the moment an input changes, every figure downstream of it is a guess until
a human re-checks it by hand.

VisiMark adds that missing layer. The working stack for collaborating with an
agent is a text editor over lightly formatted artifacts; Markdown already
covers the prose, and this covers the calculation. The arithmetic is not the
value — the audit trail is.

## What it looks like

````markdown
| Item  | Price | Qty |   Net |
|-------|------:|----:|------:|
| pen   |  5.00 |  10 | 50.00 |
| paper |  0.10 | 100 | 10.00 |

```vmark #order
Net   = Price * Qty
total = SUM(Net)
```

Order total: **60.00**<!--vmark=order.total-->
````

Four ideas, and that is the whole format:

- A **`vmark` block** declares formulas for the table above it, and names the sheet.
- **Columns are uniform** — `Net = Price * Qty` is one rule for every row, not a
  formula per cell. Columns with no rule are inputs, and are never overwritten.
- **Aggregates are scalars**, declared alongside. This is what replaces the
  totals row; tables stay rectangular.
- An **anchor** materialises a scalar into a sentence. The HTML comment is
  invisible in every target renderer, so the prose reads normally while the
  number stays machine-checkable.

## The tutorial

[`docs/tutorial.md`](docs/tutorial.md) is the end-to-end tutorial: twenty-eight
short chapters from a plain Markdown table to a checked document, a CI job and a
script reading values back out. It teaches the language in dependency order, every
finding `check` can report, and the one habit that keeps a green check meaningful.
Every transcript in it is real.

There is a side-by-side reader for it at
[`docs/tutorial.html`](https://visimark.dev/tutorial.html),
which shows each block's Markdown source next to its rendering, in lockstep.

## Worked examples

[`docs/example-invoice.md`](docs/example-invoice.md) is a complete B2B invoice
that computes itself: line items, VAT, a payment schedule derived from the gross
total, early-payment terms, a currency conversion, and a reconciliation that
proves the instalments sum to the invoice. Its appendix explains each mechanism.

[`docs/example-invoice-drift.md`](docs/example-invoice-drift.md) is that same
invoice with the drift shown at the top of this README — the `27 problems`
transcript above is `check` reading this exact file, and its appendix walks
through every one of the 27 problems.

[`docs/example-quote-plain.md`](docs/example-quote-plain.md) is the other
direction: a quote with no VisiMark in it at all — no `vmark` block, no
anchor, just a table and a total written in prose, the way an agent hands one
over before anyone has wired it up. `visimark infer` reads it and proposes the
rules that reproduce every number already there:

```console
$ visimark infer docs/example-quote-plain.md
docs/example-quote-plain.md  table at line 10 — 4 rows, 7 columns

  column rules
    Revenue    = Seats * Fee                  4/4 rows
    Materials  = Revenue * 0.08               4/4 rows
    Delivered  = Revenue + Materials          4/4 rows

  constants worth naming
    0.08   also appears as "8%" in prose, line 18

  scalars matching figures in prose
    72        line 17  = SUM(Seats)                seats_total
    27600.00  line 18  = SUM(Revenue)              revenue_total
    2208.00   line 19  = SUM(Materials)            materials_total
    29808.00  line 19  = SUM(Delivered)            delivered_total
    530.00    line 20  = AVG(Fee)                  fee_avg

  no rule found — treating as inputs
    Module, Format, Seats, Fee

  also fits, not proposed
    Delivered = Revenue * 1.08    prefers a rule over materialised columns
    Delivered = Materials * 13.5  prefers a rule