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.

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:

$ 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

| 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 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, which shows each block's Markdown source next to its rendering, in lockstep.

Worked examples

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 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 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:

$ 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 over materialised columns

docs/example-quote-plain.md  table at line 24 — 3 rows, 4 columns

  column rules
    Amount  = Share * unnamed1.delivered_total  3/3 rows

  scalars matching figures in prose
    29808.00  line 30  = SUM(Amount)               amount_total

  no rule found — treating as inputs
    Stage, Share, Due

  also fits, not proposed
    Amount = Share * 29808    prefers a rule over materialised columns

4 rules, 0 aliases, 6 scalars, 6 anchors.

A rule is proposed only if it reproduces every row exactly, at that column's own precision — never a best fit, never a threshold, and also fits, not proposed is listed rather than silently dropped, because a rule over materialised columns beating one with a bare constant is a judgment call worth seeing. --write inserts exactly the blocks and anchors above and rewrites nothing else. A rule that fits every row but one is never written; it is reported as a near-miss instead — the tool telling you the document already has a wrong number in it, before anyone runs check on it. The document's own appendix walks through every mechanism, including that near-miss case.

infer is the way in for the document check would otherwise have nothing to say about: one with no formulas at all. Pairing the two closes the loop — infer gets a plain table wired up, and check keeps it that way.

How it works

VisiMark parses the document, builds a dependency graph across every sheet, sorts it topologically, and evaluates in decimal arithmetic. Circular dependencies are reported with the full path through the cycle.