From 192084e5e0b65c3065d6df9bc5369265f1b6bb11 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 17 Sep 2025 13:40:20 -0700
Subject: [PATCH 01/13] add CI workflow

---
 .github/workflows/vale.yml | 56 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 .github/workflows/vale.yml

diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml
new file mode 100644
index 000000000..0ca5c79b1
--- /dev/null
+++ b/.github/workflows/vale.yml
@@ -0,0 +1,56 @@
+name: Vale
+
+on:
+  pull_request:
+    paths:
+      - "**/*.mdx"
+      - ".vale.ini"
+      - ".vale/**"
+  push:
+    branches: [main]
+    paths:
+      - "**/*.mdx"
+      - ".vale.ini"
+      - ".vale/**"
+
+jobs:
+  vale:
+    name: Vale linting
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Fetch full history for better diff detection
+          fetch-depth: 0
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v44
+        with:
+          files: |
+            **/*.mdx
+          files_ignore: |
+            .vale/**
+            README.md
+
+      - name: Vale (changed files only)
+        if: steps.changed-files.outputs.any_changed == 'true'
+        uses: errata-ai/vale-action@reviewdog
+        with:
+          files: ${{ steps.changed-files.outputs.all_changed_files }}
+          vale_flags: "--config=.vale.ini"
+          fail_on_error: false
+          reporter: github-pr-review
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+
+      - name: Vale (full check on config changes)
+        if: steps.changed-files.outputs.any_changed == 'false'
+        uses: errata-ai/vale-action@reviewdog
+        with:
+          files: '.'
+          vale_flags: "--config=.vale.ini"
+          fail_on_error: false
+          reporter: github-pr-review
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
\ No newline at end of file

From 73d4fb79cb15d92bc697c5986e623816653b1cde Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 17 Sep 2025 13:42:24 -0700
Subject: [PATCH 02/13] add script to find new vocabulary terms

---
 .vale/scripts/discover-vocabulary.sh | 33 ++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100755 .vale/scripts/discover-vocabulary.sh

diff --git a/.vale/scripts/discover-vocabulary.sh b/.vale/scripts/discover-vocabulary.sh
new file mode 100755
index 000000000..2c57423e4
--- /dev/null
+++ b/.vale/scripts/discover-vocabulary.sh
@@ -0,0 +1,33 @@
+#!/bin/bash
+# Script to discover potential vocabulary terms from Vale output
+# Usage: ./discover-vocabulary.sh [file-pattern]
+
+set -e
+
+PATTERN=${1:-"**/*.mdx"}
+OUTPUT_FILE=".vale/vocabulary-candidates.txt"
+
+echo "🔍 Discovering vocabulary candidates from Vale spelling errors..."
+echo "Pattern: $PATTERN"
+echo ""
+
+# Run Vale and extract spelling error words
+vale --no-exit $PATTERN 2>&1 | \
+grep "Vale.Spelling" | \
+sed -n "s/.*Did you really mean '\([^']*\)'.*/\1/p" | \
+sort | uniq -c | sort -nr > "$OUTPUT_FILE"
+
+if [ -s "$OUTPUT_FILE" ]; then
+    echo "Found vocabulary candidates in $OUTPUT_FILE:"
+    echo ""
+    head -20 "$OUTPUT_FILE"
+    echo ""
+    echo "Review these terms and add appropriate ones to:"
+    echo "   - .vale/styles/config/vocabularies/Mintlify/accept.txt (if valid)"
+    echo "   - .vale/styles/config/vocabularies/Mintlify/reject.txt (if misspellings)"
+    echo ""
+    echo "To clean up this file: rm $OUTPUT_FILE"
+else
+    echo "✅ No vocabulary issues found!"
+    rm -f "$OUTPUT_FILE"
+fi
\ No newline at end of file

From 15b2c9fb3757b5f9b0da7526164a9d8cfd3729f4 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 17 Sep 2025 14:28:02 -0700
Subject: [PATCH 03/13] add vocab accept list

---
 .../config/vocabularies/Mintlify/accept.txt   | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 .vale/styles/config/vocabularies/Mintlify/accept.txt

diff --git a/.vale/styles/config/vocabularies/Mintlify/accept.txt b/.vale/styles/config/vocabularies/Mintlify/accept.txt
new file mode 100644
index 000000000..dc8bee232
--- /dev/null
+++ b/.vale/styles/config/vocabularies/Mintlify/accept.txt
@@ -0,0 +1,22 @@
+# Mintlify vocabulary terms that actually trigger Vale errors
+
+# =============================================================================
+# MINTLIFY-SPECIFIC TERMS
+# =============================================================================
+callout
+Callouts
+callouts
+expandables
+Mintlify
+mintlify
+tooltip
+Tooltip
+tooltips
+
+# =============================================================================
+# OTHER TERMS
+# =============================================================================
+args
+Dev
+npm
+onboarding

From 04d20b00369e191bc8bd343251fbe30b8f0b057c Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 17 Sep 2025 14:51:38 -0700
Subject: [PATCH 04/13] add modified Google styles

