vale: expand Docker prose checks (#26029)

## Summary

Expand Docker's local Vale style with documented direct-language
substitutions and focused checks for marketing copy and meta-commentary.
Remove stale style-guide links and clarify how agents should review
scoped Vale output.

Generated by Codex

.agents/skills/write/SKILL.md

@@ -45,11 +45,13 @@ rumdl runs automatically after each edit via the PostToolUse hook.
 Run lint manually after all edits are complete:
 
 ```bash
-scripts/lint.sh <changed-files>
+scripts/lint.sh <changed-markdown-files>
 ```
 
 The lint script runs rumdl and Vale on only the files you pass it,
-so the output is scoped to your changes. Fix any errors it reports.
+so the output is scoped to your changes. Fix errors and warnings on lines you
+added or changed, and review each suggestion. Vale can exit successfully when
+warnings or suggestions remain in its output.
 
 ## 5. Self-review
 

.github/workflows/build.yml

@@ -106,6 +106,6 @@ jobs:
         name: Run reviewdog for vale
         if: ${{ matrix.target == 'vale' && github.event_name == 'pull_request' }}
         run: |
-          cat ./tmp/vale.out | reviewdog -f=rdjsonl -name=vale -reporter=github-pr-annotations -fail-on-error=false -filter-mode=added -level=info -fail-level=warning
+          cat ./tmp/vale.out | reviewdog -f=rdjsonl -name=vale -reporter=github-pr-annotations -filter-mode=added -level=info -fail-level=warning
         env:
           REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.vale.ini

@@ -18,7 +18,9 @@ Docker.Forbidden = NO
 Docker.GenericCTA = NO
 Docker.HeadingPunctuation = NO
 Docker.ListComma = NO
+Docker.MetaCommentary = NO
 Docker.OxfordComma = NO
+Docker.PromotionalOpeners = NO
 Docker.RecommendedWords = NO
 Docker.Spacing = NO
 Docker.Terms = NO

AGENTS.md

@@ -185,16 +185,24 @@ produces broken HTML — always check COMPONENTS.md for correct syntax.
 ```sh
 npx --no-install rumdl fmt <file>  # Format Markdown before committing
 npx prettier --write <file>        # Format non-Markdown files
-scripts/lint.sh <file>...          # Lint specific files (rumdl + Vale)
+scripts/lint.sh <markdown-file>... # Lint specific files (rumdl + Vale)
 docker buildx bake validate        # Run all validation checks
 docker buildx bake lint            # Markdown linting only
 docker buildx bake vale            # Style guide checks only
 docker buildx bake test            # HTML and link checking
 ```
 
-For incremental work, prefer `scripts/lint.sh` over the `bake` targets —
-it runs the same checks on just the files you pass, so the output stays
-scoped to your changes instead of the whole repo.
+`npx --no-install` uses the repository-pinned rumdl binary and never downloads
+a replacement. If the binary is unavailable, run `npm ci` to install the
+repository dependencies. Install Vale separately.
+
+For incremental work, prefer `scripts/lint.sh` over the `bake` targets. Pass
+only the Markdown files you changed so the output stays scoped instead of
+including the whole repository.
+
+Vale exits successfully when it reports only warnings or suggestions. Read the
+full output: fix errors and warnings on lines you added or changed, and review
+each suggestion. Don't expand the change to unrelated alerts in existing text.
 
 ### Validation in git worktrees
 
@@ -207,10 +215,10 @@ and `validate-vendor` targets run correctly in CI.
 
 1. Make changes
 2. Format Markdown with rumdl: `npx --no-install rumdl fmt <file>`
-3. Lint the changed files: `scripts/lint.sh <file>...`
+3. Lint the changed Markdown files: `scripts/lint.sh <markdown-file>...`
 4. Run a full build with `docker buildx bake` (optional for small changes)
 
-Always lint the specific files you changed before committing. Use
+Always lint the specific Markdown files you changed before committing. Use
 `scripts/lint.sh` rather than the `bake` targets so the output is scoped
 to your changes — bake runs across the entire repo and the noise makes
 real issues easy to miss.

_vale/Docker/Avoid.yml

@@ -3,6 +3,15 @@ message: "Consider removing '%s'."
 ignorecase: true
 level: warning
 tokens:
+  - amazing
+  - easily
+  - game-changing
+  - 'just(?!-in-time)'
   - please
-  - very
+  - powerful
   - really
+  - revolutionary
+  - robust
+  - seamlessly
+  - simply
+  - very

_vale/Docker/GenericCTA.yml

@@ -1,6 +1,5 @@
 extends: existence
 message: "Avoid generic calls to action: '%s'"
-link: https://docs.docker.com/contribute/style/formatting/#links
 level: warning
 scope: raw
 ignorecase: true

_vale/Docker/ListComma.yml

@@ -1,6 +1,5 @@
 extends: existence
 message: Don’t add commas (,) or semicolons (;) to the ends of list items.
-link: https://docs.docker.com/contribute/style/grammar/#lists
 level: warning
 scope: list
 raw: '[,;]$'

_vale/Docker/MetaCommentary.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "Remove meta-commentary '%s' and state the information directly."
+ignorecase: true
+level: warning
+tokens:
+  - 'worth noting(?: that)?'
+  - 'important to (?:note|understand) that'
+  - 'keep in mind(?: that)?'

_vale/Docker/PromotionalOpeners.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "Replace promotional opener '%s' with a specific description."
+ignorecase: true
+level: warning
+scope: sentence
+tokens:
+  - '^in today'
+  - '^(?:whether you[\x27’]re|whether you are)\b'

_vale/Docker/RecommendedWords.yml

@@ -1,6 +1,5 @@
 extends: substitution
 message: "Consider using '%s' instead of '%s'"
-link: https://docs.docker.com/contribute/style/recommended-words/
 ignorecase: true
 level: suggestion
 action:
@@ -29,11 +28,20 @@ swap:
   click: select
   distro: distribution
   ergo: therefore
+  facilitate: help
+  facilitates: helps
+  facilitated: helped
+  facilitating: helping
   file name: filename
+  in order to: to
   keypress: keystroke
   mutices: mutexes
   repo: repository
   scroll: navigate
   url: URL
+  utilize: use
+  utilizes: uses
+  utilized: used
+  utilizing: using
   '\bvs\b(?!\.|\s+Code)': versus
   wish: want

_vale/Docker/Units.yml

@@ -1,6 +1,5 @@
 extends: substitution
 message: "Use '%s' instead of '%s'"
-link: https://docs.docker.com/contribute/style/recommended-words/
 level: error
 swap:
   kilobytes?: kB

_vale/Docker/VersionText.yml

@@ -1,6 +1,5 @@
 extends: existence
 message: Use later when talking about version numbers.
-link: https://docs.docker.com/contribute/style/recommended-words/#later
 scope: raw
 raw:
   - '\bv?'

scripts/lint.sh

@@ -1,16 +1,25 @@
 #!/bin/bash
-# Run rumdl and Vale on specific files.
-# Usage: scripts/lint.sh <file> [file...]
+# Run rumdl and Vale on specific Markdown files.
+# Usage: scripts/lint.sh <markdown-file> [markdown-file...]
 #
 # Scoped output — no repo-wide noise. For full repo validation, use:
 #   docker buildx bake validate
 set -uo pipefail
 
 if [ $# -eq 0 ]; then
-  echo "Usage: $0 <file> [file...]" >&2
+  echo "Usage: $0 <markdown-file> [markdown-file...]" >&2
   exit 1
 fi
 
+for file in "$@"; do
+  if [[ "$file" != *.md ]]; then
+    echo "Error: scripts/lint.sh only accepts Markdown files: $file" >&2
+    exit 2
+  fi
+done
+
+repo_root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)
+
 exit_code=0
 
 echo "=== rumdl ==="
@@ -20,8 +29,11 @@ fi
 
 echo ""
 echo "=== vale ==="
-if ! vale "$@" 2>&1; then
+if ! vale --no-global --config="$repo_root/.vale.ini" "$@" 2>&1; then
   exit_code=1
 fi
 
+echo ""
+echo "Review Vale warnings and suggestions on changed lines; they don't affect the exit status."
+
 exit $exit_code