Merge pull request #4069 from replicatedhq/vale-linter

update heading rules in the vale linter

Author: paigecalvert

.claude/skills/vale-prose-review/SKILL.md

@@ -117,7 +117,7 @@ See `references/vale-rules.md` for full fix patterns, before/after examples, and
 
 **`Replicated.PositionalLanguage`** — Replace "above/below" with "the following" or a section link; replace directional "right/left" with "the following" or a UI element name.
 
-**`Replicated.Headings`** — Apply sentence case, with three exceptions: (1) **Skip entirely** when the heading IS a CLI command name or YAML field name (e.g., `# install (Beta)`, `## helmCharts`) — those follow the thing's own casing conventions. (2) **Parentheticals reset sentence case** — `(Beta)` is correct, not `(beta)`. (3) **Kubernetes custom resource kind names stay capitalized** — `Preflight`, `SupportBundle`, `Config`, `HelmChart` are proper names; check context to confirm the word refers to a `kind:` value before lowercasing. See `references/vale-rules.md` for full patterns.
+**`Replicated.Headings`** — Apply sentence case, with three exceptions: (1) **Skip entirely** when the heading IS a CLI command name or YAML field name (e.g., `# install (Beta)`, `## helmCharts`) — those follow the thing's own casing conventions. (2) **Parentheticals reset sentence case** — `(Beta)` and `(Alpha)` are correct; **never** lowercase to `(beta)` or `(alpha)`. (3) **Kubernetes custom resource kind names stay capitalized** — `Preflight`, `SupportBundle`, `Config`, `HelmChart` are proper names; check context to confirm the word refers to a `kind:` value before lowercasing. See `references/vale-rules.md` for full patterns.
 
 **`Replicated.WordsToAvoid`** — Remove "easy/easily", "simple/simply", "just" (when minimizing). Rephrase or omit.
 

.claude/skills/vale-prose-review/references/vale-rules.md

@@ -128,11 +128,13 @@ Do NOT apply sentence case to headings that are the exact name of a CLI command,
 
 ### Parentheticals reset sentence case
 
-A parenthetical like `(Beta)` or `(Preview)` opens a new "sentence" within the heading. Capitalize the first word inside the parenthetical.
+A parenthetical like `(Beta)` or `(Preview)` opens a new "sentence" within the heading. **Always capitalize the first word inside the parenthetical — do NOT lowercase it when applying sentence case to the rest of the heading.**
 
-- `(Beta)` is correct — **not** `(beta)`
-- `(Preview)` is correct — **not** `(preview)`
-- `(Deprecated)` is correct — **not** `(deprecated)`
+- `(Beta)` is correct — **never** `(beta)`
+- `(Alpha)` is correct — **never** `(alpha)`
+- `(Deprecated)` is correct — **never** `(deprecated)`
+
+> **Common mistake:** When applying `Replicated.Headings` sentence-case fixes, do not treat parenthetical words as mid-sentence words subject to lowercasing. `## This is a heading (Beta)` stays `## This is a heading (Beta)` — the `B` in `Beta` must remain uppercase.
 
 ### Kubernetes custom resource kinds — always capitalize