---
 .vale/styles/Google/AMPM.yml               |   9 +
 .vale/styles/Google/Acronyms.yml           |  64 +++++++
 .vale/styles/Google/DateFormat.yml         |   9 +
 .vale/styles/Google/Ellipses.yml           |   9 +
 .vale/styles/Google/EmDash.yml             |  13 ++
 .vale/styles/Google/Exclamation.yml        |  12 ++
 .vale/styles/Google/FirstPerson.yml        |  13 ++
 .vale/styles/Google/HeadingPunctuation.yml |  13 ++
 .vale/styles/Google/Headings.yml           |  19 +++
 .vale/styles/Google/Latin.yml              |  11 ++
 .vale/styles/Google/LyHyphens.yml          |  14 ++
 .vale/styles/Google/OptionalPlurals.yml    |  12 ++
 .vale/styles/Google/Ordinal.yml            |   7 +
 .vale/styles/Google/OxfordComma.yml        |   7 +
 .vale/styles/Google/Parens.yml             |   7 +
 .vale/styles/Google/Passive.yml            | 184 +++++++++++++++++++++
 .vale/styles/Google/Periods.yml            |   7 +
 .vale/styles/Google/Quotes.yml             |   7 +
 .vale/styles/Google/Ranges.yml             |   7 +
 .vale/styles/Google/Semicolons.yml         |   8 +
 .vale/styles/Google/Spacing.yml            |  10 ++
 .vale/styles/Google/Spelling.yml           |  10 ++
 .vale/styles/Google/Units.yml              |   8 +
 .vale/styles/Google/Will.yml               |   7 +
 .vale/styles/Google/WordList.yml           |  44 +++++
 25 files changed, 511 insertions(+)
 create mode 100644 .vale/styles/Google/AMPM.yml
 create mode 100644 .vale/styles/Google/Acronyms.yml
 create mode 100644 .vale/styles/Google/DateFormat.yml
 create mode 100644 .vale/styles/Google/Ellipses.yml
 create mode 100644 .vale/styles/Google/EmDash.yml
 create mode 100644 .vale/styles/Google/Exclamation.yml
 create mode 100644 .vale/styles/Google/FirstPerson.yml
 create mode 100644 .vale/styles/Google/HeadingPunctuation.yml
 create mode 100644 .vale/styles/Google/Headings.yml
 create mode 100644 .vale/styles/Google/Latin.yml
 create mode 100644 .vale/styles/Google/LyHyphens.yml
 create mode 100644 .vale/styles/Google/OptionalPlurals.yml
 create mode 100644 .vale/styles/Google/Ordinal.yml
 create mode 100644 .vale/styles/Google/OxfordComma.yml
 create mode 100644 .vale/styles/Google/Parens.yml
 create mode 100644 .vale/styles/Google/Passive.yml
 create mode 100644 .vale/styles/Google/Periods.yml
 create mode 100644 .vale/styles/Google/Quotes.yml
 create mode 100644 .vale/styles/Google/Ranges.yml
 create mode 100644 .vale/styles/Google/Semicolons.yml
 create mode 100644 .vale/styles/Google/Spacing.yml
 create mode 100644 .vale/styles/Google/Spelling.yml
 create mode 100644 .vale/styles/Google/Units.yml
 create mode 100644 .vale/styles/Google/Will.yml
 create mode 100644 .vale/styles/Google/WordList.yml

