Quickstart

LOG ENTRY — SOL 47: Mission Control will not accept a status report that just says "still alive lol." They want a real report. Good news: I can make the habitat's computer reject the bad ones before they burn 12 minutes of light-lag getting to Earth.

You're Mark Watney. You're stranded, you're improvising, and you have to send a status report home every sol. Let's set up a contract so a half-finished report never leaves the antenna.

1. Install

npm install -D mediva

2. Write a contract

A contract is plain Markdown. Open a tag, attach rules, close it. Save this as status.mdv.md — the shape every sol report must have:

<!-- mdv: section required minWords=15 noPlaceholder -->
## Crew Status
<!-- mdv: endsection -->

This says: the report must have a Crew Status section with enough substance for Mission Control to act on, and no template residue like TODO or TBD. minWords catches the "still alive lol" transmissions; noPlaceholder catches the unfinished template scraps.

3. Validate a document

Here's today's report, sol47.md:

## Crew Status

One crew member, nominal and still stubborn. Oxygenator stable, water reclaimer holding at ninety one percent, and the Hab potatoes remain emotionally complicated. Telemetry pulled with `./pull-telemetry.sh --sol 47`.

Beam it through the validator:

npx mediva check sol47.md --schema status.mdv.md

The CLI flag is named --schema; in these docs that schema file is the contract.

Nothing. Silence is the pass — mediva only speaks when something needs fixing, and it exits 0. Clean transmission. Mission Control gets a report they can actually act on.

4. Break it, read the failure

Now imagine a dust storm hits, you're exhausted, and tonight's report under ## Crew Status is just "Still alive. Potatoes fine." Run again:

sol47.md
  3  warning  Too short  too-few-words
      The "Crew Status" section is too short (4 words).
      fix: Add more detail - aim for at least 15 words.

✖ 1 problem (0 errors, 1 warning)

mediva names the section, the rule (too-few-words), and the line — no archaeology required. Substance floors like minWords report as warnings by default: the transmission still goes out (exit 0), but the gap is named. Fill the section back in, re-run, and the note disappears. Want the antenna to stay cold until the report is real? Promote the check in your contract — minWords=15 error=too-few-words — and the same finding becomes a blocking error.

I'm going to have to science the heck out of this contract. (You won't — it's already done.)

Next

• Contracts — file layout and composing rules.
• Recipes — gate a PR body, enforce a changelog, validate AI docs and issue forms, lock a status table or ADR, and scan a monorepo.
• Reference — the full tag and rule catalog.