Document the assistant

changelog.mdx

@@ -6,11 +6,12 @@
 
 <Update label="May 2025">
   ## API playground stability updates
+
   - Search to find an endpoint
   - Indicate a deprecated endpoint with a tag
   - Hide auto-generated API pages from navigation
   - Upload multipart or form data files
-  
+
   Learn more at [API playground docs.](/api-playground/)
 
   ## `mint update`
@@ -21,9 +22,8 @@
   ## Web Editor 3.0
 
   <Frame>
-  ![Webeditor3 Jpe](/images/webeditor3.jpeg)
+    ![Webeditor3 Jpe](/images/webeditor3.jpeg)
   </Frame>
-
   Overhauled usability in the WYSIWYG editor.
 
   **Major improvements**
@@ -83,7 +83,7 @@
   - Improved styling nits for dashboard border for mobile-tablet-desktop responsiveness
   - Show code examples even when in simple mode for API playground
   - Support "command \+ k" shortcut for search in web editor
   - Codeblocks within callouts expand to fill the width of the callout area
 </Update>
 
 <Update label="February 2025">
@@ -114,9 +114,9 @@
 
   Automatically lint your docs to find broken links, discover spelling and grammar issues, or enforce writing styles with your own Vale config. Learn more in our [docs](settings/ci).
 
   ## .md support for LLMs
 
   All documentation pages are now automatically available as plain Markdown files—just append `.md` to the URL. This makes it easier for LLMs to ingest individual pages from your documentation.
 
   ## More Themes
 
@@ -173,12 +173,12 @@
 </Update>
 
 <Update label="November 2024">
-  ## AI Assistant
+  ## AI Writer
 
   <Frame>
     ![AI Assistant](/images/changelog/ai-assistant.jpg)
   </Frame>
-  You can now ask AI to make changes to your docs, with the context of all existing documentation. Type in a prompt and the assistant will propose changes by generating a pull request.
+  You can now ask AI to make changes to your docs, with the context of all existing documentation. Type in a prompt and the writer will propose changes by generating a pull request.
 
   ## GitLab Integration Upgrade
 