diff --git a/.vale/styles/Google/AMPM.yml b/.vale/styles/Google/AMPM.yml
new file mode 100644
index 000000000..37b49edf8
--- /dev/null
+++ b/.vale/styles/Google/AMPM.yml
@@ -0,0 +1,9 @@
+extends: existence
+message: "Use 'AM' or 'PM' (preceded by a space)."
+link: "https://developers.google.com/style/word-list"
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}[AP]M\b'
+  - '\d{1,2} ?[ap]m\b'
+  - '\d{1,2} ?[aApP]\.[mM]\.'
diff --git a/.vale/styles/Google/Acronyms.yml b/.vale/styles/Google/Acronyms.yml
new file mode 100644
index 000000000..f41af0189
--- /dev/null
+++ b/.vale/styles/Google/Acronyms.yml
@@ -0,0 +1,64 @@
+extends: conditional
+message: "Spell out '%s', if it's unfamiliar to the audience."
+link: 'https://developers.google.com/style/abbreviations'
+level: suggestion
+ignorecase: false
+# Ensures that the existence of 'first' implies the existence of 'second'.
+first: '\b([A-Z]{3,5})\b'
+second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
+# ... with the exception of these:
+exceptions:
+  - API
+  - ASP
+  - CLI
+  - CPU
+  - CSS
+  - CSV
+  - DEBUG
+  - DOM
+  - DPI
+  - FAQ
+  - GCC
+  - GDB
+  - GET
+  - GPU
+  - GTK
+  - GUI
+  - HTML
+  - HTTP
+  - HTTPS
+  - IDE
+  - JAR
+  - JSON
+  - JSX
+  - LESS
+  - LLDB
+  - NET
+  - NOTE
+  - NVDA
+  - OSS
+  - PATH
+  - PDF
+  - PHP
+  - POST
+  - RAM
+  - REPL
+  - RSA
+  - SCM
+  - SCSS
+  - SDK
+  - SQL
+  - SSH
+  - SSL
+  - SVG
+  - TBD
+  - TCP
+  - TODO
+  - URI
+  - URL
+  - USB
+  - UTF
+  - XML
+  - XSS
+  - YAML
+  - ZIP
diff --git a/.vale/styles/Google/DateFormat.yml b/.vale/styles/Google/DateFormat.yml
new file mode 100644
index 000000000..e9d227fa1
--- /dev/null
+++ b/.vale/styles/Google/DateFormat.yml
@@ -0,0 +1,9 @@
+extends: existence
+message: "Use 'July 31, 2016' format, not '%s'."
+link: 'https://developers.google.com/style/dates-times'
+ignorecase: true
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}(?:\.|/)\d{1,2}(?:\.|/)\d{4}'
+  - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}'
diff --git a/.vale/styles/Google/Ellipses.yml b/.vale/styles/Google/Ellipses.yml
new file mode 100644
index 000000000..1e070517b
--- /dev/null
+++ b/.vale/styles/Google/Ellipses.yml
@@ -0,0 +1,9 @@
+extends: existence
+message: "In general, don't use an ellipsis."
+link: 'https://developers.google.com/style/ellipses'
+nonword: true
+level: warning
+action:
+  name: remove
+tokens:
+  - '\.\.\.'
diff --git a/.vale/styles/Google/EmDash.yml b/.vale/styles/Google/EmDash.yml
new file mode 100644
index 000000000..6068c2c75
--- /dev/null
+++ b/.vale/styles/Google/EmDash.yml
@@ -0,0 +1,13 @@
+extends: existence
+message: "Don't put a space before or after an em dash."
+link: "https://developers.google.com/style/dashes"
+nonword: true
+level: error
+action:
+  name: edit
+  params:
+    - trim
+    - " "
+tokens:
+  - '\s[—–]\s'
+
diff --git a/.vale/styles/Google/Exclamation.yml b/.vale/styles/Google/Exclamation.yml
new file mode 100644
index 000000000..4d9bb874e
--- /dev/null
+++ b/.vale/styles/Google/Exclamation.yml
@@ -0,0 +1,12 @@
+extends: existence
+message: "Don't use exclamation points in text."
+link: "https://developers.google.com/style/exclamation-points"
+nonword: true
+level: warning
+action:
+  name: edit
+  params:
+    - trim_right
+    - "!"
+tokens:
+  - '\w+!(?:\s|$)'
diff --git a/.vale/styles/Google/FirstPerson.yml b/.vale/styles/Google/FirstPerson.yml
new file mode 100644
index 000000000..0b7b8828c
--- /dev/null
+++ b/.vale/styles/Google/FirstPerson.yml
@@ -0,0 +1,13 @@
+extends: existence
+message: "Avoid first-person pronouns such as '%s'."
+link: 'https://developers.google.com/style/pronouns#personal-pronouns'
+ignorecase: true
+level: warning
+nonword: true
+tokens:
+  - (?:^|\s)I\s
+  - (?:^|\s)I,\s
+  - \bI'm\b
+  - \bme\b
+  - \bmy\b
+  - \bmine\b
diff --git a/.vale/styles/Google/HeadingPunctuation.yml b/.vale/styles/Google/HeadingPunctuation.yml
new file mode 100644
index 000000000..c1729868b
--- /dev/null
+++ b/.vale/styles/Google/HeadingPunctuation.yml
@@ -0,0 +1,13 @@
+extends: existence
+message: "Don't put a period at the end of a heading."
+link: "https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings"
+nonword: true
+level: warning
+scope: heading
+action:
+  name: edit
+  params:
+    - trim_right
+    - "."
+tokens:
+  - '[a-z0-9][.]\s*$'
diff --git a/.vale/styles/Google/Headings.yml b/.vale/styles/Google/Headings.yml
new file mode 100644
index 000000000..30ccc91a0
--- /dev/null
+++ b/.vale/styles/Google/Headings.yml
@@ -0,0 +1,19 @@
+extends: capitalization
+message: "'%s' should use sentence-style capitalization."
+link: "https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings"
+level: warning
+scope: heading
+match: $sentence
+indicators:
+  - ":"
+exceptions:
+  - CLI
+  - GitHub
+  - GitLab
+  - Linux
+  - macOS
+  - Mintlify
+  - TypeScript
+  - URLs
+  - Windows
+  - JSON
diff --git a/.vale/styles/Google/Latin.yml b/.vale/styles/Google/Latin.yml
new file mode 100644
index 000000000..ca03b9154
--- /dev/null
+++ b/.vale/styles/Google/Latin.yml
@@ -0,0 +1,11 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: 'https://developers.google.com/style/abbreviations'
+ignorecase: true
+level: error
+nonword: true
+action:
+  name: replace
+swap:
+  '\b(?:eg|e\.g\.)(?=[\s,;])': for example
+  '\b(?:ie|i\.e\.)(?=[\s,;])': that is
diff --git a/.vale/styles/Google/LyHyphens.yml b/.vale/styles/Google/LyHyphens.yml
new file mode 100644
index 000000000..50dacb40d
--- /dev/null
+++ b/.vale/styles/Google/LyHyphens.yml
@@ -0,0 +1,14 @@
+extends: existence
+message: "'%s' doesn't need a hyphen."
+link: "https://developers.google.com/style/hyphens"
+level: error
+ignorecase: false
+nonword: true
+action:
+  name: edit
+  params:
+    - regex
+    - "-"
+    - " "
+tokens:
+  - '\b[^\s-]+ly-\w+\b'
diff --git a/.vale/styles/Google/OptionalPlurals.yml b/.vale/styles/Google/OptionalPlurals.yml
new file mode 100644
index 000000000..4a8767d6f
--- /dev/null
+++ b/.vale/styles/Google/OptionalPlurals.yml
@@ -0,0 +1,12 @@
+extends: existence
+message: "Don't use plurals in parentheses such as in '%s'."
+link: "https://developers.google.com/style/plurals-parentheses"
+level: error
+nonword: true
+action:
+  name: edit
+  params:
+    - trim_right
+    - "(s)"
+tokens:
+  - '\b\w+\(s\)'
diff --git a/.vale/styles/Google/Ordinal.yml b/.vale/styles/Google/Ordinal.yml
new file mode 100644
index 000000000..d1ac7d27e
--- /dev/null
+++ b/.vale/styles/Google/Ordinal.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Spell out all ordinal numbers ('%s') in text."
+link: 'https://developers.google.com/style/numbers'
+level: error
+nonword: true
+tokens:
+  - \d+(?:st|nd|rd|th)
diff --git a/.vale/styles/Google/OxfordComma.yml b/.vale/styles/Google/OxfordComma.yml
new file mode 100644
index 000000000..b9ba21ebb
--- /dev/null
+++ b/.vale/styles/Google/OxfordComma.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Use the Oxford comma in '%s'."
+link: 'https://developers.google.com/style/commas'
+scope: sentence
+level: warning
+tokens:
+  - '(?:[^,]+,){1,}\s\w+\s(?:and|or)'
diff --git a/.vale/styles/Google/Parens.yml b/.vale/styles/Google/Parens.yml
new file mode 100644
index 000000000..3b8711d0c
--- /dev/null
+++ b/.vale/styles/Google/Parens.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Use parentheses judiciously."
+link: 'https://developers.google.com/style/parentheses'
+nonword: true
+level: suggestion
+tokens:
+  - '\(.+\)'
diff --git a/.vale/styles/Google/Passive.yml b/.vale/styles/Google/Passive.yml
new file mode 100644
index 000000000..3265890e5
--- /dev/null
+++ b/.vale/styles/Google/Passive.yml
@@ -0,0 +1,184 @@
+extends: existence
+link: 'https://developers.google.com/style/voice'
+message: "In general, use active voice instead of passive voice ('%s')."
+ignorecase: true
+level: suggestion
+raw:
+  - \b(am|are|were|being|is|been|was|be)\b\s*
+tokens:
+  - '[\w]+ed'
+  - awoken
+  - beat
+  - become
+  - been
+  - begun
+  - bent
+  - beset
+  - bet
+  - bid
+  - bidden
+  - bitten
+  - bled
+  - blown
+  - born
+  - bought
+  - bound
+  - bred
+  - broadcast
+  - broken
+  - brought
+  - built
+  - burnt
+  - burst
+  - cast
+  - caught
+  - chosen
+  - clung
+  - come
+  - cost
+  - crept
+  - cut
+  - dealt
+  - dived
+  - done
+  - drawn
+  - dreamt
+  - driven
+  - drunk
+  - dug
+  - eaten
+  - fallen
+  - fed
+  - felt
+  - fit
+  - fled
+  - flown
+  - flung
+  - forbidden
+  - foregone
+  - forgiven
+  - forgotten
+  - forsaken
+  - fought
+  - found
+  - frozen
+  - given
+  - gone
+  - gotten
+  - ground
+  - grown
+  - heard
+  - held
+  - hidden
+  - hit
+  - hung
+  - hurt
+  - kept
+  - knelt
+  - knit
+  - known
+  - laid
+  - lain
+  - leapt
+  - learnt
+  - led
+  - left
+  - lent
+  - let
+  - lighted
+  - lost
+  - made
+  - meant
+  - met
+  - misspelt
+  - mistaken
+  - mown
+  - overcome
+  - overdone
+  - overtaken
+  - overthrown
+  - paid
+  - pled
+  - proven
+  - put
+  - quit
+  - read
+  - rid
+  - ridden
+  - risen
+  - run
+  - rung
+  - said
+  - sat
+  - sawn
+  - seen
+  - sent
+  - set
+  - sewn
+  - shaken
+  - shaven
+  - shed
+  - shod
+  - shone
+  - shorn
+  - shot
+  - shown
+  - shrunk
+  - shut
+  - slain
+  - slept
+  - slid
+  - slit
+  - slung
+  - smitten
+  - sold
+  - sought
+  - sown
+  - sped
+  - spent
+  - spilt
+  - spit
+  - split
+  - spoken
+  - spread
+  - sprung
+  - spun
+  - stolen
+  - stood
+  - stridden
+  - striven
+  - struck
+  - strung
+  - stuck
+  - stung
+  - stunk
+  - sung
+  - sunk
+  - swept
+  - swollen
+  - sworn
+  - swum
+  - swung
+  - taken
+  - taught
+  - thought
+  - thrived
+  - thrown
+  - thrust
+  - told
+  - torn
+  - trodden
+  - understood
+  - upheld
+  - upset
+  - wed
+  - wept
+  - withheld
+  - withstood
+  - woken
+  - won
+  - worn
+  - wound
+  - woven
+  - written
+  - wrung
diff --git a/.vale/styles/Google/Periods.yml b/.vale/styles/Google/Periods.yml
new file mode 100644
index 000000000..d24a6a6c0
--- /dev/null
+++ b/.vale/styles/Google/Periods.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Don't use periods with acronyms or initialisms such as '%s'."
+link: 'https://developers.google.com/style/abbreviations'
+level: error
+nonword: true
+tokens:
+  - '\b(?:[A-Z]\.){3,}'
diff --git a/.vale/styles/Google/Quotes.yml b/.vale/styles/Google/Quotes.yml
new file mode 100644
index 000000000..3cb6f1abd
--- /dev/null
+++ b/.vale/styles/Google/Quotes.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Commas and periods go inside quotation marks."
+link: 'https://developers.google.com/style/quotation-marks'
+level: error
+nonword: true
+tokens:
+  - '"[^"]+"[.,?]'
diff --git a/.vale/styles/Google/Ranges.yml b/.vale/styles/Google/Ranges.yml
new file mode 100644
index 000000000..3ec045e77
--- /dev/null
+++ b/.vale/styles/Google/Ranges.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Don't add words such as 'from' or 'between' to describe a range of numbers."
+link: 'https://developers.google.com/style/hyphens'
+nonword: true
+level: warning
+tokens:
+  - '(?:from|between)\s\d+\s?-\s?\d+'
diff --git a/.vale/styles/Google/Semicolons.yml b/.vale/styles/Google/Semicolons.yml
new file mode 100644
index 000000000..bb8b85b42
--- /dev/null
+++ b/.vale/styles/Google/Semicolons.yml
@@ -0,0 +1,8 @@
+extends: existence
+message: "Use semicolons judiciously."
+link: 'https://developers.google.com/style/semicolons'
+nonword: true
+scope: sentence
+level: suggestion
+tokens:
+  - ';'
diff --git a/.vale/styles/Google/Spacing.yml b/.vale/styles/Google/Spacing.yml
new file mode 100644
index 000000000..66e45a6b7
--- /dev/null
+++ b/.vale/styles/Google/Spacing.yml
@@ -0,0 +1,10 @@
+extends: existence
+message: "'%s' should have one space."
+link: 'https://developers.google.com/style/sentence-spacing'
+level: error
+nonword: true
+action:
+  name: remove
+tokens:
+  - '[a-z][.?!] {2,}[A-Z]'
+  - '[a-z][.?!][A-Z]'
diff --git a/.vale/styles/Google/Spelling.yml b/.vale/styles/Google/Spelling.yml
new file mode 100644
index 000000000..527ac07d3
--- /dev/null
+++ b/.vale/styles/Google/Spelling.yml
@@ -0,0 +1,10 @@
+extends: existence
+message: "In general, use American spelling instead of '%s'."
+link: 'https://developers.google.com/style/spelling'
+ignorecase: true
+level: warning
+tokens:
+  - '(?:\w+)nised?'
+  - 'colour'
+  - 'labour'
+  - 'centre'
diff --git a/.vale/styles/Google/Units.yml b/.vale/styles/Google/Units.yml
new file mode 100644
index 000000000..53522ab2d
--- /dev/null
+++ b/.vale/styles/Google/Units.yml
@@ -0,0 +1,8 @@
+extends: existence
+message: "Put a nonbreaking space between the number and the unit in '%s'."
+link: "https://developers.google.com/style/units-of-measure"
+nonword: true
+level: error
+tokens:
+  - \b\d+(?:B|kB|MB|GB|TB)
+  - \b\d+(?:ns|ms|s|min|h|d)
diff --git a/.vale/styles/Google/Will.yml b/.vale/styles/Google/Will.yml
new file mode 100644
index 000000000..128a91836
--- /dev/null
+++ b/.vale/styles/Google/Will.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Avoid using '%s'."
+link: 'https://developers.google.com/style/tense'
+ignorecase: true
+level: warning
+tokens:
+  - will
diff --git a/.vale/styles/Google/WordList.yml b/.vale/styles/Google/WordList.yml
new file mode 100644
index 000000000..fee14b3d0
--- /dev/null
+++ b/.vale/styles/Google/WordList.yml
@@ -0,0 +1,44 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: "https://developers.google.com/style/word-list"
+level: warning
+ignorecase: false
+action:
+  name: replace
+swap:
+  "(?:API Console|dev|developer) key": API key
+  "(?:cell ?phone|smart ?phone)": phone|mobile phone
+  "(?:e-mail|Email|E-mail)": email
+  "(?:file ?path|path ?name)": path
+  "(?:kill|terminate|abort)": stop|exit|cancel|end
+  "(?:OAuth ?2|Oauth)": OAuth 2.0
+  "(?:WiFi|wifi)": Wi-Fi
+  '[\.]+apk': APK
+  '3\-D': 3D
+  "un(?:check|select)": clear
+  above: preceding
+  account name: username
+  approx\.: approximately
+  authN: authentication
+  authZ: authorization
+  autoupdate: automatically update
+  check box: checkbox
+  click on: click|click in
+  data are: data is
+  disabled?: turn off|off
+  fewer data: less data
+  file name: filename
+  functionality: capability|feature
+  grayed-out: unavailable
+  HTTPs: HTTPS
+  in order to: to
+  open-source: open source
+  SHA1: SHA-1|HAS-SHA1
+  sign into: sign in to
+  sign-?on: single sign-on
+  static IP address: static external IP address
+  stylesheet: style sheet
+  synch: sync
+  tablename: table name
+  url: URL
+  vs\.: versus

