Add automated grammar and style checks for documentation

Summary

Enable automated grammar and style checks in pre-commit hooks and CI to complement existing spelling checks and reduce manual review overhead for documentation.

Current State

• ✅ Spelling: codespell (v2.2.4) already configured in .pre-commit-config.yaml
• ✅ Markdown checks: Custom check-markdown script via ./tools/check-docs.sh
• ❌ Grammar/Style: Not automated

Proposed Addition

Option 1: Vale with Microsoft style (recommended starting point)

• ✅ Pros: Style enforcement (wordiness, sentence length, heading consistency), complements codespell, highly customizable, fast, YAML config, easy pre-commit integration
• ❌ Cons: Limited grammar checking - catches style issues but not deep grammar errors (missing verbs, sentence fragments, subject-verb agreement). Requires initial configuration.

Option 2: LanguageTool (for comprehensive grammar)

• ✅ Pros: True grammar checking with syntax parsing, catches missing verbs, fragments, agreement errors, multilingual support
• ❌ Cons: Requires Java runtime + standalone server setup, slower, heavier resource usage. Pre-commit integration is inconvenient (server startup overhead on each commit), but CI integration is feasible with centralized orchestration via Makefile or similar tool to manage server lifecycle.

Option 3: Vale + LanguageTool (comprehensive)

• ✅ Pros: Best of both - Vale for fast style checks in pre-commit, LanguageTool for deep grammar
• ❌ Cons: Requires managing two tools. LanguageTool needs orchestration layer (Makefile/script) to start server and invoke endpoints.

Recommendation

Phase 1: Start with Vale with styles (e.g. Microsoft style) for pre-commit and CI to address common style issues .

Phase 2: If deep grammar checking proves necessary, add LanguageTool using:

• Makefile target to download/cache LanguageTool
• Makefile with targets to start and stop the server, and run checks (logic can reside in a separate script if complex)
• Skip pre-commit integration due to server startup overhead

Implementation

Vale (Pre-commit + CI):

- repo: https://github.com/errata-ai/vale
  rev: v3.13.0
  hooks:
  - id: vale
    files: ^docs/.*\.md$
    exclude: ^docs/bin/|^tools/release-notes/

LanguageTool (Makefile (+ optionally script) + CI):

# In CI workflow
- name: Grammar check with LanguageTool
  run: make languagetool-check

# In Makefile
.PHONY: languagetool-check
languagetool-check:
	@./tools/languagetool.sh check docs/

Scope

• Markdown files (.md) in docs/ directory
• Exclude: docs/bin/, tools/release-notes/

Question

Is style checking (with limited grammar) via Vale sufficient, or should we invest in LanguageTool setup for comprehensive grammar checking?

Start by reviewing .pre-commit-config.yaml and ./tools/check-docs.sh to understand the existing spelling and Markdown checks, then inspect the CI workflow and Makefile entry points. Resolve whether Vale alone or Vale plus LanguageTool is wanted, implement checks for docs/*.md with the stated exclusions, and verify both pre-commit and CI behavior.