Merge branch 'main' into 4.74-RN

Author: aevesdocker

.agents/skills/write/SKILL.md

@@ -45,7 +45,7 @@ Prettier runs automatically after each edit via the PostToolUse hook.
 Run lint manually after all edits are complete:
 
 ```bash
-${CLAUDE_SKILL_DIR}/scripts/lint.sh <changed-files>
+scripts/lint.sh <changed-files>
 ```
 
 The lint script runs markdownlint and vale on only the files you pass it,

.github/workflows/nightly-docs-scan.yml

@@ -66,7 +66,7 @@ jobs:
           echo "GITHUB_APP_TOKEN=$PAT" >> "$GITHUB_ENV"
 
       - name: Run documentation scan
-        uses: docker/cagent-action@2a43a3882401f45e3114df7f6d66eca184993a90 # latest
+        uses: docker/cagent-action@f208610469d69f20983cad64c577949a132caa33 # v1.5.3
         env:
           GH_TOKEN: ${{ env.GITHUB_APP_TOKEN || github.token }}
         with:

.github/workflows/pr-review.yml

@@ -14,7 +14,7 @@ jobs:
     if: |
       github.event_name == 'issue_comment' ||
       github.event.workflow_run.conclusion == 'success'
-    uses: docker/cagent-action/.github/workflows/review-pr.yml@2a43a3882401f45e3114df7f6d66eca184993a90 # v1.5.2
+    uses: docker/cagent-action/.github/workflows/review-pr.yml@f208610469d69f20983cad64c577949a132caa33 # v1.5.3
     # Scoped to the job so other jobs in this workflow aren't over-permissioned
     permissions:
       contents: read # Read repository files and PR diffs

.vale.ini

@@ -3,45 +3,34 @@ MinAlertLevel = suggestion
 IgnoredScopes = text.frontmatter, code, tt, b, strong, i, a
 Vocab = Docker
 
-# Disable rules for genered content
-[content/reference/**/**.md]
-Vale.Spelling = NO
-Vale.Terms = NO
+# Generated reference content — disable rules that don't apply
+[content/reference/**]
 Docker.Capitalization = NO
-
-[content/manuals/*/release-notes/*.md]
 Vale.Spelling = NO
 Vale.Terms = NO
-Docker.Capitalization = NO
-Docker.We = NO
 
-[content/manuals/*/release-notes.md]
-Vale.Spelling = NO
-Vale.Terms = NO
-Docker.Capitalization = NO
-Docker.We = NO
-
-[content/contribute/*.md]
-Vale.Spelling = NO
-Vale.Terms = NO
+# Skip release notes and old desktop changelog content entirely
+[{content/manuals/*/release-notes.md,content/manuals/*/release-notes/**,content/manuals/desktop/previous-versions/**}]
+Docker.Avoid = NO
 Docker.Capitalization = NO
 Docker.Exclamation = NO
-
-[content/manuals/desktop/previous-versions/*.md]
+Docker.Forbidden = NO
+Docker.GenericCTA = NO
+Docker.HeadingPunctuation = NO
+Docker.ListComma = NO
+Docker.OxfordComma = NO
+Docker.RecommendedWords = NO
+Docker.Spacing = NO
+Docker.Terms = NO
+Docker.URLFormat = NO
+Docker.Units = NO
+Docker.VersionText = NO
+Docker.We = NO
 Vale.Spelling = NO
+Vale.Repetition = NO
 Vale.Terms = NO
-Docker.Capitalization = NO
-Docker.Exclamation = NO
 
 [*.md]
-BasedOnStyles = Vale, Docker
-# Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}})
-TokenIgnores = ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \
-(\[.+\]\({{< .+ >}}\)), \
-[^\S\r\n]({{[%<] \w+ .+ [%>]}})\s, \
-[^\S\r\n]({{[%<](?:/\*) .* (?:\*/)[%>]}})\s, \
-(?sm)({{[%<] .*?\s[%>]}})
-
-# Exclude `{{< myshortcode `This is some <b>HTML</b>, ... >}}`
-BlockIgnores = (?sm)^({{[%<] \w+ [^{]*?\s[%>]}})\n$, \
-(?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}})
+BasedOnStyles = Docker, Vale
+TokenIgnores = ({{[^}]+}}\S*)
+BlockIgnores = (?m)^[ \t]*({{[^}]+}})[ \t]*$, (\[[^\]]*{{[^}]+}}[^\]]*\]\([^)]*\))

AGENTS.md

@@ -80,6 +80,25 @@ introduced, which is permanently true.
 
 - Use lowercase "config" in prose — `vale.Terms` flags a capital-C "Config"
 