From 41a7adb0f57ac2d6fc2bf4476947aecd06c071ae Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 17 Sep 2025 14:59:16 -0700
Subject: [PATCH 05/13] add Mintlify headings

---
 .vale/styles/Google/Headings.yml | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/.vale/styles/Google/Headings.yml b/.vale/styles/Google/Headings.yml
index 30ccc91a0..a54386f33 100644
--- a/.vale/styles/Google/Headings.yml
+++ b/.vale/styles/Google/Headings.yml
@@ -4,16 +4,35 @@ link: "https://developers.google.com/style/capitalization#capitalization-in-titl
 level: warning
 scope: heading
 match: $sentence
-indicators:
-  - ":"
 exceptions:
+  - API
+  - APIs
+  - CDN
+  - CORS
   - CLI
+  - CSS
+  - DNS
   - GitHub
   - GitLab
+  - HTML
+  - JavaScript
+  - JSON
+  - JWT
   - Linux
   - macOS
   - Mintlify
+  - MDX
+  - OAuth
+  - OpenAPI
+  - PDF
+  - SAML
+  - SDK
+  - SSL
+  - SSO
+  - TLS
   - TypeScript
+  - UI
+  - UX
+  - URL
   - URLs
   - Windows
-  - JSON

From e85109926e1af074a10b81d978f03322b5a4299a Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 17 Sep 2025 15:15:01 -0700
Subject: [PATCH 06/13] add vale.ini

