docs: enforce sentence-case headings and codify prose conventions

Signed-off-by: Patrick Linnane <patrick@linnane.io>

.vale.ini

@@ -5,3 +5,9 @@ rb = md
 
 [*.{md,rb}]
 BasedOnStyles = Homebrew
+
+[{docs/,}Manpage.md]
+Homebrew.Headings = NO
+
+[{docs/,}governance/*.md]
+Homebrew.Headings = NO

docs/AGENTS.md

@@ -21,6 +21,8 @@ These instructions apply when working in `docs/`.
   This keeps diffs small and readable.
 - Format tables so the raw Markdown is readable: pad each column with spaces so the cell borders line up vertically.
 - Use UK spelling and punctuation.
+- Use `licence` for the noun and `license` for the verb.
+  Keep `license` when referring to the exact DSL stanza, command-line option or other interface name.
 - Avoid em-dashes (prefer semicolons, colons and commas) and Oxford commas.
 - Do not use bare URLs; use Markdown links.
   Internal links must point at the `.md` file (for example `[Bottles](Bottles.md)`), not a `docs.brew.sh` URL.
@@ -40,7 +42,7 @@ At a minimum, from `docs/` run:
 
 Also run these from the repository root when docs content changes:
 
-- `HOMEBREW_NO_AUTO_UPDATE=1 vale docs/`
+- `rg --files docs -0 -g '*.md' -g '!vendor/**' -g '!_site/**' -g '!rubydoc/**' | xargs -0 vale`
 - `HOMEBREW_NO_AUTO_UPDATE=1 brew style docs`
 
 ## Notes

docs/Prose-Style-Guidelines.md

@@ -34,6 +34,7 @@ We prefer:
 ### Style and usage
 
 * British/Commonwealth English over American English, in general
+* "licence" as a noun and "license" as a verb, while preserving literal interface names such as the `license` stanza
 * "e.g." and "i.e.": Go ahead and use "e.g." or "i.e." instead of spelling them out. Don't worry about putting a comma after them.
   * "e.g." means "for example"; "i.e." means "that is"
 * Offset nontrivial subordinate clauses with commas
@@ -52,6 +53,7 @@ We prefer:
 * Capitalise all list items if you want, even if they're not complete sentences; just be consistent within each list, and preferably, throughout the whole page
 * Use a subordinate list item instead of dropping a multi-sentence paragraph-long item into a list of sentence fragments
 * Prefer Markdown over other markup formats unless their specific features are needed
+* One sentence per source line in Markdown, without wrapping prose to a fixed width
   * GitHub Flavoured Markdown. GitHub's implementation is the standard, period.
 * Link to other documentation pages with relative links to the Markdown filename rather than the full URL
   * e.g. `FAQ.md` instead of `https://docs.brew.sh/FAQ`
@@ -65,6 +67,7 @@ We prefer:
 * No "$" with environment variables mentioned outside code snippets
   * e.g. "Set `BLAH` to 5", not "Set `$BLAH` to 5"
 * One space after periods, not two
+* Commas, colons or semicolons instead of em dashes
 * Capitalised proper nouns
 * We do not defer to extensive nonstandard capitalisation, typesetting, or other styling of brand names, aside from the normal capitalisation of proper nouns and simple internal capitalisation
 * No "TM", &trade;, <sup>SM</sup>, &copy;, &reg;, or other explicit indicators of rights ownership or trademarks; we take these as understood when the brand name is mentioned

docs/index.md

@@ -1,5 +1,5 @@
 ---
-last_review_date: "2026-06-08"
+last_review_date: "2026-07-18"
 ---
 
 Start with [installation](Installation.md),

docs/vale-styles/Homebrew/Headings.yml

@@ -0,0 +1,89 @@
+extends: capitalization
+message: "'%s' should be in sentence case"
+level: error
+scope:
+  - heading.h2
+  - heading.h3
+  - heading.h4
+  - heading.h5
+  - heading.h6
+match: $sentence
+threshold: 1.0
+exceptions:
+  - Annual General Meeting
+  - Apple Silicon
+  - AGM
+  - AI
+  - API
+  - ARM32
+  - ASCII
+  - CI
+  - CLI
+  - CLT
+  - CMake
+  - Claude Desktop
+  - Codecov
+  - Cursor
+  - DSL
+  - Dock
+  - Git
+  - GitHub
+  - Go
+  - Homebrew
+  - HTTPS
+  - ID
+  - How do I
+  - after I
+  - should I
+  - Can I
+  - can I
+  - when I
+  - JDK
+  - JSON
+  - Linux
+  - LLM
+  - Launchpad
+  - MPI
+  - OSDN
+  - Ops Team
+  - PLC
+  - PRs
+  - PowerShell
+  - Python
+  - Project Leader
+  - Project Leadership Committee
+  - Ruby
+  - Rust
+  - SHA-256
+  - SPDX
+  - Security Team
+  - SOS
+  - Sublime Text
+  - SourceForge
+  - Subversion
+  - URL
+  - URLs
+  - Terminal.app
+  - Tier 1 Support
+  - Tier 2 Support
+  - Tier 3 Support
+  - Open man Page
+  - VS Code
+  - Visual Studio Code
+  - Windows
+  - Windows Subsystem for Linux
+  - Windows 10 Subsystem for Linux
+  - Xcode
+  - Zed
+  - Brewfiles
+  - Command Line Tools
+  - Lead Maintainer
+  - Lead Maintainers
+  - PLC Members
+  - caveats
+  - fish
+  - formulae.brew.sh
+  - macOS
+  - target
+  - x86
+  - zsh