diff --git a/deploy/ci.mdx b/deploy/ci.mdx
index 0c53a8509..e7b575f68 100644
--- a/deploy/ci.mdx
+++ b/deploy/ci.mdx
@@ -1,5 +1,5 @@
 ---
-title: "CI checks"
+title: "TEST: CI checks"
 description: "Automate broken link checks, linting, and grammar validation in CI/CD."
 keywords: ["continuous integration", "CI/CD", "checks", "Vale", "linter"]
 ---
@@ -10,10 +10,22 @@ keywords: ["continuous integration", "CI/CD", "checks", "Vale", "linter"]
 
 Use CI checks to lint your docs for errors and provide warnings before you deploy. Mintlify CI checks run on pull requests against a configured deployment branch.
 
+CI checks are an essential part of maintaining high-quality documentation. They help catch issues early in the development process, before changes are merged into your main branch. By automating these checks, you can ensure consistency across your documentation, maintain style guidelines, and prevent broken links from reaching production. This automated validation process saves time for your team and improves the overall quality of your documentation.
+
+The CI check system integrates seamlessly with your existing GitHub workflow. When a pull request is opened or updated, Mintlify automatically runs the configured checks and reports the results directly in the GitHub interface. This means your team can review documentation changes alongside code changes, with immediate feedback on any issues that need to be addressed.
+
+CI checks can be customized to match your team's workflow. You can choose which checks to enable, set their severity levels, and configure them to either warn about issues or block merges when problems are detected. This flexibility allows you to gradually adopt stricter documentation standards or maintain different requirements for different types of changes.
+
 ## Installation
 
 To begin, follow the steps on the [GitHub](/deploy/github) page.
 
+Installing CI checks for your documentation is a straightforward process that builds on your existing GitHub integration. The installation process requires minimal configuration and can be completed in just a few minutes. Once installed, the CI checks will automatically run on every pull request, providing immediate feedback to your team.
+
+The installation process involves connecting your GitHub repository to Mintlify and configuring the appropriate permissions. Mintlify needs read access to your repository to analyze your documentation files and write access to post check results back to your pull requests. This integration is secure and follows GitHub's best practices for third-party applications.
+
+After installation, you'll be able to see CI check results directly in your GitHub pull request interface. Each check runs independently and reports its status, making it easy to identify and fix specific issues. The checks are designed to be fast and efficient, typically completing within seconds to minutes depending on the size of your documentation.
+
 <Tip>
   Only access to the repository where your documentation content exists is required, so it is highly recommended to only grant access to that repository. 
 </Tip>
