Merge branch 'main' into michael/removeinitialvalue

Author: mycho2003

.claude/CLAUDE.md

@@ -0,0 +1,83 @@
+# Mintlify documentation
+
+## Working relationship
+- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
+- ALWAYS ask for clarification rather than making assumptions
+- NEVER lie, guess, or make up information
+
+## Project context
+- Format: MDX files with YAML frontmatter
+- Config: docs.json for navigation, theme, settings
+- Components: Mintlify components
+
+## Content strategy
+- Document just enough for user success - not too much, not too little
+- Prioritize accuracy and usability of information
+- Make content evergreen when possible
+- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
+- Check existing patterns for consistency
+- Start by making the smallest reasonable changes
+
+## Frontmatter requirements for pages
+- title: Clear, descriptive page title
+- description: Concise summary for SEO/navigation
+
+## Writing standards
+- Second-person voice ("you")
+- Prerequisites at start of procedural content
+- Test all code examples before publishing
+- Match style and formatting of existing pages
+- Include both basic and advanced use cases
+- Language tags on all code blocks
+- Alt text on all images
+- Relative paths for internal links
+- Use broadly applicable examples rather than overly specific business cases
+- Lead with context when helpful - explain what something is before diving into implementation details
+
+### Style preferences (learned from content refresh project)
+#### Headings and formatting
+- Use sentence case for all headings ("Getting started", not "Getting Started")
+- Use "Properties" instead of "Props" for component documentation
+- Use sentence case for code block titles ("Expandable example", not "Expandable Example")
+
+#### Component introductions
+- Start with action-oriented language: "Use [component] to..." rather than "The [component] component..."
+- Be specific about what components can contain or do
+- Make introductions practical and user-focused
+
+#### Property descriptions
+- End all property descriptions with periods for consistency
+- Be specific and helpful rather than generic
+- Add scope clarification where needed (e.g., "For Font Awesome icons only:")
+- Use proper technical terminology ("boolean" not "bool")
+
+#### Language and tone
+- Prefer active voice and direct language
+- Remove unnecessary words while maintaining clarity
+- Use "you complete" over "completing" for more direct communication
+- Break complex instructions into clear numbered steps
+- Make language more precise and contextual
+
+#### Code examples
+- Keep examples simple and practical
+- Use consistent formatting and naming
+- Provide clear, actionable examples rather than showing multiple options when one will do
+
+#### Content organization
+- Structure content in the order users need it
+- Combine related information to reduce redundancy
+- Use specific links (direct to relevant pages rather than generic dashboards)
+- Put most commonly needed information first
+
+## Git workflow
+- NEVER use --no-verify when committing
+- Ask how to handle uncommitted changes before starting
+- Create a new branch when no clear branch exists for changes
+- Commit frequently throughout development
+- NEVER skip or disable pre-commit hooks
+
+## Do not
+- Skip frontmatter on any MDX file
+- Use absolute URLs for internal links
+- Include untested code examples
+- Make assumptions - always ask for clarification

.cursor/rules/writing-standards.mdc

@@ -428,7 +428,7 @@ description: "Concise description explaining page purpose and value"
 - Verify all code examples are syntactically correct and executable
 - Test all links to ensure they are functional and lead to relevant content
 - Validate Mintlify component syntax with all required properties
-- Confirm proper heading hierarchy with H2 for main sections, H3 for subsections
+- Confirm proper heading hierarchy with H2 for main sections, H3 for subsections. Do not use H1 (reserved for page title)
 - Ensure content flows logically from basic concepts to advanced topics
 - Check for consistency in terminology, formatting, and component usage
 - Include appropriate warnings for destructive or security-sensitive actions
@@ -483,4 +483,30 @@ description: "Concise description explaining page purpose and value"
 - Regularly review and update outdated information
 - Remove deprecated features and references
 - Update screenshots when UI changes occur
