AGENTS.md

@@ -18,19 +18,21 @@ venv activation automatically — always prefer `make <target>` over raw command
 
 ```bash
 make setup           # Create venv, install deps, set up hooks, install CI tools
-make install-tools   # Install actionlint, git-cliff, act_runner, tea, hadolint to ~/.local/bin
+make install-tools   # Install actionlint, git-cliff, act_runner, tea, hadolint, vale to ~/.local/bin
 make lint-all        # ruff + pyright + bandit + actionlint + lint-dockerfiles
 make pytest-cov      # Unit tests with 100% coverage enforcement
 make test-unit       # Unit tests without coverage
 make workflow-lint   # Static lint of .gitea/workflows/*.yml (actionlint)
 make workflow-dryrun # Dry-run all workflows in Docker (act_runner exec --dryrun)
 make workflow-check  # workflow-lint + workflow-dryrun
+make devx-check-doc-versions  # Verify docs version refs match __version__
+make devx-vale       # Run Vale prose linter on docs and README
 make clean           # Remove caches, build artifacts, coverage data
 ```
 
 `make setup` automatically installs all development tools:
 - **Python deps** via `python -m devx.tools.setup` (pip install -e .[dev], pre-commit hooks)
-- **actionlint, git-cliff, act_runner, tea, hadolint** via `python -m devx.tools.install_tools` (CI/CD tools to ~/.local/bin)
+- **actionlint, git-cliff, act_runner, tea, hadolint, vale** via `python -m devx.tools.install_tools` (CI/CD tools to ~/.local/bin)
 - **tea CLI login** via `python -m devx.tools.setup` (configures `tea login` from `.env` `CI_GITEA_TOKEN`)
 
 ## Workflow Verification (Before Push)
@@ -86,11 +88,12 @@ src/devx/
 │   ├── integration_guard.py # Run pytest with cross-runner fail-fast
 │   ├── check_translations.py  # Translation completeness check
 │   ├── doc_coverage.py  # Documentation coverage check
-│   └── lint_docs.py  # Documentation linter (structure, links, headings)
+│   └── lint_docs.py  # Documentation linter (structure, links, headings, code blocks, orphans)
 ├── tools/               # Developer tooling modules (run locally or by CI)
 │   ├── setup.py         # Environment setup (venv, deps, hooks)
-│   ├── install_tools.py # Install actionlint, git-cliff, act_runner, tea, hadolint
+│   ├── install_tools.py # Install actionlint, git-cliff, act_runner, tea, hadolint, vale
 │   ├── install_checkmake.py  # Install checkmake (Makefile linter)
+│   ├── check_doc_versions.py  # Verify docs version refs match __version__
 │   ├── build_image.py   # Build and push Docker images to Gitea registry
 │   ├── clean_images.py  # Clean up old Docker image versions from Gitea registry
 │   ├── check_test_speed.py  # Measure unit test execution time