Vale style audit: fix em-dash spacing and tune Acronyms/kbd scopes

[mintlify]

Summary

Audit of English MDX files touched by PRs merged 2026-08-06 through 2026-08-13: fix real style hits and tighten two rules that were over-matching.

Changes

Prose fixes

• Mintlify.EmDash — Remove spaces around em-dashes in bullet definition lists (term — desc → term—desc). 185 in customize/custom-scripts.mdx, 8 in organize/settings-seo.mdx, 4 in assistant/use.mdx.
• Mintlify.WordList
  • api-playground/sdk-reference-setup.mdx: "the tab or group above them" → "the parent tab or group" (matches "above" → "preceding"; "parent" reads more naturally for hierarchy inheritance).
  • assistant/use.mdx: "the hostnames above" → "the preceding hostnames".
  • assistant/widget.mdx: "stylesheet" → "style sheet".
  • dashboard/sso.mdx: Wrap the Okta UI value Matches regex in backticks so regex sits in an ignored scope rather than reword a verbatim UI label.
• Mintlify.Quotes — guides/knowledge-base.mdx: move terminal period inside the closing quote of an example prompt.
• Mintlify.Will — enterprise-contracting.mdx: "We will warrant in writing" → "We warrant in writing" (drops the hedge; the surrounding clause already uses simple present).

Rule changes

• .vale.ini — Add kbd to IgnoredScopes. Content of <kbd> tags is a keyboard character, not prose. <kbd>I</kbd> was firing Mintlify.FirstPerson in assistant/use.mdx, contact-support.mdx, editor/agent.mdx, and editor/keyboard-shortcuts.mdx. The rule still fires on prose I/me/my outside <kbd>.
• .vale/styles/Mintlify/Acronyms.yml — Add 34 exceptions for acronyms already used unexplained throughout the docs: ACS, AEO, ANSI, AWS, CAA, CDN, CIDR, CNAME, CSP, CTA, CTR, DNS, DOCX, GEO, HEAD, IAM, ISO, JSONC, MCP, MDX, NAT, OAI, OIDC, PATCH, PUT, RBAC, ROI, RPC, SCIM, SEO, TLS, TOML, TSV, TXT, UTC, WAVE, YYYY. These already live in the Mintlify vocabulary; the rule's separate exceptions: list was silently drifting behind it and produced 371 "spell out" suggestions in the audited files. Unknown 3–5 letter acronyms still fire.

For human review

• Mintlify.OxfordComma (10 hits, all false positives) — The pattern (?:[^,]+,){1,}\s\w+\s(?:and|or) counts any comma as a list separator, so it fires on date commas (July 31, 2026 or later), conditional-clause commas (If this key type is unavailable, your organization…), and parenthetical commas (in meta tags, globally or per-page,), even when the sentence already has correct Oxford commas. All 10 flagged sentences in ai/mintlify-mcp.mdx, analytics/streaming.mdx, analytics/user-engagements.mdx, api/search-index/introduction.mdx, assistant/widget.mdx, help-center/domain-already-claimed-by-another-organization.mdx, optimize/seo.mdx, and quickstart.mdx are correct as written. Consider lowering the level or narrowing the pattern to exclude date literals and known clause markers; I didn't touch it here because I can't run Vale in the sandbox to verify a replacement pattern doesn't silently break the rule.
• Mintlify.FirstPerson on link text like [My profile] (agent/index.mdx:38, deploy/github.mdx:139) — "My profile"/"My Profile" is the literal name of a dashboard page. Rewording the link text would misidentify the UI. Vale may already ignore markdown link text via IgnoredScopes = a; if not, the narrowest fix is to add link-text scope handling to Mintlify.FirstPerson. Left untouched.
• Mintlify.FirstPerson on ## I in reference/glossary.mdx:111 — Single-letter section heading used as an alphabet marker in the glossary. Edge case; not worth a rule carve-out unless more glossaries appear.

Notes

• Vale binary is not available in this environment. Rules were evaluated against .vale/styles/Mintlify/*.yml directly, so alert counts are approximate but the classifications above reflect the actual prose.
• es/, fr/, and zh/ were not scanned (Vale is disabled there via .vale.ini).
• Alerts from inside code fences, {/* vale off */} blocks, or nested code fences were treated as scanner false positives and left alone.

---

Note

Low Risk
Changes are limited to Vale configuration and documentation copy/formatting; no application code, auth, or data handling paths are modified.

Overview
Tightens Vale so lint matches how the docs already read, then applies the resulting fixes across English and localized MDX.

Rule/config: .vale.ini ignores kbd scopes (keyboard shortcuts in <kbd> were tripping first-person rules). Mintlify/Acronyms.yml adds 34 acronym exceptions aligned with the Mintlify vocabulary so common terms (e.g. MDX, DNS, OIDC) no longer spam “spell out” suggestions.

Prose (English + mirrored es/, fr/, zh/ where the diff shows): Definition lists in customize/custom-scripts.mdx switch from spaced em-dashes (term — desc) to no-space em-dashes (term—desc). Similar list formatting updates land in organize/settings-seo.mdx and assistant hostname bullets. Small wording fixes: SDK nav inheritance uses parent tab/group; assistant copy uses preceding hostnames; widget CSP text uses style sheet; enterprise contracting drops “will warrant”; knowledge-base example prompt punctuation; Okta SAML table keeps UI label Matches regex in backticks.

Risk: Documentation and linter configuration only—no runtime product behavior.

^{Reviewed by Cursor Bugbot for commit e871402. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
mintlify	🟢 Ready	View Preview	Aug 13, 2026, 3:21 PM

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tomee	🟢 Ready	View Preview	Aug 13, 2026, 3:21 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.