coder · nickvigilante · Jun 23, 2026 · Jun 22, 2026 · Jun 22, 2026
@@ -234,9 +234,25 @@ jobs:
             echo "No changed Markdown files under docs/ on disk; skipping Vale."
             exit 0
           fi
-          echo "::add-matcher::.github/vale-problem-matcher.json"
-          printf '%s\n' "$files" | xargs -d '\n' mise exec "aqua:errata-ai/vale" -- vale --no-exit --output=line
-          echo "::remove-matcher owner=vale::"
+          # Vale's --output=line strips per-finding severity, so the
+          # previous problem-matcher approach collapsed every finding to
+          # a single hard-coded severity. Use --output=JSON instead and
+          # emit GitHub workflow commands directly so error/warning/
+          # suggestion render with their actual Vale severities. URL-
+          # encode message bodies for `%`, `\r`, and `\n` per the
+          # GitHub Actions workflow command spec. See DOCS-426.
+          printf '%s\n' "$files" \
+            | xargs -d '\n' mise exec "aqua:errata-ai/vale" -- vale --no-exit --output=JSON \
+            | jq -r '
+                to_entries[]
+                | .key as $file
+                | .value[]
+                | (if .Severity == "suggestion" then "notice"
+                   elif .Severity == "warning" then "warning"
+                   else "error" end) as $level
+                | (.Message | gsub("%"; "%25") | gsub("\r"; "%0D") | gsub("\n"; "%0A")) as $msg
+                | "::\($level) file=\($file),line=\(.Line),col=\(.Span[0]),title=\(.Check)::\($msg)"
+              '
 
       - name: Save Vale styles
         # Only the default branch is trusted to write the cache, so PR

diff --git a/docs/.style/_vale-annotation-demo.md b/docs/.style/_vale-annotation-demo.md
@@ -0,0 +1,25 @@
+# Vale annotation rendering demo
+
+> [!NOTE]
+> This page exists only to verify how GitHub renders Vale annotations
+> at each severity level.
+> The three `Coder.Demo*` rules under
+> [`docs/.style/styles/Coder/`](styles/Coder/) fire on the marker
+> strings below.
+> This page and its rules disappear in a follow-up commit on the same
+> PR once the rendering check completes; see DOCS-426.
+
+## Markers
+
+Each marker fires exactly one Vale annotation when this page lints:
+
+- Suggestion (rendered as GitHub `notice`):
+  vale-demo-suggestion-marker.
+- Warning (rendered as GitHub `warning`):
+  vale-demo-warning-marker.
+- Error (rendered as GitHub `error`):
+  vale-demo-error-marker.
+
+The rules use Vale's `existence` extension type and target a single
+literal token each, so each marker produces a single annotation at its
+exact location.
diff --git a/docs/.style/styles/Coder/DemoError.yml b/docs/.style/styles/Coder/DemoError.yml
@@ -0,0 +1,11 @@
+# DemoError - canary rule used to verify how GitHub renders error-level
+# Vale annotations in PR diffs. Fires on the literal phrase
+# `vale-demo-error-marker`, which appears only in
+# docs/.style/_vale-annotation-demo.md. Demo rules drop in a follow-up
+# commit before the parent PR merges; see DOCS-426.
+extends: existence
+message: "[Demo] Error-level Vale annotation."
+link: https://github.com/coder/coder/blob/main/docs/.style/_vale-annotation-demo.md
+level: error
+tokens:
+  - vale-demo-error-marker
diff --git a/docs/.style/styles/Coder/DemoSuggestion.yml b/docs/.style/styles/Coder/DemoSuggestion.yml
@@ -0,0 +1,11 @@
+# DemoSuggestion - canary rule used to verify how GitHub renders
+# suggestion-level Vale annotations in PR diffs. Fires on the literal
+# phrase `vale-demo-suggestion-marker`, which appears only in
+# docs/.style/_vale-annotation-demo.md. Demo rules drop in a follow-up
+# commit before the parent PR merges; see DOCS-426.
+extends: existence
+message: "[Demo] Suggestion-level Vale annotation."
+link: https://github.com/coder/coder/blob/main/docs/.style/_vale-annotation-demo.md
+level: suggestion
+tokens:
+  - vale-demo-suggestion-marker
diff --git a/docs/.style/styles/Coder/DemoWarning.yml b/docs/.style/styles/Coder/DemoWarning.yml
@@ -0,0 +1,11 @@
+# DemoWarning - canary rule used to verify how GitHub renders
+# warning-level Vale annotations in PR diffs. Fires on the literal phrase
+# `vale-demo-warning-marker`, which appears only in
+# docs/.style/_vale-annotation-demo.md. Demo rules drop in a follow-up
+# commit before the parent PR merges; see DOCS-426.
+extends: existence
+message: "[Demo] Warning-level Vale annotation."
+link: https://github.com/coder/coder/blob/main/docs/.style/_vale-annotation-demo.md
+level: warning
+tokens:
+  - vale-demo-warning-marker