chore: add markdown linting

[rlippmann]

Summary

Adds repository-wide Markdown linting using markdownlint-cli2.

Changes include:

• add .markdownlint-cli2.jsonc with a tuned low-noise configuration
• add a dedicated Markdown lint CI job
• document the local Markdown lint command in CONTRIBUTING.md
• fix existing Markdown lint findings across repository documentation
• keep Python and TypeScript validation scripts unchanged

Why

Documentation is part of the repository contract and a significant portion of this repository consists of examples, integration guides, and reference documentation.

Markdown linting provides automated structural validation for documentation and helps prevent formatting regressions, duplicate headings, malformed lists, inconsistent tables, and similar issues that are easy to miss during normal review.

Example metadata

• Enforcement point: repository governance
• Domain: documentation quality
• Technology/runtime: markdownlint-cli2
• Example type: repository tooling
• Does this use directive drafter? no
• Does this derive state from model output? must be no for primary examples: no

Checklist

• Repository scaffolding / governance change
• One primary enforcement point
• Explicit authoritative state
• No model-derived state mutation
• Adversarial stub or equivalent test
• Observable runtime behavior change
• Domain vocabulary is natural
• Framework is secondary to the enforcement point
• Docs updated
• Tests/smoke checks added where practical

Notes

Validation passed:

• npx --yes markdownlint-cli2
• ./scripts/validate_python.sh

The Markdown lint configuration intentionally disables high-noise rules such as line-length enforcement and is focused on structural documentation correctness.