Validate docs across a monorepo

One scanner pass across the fleet beats one hand-written command per ship.

In a monorepo, keep every contract next to the document it protects:

packages/api/README.md
packages/api/README.mdv.md
packages/web/README.md
packages/web/README.mdv.md
packages/worker/README.md
packages/worker/README.mdv.md

Run npx mediva check with no file arguments from the repo root. That zero-config scan validates every X.md that has a sibling X.mdv.md schema.

The contract

<!-- mdv: block required minWords=15 noPlaceholder -->
## Overview

Explain what this package owns and when another package should depend on it.
<!-- mdv: endblock -->

<!-- mdv: block required minWords=10 noPlaceholder -->
## Development

Explain the local commands needed to build, test, and run this package.
<!-- mdv: endblock -->

<!-- mdv: list required minItems=2 -->
## Commands

- Run `npm test` from this package before opening a pull request.
- Run `npm run build` from this package before publishing it.
<!-- mdv: endlist -->

Copy that shape into each package and tune the sections for that package's ownership.

The GitHub Action

on:
  pull_request:
    paths:
      - "**/*.md"
      - "**/*.mdv.md"
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -D mediva
      - run: npx mediva check

Exit code 1 means validation errors and fails the job. Exit code 2 means usage or configuration error, such as an unreadable file.

Variations

• The CLI does not expand globs. Prefer the zero-config scan, or let the shell expand explicit paths, for example npx mediva check packages/*/README.md --schema docs/readme.mdv.md.
• The scan skips node_modules, dist, and every hidden directory automatically. To exclude anything else — a folder of intentionally-invalid fixtures, a vendored package — drop an empty .mdvignore file in it and the whole subtree is pruned. See CLI → the zero-config scan for the full walk rules.
• Keep shared guidance in the visible README text and hidden mdv directives in the sibling schema; the schema can be rendered to plain Markdown if authors need a starter file.