+### Updating the vocabulary
+
+If Vale flags a legitimate tech term, product name, or compound identifier
+as a misspelling, add it to `_vale/config/vocabularies/Docker/accept.txt`.
+This is optional — only update when a real new term is missing, not to
+silence individual violations.
+
+- Use the canonical form for case-sensitive product names (`PyTorch`,
+  `GitHub`, `Kubernetes`, `BuildKit`). `Vale.Terms` enforces that exact
+  case across the docs.
+- Use `[Aa]bcd` character-class regex for words that legitimately appear
+  in multiple cases (e.g., sentence-starting capitalization, or a name
+  that's also a generic noun). This covers spelling without enforcing
+  a single canonical form.
+- Avoid broad regex patterns — entries that match many words at once
+  (especially with `(?i)`) suppress other rule checks on every match.
+- Don't add a wrong-cased entry to silence one false positive — it
+  cascades into `Vale.Terms` violations on every correct usage.
+
 ## Alpine.js patterns
 
 Do not combine Alpine's `x-show` with the HTML `hidden` attribute on the
@@ -111,12 +130,17 @@ produces broken HTML — always check COMPONENTS.md for correct syntax.
 
 ```sh
 npx prettier --write <file>        # Format before committing
+scripts/lint.sh <file>...          # Lint specific files (markdownlint + 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.
+
 ### Validation in git worktrees
 
 `docker buildx bake validate` fails in git worktrees because Hugo cannot
@@ -128,9 +152,14 @@ and `validate-vendor` targets run correctly in CI.
 
 1. Make changes
 2. Format with prettier: `npx prettier --write <file>`
-3. Run `docker buildx bake lint vale`
+3. Lint the changed files: `scripts/lint.sh <file>...`
 4. Run a full build with `docker buildx bake` (optional for small changes)
 
+Always lint the specific 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.
+
 ## Git hygiene
 
 - **Stage files explicitly.** Never use `git add .` / `git add -A` /

_vale/Docker/Capitalization.yml

@@ -7,4 +7,4 @@ action:
   params:
     - Docker
 tokens:
-  - '[^\[/]docker[^/]'
+  - '[^\[/\-.]docker[^/\-.\w]'

_vale/Docker/RecommendedWords.yml

@@ -10,9 +10,8 @@ swap:
   '\b(?:ie|i\.e\.)[\s,]': that is
   (?:account name|accountname|user name): username
   (?:drop down|dropdown): drop-down
-  (?:log out|logout): sign out
-  (?:sign on|log on|log in|logon|login): sign in
-  above: previous
+  \blog out\b: sign out
+  \b(?:sign on|log on|log in)\b: sign in
   adaptor: adapter
   administrate: administer
   afterwards: afterward
@@ -25,7 +24,6 @@ swap:
   anti-virus: antivirus
   appendixes: appendices
   assembler: assembly
-  below: following
   check box: checkbox
   check boxes: checkboxes
   click: select
@@ -37,5 +35,5 @@ swap:
   repo: repository
   scroll: navigate
   url: URL
-  vs: versus
+  '\bvs\b(?!\.|\s+Code)': versus
   wish: want

_vale/Docker/Units.yml

@@ -3,7 +3,7 @@ message: "Use '%s' instead of '%s'"
 link: https://docs.docker.com/contribute/style/recommended-words/
 level: error
 swap:
-  (?:kilobytes?|KB): kB
+  kilobytes?: kB
   gigabytes?: GB
   megabytes?: MB
   petabytes?: PB

_vale/Docker/VersionText.yml

@@ -4,9 +4,9 @@ link: https://docs.docker.com/contribute/style/recommended-words/#later
 scope: raw
 raw:
   - '\bv?'
-  - '(?P<major>0|[1-9]\d*)\.?'
-  - '(?P<minor>0|[1-9]\d*)?\.?'
-  - '(?P<patch>0|[1-9]\d*)?'
+  - '(?P<major>0|[1-9]\d*)\.'
+  - '(?P<minor>0|[1-9]\d*)'
+  - '(?:\.(?P<patch>0|[1-9]\d*))?'
   - '(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?'
   - '(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?'
   - '\b (and|or) (higher|above)'

_vale/Docker/We.yml

@@ -1,10 +1,11 @@
 extends: existence
 message: "Avoid using first-person plural like '%s'."
 level: warning
-ignorecase: true
+ignorecase: false
 tokens:
-  - we
-  - we'(?:ve|re)
-  - ours?
+  - '[Ww]e'
+  - "[Ww]e'(?:ve|re)"
+  - '[Oo]urs?'
   - us
-  - let's
+  - Us
+  - "[Ll]et's"