markdown-lint

name	markdown-lint
description	Lint every `.md` file in the workspace with the navigator CLI (M-family rules + S101 120-char line limit). Trigger when adding or editing any Markdown file (READMEs, `docs/`, `CLAUDE.md`, blog posts under `web/content/`) and before committing `.md` changes. Dogfood the workspace's own binary; never hand-roll a different linter.

Markdown linting via the navigator CLI

Every .md file in this repo must pass the navigator CLI's markdown rule set. We dogfood our own linter so the rule definitions, exit codes, and CI behavior stay coherent.

The canonical command

cargo run -p cli --quiet -- validate <path>

What each piece does:

• validate classifies each file by its content and path — prose markdown gets the M-family rules + S101/S102, a notation template under templates/ (or any file declaring questionnaire:/workflow:) also gets the N-family, events get the E-family, and blog posts / board minutes get the C-family. A plain README classifies as prose on its own, so it never trips bogus N101/N102/N103. It walks the whole tree — README/CLAUDE.md/LICENSE.md and every directory are in scope (only hidden dirs and target/ are skipped) — and folds in the typed event pass and a .yaml/.yml parse over the same walk. The per-kind frontmatter keys are documented for attorneys in docs/frontmatter.md.
• <path> — either a file or a directory (default .). The walker recurses.

Lint every workspace README in one pass

for d in rules store views workflows cloud web cli mcp; do
  cargo run -p cli --quiet -- validate "$d"
done

Exit 0 on every iteration means clean. Otherwise the violating file, line, rule code, and message print to stdout.

Common rules that fire

• S101 — line longer than 120 characters. Reflow the paragraph; don't fight the limit. M026 — heading ends with trailing punctuation .. Drop the period from ## Headings. (watch for false positives: bash # comment. lines inside fenced code blocks trip the same rule).
• M038 — inline code span has leading or trailing whitespace. Usually means the span got broken across two lines; keep code spans on a single line.
• M040 — fenced code block is missing a language tag. Add one (bash, rust, text, yaml, …) right after the opening fence.
• M031 — fenced code block must have a blank line before it. Common when a code block is nested inside a list item.
• M060 — table column alignment is inconsistent within a table.

When to run it

• Before committing any change that touches a .md file. When you create a new README. As part of CI for the docs surface (not currently wired in ci.yml, but on the roadmap).

What NOT to do

• Don't reach for markdownlint, mdformat, or any non-Rust linter. We standardize on the in-house cli — that's the whole point of dogfooding. See [[rust]] for the Rust-only stance.
• Don't disable a rule by editing cli/src/main.rs. If a rule is wrong, fix it in rules/src/<code>.rs with a test.