refactor: use path-based vale rules instead of inline comments

- Update .vale.ini with improved MDX parsing and path-based rules
- Add scopes (IgnoredScopes/SkippedScopes) to skip code blocks and links
- Configure TokenIgnores/BlockIgnores for import/export and JS expressions
- Add path-specific rules for snippets, sample-apps, and components
- Remove all 53 inline HTML vale comment lines across 27 files
- Fix BlockIgnores regex to be non-greedy: (?sm)^{.+?}$
- Update snippet glob to snippets/**/*.mdx for better nested directory handling
- Add scope: text to AuthDocs.Spelling rule for consistency
- Restore HTML list structure in github.mdx (broken by comment removal)
- Remove orphaned Info component in google-calendar/langgraph.mdx

Benefits:
- Cleaner, more maintainable documentation
- Less noisy diffs going forward
- Vale rules configured by content type, not per-block
- Still passes with 0 errors, 0 warnings, 0 suggestions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: btiernay

auth4genai/.vale.ini

@@ -13,6 +13,10 @@ StylesPath = .vale/styles
 ; Only show / fail on error-level issues in CI.
 MinAlertLevel = error
 
+; Scopes to ignore completely
+IgnoredScopes = code, tt, img, url, a
+SkippedScopes = script, style, pre, figure, code
+
 [formats]
 ; Normalize MDX into Markdown so Vale can parse it.
 mdx = md
@@ -22,6 +26,9 @@ mdx = md
 ; https://vale.sh/docs/getting-started/configuration/#basedonstyles
 BasedOnStyles = Vale, AuthDocs
 
+; MDX-aware comment delimiters for inline vale off/on
+CommentDelimiters = {/*, */}
+
 ; Keep helpful core rules.
 Vale.Terms = YES
 Vale.Repetition = YES
@@ -35,3 +42,25 @@ AuthDocs.Spelling = YES
 ; Substitution rule for brand capitalization and common typos:
 ; https://vale.sh/docs/checks/substitution
 AuthDocs.Brands = YES
+
+; MDX structural patterns to ignore:
+; - import/export statements
+; - JavaScript expression blocks (non-greedy to avoid hiding content)
+TokenIgnores = (?m)^(?:import|export) .+$
+BlockIgnores = (?sm)^{.+?}$
+
+; Snippets and code-heavy examples: relax brand rules
+[snippets/**/*.mdx]
+AuthDocs.Brands = suggestion
+
+; Component demo content: disable strict rules
+[components.mdx]
+AuthDocs.Brands = NO
+AuthDocs.Spelling = suggestion
+
+; Sample app index pages: mostly links and metadata
+[mcp/sample-apps.mdx]
+AuthDocs.Brands = NO
+
+[sample-apps.mdx]
+AuthDocs.Brands = NO

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

@@ -9,6 +9,7 @@
 extends: spelling
 message: "Did you really mean '%s'?"
 level: error
+scope: text
 
 # Paths are relative to StylesPath (here: .vale/styles).
 # This file lives at:

auth4genai/how-tos/list-github-repositories.mdx

@@ -4,7 +4,6 @@ description: "Use OpenAI, NextJS, and the Auth0-AI SDKs to list your GitHub repo
 mode: "wide"
 ---
 
-<!-- vale off -->
 import AISDKSample from "/snippets/how-tos/github/ai-sdk.mdx";
 import CloudflareAgents from "/snippets/how-tos/github/cloudflare-agents.mdx";
 import LangGraphJSSample from "/snippets/how-tos/github/langgraph.mdx";
@@ -13,7 +12,6 @@ import LlamaIndexSample from "/snippets/how-tos/github/llamaindex-python.mdx";
 import NextJSAuth0Sample from "/snippets/how-tos/github/nextjs-auth0.mdx";
 import GenKitSample from "/snippets/how-tos/github/genkit.mdx";
 import LlamaIndexJSSample from "/snippets/how-tos/github/llamaindex.mdx";
-<!-- vale on -->
 import AccountLinking from "/snippets/how-tos/account-linking.mdx";
 import CreateCustomApiClient from "/snippets/common/create-custom-api-client.mdx";
 

auth4genai/integrations/github.mdx

