md-business

Your agent writes the code.
It never sees the spec.

Invoices, specifications and test sheets live as Markdown, not inside a .docx.
People read PDF and Sheets. Agents read and edit the same file.

Download the desktop app GitHub Chrome extension Windows / macOS · MIT
The md-business desktop app. On the left, a tree of Markdown files grouped into invoices, design documents, test specifications and reports. In the middle, the Markdown source of an invoice with its YAML frontmatter: issuer, registration number, line items and tax rates. On the right, the same file rendered as a Japanese qualified invoice with a per-rate tax breakdown and a total of 566,980 yen.
A qualified invoice (適格請求書), rendered for a person to sign off on. It is one Markdown file — your agent can open it, change a line, and show you the diff.

Why documents go stale

The design changes → the specification is a .docx on a shared drive → the agent cannot open it → it guesses from the code → the document stops being true → nobody opens it again.

Every part of the work has moved to text an agent can read — except the documents that say what the work is supposed to be. Word, Excel, PDF and most document SaaS hand an agent a binary blob, or an API with no diff. So the agent works from the code, and the document drifts away from it.

md-business is an open-source framework (MIT) that moves the source of truth to Markdown — invoices, test specifications, design documents, API specifications, database design documents — with structured YAML frontmatter and JSON Schema validation. It does not ask anyone to give up the format they review in: people read a PDF, a Google Sheet or a purpose-built viewer, while agents read, edit, validate and diff the same underlying file.

How it fits together

Markdown                         ← the source of truth. One file per document.
   ↓
JSON Schema validation           ← a broken invoice fails before anyone signs it
   ↓
An agent edits it                ← over MCP, in the folder you have open
   ↓
git diff / review / approval     ← you see exactly which line changed
   ↓
PDF · Sheets · Chrome · desktop  ← how people actually read it

The last row is the point. A document counts as reviewed only when a person reads it in a form they trust — an A4 invoice, a spreadsheet of test cases. Markdown underneath does not change that.

A look around the desktop app

What the app does, before you install anything.

A basic design document open in a two-pane split view. The left pane holds Markdown with frontmatter — document number, version, authors, reviewers, related documents — and the right pane shows the same content laid out as a specification, with a draft badge, an author table and a reviewer table.
Write on the left; the right side keeps up as you type. What you see is what the PDF will be, so you do not have to save to find out.
The same basic design document, scrolled to its system architecture section. The left pane holds a fenced block of YAML listing nodes — an API gateway, an order service, an order database, two queues — with a type and a group on each. The right pane shows those same nodes drawn as a boxed architecture diagram, grouped into front end, the subsystem itself, and external services, with labelled arrows between them. Below the diagram sits its title, centred — the same line written in the block.
Architecture diagrams come from the same source. You list what exists and what talks to what; you do not place boxes. Drawing is zumen, which means the diagram is text your agent can edit and Git can diff — and it ends up in the PDF like anything else.
A test specification open as a spreadsheet-like grid. Numbered cases with steps and expected results, each row tinted by its result column: green for pass, red for fail, amber for on hold, plain for not yet run. Buttons below the grid add, duplicate, clear and group rows.
Test specifications open as a grid, so whoever runs the tests fills in results the way they would in a spreadsheet. The file underneath stays a plain TSV that Git can diff line by line.
The same invoice with the right-hand panel switched to its MCP tab. It shows a local server address, a button that writes the connection settings into the folder that is open, and a log of the calls an AI client has just made — search_documents, read_tsv, read_document, validate_document — each with a timestamp and the file it touched.
Point an AI client at the folder you have open — Claude Code, Claude Desktop, Cursor, Cline — by handing it the connection settings once. Every call it makes is listed here, so you can see what it read and what it changed.
The print dialog over the invoice, set to save as PDF, with the A4 page preview on the right showing the finished invoice: issuer and recipient blocks, line items, the per-rate tax breakdown, the total and the bank transfer details.
Print to A4 when the document is done. The page comes out as it looked on screen — there is no separate template to keep in sync with the source.

These are captures of the app itself against a seeded, fictional workspace (scripts/demo-workspace), not mockups — no real company, registration number or bank account appears in them. The interface is shown in Japanese here; it also ships in English, 中文 and 한국어.

What you can write today

invoice stable

Japan-compliant qualified invoice (適格請求書) with registration number, per-rate tax breakdown, and totals filled in for you.

spec stable

Basic design specifications with structured sections for system overview, screens, data flow, and acceptance criteria.

test-spec stable

Test sheets as a grid, with pass / fail / on-hold per case and a round trip to Google Sheets.

api-spec planned

API endpoint specifications with request / response shapes and example payloads.

db-spec / nosql-db-spec planned

RDB and NoSQL schema design documents with field-level definitions and relationships.

How you read and edit them

Desktop app Windows / macOS

Standalone viewer and editor (Tauri 2 + SvelteKit). Purpose-built viewers for each document type, live split-view editing, A4 PDF export, self-updating. A built-in MCP server lets an AI client (Claude Code, Claude Desktop, Cursor, Cline, …) read and write the documents in the folder you have open — copy the connection settings from the MCP tab and paste them once.
Download →   Connect an AI assistant →   User guide →

Chrome extension published

Open a local .md in Chrome, preview it as a rendered business document, and export to A4 PDF.
Install from Chrome Web Store →

Google Workspace add-on under review

Edit test specifications and other Markdown business documents as a Google Sheet, then push the result back to a GitHub repository as a single commit — same mental model as git push.

PWA viewer in development

Astro 5 + Lit web components viewer for browser-based preview without installation.

Renderer (Paged.js)

A4 print-quality PDF generation from Markdown source via Paged.js.

Better with zumen

zumen icon: an architecture diagram shaped like a tree that splits from one into two, on dark grey.

zumen — diagrams the AI draws, you fix, and your fix survives

An architecture-diagram editor whose source of truth is text. Fix one spot in a diagram an AI drew, and the next time the AI redraws it, your fix is still there. It has an MCP server, so an agent can draw directly.

Same idea, so they fit together. md-business keeps documents, zumen keeps diagrams — both as text that people and AI edit in place. The design document lives in md-business, the architecture diagram inside it in zumen, and neither ends up in a separate binary format: you diff both in the same repository.

Write the diagram inside the design document, as text. Put a ```zumen fence in the body and it renders as a diagram in the preview, the PDF, and the HTML and image exports. When the system changes, you edit the fence — no redrawing and re-pasting. Connect an agent to both MCP servers and it can fix the diagram while it fixes the document.

```zumen fences arrive with the next desktop release.

Not there yet

More