docs: enforce documentation style with Vale

[loks0n]

What

Adds an opinionated Vale setup to lint all markdown documentation, and brings every package's docs up to the standard (0 errors across 99 files).

Setup

• .vale.ini lints README.md, docs/, and packages/. It skips files we don't author as prose: CHANGELOG/LICENSE/CODE_OF_CONDUCT/CONTRIBUTING boilerplate, CLAUDE/AGENTS instructions, and the vendored RFC/PSR spec texts in packages/*/docs/{rfc,psr}/.
• Vendored Utopia style in .vale/styles/ — no vale sync, no network dependency.
• CI: a docs-lint step in the existing validate job via SHA-pinned vale-cli/vale-action (Vale 3.15.1), with reviewdog annotations in the PR diff. Errors fail the build; warnings are advisory.

The opinions

Rule	Level	Enforces
Utopia.HeadingSentenceCase	error	Section headings are sentence case; H1 is exempt (it's the library's proper name)
Utopia.WeaselWords	error	No "simply", "easily", "obviously", "of course"
Utopia.Terms	error	Brand casing in prose: GitHub, Composer, PHPStan, DigitalOcean, …
Vale.Spelling	error	Spell-check against the shared vocabulary (.vale/styles/config/vocabularies/Utopia/accept.txt)
Utopia.Exclamation	warning	Advisory nudge away from exclamation marks

Legitimate new terms (brands, tech vocabulary) go in accept.txt; code identifiers in prose should be backticked instead.

Docs cleanup to get green

• Sentence-cased ~110 headings ("Getting Started" → "Getting started"), preserving acronyms, camelCase identifiers, and product names (Backblaze B2, DigitalOcean Spaces, Linode Object Storage)
• Fixed real typos: "Telemtry", "Prerequisities", "sanitisation" → sanitization, "eg:" → "e.g.", "passing it's" → "its"
• Corrected brand casing ("Install using composer" → Composer, phpstan → PHPStan)
• Backticked code identifiers in prose (the getCPUCores… table in system, class-name headings like UpDownCounter)

Verified locally with the exact CI docker invocation: 0 errors, 7 advisory warnings in 99 files. bin/monorepo validate still passes.

🤖 Generated with Claude Code

[github-actions]

Benchmark results

http — Swoole modes (4 cores, 200 VUs, 20s/run)

workload	mode	req/s	p95
ok	a	16305.743006/s	26.97ms
ok	b	17859.545894/s	24.77ms
io	a	454.722015/s	1s
io	b	3346.754445/s	51.49ms
cpu	a	3361.308562/s	167.53ms
cpu	b	3162.731012/s	82.07ms

a = HYPERLOOP_A (process), b = HYPERLOOP_B (coroutine)

Shared CI runners — treat absolute numbers as rough, compare modes within a run. Commit 70970e4.

[greptile-apps]

Greptile Summary

Introduces a vendored Vale linting setup (no network sync required) and brings all 99 scanned markdown files to zero errors. The CI validate job gains a SHA-pinned vale-cli/vale-action step that fails on errors and surfaces reviewdog annotations.

• Vale rules: five Utopia-specific rules (sentence-case headings H2–H6, brand casing, weasel words, exclamation marks) plus Vale.Spelling backed by a 147-entry accept.txt vocabulary; boilerplate, legal, CLAUDE/AGENTS, and vendored RFC/PSR files are correctly excluded.
• Docs cleanup across 35 files: ~110 headings sentence-cased, real typos fixed ("Telemtry", "Prerequisities", "passing it's"), brand casing corrected (Composer, PHPStan, DigitalOcean), and code identifiers backticked in prose.

Confidence Score: 5/5

Safe to merge — all changes are documentation text and additive linting infrastructure with no impact on runtime behaviour.

All changed files are markdown docs, Vale style rules, a vocabulary list, and one additive CI step. The action is SHA-pinned, fail_on_error is set, and the author verified 0 errors across 99 files locally. No application logic is touched.

No files require special attention.

Important Files Changed

Filename	Overview
.github/workflows/tests.yml	Adds a SHA-pinned vale-cli/vale-action step to the validate job; correctly uses fail_on_error and nofilter mode
.vale.ini	Core Vale config: lints README.md, docs/, and packages/; correctly disables linting for boilerplate, legal, CLAUDE, AGENTS, and vendored RFC/PSR files
.vale/styles/Utopia/HeadingSentenceCase.yml	Sentence-case rule for H2–H6 using Vale's $sentence match; H1 exempted intentionally
.vale/styles/Utopia/Terms.yml	Brand-casing substitution rule; ignorecase: false means a few all-lowercase variants (e.g. digitalocean) aren't caught, though common cases are covered
.vale/styles/Utopia/WeaselWords.yml	Bans weasel words including simply, easily, obviously, clearly, and common dismissive phrases; ignorecase: true correctly set
.vale/styles/config/vocabularies/Utopia/accept.txt	147-entry vocabulary covering brands, protocols, acronyms, and tech terms; includes regex variants (e.g. JWT(?:s)?) and multi-word product names
CLAUDE.md	Adds one-line Vale documentation hint for contributors; file itself is excluded from Vale linting
packages/span/README.md	Sentence-cased ~13 headings; no logic changes
packages/telemetry/README.md	Fixed "Telemtry" typo, sentence-cased headings, backticked UpDownCounter and ObservableGauge class-name headings
packages/storage/docs/adding-new-storage-adapter.md	Fixed "Prerequisities" → "Prerequisites" typo and "Digitalocean" → "DigitalOcean" brand casing
packages/http/docs/Getting-Starting-Guide.md	Fixed "passing it's" → "its", "eg:" → "e.g.", removed weasel word "simply", sentence-cased headings

_{Reviews (2): Last reviewed commit: "docs(vale): widen exclamation lookahead ..." | Re-trigger Greptile}