@@ -24,13 +24,13 @@ GitHub apps [use fine grained permissions](https://docs.github.com/en/enterprise
 <Steps>
   <Step title="Set up app in GitHub">
     <ol>
-      <!-- vale off --> <li>
+      <li>
         Sign up for a [GitHub Developer account](https://github.com/signup)
-      </li> <!-- vale on -->
-      <!-- vale off --> <li>
+      </li>
+      <li>
         Set up a new GitHub app via [GitHub Developer Settings > GitHub
         Apps](https://github.com/settings/apps/new)
-      </li> <!-- vale on -->
+      </li>
       <li>
         Use the following settings when configuring your GitHub app:
         <ul>

auth4genai/mcp/sample-apps.mdx

@@ -5,15 +5,12 @@ description: Explore sample MCP apps built using Auth for MCP.
 mode: "wide"
 ---
 
-<!-- vale off -->
 <Note>
   We value your feedback! To ask questions, report issues, or request new
   frameworks and providers, connect with us on
   [GitHub](https://github.com/auth0/auth-for-genai).
 </Note>
-<!-- vale on -->
 
-<!-- vale off -->
 <Columns cols={2}>
   <Card
     title="Task Vantage"
@@ -43,4 +40,3 @@ mode: "wide"
     Go further and explore our repository of standalone sample applications that showcase Auth0's authentication and authorization capabilities in MCP servers. Each sample demonstrates how to implement Auth for MCP in your MCP servers with different frameworks and different features that Auth0 offers.
   </Card>
 </Columns>
-<!-- vale on -->

auth4genai/sample-apps.mdx

@@ -5,15 +5,12 @@ sidebarTitle: AI Agent Sample Apps
 mode: "wide"
 ---
 
-<!-- vale off -->
 <Note>
   We value your feedback! To ask questions, report issues, or request new
   frameworks and providers, connect with us on
   [GitHub](https://github.com/auth0/auth-for-genai).
 </Note>
-<!-- vale on -->
 
-<!-- vale off -->
 <Columns cols={2}>
   <Card
     title="Assistant0"
@@ -41,7 +38,6 @@ mode: "wide"
         [LlamaIndex + Next.js
         version](https://github.com/auth0-samples/auth0-assistant0/tree/main/ts-llamaindex)
       </li>
-      <!-- vale on -->
     </ul>
   </Card>
   <Card
@@ -80,4 +76,3 @@ mode: "wide"
     demonstrate recommended implementation patterns for the SDKs.
   </Card>
 </Columns>
-<!-- vale on -->

auth4genai/sdks/javascript-sdk.mdx

@@ -92,7 +92,6 @@ Checkout our sample applications for JavaScript/TypeScript built with frameworks
     (Gmail, Google Calendar, etc) securely using Token Vault, Human-in-the-loop
     interactions using Asynchronous Authorization, and using Auth0 FGA for
     securing RAG tools.
-    <!-- vale off -->
     <ul className="list-disc list-inside pl-4">
       <li>
         [LangGraph
@@ -106,7 +105,6 @@ Checkout our sample applications for JavaScript/TypeScript built with frameworks
         [LlamaIndex
         version](https://github.com/auth0-samples/auth0-assistant0/tree/main/ts-llamaindex)
       </li>
-      <!-- vale on -->
     </ul>
   </Card>
   <Card

auth4genai/snippets/get-started/langchain-next-js/async-auth.mdx

@@ -152,11 +152,9 @@ export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, runtime } =
 ```
 
 ### Add Custom Authentication
-<!-- vale off -->
 <Info>
 For more information on how to add custom authentication for your LangGraph Platform application, read the [Custom Auth](https://langchain-ai.github.io/langgraphjs/how-tos/auth/custom_auth/) guide.
 </Info>
-<!-- vale on -->
 In your `langgraph.json`, add the path to your auth file:
 ```typescript langgraph.json wrap lines highlight={8}
 {

auth4genai/snippets/get-started/langchain-next-js/auth-for-rag.mdx

@@ -180,11 +180,9 @@ export const getUser = async () => {
 ```
 
 ### Add Custom Authentication
-<!-- vale off -->
 <Info>
 For more information on how to add custom authentication for your LangGraph Platform application, read the [Custom Auth](https://langchain-ai.github.io/langgraphjs/how-tos/auth/custom_auth/) guide.
 </Info>
-<!-- vale on -->
 In your `langgraph.json`, add the path to your auth file:
 ```typescript langgraph.json wrap lines highlight={8}
 {

auth4genai/snippets/get-started/langchain-next-js/call-others-api.mdx

@@ -216,11 +216,9 @@ export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, runtime } =
 ```
 
 ### Add Custom Authentication
-<!-- vale off -->
 <Info>
 For more information on how to add custom authentication for your LangGraph Platform application, read the [Custom Auth](https://langchain-ai.github.io/langgraphjs/how-tos/auth/custom_auth/) guide.
 </Info>
-<!-- vale on -->
 In your `langgraph.json`, add the path to your auth file:
 ```typescript langgraph.json wrap lines highlight={8}
 {