---
 .vale.ini | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 .vale.ini

diff --git a/.vale.ini b/.vale.ini
new file mode 100644
index 000000000..245fbd00b
--- /dev/null
+++ b/.vale.ini
@@ -0,0 +1,30 @@
+# Vale configuration for Mintlify documentation
+
+StylesPath = .vale/styles
+MinAlertLevel = suggestion
+IgnoredScopes = code, tt, img, url, a
+SkippedScopes = script, style, pre, figure, code
+
+Packages = Google
+
+Vocab = Mintlify
+
+# This is required since Vale doesn't officially support MDX
+[formats]
+mdx = md
+
+# MDX support
+[*.mdx]
+BasedOnStyles = Vale, Google, Mintlify
+Vale.Terms = NO # Enforces really harsh capitalization rules, keep off
+Vale.Avoid = NO # Too aggressive about common technical terms
+
+# Token and block ignores for MDX-specific syntax
+TokenIgnores = (?sm)((?:import|export) .+?$), \
+(?<!`)(<\w+ ?.+ ?\/>)(?!`), \
+(<[A-Z]\w+>.+?<\/[A-Z]\w+>)
+
+BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \
+(?sm)^({.+.*})
+
+CommentDelimiters = {/*, */}
\ No newline at end of file

From 35226c8fbf08a81bdb802a99bff6ee6bbae75334 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 17 Sep 2025 15:18:58 -0700
Subject: [PATCH 07/13] update vocab with Mintlify defaults