-- Maintain consistency across related documentation pages
+- Maintain consistency across related documentation pages
+
+## Request handling examples
+
+### When asked to "create a new page":
+1. First, determine the appropriate location in the file structure
+2. Create the file with proper frontmatter
+3. Structure content using appropriate Mintlify components
+4. Include relevant images and code examples
+
+### When asked to "improve existing content":
+1. Review current structure and identify gaps
+2. Suggest specific component improvements
+3. Add missing callouts or examples
+4. Ensure proper heading hierarchy
+
+## Component selection decision trees
+
+### For procedures:
+- Use <Steps> when: Sequential numbered instructions
+- Use <Tabs> when: Platform-specific alternatives
+- Use <AccordionGroup> when: Optional supplementary info
+
+### For code examples:
+- Use single ``` when: One language, simple example
+- Use <CodeGroup> when: Same concept in multiple languages
+- Use <RequestExample>/<ResponseExample> when: API documentation

README.md

@@ -0,0 +1,13 @@
+# Mintlify Documentation
+
+Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command
+
+```
+npm i -g mintlify
+```
+
+Run the following command at the root of your documentation (where mint.json is)
+
+```
+mintlify dev
+```

advanced/dashboard/roles.mdx

@@ -3,6 +3,10 @@ title: "Roles"
 description: "Control access to your dashboard with roles."
 ---
 
+<Info>
+  RBAC functionality is available on [Enterprise plan](https://mintlify.com/pricing?ref=rbac).
+</Info>
+
 Mintlify provides two dashboard access levels: Editor and Admin.
 
 The following describes actions that are limited to the Admin role:

advanced/subpath/cloudflare.mdx

@@ -19,6 +19,25 @@ Create a Cloudflare Worker by following the [Cloudflare Workers getting started
   If your DNS provider is Cloudflare, do not use proxying for the CNAME record.
 </Warning>
 
+### Proxies with Vercel deployments
+
+If you use Cloudflare as a proxy with Vercel deployments, you must ensure proper configuration to avoid conflicts with Vercel's domain verification and SSL certificate provisioning.
+
+Improper proxy configuration can prevent Vercel from provisioning Let's Encrypt SSL certificates and cause domain verification failures.
+
+#### Required path allowlist
+
+Your Cloudflare Worker must allow traffic to these specific paths without blocking or redirecting:
+
+- `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
+- `/.well-known/vercel/*` - Required for Vercel domain verification
+
+While Cloudflare automatically handles many verification rules, creating additional custom rules may inadvertently block this critical traffic.
+
+#### Header forwarding requirements
+
+Ensure that the `HOST` header is correctly forwarded in your Worker configuration. Failure to properly forward headers will cause verification requests to fail.
+
 ### Configure routing
 
 In your Cloudflare dashboard, select **Edit Code** and add the following script into your Worker's code. See the [Cloudflare documentation](https://developers.cloudflare.com/workers-ai/get-started/dashboard/#development) for more information on editing a Worker.