@@ -22,10 +34,15 @@ To begin, follow the steps on the [GitHub](/deploy/github) page.
 
 Configure the CI checks enabled for a deployment by navigating to the [Add-ons](https://dashboard.mintlify.com/products/addons) page of your dashboard. Enable the checks that you want to run.
 
+The configuration interface provides a comprehensive view of all available CI checks and their current status. You can enable or disable checks individually, allowing you to tailor the CI system to your specific needs. This granular control means you can start with basic checks and gradually add more sophisticated validation as your documentation practices mature.
+
 When enabling checks, you can choose to run them at a `Warning` or `Blocking` level.
 
-- A `Warning` level check will never provide a failure status, even if there is an error or suggestions.
-- A `Blocking` level check will provide a failure status if there is an error or suggestions.
+- A `Warning` level check will never provide a failure status, even if there is an error or suggestions. This is ideal when you're first introducing a new check to your team, as it allows developers to see the feedback without blocking their workflow. Warning-level checks help build awareness of documentation standards without creating friction in the development process. You can use this mode to gather data about common issues before deciding to enforce stricter rules.
+
+- A `Blocking` level check will provide a failure status if there is an error or suggestions. This mode is appropriate for critical checks that must pass before code can be merged. Blocking checks ensure that your documentation maintains a minimum quality standard and that serious issues like broken links are caught before deployment. When a blocking check fails, the pull request cannot be merged until the issues are resolved, making it an effective enforcement mechanism for documentation quality.
+
+The choice between warning and blocking levels depends on your team's workflow and documentation maturity. Many teams start with warning-level checks to build familiarity and gradually transition to blocking checks as documentation practices improve. You can also use different levels for different checks - for example, making broken link checks blocking while keeping style checks at the warning level.
 
 ## Available CI checks
 
@@ -34,18 +51,34 @@ When enabling checks, you can choose to run them at a `Warning` or `Blocking` le
 Similar to how the [CLI link checker](/installation#find-broken-links) works on your local machine, the 
 broken link CI check automatically searches your documentation content for broken internal links.
 
-To see the results of this check, visit GitHub's check results page for a specific commit.
+Broken links are one of the most common and frustrating issues in documentation. They create a poor user experience, damage credibility, and can prevent users from finding the information they need. The broken link checker helps prevent these issues by automatically scanning all internal links in your documentation and verifying that they point to valid pages.
+
+The broken link checker is intelligent and understands the structure of your documentation. It validates links to other MDX pages, anchors within pages, and references to images and other assets. The checker also understands relative and absolute paths, ensuring that links work correctly regardless of how they're formatted. This comprehensive validation catches issues that might be missed during manual review.
+
+When the broken link checker finds an issue, it provides detailed information about the problem. You'll see which file contains the broken link, what the link text is, and where it's trying to point. This detailed feedback makes it easy to fix issues quickly. The checker also distinguishes between different types of link problems, such as links to pages that don't exist versus links with incorrect anchor references.
+
+To see the results of this check, visit GitHub's check results page for a specific commit. The results are presented in a clear, actionable format that makes it easy to understand what needs to be fixed. Each broken link is listed with its location and the reason it failed validation. You can click through to see the specific line in your documentation where the issue occurs, making fixes straightforward and efficient.
 
 ### Vale
 
 [Vale](https://vale.sh/) is an open source rule-based prose linter which supports a range of document types, including Markdown and MDX. Use Vale to check for consistency of style and tone in your documentation.
 
-Mintlify supports automatically running Vale in a CI check and displaying the results as a check status.
+Vale is a powerful tool for maintaining consistent writing style across your documentation. It can check for grammar issues, style violations, terminology consistency, and adherence to your organization's writing guidelines. By automating these checks, Vale helps ensure that your documentation maintains a professional, consistent voice regardless of how many contributors are involved.
+
+The Vale linter works by applying a set of rules to your documentation content. These rules can check for everything from simple issues like passive voice and complex words to more sophisticated concerns like brand terminology and tone consistency. Vale's rule-based approach means it can be customized to match your organization's specific style guide and documentation standards.
+
+One of Vale's key strengths is its flexibility. You can use pre-built style guides from major organizations like Microsoft, Google, and write.good, or create your own custom rules. This flexibility allows you to enforce your organization's unique terminology, preferred phrasings, and writing conventions. Vale can also be configured to check different types of content with different rules, allowing for more formal language in API documentation and more conversational language in tutorials.
+
+Mintlify supports automatically running Vale in a CI check and displaying the results as a check status. This integration means you get the full power of Vale's linting capabilities without needing to set up and maintain your own CI infrastructure. The results are displayed directly in your GitHub pull requests, making it easy for contributors to see and address style issues before merging their changes.
 
 #### Configuration
 If you have a `.vale.ini` file in the root content directory of your deployment, the Vale CI check uses that configuration file and any configuration files in your specified `stylesPath`.
 
-If you don't have a Vale config file, the default configuration automatically loads.
+The Vale configuration file uses INI format and provides extensive control over how Vale analyzes your documentation. You can specify which style guides to use, set the minimum alert level for issues, define which parts of your documents to ignore, and configure custom vocabularies. This configuration flexibility allows you to tailor Vale's behavior to match your documentation needs precisely.
+
+When you provide your own Vale configuration, Mintlify respects all your settings and uses them exactly as specified. This means you can develop and test your Vale configuration locally, then deploy it to CI with confidence that it will behave the same way. The configuration file also supports comments, making it easy to document why specific rules are enabled or disabled.
+
+If you don't have a Vale config file, the default configuration automatically loads. The default configuration is designed to work well for most documentation projects and includes sensible defaults for MDX files. It includes basic style checking, ignores code blocks and other technical content that shouldn't be linted, and uses a vocabulary that includes common technical terms. This default configuration provides immediate value without requiring any setup, while still allowing you to customize it later as your needs evolve.
 
 ````mdx Default vale.ini configuration expandable
 # Top level styles
@@ -396,7 +429,13 @@ Use relative paths and include the `stylesPath` in your repository.
 #### Packages
 Vale supports a range of [packages](https://vale.sh/docs/keys/packages), which can be used to check for spelling and style errors. Any packages you include in your repository under the correct `stylesPath` are automatically installed and used in your Vale configuration.
 
-For packages not included in your repository, you may specify any packages from the [Vale package registry](https://vale.sh/explorer), and they're automatically downloaded and used in your Vale configuration.
+Vale packages are collections of rules and styles that can be easily shared and reused across projects. These packages can include complete style guides from major organizations, specialized rule sets for specific types of documentation, or custom packages created by your team. Using packages allows you to leverage the work of the documentation community and adopt industry-standard writing guidelines without creating rules from scratch.
+
+The package system makes it easy to maintain consistent documentation standards across multiple projects. You can create a custom package with your organization's style rules and use it across all your documentation repositories. This centralized approach to style management ensures consistency and makes it easy to update rules across all your projects simultaneously.
+
+Any packages you include in your repository under the correct `stylesPath` are automatically installed and used in your Vale configuration. This approach gives you complete control over which packages are used and allows you to version control your style rules alongside your documentation. Including packages in your repository also ensures that your Vale configuration is self-contained and doesn't depend on external resources.
+
+For packages not included in your repository, you may specify any packages from the [Vale package registry](https://vale.sh/explorer), and they're automatically downloaded and used in your Vale configuration. The Vale package registry hosts a wide variety of style guides and rule sets, including packages for major style guides like Microsoft Writing Style Guide, Google Developer Documentation Style Guide, and many others. These packages are maintained by the community and regularly updated to reflect current best practices in technical writing.
 
 <Note>
 For security reasons, automatically downloading packages that aren't from the [Vale package registry](https://vale.sh/explorer) is **not** supported.
@@ -408,6 +447,12 @@ For security reasons, automatically downloading packages that aren't from the [V
 MDX native support requires Vale 3.10.0 or later. Check your Vale version with `vale --version`.
 </Note>
 
+Vale's native MDX support represents a significant improvement in how the linter handles modern documentation formats. Previously, Vale required workarounds to process MDX files, treating them as Markdown and potentially missing or incorrectly flagging MDX-specific syntax. With native MDX support, Vale understands the structure of MDX files, including JSX components, imports, and other MDX-specific features.
+
+This native support means Vale can accurately distinguish between prose that should be linted and code or component syntax that should be ignored. The linter understands MDX component boundaries, JSX expressions, and other MDX constructs, preventing false positives and ensuring that only your actual documentation content is checked. This improved accuracy makes Vale's feedback more reliable and reduces the time spent investigating false alarms.
+
+The native MDX support also enables better integration with MDX-specific features. Vale can now properly handle MDX comments, frontmatter, and other MDX conventions without requiring special configuration. This seamless integration makes it easier to use Vale with modern documentation toolchains and reduces the configuration overhead required to get accurate results.
+
 To use Vale's in-document comments in MDX files, use MDX-style comments `{/* ... */}`:
 
 ```mdx
@@ -418,4 +463,6 @@ This text is ignored by Vale
 {/* vale on */}
 ```
 
-Vale automatically recognizes and respects these comments in MDX files without additional configuration. Use comments to skip lines or sections that should be ignored by the linter.
+Vale automatically recognizes and respects these comments in MDX files without additional configuration. Use comments to skip lines or sections that should be ignored by the linter. This is particularly useful for code examples, technical specifications, or other content that doesn't follow standard prose rules. You can also use these comments to temporarily disable specific rules or to exclude content that you know violates style guidelines but needs to remain as-is for technical accuracy.
+
+The comment syntax is intuitive and follows MDX conventions, making it easy for documentation contributors to use. Comments can be placed inline or around blocks of content, giving you fine-grained control over what Vale checks. This flexibility allows you to maintain strict style standards for most of your documentation while making exceptions where necessary.