---
 .../config/vocabularies/Mintlify/accept.txt   | 191 +++++++++++++++++-
 1 file changed, 189 insertions(+), 2 deletions(-)

diff --git a/.vale/styles/config/vocabularies/Mintlify/accept.txt b/.vale/styles/config/vocabularies/Mintlify/accept.txt
index dc8bee232..919ee4323 100644
--- a/.vale/styles/config/vocabularies/Mintlify/accept.txt
+++ b/.vale/styles/config/vocabularies/Mintlify/accept.txt
@@ -3,20 +3,207 @@
 # =============================================================================
 # MINTLIFY-SPECIFIC TERMS
 # =============================================================================
+autoplay
+bearerAuth
+borderRadius
 callout
 Callouts
 callouts
 expandables
+favicon
+isHidden
 Mintlify
 mintlify
+modeToggle
+ModeToggle
+myName
+myObject
+onboarding
+openapi
+OpenAPI
+repo
+topbar
 tooltip
 Tooltip
 tooltips
+url
+
+# =============================================================================
+# PROGRAMMING LANGUAGES & FRAMEWORKS
+# =============================================================================
+Angular
+AWS
+Azure
+Babel
+babel
+Bitbucket
+Chromium
+CircleCI
+Cypress
+Django
+DynamoDB
+Elasticsearch
+ESLint
+eslint
+Express
+Firefox
+Flask
+GCP
+Git
+git
+GitHub
+GitLab
+Go
+Golang
+GraphQL
+Heroku
+IntelliJ
+Java
+JavaScript
+Jest
+jest
+JSDoc
+Kotlin
+Kubernetes
+Laravel
+Linux
+macOS
+MDX
+Mocha
+MongoDB
+MySQL
+Next.js
+Node.js
+NodeJS
+Nuxt
+OAuth
+PNPM
+Postman
+PostgreSQL
+Prettier
+prettier
+Python
+React
+Redis
+Ruby
+RubyGems
+Rust
+Spring
+Storybook
+Swift
+TensorFlow
+Terraform
+TypeDoc
+TypeScript
+Unix
+Vite
+vite
+Visual Studio Code
+VS Code
+Vue
+Vuex
+Webpack
+webpack
+WebKit
+WebStorm
 
 # =============================================================================