@@ -35,6 +54,12 @@ addEventListener("fetch", (event) => {
 async function handleRequest(request) {
   try {
     const urlObject = new URL(request.url);
+    
+    // If the request is to a Vercel verification path, allow it to pass through
+    if (urlObject.pathname.startsWith('/.well-known/')) {
+      return await fetch(request);
+    }
+    
     // If the request is to the docs subdirectory
     if (/^\/docs/.test(urlObject.pathname)) {
       // Then Proxy to Mintlify
@@ -49,11 +74,13 @@ async function handleRequest(request) {
       proxyRequest.headers.set("Host", DOCS_URL);
       proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
       proxyRequest.headers.set("X-Forwarded-Proto", "https");
+      // If deploying to Vercel, preserve client IP
+      proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
 
       return await fetch(proxyRequest);
     }
   } catch (error) {
-    // if no action found, play the regular request
+    // If no action found, play the regular request
     return await fetch(request);
   }
 }
@@ -110,6 +137,12 @@ If you use Webflow to host your main site and want to serve Mintlify docs at `/d
   async function handleRequest(request) {
   try {
     const urlObject = new URL(request.url);
+    
+    // If the request is to a Vercel verification path, allow it to pass through
+    if (urlObject.pathname.startsWith('/.well-known/')) {
+      return await fetch(request);
+    }
+    
     // If the request is to the docs subdirectory
     if (/^\/docs/.test(urlObject.pathname)) {
       // Proxy to Mintlify
@@ -121,6 +154,8 @@ If you use Webflow to host your main site and want to serve Mintlify docs at `/d
       proxyRequest.headers.set("Host", DOCS_URL);
       proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
       proxyRequest.headers.set("X-Forwarded-Proto", "https");
+      // If deploying to Vercel, preserve client IP
+      proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
       return await fetch(proxyRequest);
     }
     // Route everything else to main site

advanced/subpath/route53-cloudfront.mdx

@@ -6,6 +6,31 @@ description: "Host documentation at a /docs subdirectory using AWS services"
 
 import Propagating from "/snippets/custom-subpath-propagating.mdx";
 
+To host your documentation at a `/docs` subpath using AWS Route 53 and Cloudfront, you need to configure your DNS provider to point to your Cloudfront distribution.
+
+## Proxies with Vercel deployments
+
+If you use AWS CloudFront as a proxy with Vercel deployments, you must configure CloudFront to avoid interfering with Vercel's domain verification and SSL certificate provisioning.
+
+Improper CloudFront configuration can prevent Vercel from provisioning Let's Encrypt SSL certificates and cause domain verification failures.
+
+### Required path allowlist
+
+CloudFront must allow traffic to these specific paths without caching or blocking:
+
+- `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
+- `/.well-known/vercel/*` - Required for Vercel domain verification
+
+These paths should be configured to bypass CloudFront caching and pass through directly to your origin.
+
+### Header forwarding requirements
+
+Ensure that CloudFront forwards the `HOST` header and client IP information correctly. This is critical for Vercel's verification processes.
+
+When using CloudFront with Vercel deployments, CloudFront automatically adds the `CloudFront-Viewer-Address` header containing the original client's IP address.
+
+Make sure your CloudFront distribution is configured to forward this header to your origin by including it in your origin request policy or cache policy headers configuration.
+
 ## Create Cloudfront Distribution
 
 Navigate to [Cloudfront](https://aws.amazon.com/cloudfront) inside the AWS console and click on `Create distribution`
@@ -70,19 +95,25 @@ Behaviors in Cloudfront enables control over the subpath logic. At a high level,
 - **If a user lands on /docs**, go to `[SUBDOMAIN].mintlify.dev`
 - **If a user lands on any other page**, go the current landing page
 
-We're going to create three behaviors by clicking on the `Create behavior` button.
+Select the **Create behavior** button and create the following behaviors.
+
+### `/.well-known/*`
+
+If you are deploying to Vercel, create a behavior for Vercel verification paths with a **Path pattern** of `/.well-known/*` and **Origin and origin groups** pointing to your main origin (the staging URL).
+
+For **Cache policy**, select `CachingDisabled` to ensure these verification requests pass through without caching.
 
 ### `/docs/*`
 
-The first behavior should have a **Path pattern** of `/docs/*` with **Origin and origin groups** pointing to the `.mintlify.dev` URL (in our case `acme.mintlify.dev`)
+Create a behavior with a **Path pattern** of `/docs/*` with **Origin and origin groups** pointing to the `.mintlify.dev` URL (in our case `acme.mintlify.dev`)
 
 <Frame>![Cloudfront Behavior 1](/images/cloudfront/behavior-1.png)</Frame>
 
 For **Cache policy**, select `CachingOptimized` and create behavior.
 
 ### `/docs`
 
-The second behavior should be the same as the first one but with a **Path pattern** of `/docs` and **Origin and origin groups** pointing to the same `.mintlify.dev` URL.
+Create a behavior with a **Path pattern** of `/docs` and **Origin and origin groups** pointing to the same `.mintlify.dev` URL.
 
 <Frame>![Cloudfront Behavior 2](/images/cloudfront/behavior-2.png)</Frame>
 

advanced/subpath/vercel.mdx

@@ -3,10 +3,17 @@ title: "Vercel"
 description: "Host documentation at a /docs subpath using Vercel"
 ---
 
-## vercel.json Configuration
+## vercel.json file
 
-To host your documentation at a custom subpath using Vercel, you need to add the
-following configuration to your `vercel.json` file.
+The `vercel.json` file is Vercel's configuration file that allows you to customize how your project is built and deployed. It sits in your project's root directory and controls various aspects of your deployment, including routing, redirects, headers, and build settings.
+
+We use the `rewrites` configuration to proxy requests from your main domain to your documentation.
+
+Rewrites allow you to map incoming requests to different destinations without changing the URL in the browser. When someone visits `yoursite.com/docs`, Vercel will internally fetch content from `your-subdomain.mintlify.dev/docs` but the user will still see `yoursite.com/docs` in their browser. This is different from redirects, which would send users to a different URL entirely.
+
+## Configuration
+
+To host your documentation at a custom `/docs` subpath using Vercel, add the following configuration to your `vercel.json` file:
 
 ```json
 {
@@ -23,8 +30,38 @@ following configuration to your `vercel.json` file.
 }
 ```
 
-<Note>
-  For more information, you can also refer to Vercel's offical guide on
-  rewrites: [Project Configuration:
-  Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites)
-</Note>
+- **`source`**: The path pattern on your domain that triggers the rewrite.
+- **`destination`**: Where the request should be proxied to.
+- **`:match*`**: A wildcard that captures any path segments after `/docs/`.
+
+
+For more information, see [Configuring projects with vercel.json: Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites) in the Vercel documentation.
+
+## Using external proxies with Vercel
+
+If you're using an external proxy (like Cloudflare or AWS CloudFront) in front of your Vercel deployment, you must configure it properly to avoid conflicts with Vercel's domain verification and SSL certificate provisioning.
+
+Improper proxy configuration can prevent Vercel from provisioning Let's Encrypt SSL certificates and cause domain verification failures.
+
+See the [supported providers](https://vercel.com/guides/how-to-setup-verified-proxy#supported-providers-verified-proxy-lite) in the Vercel documentation.
+
+### Required path allowlist
+
+Your external proxy must allow traffic to these specific paths without blocking, redirecting, or heavily caching:
+
+- `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
+- `/.well-known/vercel/*` - Required for Vercel domain verification
+
+These paths should pass through directly to your Vercel deployment without modification.
+
+### Header forwarding requirements
+
+Ensure that your proxy correctly forwards the `HOST` header. Without proper header forwarding, verification requests will fail.
+
+### Testing your proxy setup
+
+To verify your proxy is correctly configured:
+
+1. Test that `https://[yourdomain].com/.well-known/vercel/` returns a response.
+2. Ensure SSL certificates are provisioning correctly in your Vercel dashboard.
+3. Check that domain verification completes successfully.