fix: resolve all vale linting errors

auth4genai/.vale.ini

@@ -1,10 +1,122 @@
+; Vale configuration for Mintlify docs.
+; Mintlify CI will pick this up if enabled:
+; https://www.mintlify.com/docs/deploy/ci
+;
+; Keep this file under version control and evolve it with the docs:
+; https://www.mintlify.com/guides/maintenance
+;
+; Vale config reference:
+; https://vale.sh/docs
+;
+; MDX support:
+; - Vale 3.13+ treats .mdx as a first class format.
+; - MDX parsing is handled by the external mdx2vast CLI, which must be
+;   installed and available on $PATH:
+;     npm install -g mdx2vast
+;
+; When Vale flags something that is actually OK:
+; - If it is project-wide (for example a product name), add it to:
+;     .vale/styles/config/ignore/authdocs.txt
+; - If it is a systematic branding issue, add a swap to:
+;     .vale/styles/AuthDocs/Brands.yml
+; - Only use {/* vale off */} / {/* vale on */} for
+;   narrow, one-off cases (quotes, unusual examples).
+
+StylesPath = .vale/styles
+
+; Only report error-level issues. Suggestions and warnings are suppressed
+; entirely so devs are not blocked on minor style nits.
 MinAlertLevel = error
 
-[formats]
-mdx = md
+; Scopes to ignore completely. These are either:
+; - Already covered by other tooling, or
+; - Places where language checks are too noisy or fragile
+;   (inline code, URLs, links, images).
+; Note: 'code' is handled by SkippedScopes below for block-level code.
+IgnoredScopes = tt, img, url, a
+
+; Skip entire blocks that are not prose. This keeps Vale out of
+; style/script tags, <pre> blocks, code fences, and figures.
+SkippedScopes = script, style, pre, figure, code
+
+; Optional checks developers may enable locally:
+; vale.Annotations = YES
 
 [*.mdx]
-BasedOnStyles = Vale
-Vale.Terms = NO
+; Base on Vale's core rules plus our custom AuthDocs style:
+; https://vale.sh/docs/getting-started/configuration/#basedonstyles
+BasedOnStyles = Vale, AuthDocs
+
+; Keep helpful core rules for terminology consistency and
+; repeated word detection across the docs.
+Vale.Terms = YES
+Vale.Repetition = YES
+
+; Replace the built-in spelling rule with a custom one that knows about our
+; domain-specific vocabulary:
+; https://vale.sh/docs/checks/spelling
+; Turning Vale.Spelling off here avoids double reporting issues that our
+; AuthDocs.Spelling rule already handles with an ignore list.
 Vale.Spelling = NO
-Vale.Repetition = NO
+AuthDocs.Spelling = YES
+
+; Substitution rule for brand capitalization and common typos:
+; https://vale.sh/docs/checks/substitution
+; Keep this focused so that automated fixes remain predictable.
+AuthDocs.Brands = YES
+
+[*.md]
+; Apply the same style stack to plain Markdown files so behavior
+; is consistent across .md and .mdx content.
+BasedOnStyles = Vale, AuthDocs
+
+; Keep behavior consistent with MDX files.
+Vale.Terms = YES
+Vale.Repetition = YES
+
+; Use the same custom spelling + brand rules as MDX.
+Vale.Spelling = NO
+AuthDocs.Spelling = YES
+AuthDocs.Brands = YES
+
+; Snippets and code-heavy examples: disable brand rules.
+; These files are mostly inline code and copied examples where
+; strict brand enforcement would generate a lot of noise.
+[snippets/**/*.mdx]
+AuthDocs.Brands = NO
+
+; Component demo content: disable spelling and brand rules.
+; This page is primarily example copy used to exercise UI components,
+; not user-facing documentation.
+[components.mdx]
+AuthDocs.Brands = NO
+AuthDocs.Spelling = NO
+
+; Sample app index pages: disable brands.
+; Mostly links, titles, and names where strict enforcement over-triggers.
+[mcp/sample-apps.mdx]
+AuthDocs.Brands = NO
+
+[sample-apps.mdx]
+AuthDocs.Brands = NO
+
+; GitHub integration page: disable brands.
+; Contains github in URLs and domain-like strings where strict brand
+; correction would generate noise.
+[integrations/github.mdx]
+AuthDocs.Brands = NO
+
+; GitHub how-to snippet files: disable brands.
+; Contain lowercase github in text and URLs.
+[snippets/how-tos/github/**/*.mdx]
+AuthDocs.Brands = NO
+
+; SDK documentation pages: disable brands.
+; Contain GitHub sample repository URLs.
+[sdks/**/*.mdx]
+AuthDocs.Brands = NO
+
+; Overview and hub pages: disable brands.
+; Mostly cards and links that aggregate other content.
+[how-tos/overview.mdx]
+AuthDocs.Brands = NO