-# OTHER TERMS
+# TERMS
 # =============================================================================
+APIs
 args
+async
+await
+bool
+boolean
+Blockquote
+Blockquotes
+cdn
+cli
+config
+const
+cors
+csrf
+css
+ctx
+desc
 Dev
+dir
+dom
+dto
+elem
+enum
+env
+err
+func
+gui
+href
+html
+http
+https
+ide
+impl
+init
+instanceof
+jvm
+jwt
+lang
+len
+localhost
+
+md
+middleware
+Multiline
+mvc
+nav
+next
+nodejs
 npm
-onboarding
+num
+oauth
+obj
+orm
+params
+pnpm
+png
+prev
+proc
+ptr
+pytest
+req
+res
+rpc
+runtime
+scss
+sdk
+Singleline
+sql
+ssh
+ssl
+stderr
+stdin
+stdout
+Strikethrough
+struct
+svg
+tcp
+tls
+tmp
+toc
+todo
+tsx
+typeof
+ui
+undefined
+uri
+ux
+val
+var
+vars
+webhook
+websocket
+xhr
+xhr2
+yaml
+yarn
+yml

From effce39fccbfa0ad1e7f27a0e016581e4c8ea3a2 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 17 Sep 2025 15:24:21 -0700
Subject: [PATCH 08/13] add README for vale

---
 .vale/README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 .vale/README.md

diff --git a/.vale/README.md b/.vale/README.md
new file mode 100644
index 000000000..98d533d45
--- /dev/null
+++ b/.vale/README.md
@@ -0,0 +1,45 @@
+# Vale Configuration for Mintlify Docs
+
+This directory contains the Vale linting configuration for Mintlify documentation.
+
+## Philosophy
+
+Start simple and grow incrementally as needs emerge. The current setup uses:
+
+- Core Mintlify-specific vocabulary
+- Customized rules from the Google developer documentation style guide
+
+## Vale files
+- `.vale.ini` - Main configuration file
+- `styles/config/vocabularies/Mintlify/` - Mintlify-specific terms
+- `styles/Google/` - Google developer documentation style rules customized for Mintlify docs
+
+## When to add vocabulary
+- **Mintlify terms** - New components, features, platform-specific concepts
+- **Frequent false positives** - Any terms that repeatedly trigger spelling errors, but shouldn't
+
+### Discover new vocabulary
+Use the included script to find vocabulary candidates:
+```bash
+# Discover terms from all files
+.vale/scripts/discover-vocabulary.sh
+
+# Discover from specific files
+.vale/scripts/discover-vocabulary.sh "components/*.mdx"
+```
+
+This script:
+1. Runs Vale on specified files
+2. Extracts spelling error suggestions
+3. Saves results to `.vale/vocabulary-candidates.txt`
+
+## When to add new rules
+- **Consistent patterns** - The same style issue appears frequently
+- **High-value, low-noise** - Rules that catch problems with minimal false positives
+
+### Testing new rules
+Before adding a new rule:
+1. Test locally: `vale path/to/file.mdx`
+2. Run on sample files: `vale components/*.mdx`
+3. Check false positive rate
+4. Start with `level: suggestion` then promote to `warning` or `error`

From 8641917cd3fc29fb70907e69d456f0c99101e4fd Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 17 Sep 2025 15:27:28 -0700
Subject: [PATCH 09/13] update vocab

---
 .vale/styles/config/vocabularies/Mintlify/accept.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.vale/styles/config/vocabularies/Mintlify/accept.txt b/.vale/styles/config/vocabularies/Mintlify/accept.txt
index 919ee4323..d10fc87b1 100644
--- a/.vale/styles/config/vocabularies/Mintlify/accept.txt
+++ b/.vale/styles/config/vocabularies/Mintlify/accept.txt
@@ -6,6 +6,8 @@
 autoplay
 bearerAuth
 borderRadius
