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: block required minWords=15 noPlaceholder -->
## Crew Status
<!-- mdv: code required lang=sh -->
<!-- mdv: endcode -->
<!-- mdv: endblock -->

This says: the report must have a Crew Status section with enough substance for Mission Control to act on, no template residue like TODO or TBD, plus a shell code block — say, the command that pulled the telemetry. 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.

```sh
./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.

0 errors, 0 warnings

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 you delete the prose under ## Crew Status before hitting send. Run again:

sol47.md:1  error  [too-few-words] Too short
    The "Crew Status" section is too short (5 words).
    fix: Add more detail - aim for at least 15 words.

1 error, 0 warnings

mediva names the section, the rule (too-few-words), and the line — no archaeology required. Fill the section back in, re-run, and you're green. The antenna stays cold until the report is real.

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.