auth4genai/.vale/README.md

@@ -0,0 +1,164 @@
+# Vale Linting
+
+This directory contains the Vale configuration used to lint and standardize the documentation in `auth4genai`. Vale helps ensure consistent terminology, brand usage, spelling, and overall prose quality.
+
+## Requirements
+
+To run Vale with MDX support, you must have:
+
+- **Vale 3.13.0 or newer**
+- **mdx2vast 0.3.0 or newer**
+- Node.js and npm installed
+- Both `vale` and `mdx2vast` available on your `$PATH`
+
+## Installation
+
+Vale must be installed locally before running checks. MDX support additionally requires the external parser `mdx2vast`.
+
+Install Vale ([docs](https://vale.sh/docs/install)):
+
+```bash
+brew install vale
+```
+
+Install the MDX parser ([MDX format docs](https://vale.sh/docs/formats/mdx)):
+
+```bash
+npm install -g mdx2vast
+```
+
+Both executables must be available in your `$PATH`.
+
+Run Vale from the `auth4genai` directory:
+
+```bash
+vale .
+```
+
+A clean run should report zero errors. If you see unexpected output, refer to the [MDX behavior notes](https://vale.sh/docs/formats/mdx#behaviors) for details on what Vale ignores by default.
+
+## How MDX content is interpreted
+
+> **Important:** MDX files do *not* support HTML comments (`<!-- vale off -->`).
+> Always use MDX comment syntax instead:
+>
+> ```mdx
+> {/* vale off */}
+> ...ignored content...
+> {/* vale on */}
+> ```
+
+Vale parses `.mdx` files using `mdx2vast`. The parser automatically ignores:
+
+* `import` and `export` statements
+* JSX components and JSX blocks
+* fenced code blocks
+* inline backtick code
+* URLs (see [URL handling](https://vale.sh/docs/topics/urls))
+* single-line `{ ... }` JavaScript expressions
+
+These defaults help avoid false positives in pages that combine prose with examples, components, and structured metadata.
+
+Inline MDX-aware controls are supported when necessary. MDX files use curly-brace comment syntax (not HTML comments):
+
+```mdx
+{/* vale off */}   …ignored…   {/* vale on */}
+{/* vale Style.RuleName = NO */}
+{/* vale Style.RuleName["match"] = NO */}
+```
+
+For example, to disable the custom spelling rule for a specific word that would normally be flagged:
+
+```mdx
+{/* vale AuthDocs.Spelling["ocurrance"] = NO */}
+This misspelling is intentional in this context and should be skipped.
+{/* vale AuthDocs.Spelling["ocurrance"] = YES */}
+```
+
+**Note:** These are MDX-style comments. HTML comments (`<!-- vale off -->`) will not work in `.mdx` files.
+
+Guidance on these controls:
+[https://vale.sh/docs/topics/config/#comment-based-controls](https://vale.sh/docs/topics/config/#comment-based-controls)
+
+## Configuration structure
+
+All configuration begins with a single file: `.vale.ini`. That file loads a custom style bundle located under `.vale/styles`.
+
+### `.vale.ini`
+
+* Configures MDX and Markdown behavior using a shared style stack
+* Enables project-specific rules via `AuthDocs`
+* Sets global defaults such as `MinAlertLevel = error` (only error-level issues are reported; suggestions and warnings are suppressed)
+* Applies overrides for snippet directories, component demos, and sample-app index pages
+* Contains path-based exceptions for content where strict linting generates false positives
+
+See the Vale config reference:
+[https://vale.sh/docs/topics/config](https://vale.sh/docs/topics/config)
+
+### `.vale/styles/AuthDocs/Spelling.yml`
+
+Defines a custom spelling rule that replaces Vale’s default spellchecker.
+This rule:
+
+* Uses project-specific ignore lists
+* Reduces noise from acronyms, product names, config keys, or identifiers
+* Helps catch real typos while avoiding false positives
+
+Vale spelling check reference:
+[https://vale.sh/docs/checks/spelling](https://vale.sh/docs/checks/spelling)
+
+The ignore list it relies on lives at:
+
+```
+.vale/styles/config/ignore/authdocs.txt
+```
+
+### `.vale/styles/config/ignore/authdocs.txt`
+
+Contains domain-specific vocabulary:
+
+* Product names
+* Framework and platform names
+* Identifiers and config keys
+* Project jargon
+* Terms we expect to appear in code or prose without being flagged
+
+See the “ignore files” section of the spelling check docs:
+[https://vale.sh/docs/checks/spelling/#ignore-files](https://vale.sh/docs/checks/spelling/#ignore-files)
+
+This file should be kept up to date as terminology evolves. Mintlify’s maintenance guidance is helpful here:
+[https://www.mintlify.com/guides/maintenance](https://www.mintlify.com/guides/maintenance)
+
+### `.vale/styles/AuthDocs/Brands.yml`
+
+Contains substitution rules for:
+
+* brand capitalization (for example, `github` → `GitHub`, `javascript` → `JavaScript`)
+* recurring misspellings
+* invalid plurals (for example, `SDK's` → `SDKs`)
+
+Vale substitution check reference:
+[https://vale.sh/docs/checks/substitution](https://vale.sh/docs/checks/substitution)
+
+Only systematic, project-wide corrections should be added.
+
+**Note:** If a file generates repeated false positives from brand checks (for example, GitHub URLs on an integration page), the preferred approach is to disable `AuthDocs.Brands` for that path in `.vale.ini` rather than adding exceptions to the rule. See the "MDX and Markdown overrides in `.vale.ini`" section below.
+
+### MDX and Markdown overrides in `.vale.ini`
+
+Certain paths contain examples, generated text, or content where strict rules generate noise. In these paths we disable or relax specific rules:
+
+* `snippets/**/*.mdx` – brand checks disabled
+* `components.mdx` – brand and spelling checks disabled
+* `sample-apps.mdx` and `mcp/sample-apps.mdx` – brand checks disabled
+* overview or card-heavy pages (`how-tos/overview.mdx`) – brand checks disabled
+
+These overrides help keep CI output stable without disabling important linting elsewhere.
+
+## Helpful references
+
+* Vale documentation: [https://vale.sh/docs](https://vale.sh/docs)
+* MDX parser (`mdx2vast`): [https://github.com/errata-ai/MDX](https://github.com/errata-ai/MDX)
+* Mintlify CI integration: [https://mintlify.com/docs/deploy/ci](https://mintlify.com/docs/deploy/ci)
+* Mintlify maintenance guidance: [https://mintlify.com/guides/maintenance](https://mintlify.com/guides/maintenance)
+* Mintlify writing style tips: [https://mintlify.com/guides/writing-style-tips](https://mintlify.com/guides/writing-style-tips)

auth4genai/.vale/styles/AuthDocs/Brands.yml

@@ -0,0 +1,34 @@
+# Normalization rules for brand names, pluralization fixes, and recurring typos.
+#
+# Substitution rule reference:
+#   https://vale.sh/docs/checks/substitution
+#
+# Guidelines:
+#   - Use this file for systematic, project-wide corrections.
+#   - Add legitimate domain terms to the ignore list instead:
+#       .vale/styles/config/ignore/authdocs.txt
+#   - Prefer substitutions here over inline disable blocks.
+#   - Avoid adding one-off or file-specific corrections.
+
+extends: substitution
+message: "Consider using '%s' instead of '%s'."
+level: error
+ignorecase: true
+scope: text
+
+swap:
+  # Brand capitalization
+  # Word boundaries match whole words only. This can trigger on substrings
+  # like github in "example.github.io" due to punctuation (. = non-word char).
+  # Disable AuthDocs.Brands in files where this generates false positives.
+  "\\bgithub\\b": GitHub
+  "\\bjavascript\\b": JavaScript
+
+  # Incorrect plurals / possessives
+  "SDK's": SDKs
+  "sdk's": SDKs
+
+  # Recurring typos in this repo
+  commnd: command
+  ocurrs: occurs
+  repositores: repositories

auth4genai/.vale/styles/AuthDocs/Spelling.yml

@@ -0,0 +1,18 @@
+# Custom spelling rule for this documentation set.
+#
+# Spelling rule reference:
+#   https://vale.sh/docs/checks/spelling
+#
+# Purpose:
+#   - Catch actual typos while avoiding noise from domain-specific terms.
+#   - Accepted terms must be placed in the ignore file:
+#       .vale/styles/config/ignore/authdocs.txt
+#   - Inline disabling should be rare and only for unusual cases.
+
+extends: spelling
+message: "Did you really mean '%s'?"
+level: error
+scope: text
+
+ignore:
+- config/ignore/authdocs.txt