Add missing proper nouns to the Temporal.Headings exception list

[DABH]

Draft — the additions below are backed by repo evidence, but the open questions at the end need a docs-team call before this should merge.

Context

Temporal.Headings currently flags 407 headings across 190 files (all suggestion level). It doesn't drown CI only because vale-ci.yml uses filter_mode: diff_context and fail_on_error: false, so violations surface only when someone touches those lines.

Sampling that backlog showed it's a mix of genuine sentence-case violations and false positives on words this repo does treat as proper nouns. This PR fixes only the false-positive half — the config side. It deliberately does not touch content.

Additions, and the evidence for each

Addition	Evidence
Command, Commands	docs/glossary.md:135 defines [Command](/workflow-execution#command); used capitalized in docs/encyclopedia/architecture/temporal-sdks.mdx prose
Events	Plural parity — Event was already present
Application, Applications	"Temporal Application" is a core term; Application is already in vocabularies/Temporal/accept.txt
Plugin, Plugins	"Plugin system" (×5) and "Plugins guide" (×4) are capitalized in prose; /develop/plugins-guide is a real page
Audit Log, Audit Logs, Audit Logging	Temporal/terms.yml:21 canonicalizes audit logging → Audit Logging. Added as exact phrases so bare Log/Logs stay flagged elsewhere
Amazon	Cloud provider proper noun; AWS, GCP, Azure, Google were already present
CA	Acronym (CA certificates was flagged)
Private Service Connect, Cloud Ops API	Product names, following the existing exact-phrase pattern (Azure Key Vault, GCP Workload Identity)

Multi-word entries were verified to actually work: ## Configure Azure Key Vault access passes while ## Configure Key Vault access is flagged.

Measured impact

	Before	After
Temporal.Headings violations	407	367
Files affected	190	176
All CI-scoped rules	500	458
Newly flagged headings (regressions)	—	0

40 false positives cleared, no regressions. Verified the rule still fires on genuine title case (## This Is Clearly Title Case Here → flagged).

Config alone is necessary but not sufficient. Most flagged headings contain several stray capitals, so clearing one word often leaves the heading flagged — correctly, since the rest is a real violation. The remaining 366 are content work, not config work.

Deliberately NOT added

• Connected, Community — genuine violations. The 7 ## Get Connected with the Temporal <X> Community headings should be sentence-cased instead: the repo's own prose uses lowercase "the Temporal community" 10 times, Community is absent from terms.yml and accept.txt, and STYLE.md says only proper nouns are capitalized. Separate content PR.
• Continue-as-New — looks like a casing mismatch, but terms.yml canonicalizes to Continue-As-New, which is already in the list. The heading How to test Continue-as-New using the .NET SDK is the thing that's wrong. Content fix.
• Overview, Steps ("Next Steps"), Section, Hello, World, Test, Your, Installation, Success, Code, Maps, Map, Provides, Verify, Options, When, Saved, View — ordinary words, genuine violations.

Open questions for reviewers

1. Summary / Details (29 violations, the single biggest chunk). docs/web-ui.mdx:229 describes "User Metadata including static Workflow Summary and Details and dynamic Current Details" — these are real Web UI field names. Are they proper nouns (add exceptions) or should headings like ## Adding Summary and Details to Workflows be sentence-cased? I left them out pending a call.
2. Handler / Handlers (9), Message (6) — "Message Handlers", "Update Handlers" read like Temporal concepts, but neither appears in terms.yml. Term or not?
3. Replay (6) — "Replay Testing", "History Replay". Concept name or ordinary verb?

A note on the rule itself

Worth knowing when interpreting its output: Temporal.Headings tolerates one stray non-exception capital and only flags at two or more. Probed:

Heading	Flagged
Get Connected with the Temporal Python Community	yes
Get Connected with the Temporal Python community	no
Get connected with the Temporal Python Community	no

So passing this rule does not mean a heading is correctly sentence-cased, and the 407 count under-reports the real backlog. Style decisions should come from STYLE.md, with Vale as a coarse net rather than the source of truth.

┆Attachments: EDU-6987 Add missing proper nouns to the Temporal.Headings exception list

---

Update: also runs Vale CI on ruleset changes

Second commit (fce5fd0) fixes a gap this PR itself exposed. vale-ci.yml triggered on paths: docs/** only, so a PR touching just vale/styles/** never ran Vale — the "Lint prose" check did not run on the first commit of this PR at all. A ruleset change was the one change Vale CI most needed to exercise, and the one case it skipped.

Audited every workflow's path filter to confirm nothing else covered it:

Workflow	Ran on a vale/**-only change?
vale-ci.yml	❌ docs/** only
build-check.yml	❌ docs/**, src/**, static/**, …
check-orphan-pages.yml	❌ docs/**, sidebars.js, …
mermaid-ci.yml	❌ docs/**, …
check-redirects.yml, docs-preview-links.yml	✅ but indifferent to Vale

Added vale/**, .vale-ci.ini, and .github/workflows/vale-ci.yml to the trigger.

What this catches: a malformed style file. Verified locally — corrupting Headings.yml makes Vale exit 2 with Execution stopped, linting nothing. Without this trigger, such a change could merge and then fail open on every subsequent PR with nothing having flagged it.

What it does not catch: because the action uses filter_mode: diff_context, a vale/**-only PR has no docs/ lines in its diff, so no heading alerts get reported. The job proves the ruleset loads; it does not show the ruleset's impact. The before/after numbers above came from running Vale locally across docs/, and that remains the evidence for the exception list itself.

---

Update: dropped the Metric exception (Copilot review)

Copilot flagged Metric and was right on every point. Verified each claim:

• metric is absent from Temporal/terms.yml.
• docs/cloud/metrics/openmetrics/api-reference.mdx:67 reads "A metric is a numeric attribute measured at a specific point in time" — lowercase, as a common noun.
• Isolating the entry showed it suppressed exactly one heading and nothing else: Namespace/Metric filtering (migration-guide.mdx:337), which is a genuine violation that should become Namespace/metric filtering in the content cleanup.

My justification had been "singular parity with the existing Metrics," which was reasoning from symmetry rather than evidence. Isolating the plural entry shows why the parity doesn't hold — Metrics guards 11 compound product names:

Cloud Metrics · SDK Metrics · Workflow Metrics · Latency Metrics
Poll Metrics · Schedule Metrics · Frontend Service Metrics · Reference Metrics

The plural appears inside product names; the singular appears as a common noun. Different cases, so the plural staying does not imply the singular should be added.

Removed in 9ee4882. Namespace/Metric filtering is flagged again, as it should be. Revised totals are in the table above (407 → 367, one fewer than before).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
temporal-documentation	Ready	Preview	Aug 19, 2026 3:53pm

[github-actions]

📖 Docs PR preview links

This PR does not change any pages in /docs. If you make updates, links to the modified pages will appear here.

[Copilot]

Pull request overview

Expands the Vale heading-rule exceptions to avoid false positives for Temporal terminology and product names.

Changes:

• Adds Temporal concepts and plural variants.
• Adds exact product phrases, provider names, and acronyms.
• Preserves narrow matching for Audit Log terminology.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.