@@ -198,7 +198,7 @@
   <Frame>
     ![llms.txt support](/images/changelog/llms.jpg)
   </Frame>
   All docs instances are now automatically hosted at /llms.txt and /llms-full.txt so that LLMs can easily ingest your documentation. For more information, read the [docs on the new llms.txt standard.](https://llmstxt.org)
 
   ## Localization
 
@@ -270,7 +270,7 @@
   ## Dashboard Improvements
 
   - Added ability to change custom domain to be /docs directly through dashboard settings.
   - Consolidated the login and signup pages to decrease friction and confusion.
   - Implemented the discovery login flow so that users that are members of multiple organizations can now switch between them.
   - Added login with Google OAuth
   - Added ability to add new deployment through dashboard settings.
@@ -284,7 +284,7 @@
   - Don't allow search engines to crawl user-auth protected pages.
   - Revalidate the cache when an org is deleted.
   - We now use the Scalar OpenAPI parser to parse OpenAPI definitions which improves the performance, fixes parsing issues, and surfaces better error messages.
   - Top-level descriptions are now supported in API reference pages autogenerated from OpenAPI definitions.
   - Add in-line-style support for icons
   - Fixed the pop-in of custom CSS in docs.
   - Properly show in-line code styling in conjunction with links.
@@ -317,7 +317,7 @@
   <Frame>
     ![SEO Improvements](/images/changelog/seo-improvements.jpeg)
   </Frame>
   We've fixed  both the mobile and desktop layout of our docs so that they are more SEO-friendly - including adding proper aria tags to navbar and toggle elements.
 
   ## Dashboard Improvements
 
@@ -351,7 +351,7 @@
 
   ## File Uploads in API Playground
 
   By default, API playground requests are proxied by Mintlify. Now you can use
   `disableProxy` to disable this behavior and support request types like file
   uploads.
 
@@ -384,7 +384,7 @@
   </Frame>
   For `Pro` users, we introduced Mintlify Widget, an extension of your docs to
   answer your users' questions when and where they asked. You can add this
   AI-powered chatbot to any web page: your landing page, inside your product, or
   on your existing documentation pages.
 
   - [Read the blog announcement](https://mintlify.com/blog/widget)
@@ -419,7 +419,7 @@
 <Update label="May 2024">
   ## Okta SSO
 
   We now support sign-on via Okta SAML and OIDC.
 
   ## Mintlify REST API
 
@@ -442,7 +442,7 @@
 <Update label="March 2024">
   ## Mintlify MDX for VSCode
 
   Call snippets of our pre-built components and callouts without leaving VSCode. [Install the extension here](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets).
 </Update>
 
 <Update label="February 2024">
@@ -451,7 +451,7 @@
   - Dashboard upgrades: view update logs to see what's changed and status of an update, toggle between Mintlify projects to manage deployments
   - Versioning with tabs fully supported
   - Wildcard redirects now supported
   - CLI Error Detection: we now show the position of invalid frontmatter when there are parsing issues during local development
 </Update>
 
 <Update label="January 2024">
@@ -461,4 +461,4 @@
   - Snippets V2: We now support fully reusable components and variables for snippets.
   - Open-source MDX Engine: We've exposed two APIs—getCompiledMdx and MDXComponent—so you can access Mintlify markdown and code syntax highlighting. [Contributions to the project](https://github.com/mintlify/mdx) are welcome.
   - AI Chat Insights: Segment chat history by date and increase AI Chat quota from the dashboard, and see how often a specific query appears.
-</Update>
+</Update>

docs.json

@@ -112,6 +112,7 @@
             "group": "Guides",
             "pages": [
               "guides/migration",
+              "guides/assistant",
               "mcp",
               "guides/cursor",
               "translations",

guides/assistant.mdx

@@ -0,0 +1,110 @@
+---
+title: "AI Assistant"
+description: "Help users succeed with your product and find answers faster"
+icon: "bot"
+---
+
+<Info>
+  The AI assistant is available on [Pro, Growth, and Enterprise plans](https://mintlify.com/pricing?ref=assistant). Please{" "}
+  <a href="mailto:[email protected]">contact sales</a> for more information.
+</Info>
+
+## About the assistant
+
+The AI assistant answers questions about your documentation through natural language queries. When users ask a question, the assistant searches your content, cites relevant sources, and provides contextual answers sourced from your documentation.
+
+The assistant uses agentic RAG (retrieval-augmented generation) with tool calling and runs on Claude Sonnet 4 by default.
+
+You can monitor user interactions and export query data from your dashboard to gain insights into user needs and identify content gaps.
+
+The assistant is automatically enabled for accounts on Pro, Growth, and Enterprise plans. See [Pricing](https://mintlify.com/pricing) for details.
+
+## Using the assistant
+
+Users can access the assistant in two ways:
+
+- **Keyboard shortcut**: <kbd>Command</kbd> + <kbd>I</kbd> (<kbd>Ctrl</kbd> + <kbd>I</kbd> on Windows)
+- **Assistant button** next to the search bar
+  <img
+    src="/images/assistant/assistant-button-light.png"
+    className="block dark:hidden rounded-2xl border border-gray-100 shadow-lg"
+    style={{
+      width: '268px',
+      height: 'auto',
+    }}
+    alt="Search bar and assistant button in light mode."
+  />
+  <img
+    src="/images/assistant/assistant-button-dark.png"
+    className="hidden dark:block rounded-2xl border border-white/10 shadow-lg"
+    style={{
+      width: '268px',
+      height: 'auto',
+    }}
+    alt="Search bar and assistant button in dark mode."
+  />
+
+Both methods open a chat panel on the right side of your docs. Users can ask any question and the assistant will search your documentation for an answer. If no relevant information is found, the assistant will respond that it cannot answer the question.
+
+## Making content AI ingestible
+
+Structure your documentation to help the assistant provide accurate, relevant answers. Clear organization and comprehensive context benefit both human readers and AI understanding.
+
+### Structure and organization
+
+- Write descriptive headings for sections.
+- Create a logical information hierarchy with proper nesting (H1 \> H2 \> H3).
+- Break up long blocks of text into shorter paragraphs.
+- Use consistent formatting across your docs.
+- Use semantic markup.
+- Include comprehensive metadata in page frontmatter.
+
+### Context
+
+- Define specific terms and acronyms when first introduced.
+- Provide sufficient conceptual content about features and procedures.
+- Include examples and use cases.
+- Cross-reference related topics.
+- Add [hidden pages](/guides/hidden-pages) with additional context that users don't need, but the assistant can reference.
+
+## Exporting and analyzing queries
+
+Review and export queries from your dashboard to understand how people interact with your documentation and identify improvement opportunities. Some ways that analyzing queries can help you improve your documentation:
+
+- Identify content gaps where frequent queries receive insufficient answers.
+- Discover user behavior patterns and common information needs from themes and patterns in queries.
+- Prioritize high-traffic pages for accuracy and quality improvements.
+
+You can explore queries from your [dashboard](https://dashboard.mintlify.com/products/assistant), but to get more powerful insights we recommend exporting a `CSV` file of your queries, responses, and sources to analyze with your preferred AI tool.
+
+1. Navigate to the [assistant page](https://dashboard.mintlify.com/products/assistant) in your dashboard.
+2. Select **Export to CSV**.
+3. Analyze the exported data using your preferred tool.
+
+Sample analysis prompts:
+
+- Summarize the most common themes of the queries.
+- List any queries that had no sources cited.
+- Find patterns in unsuccessful interactions.
+
+## Changing the model
+
+The assistant uses Claude Sonnet 4 by default. We have found that this model performs the best when searching and answering questions.
+
+If you want to select another model:
+
+1. Navigate to the [assistant page](https://dashboard.mintlify.com/products/assistant) in your dashboard.
+2. Select **Manage**.
+3. Choose your preferred model.
+4. Select **Save**.
+
+Available models:
+
+- Claude 4 Sonnet (default)
+- Claude 3.7 Sonnet
+- GPT 4.1
+- GPT-4o
+- o3-mini
+- Gemini 2.5 Pro (Preview)
+- Llama 4 Maverick
+- Grok 3

guides/hidden-pages.mdx

@@ -16,11 +16,13 @@
 
 A page is hidden if it is not included in your `docs.json` navigation. To hide a page, remove it from your navigation structure.
 
+Hidden pages use the same URL structure as regular pages based on their file path.  For example,  `guides/hidden-page.mdx` would be accessible at `docs.yoursite.com/guides/hidden-page`.
+
 <Note>
-Some navigation elements like sidebars, dropdowns, and tabs may appear empty or shift layout on hidden pages.
+  Some navigation elements like sidebars, dropdowns, and tabs may appear empty or shift layout on hidden pages.
 </Note>
 
-## Search, SEO, and AI context
+## Search, SEO, and AI indexing
 
 By default, hidden pages are excluded from indexing for search engines, internal search within your docs, and as context for the AI assistant. To include hidden pages in search results and as context for the assistant, add the `seo` property to your `docs.json`:
 
@@ -30,4 +32,4 @@
 }
 ```
 
-To exclude a specific page, add `noindex: "true"` to its frontmatter.
+To exclude a specific page, add `noindex: "true"` to its frontmatter.