+camelCase
+discoverability
 callout
 Callouts
 callouts

From 7c0257902d480cde68431e1372de102887518b9f Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 17 Sep 2025 15:27:33 -0700
Subject: [PATCH 10/13] fix vale.ini

---
 .vale.ini | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.vale.ini b/.vale.ini
index 245fbd00b..9c3a813f9 100644
--- a/.vale.ini
+++ b/.vale.ini
@@ -15,7 +15,7 @@ mdx = md
 
 # MDX support
 [*.mdx]
-BasedOnStyles = Vale, Google, Mintlify
+BasedOnStyles = Vale, Google
 Vale.Terms = NO # Enforces really harsh capitalization rules, keep off
 Vale.Avoid = NO # Too aggressive about common technical terms
 

From 2f05e2dfafc40372b386920c4f3d90d2dc651aeb Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Fri, 19 Sep 2025 09:53:44 -0700
Subject: [PATCH 11/13] remove redundant workflow

---
 .github/workflows/vale.yml | 56 --------------------------------------
 1 file changed, 56 deletions(-)
 delete mode 100644 .github/workflows/vale.yml

diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml
deleted file mode 100644
index 0ca5c79b1..000000000
--- a/.github/workflows/vale.yml
+++ /dev/null
@@ -1,56 +0,0 @@
-name: Vale
-
-on:
-  pull_request:
-    paths:
-      - "**/*.mdx"
-      - ".vale.ini"
-      - ".vale/**"
-  push:
-    branches: [main]
-    paths:
-      - "**/*.mdx"
-      - ".vale.ini"
-      - ".vale/**"
-
-jobs:
-  vale:
-    name: Vale linting
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          # Fetch full history for better diff detection
-          fetch-depth: 0
-
-      - name: Get changed files
-        id: changed-files
-        uses: tj-actions/changed-files@v44
-        with:
-          files: |
-            **/*.mdx
-          files_ignore: |
-            .vale/**
-            README.md
-
-      - name: Vale (changed files only)
-        if: steps.changed-files.outputs.any_changed == 'true'
-        uses: errata-ai/vale-action@reviewdog
-        with:
-          files: ${{ steps.changed-files.outputs.all_changed_files }}
-          vale_flags: "--config=.vale.ini"
-          fail_on_error: false
-          reporter: github-pr-review
-        env:
-          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
-
-      - name: Vale (full check on config changes)
-        if: steps.changed-files.outputs.any_changed == 'false'
-        uses: errata-ai/vale-action@reviewdog
-        with:
-          files: '.'
-          vale_flags: "--config=.vale.ini"
-          fail_on_error: false
-          reporter: github-pr-review
-        env:
-          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
\ No newline at end of file

From c5e862d30c9ab42d4e823853523069973633e10b Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Fri, 19 Sep 2025 10:00:46 -0700
Subject: [PATCH 12/13] update vocab

---
 .vale/styles/Google/Headings.yml                     | 1 +
 .vale/styles/config/vocabularies/Mintlify/accept.txt | 4 +++-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/.vale/styles/Google/Headings.yml b/.vale/styles/Google/Headings.yml
index a54386f33..756f95209 100644
--- a/.vale/styles/Google/Headings.yml
+++ b/.vale/styles/Google/Headings.yml
@@ -7,6 +7,7 @@ match: $sentence
 exceptions:
   - API
   - APIs
+  - APP
   - CDN
   - CORS
   - CLI
diff --git a/.vale/styles/config/vocabularies/Mintlify/accept.txt b/.vale/styles/config/vocabularies/Mintlify/accept.txt
index d10fc87b1..647318c6b 100644
--- a/.vale/styles/config/vocabularies/Mintlify/accept.txt
+++ b/.vale/styles/config/vocabularies/Mintlify/accept.txt
@@ -125,12 +125,14 @@ cli
 config
 const
 cors
+CNAME
 csrf
 css
 ctx
 desc
 Dev
 dir
+DNS
 dom
 dto
 elem
@@ -152,7 +154,6 @@ jwt
 lang
 len
 localhost
-
 md
 middleware
 Multiline
@@ -194,6 +195,7 @@ tmp
 toc
 todo
 tsx
+TTL
 typeof
 ui
 undefined

From ec1919dad5e3a9d17bc1694796e2e6b769f98e7e Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Fri, 19 Sep 2025 10:00:58 -0700
Subject: [PATCH 13/13] add running vale to the Claude review command

---
 .claude/commands/review.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.claude/commands/review.md b/.claude/commands/review.md
index f75a18c3d..094dd4ece 100644
--- a/.claude/commands/review.md
+++ b/.claude/commands/review.md
@@ -9,6 +9,7 @@ Please review the changes I'm about to commit and check:
 3. Are any code examples accurate?
 4. Is the frontmatter complete and correct?
 5. Does the content match our existing style?
-6. Are there any links that need testing?
+6. Run vale on the files being updated and make a plan to resolve any errors, warnings, and suggestions.
+7. Are there any links that need testing?
 
 $ARGUMENTS