Merge branch 'main' into openapi-nav-updates

Author: mycho2003

.claude/CLAUDE.md

@@ -43,6 +43,21 @@
 - Make language more precise and contextual
 - Use [Lucide](https://lucide.dev) icon library
 
+### Language and tone standards
+- Avoid promotional language. You are a technical writing assistant, not a marketer. Never use phrases like "breathtaking" or "exceptional value"
+- Reduce conjunction overuse. Limit use of "moreover," "furthermore," "additionally," "on the other hand." Favor direct, clear statements
+- Avoid editorializing. Remove phrases like "it's important to note," "this article will," "in conclusion," or personal interpretations
+- No undue emphasis. Avoid overstating importance or significance of routine technical concepts
+
+### Technical accuracy standards
+- Verify all links. Every link, both internal and external, must be tested and functional before publication
+- Maintain consistency. Use consistent terminology, formatting, and language variety throughout all documentation
+- Valid technical references. Ensure all code examples, API references, and technical specifications are current and accurate
+
+### Formatting discipline
+- Purposeful formatting. Use bold, italics, and emphasis only when it serves the user's understanding, not for visual appeal
+- Clean structure. Avoid excessive formatting. Never use emoji or decorative elements that don't add functional value
+
 ### Component introductions
 - Start with action-oriented language: "Use [component] to..." rather than "The [component] component..."
 - Be specific about what components can contain or do

README.md

@@ -1,13 +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
+Install the [Mint CLI](https://www.npmjs.com/package/mint) to preview the documentation changes locally. To install, use the following command
 
 ```
-npm i -g mintlify
+npm i -g mint
 ```
 
-Run the following command at the root of your documentation (where mint.json is)
+Run the following command at the root of your documentation (where docs.json is)
 
 ```
-mintlify dev
+mint dev
 ```

ai/contextual-menu.mdx

@@ -5,6 +5,7 @@ icon: "square-menu"
 ---
 
 import { PreviewButton } from "/snippets/previewbutton.jsx"
+import IconsRequired from "/snippets/icons-required.mdx";
 
 The contextual menu provides quick access to AI-optimized content and direct integrations with popular AI tools. When users select the contextual menu on any page, they can copy content as context for AI tools or open conversations in ChatGPT, Claude, Perplexity, or a custom tool of your choice with your documentation already loaded as context.
 
@@ -63,9 +64,7 @@ Create custom options in the contextual menu by adding an object to the `options
   The description of the option. Displayed beneath the title when the contextual menu is expanded.
 </ResponseField>
 
-<ResponseField name="icon" type="string" required>
-  The icon of the option. Accepts any icon from the [Icons](/components/icons) collection.
-</ResponseField>
+<IconsRequired />
 
 <ResponseField name="href" type="string | object" required>
   The href of the option. Use a string for simple links or an object for dynamic links with query parameters.

ai/llmstxt.mdx

@@ -6,22 +6,20 @@ icon: "file-code"
 
 import { PreviewButton } from "/snippets/previewbutton.jsx"
 
-The [llms.txt file](https://llmstxt.org) is an industry standard that helps LLMs index content more efficiently, similar to how a sitemap helps search engines.
+The [llms.txt file](https://llmstxt.org) is an industry standard that helps LLMs index content more efficiently, similar to how a sitemap helps search engines. AI tools can use this file to understand your documentation structure and find content relevant to user queries.
 
-Mintlify automatically hosts an `llms.txt` file at the root of your project that lists all available pages in your documentation. AI tools can use this file to understand your documentation structure and find relevant content to user prompts.
+Mintlify automatically hosts an `llms.txt` file at the root of your project that lists all available pages in your documentation. This file is always up to date and requires zero maintenance. You can optionally add a custom `llms.txt` file to the root of your project.
 
 View your `llms.txt` by appending `/llms.txt` to your documentation site's URL.
 
-<PreviewButton href="https://mintlify.com/docs/llms.txt">Open the llms.txt for this site</PreviewButton>
-
-Your site's `llms.txt` is always up to date and requires zero maintenance.
+<PreviewButton href="https://mintlify.com/docs/llms.txt">Open the llms.txt for this site.</PreviewButton>
 
 ## llms.txt structure
 
 An `llms.txt` file is a plain Markdown file that contains:
 
-- **Site title** as an H1 heading. This is the only required section of an `llms.txt`.
-- **Structured content sections** with descriptive links to key pages.
+- **Site title** as an H1 heading.
+- **Structured content sections** with links and a description of each page in your documentation.
 
 ```mdx Example llms.txt
 # Example product docs
@@ -34,14 +32,18 @@ An `llms.txt` file is a plain Markdown file that contains:
 - [API](https://example.com/docs/api): Endpoint list and usage
 ```
 
-This structured approach allows LLMs to quickly process your documentation hierarchy and locate relevant content for user queries, improving the accuracy and speed of AI-assisted documentation searches.
+This structured approach allows LLMs to efficiently process your documentation at a high level and locate relevant content for user queries, improving the accuracy and speed of AI-assisted documentation searches.
 
 ## llms-full.txt
 
-The `llms-full.txt` file combines your entire documentation site into a single file as context for AI tools and is indexed by LLM traffic. Users can paste a single URL as context for AI tools for more relevant and accurate responses.
+The `llms-full.txt` file combines your entire documentation site into a single file as context for AI tools and is indexed by LLM traffic.
 
 Mintlify automatically hosts an `llms-full.txt` file at the root of your project. View your `llms-full.txt` by appending `/llms-full.txt` to your documentation site's URL.
 
-<PreviewButton href="https://mintlify.com/docs/llms-full.txt">Open the llms-full.txt for this site</PreviewButton>
+<PreviewButton href="https://mintlify.com/docs/llms-full.txt">Open the llms-full.txt for this site.</PreviewButton>
+
+## Custom files
+
+To add a custom `llms.txt` or `llms-full.txt` file, create an `llms.txt` or `llms-full.txt` file at the root of your project. Adding a custom file will override the automatically generated file of the same name. If you delete a custom file, the default file will be used again.
 
-Your site's `llms-full.txt` is always up to date and requires zero maintenance.
+Your custom `llms.txt` or `llms-full.txt` file must have a site title as an H1 heading. Other content is optional. See [Format](https://llmstxt.org/#format) in the `llms.txt` specification for more information on optional sections and best practices.

ai/model-context-protocol.mdx

@@ -28,7 +28,7 @@ For example, Mintlify's MCP server is available at `https://mintlify.com/docs/mc
 
 All MCP servers include the `search` tool by default, allowing users to query information from your docs in other tools.
 
-If you have an OpenAPI specification, you can expose specific endpoints as MCP tools by using the `x-mcp` extension at either the file or endpoint level.
+If you have an OpenAPI specification, you can expose specific endpoints as MCP tools by using the `mcp` object within the `x-mint` extension at either the file or endpoint level.
 
 For example, the Mintlify MCP server includes tools to get status updates, trigger updates, and create assistant chats.
 
@@ -39,8 +39,10 @@ Enable MCP for all endpoints in an OpenAPI specification file:
 ```json
 {
   "openapi": "3.1.0",
-  "x-mcp": {
-    "enabled": true
+  "x-mint": {
+    "mcp": {
+      "enabled": true
+    }
   },
   // Other OpenAPI content
 }
@@ -54,8 +56,10 @@ Enable MCP for specific endpoints only:
 {
   "paths": {
     "/api/v1/users": {
-      "x-mcp": {
-        "enabled": true
+      "x-mint": {
+        "mcp": {
+          "enabled": true
+        }
       },
       // Endpoint configuration
     }

ai/slack-app.mdx

@@ -8,7 +8,9 @@ icon: "slack"
   The Slack app is available for [Pro and Enterprise plans](https://mintlify.com/pricing?ref=slack-app).
 </Info>
 
-The Slack app adds a bot to your Slack workspace that searches your documentation to answer users' questions. The bot responds to direct messages, @mentions, and to any questions in a channel specifically named `#ask-ai`.
+The Slack app adds a bot named `@mintlify` to your Slack workspace that can search your documentation and answer users' questions. The bot responds to direct messages, @mentions, and to any questions in a channel specifically named `#ask-ai`.
+
+The Slack app can incur costs: either using your AI chat credits or incurring overages.
 
 ## Setting up the Slack app
 

api-playground/openapi-setup.mdx

@@ -101,7 +101,7 @@ The `x-mint` extension is a custom OpenAPI extension that provides additional co
 
 ### Metadata
 
-Override the default metadata for generated API pages by adding `x-mint: metadata` to any operation. You can use any metadata field that would be valid in `MDX` frontmatter except for `openapi`, `version`, or `deprecated`:
+Override the default metadata for generated API pages by adding `x-mint: metadata` to any operation. You can use any metadata field that would be valid in `MDX` frontmatter except for `openapi`:
 
 ```json {7-13}
 {
@@ -154,7 +154,7 @@ Add content before the auto-generated API documentation using `x-mint: content`:
 
 The `content` extension supports all Mintlify MDX components and formatting.
 
-### href
+### Href
 
 Change the URL of the endpoint page in your docs using `x-mint: href`:
 
@@ -183,6 +183,32 @@ Change the URL of the endpoint page in your docs using `x-mint: href`:
 
 When `x-mint: href` is present, the navigation entry will link directly to the specified URL instead of generating an API page.
 
+### MCP
+
+Expose endpoints as MCP tools by using `x-mint: mcp`:
+
+```json {6-10}
+{
+  "paths": {
+    "/users": {
+      "post": {
+        "summary": "Create user",
+        "x-mint": {
+          "mcp": {
+            "enabled": true
+          }
+        },
+        "parameters": [
+          {
+            // Parameter configuration
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
 ## Auto-populate API pages
 
 Add an `openapi` field to any navigation element in your `docs.json` to automatically generate pages for OpenAPI endpoints. You can control where these pages appear in your navigation structure, as dedicated API sections or with other pages.
@@ -337,7 +363,7 @@ This approach is useful when you need individual endpoints from different specs
 
 ## Create `MDX` files for API pages
 
-For control over individual endpoint pages, you can also create `MDX` pages for each operation. This lets you customize page metadata, add content, omit certain operations, or reorder pages in your navigation at the page level.
+For control over individual endpoint pages, create `MDX` pages for each operation. This lets you customize page metadata, add content, omit certain operations, or reorder pages in your navigation at the page level.
 
 See an [example MDX OpenAPI page from MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) and how it appears in their [live documentation](https://docs.mindsdb.com/rest/databases/create-databases).
 

api-reference/assistant/create-assistant-message.mdx

@@ -0,0 +1,17 @@
+---
+openapi: POST /assistant/{domain}/message
+---
+
+## Rate limits
+
+The assistant API has the following limits:
+
+- 10,000 uses per key per month
+- 10,000 requests per Mintlify organization per hour
+- 10,000 requests per IP per day
+
+## Suggested usage
+
+For best results, use the [useChat hook from ai-sdk](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) to send requests and handle responses.
+
+You can set `fp`, `threadId`, and `filter` in the `body` field of the options parameter passed to the hook.