docs: fix Vale warnings from PRs merged in the last week

[mintlify]

Summary

Audit and remediate Vale spellcheck warnings surfaced by the Mintlify Validation (mintlify) - vale-spellcheck check across the 39 PRs merged into mintlify/docs since 2026-06-04. Findings were deduplicated by file and filtered to English-only files (translations under es/, fr/, zh/ and changelog.mdx are excluded by .vale.ini, so warnings on those paths are out of scope).

Changes

Style fixes

• assistant/index.mdx:9 — passive "is enabled by default" → "is on by default" (Vale: Mintlify.Passive).
• deploy/cloudflare.mdx:125 — passive "your main site is set up" → imperative "Set up your main site…" (Vale: Mintlify.Passive).
• guides/internationalization.mdx:743 — two passive "should/be translated" instances rewritten in active voice (Vale: Mintlify.Passive).
• migration-services/pro.mdx:70 — Card title Functionality → Features (Vale: Mintlify.WordList "functionality" → "capability|feature").

Vocabulary additions

Three legitimate English words that Vale flagged as misspellings (Vale.Spelling "Did you really mean 'X'?") were added to .vale/styles/config/vocabularies/Mintlify/accept.txt:

• sandboxed — used in customize/react-components.mdx:71
• scrollable — used in customize/custom-scripts.mdx:82, 87
• unmerged — used in workflows/reference.mdx:17

This follows the precedent set in #6131 (adding new technical terms to the accept list rather than rewriting copy).

Items flagged for human review

The remaining Vale findings from the audited PRs appear to be false positives or context-dependent calls that I am not confident enough to fix without risking a meaning change. Listing them here for a human pass:

Sentence-case headings flagged as needing lowercase

The Vale.Vocab/WordList substitution rules are case-sensitive against the accept list, so they fire on perfectly correct sentence-case headings.

• organize/navigation.mdx:442, 444 — ## Dropdowns ("Use 'dropdowns?' instead of 'Dropdowns'.")
• organize/navigation.mdx:1014, 1016 — ## Breadcrumbs
• organize/pages.mdx:17 — <Tooltip tip="Sidebar">-style heading flagged ("Use 'sidebars?' instead of 'Sidebar'.")
• create/image-embeds.mdx:181 — ## Iframes
• customize/custom-scripts.mdx — multiple <Accordion title="Dropdown">, <Accordion title="Sidebar">, etc. accordion category labels (lines 125, 133, 149, 173, 231, 258, 271)
• organize/settings-reference.mdx:157, 163, 209, 215 — same pattern
• organize/settings-structure.mdx:185 — same pattern

These look correct as-is. Consider either (a) loosening the WordList rule to ignorecase: true or (b) adding heading-only exceptions.

"agents" vs "AGENTS"

Vale flags every lowercase agents because AGENTS (the filename AGENTS.md) is in vocab in that exact case. Rewriting the noun "agents" (referring to AI agents in prose) to AGENTS would be wrong. Affected lines include ai/model-context-protocol.mdx:17, 29, 34, 39, 43, 85 and workflows/create.mdx:28. Suggest the same ignorecase: true / vocab rework as above.

"above" used spatially, not positionally

Mintlify.WordList rewrites above → preceding, which is correct for "see the table above" but wrong for spatial usage. Currently false-positive on:

• customize/custom-scripts.mdx:67 ("Announcement banner displayed above the navbar.")
• customize/custom-scripts.mdx:171 ("Small label displayed above a page title.")

Code/JSX content that Vale's TokenIgnores didn't catch

• create/image-embeds.mdx:11, 12 — className, https inside a fenced HTML/JSX block.
• create/image-embeds.mdx:135 — multiple semicolons inside an HTML allow= attribute value (accelerometer; autoplay; …).
• create/image-embeds.mdx:89 — "pointer cursor" describing the CSS cursor, not the IDE.
• create/redirects.mdx:3 — frontmatter description mentions docs.json (the filename, not the language name); Vale's JSON/json substitution shouldn't apply here.
• organize/settings-reference.mdx:2, 3 and organize/settings-structure.mdx:3 — same docs.json filename issue.
• customize/react-components.mdx:75 — ellipsis inside a code span `export const MyComponent = ...`; should be skipped by SkippedScopes = code.

Quoted user/example text

• agent/slack.mdx:78 — "How do I set up authentication?" (example user question, first-person is intentional).
• guides/linking.mdx:218 — Oxford-comma rule fires on "bookmarked and shared links" (only two items; rule misfires).
• guides/internationalization.mdx:665, 667, 669 — .png extensions appearing inside a fenced code block file tree; Vale.Spelling/case rule incorrectly triggered.

"are read-only" parsed as passive

• ai/model-context-protocol.mdx:171 — "tools are read-only" — read-only is a compound adjective, not the passive verb form. False positive on Mintlify.Passive.

Other ambiguous cases

• customize/react-components.mdx:74 — "cannot be imported" inside a bulleted constraint list. Rewriting to active voice would require restructuring the bullet pattern; left as-is.
• organize/settings-reference.mdx:247 — "Don't put a space before or after a dash" — wasn't able to confidently identify which dash; suggest a manual look.

Validation

• mint broken-links → no broken links.
• mint validate reports the same pre-existing docs.json schema error noted in docs: sync es/fr/zh translations with recent English updates #6140 (contextual.options[1] = 'download-spec' not in enum); unrelated to this PR.
• The Vale check on this PR's head SHA will re-run automatically; expect a reduced (but not zero) finding count, with the remaining findings matching the "flagged for human review" list above.

---

Note

Low Risk
Documentation-only edits to style guide vocabulary and copy; no runtime, auth, or product behavior changes.

Overview
Clears Vale spellcheck and style warnings from recent docs PRs by extending the Mintlify accept list and tightening prose in a few English MDX pages.

Vocabulary: Adds sandboxed, scrollable, and unmerged to .vale/styles/config/vocabularies/Mintlify/accept.txt so legitimate technical terms in existing copy stop failing Vale.Spelling.

Style: Rewrites passive phrasing flagged by Mintlify.Passive—assistant default state (assistant/index.mdx), Cloudflare Webflow deploy warning (deploy/cloudflare.mdx), and i18n FAQ guidance on code vs. surrounding text (guides/internationalization.mdx). Per the PR scope, a migration-services/pro.mdx card title is also aligned with the word list (Functionality → Features).

Many remaining Vale hits are documented as likely false positives (sentence-case headings, spatial “above”, code/JSX scopes) and are intentionally out of scope for this pass.

^{Reviewed by Cursor Bugbot for commit 75ffdbf. 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	Jun 11, 2026, 4:40 PM

[mintlify]

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

Project	Status	Preview	Updated (UTC)
smartac	🟢 Ready	View Preview	Jun 11, 2026, 4:52 PM

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

[mintlify]

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

Project	Status	Preview	Updated (UTC)
testsignup415	🔴 Failed	–	Jun 11, 2026, 5:26 PM

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

[mintlify]

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

Project	Status	Preview	Updated (UTC)
adminroletesting	🔴 Failed	–	Jun 11, 2026, 5:52 PM

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