thanh-kit 2.5.0 → 2.5.2

package/templates/skills/mintlify/references/ai-features-and-integrations-reference.md

@@ -0,0 +1,756 @@
+# AI Features and Integrations Reference
+
+Complete guide for Mintlify's AI-powered features including AI assistant, llms.txt, MCP, and automation.
+
+## AI Assistant
+
+Built-in AI assistant for documentation search and Q&A.
+
+### Configuration
+
+Enable AI assistant in `docs.json`:
+
+```json
+{
+  "search": {
+    "prompt": "Ask me anything about our documentation..."
+  }
+}
+```
+
+### Features
+
+**Conversational Search:**
+- Natural language queries
+- Context-aware responses
+- Source citations from docs
+- Follow-up questions
+
+**Capabilities:**
+- Search across all documentation
+- Answer technical questions
+- Provide code examples
+- Navigate to relevant pages
+- Suggest related content
+
+### Customization
+
+**Custom Prompt:**
+```json
+{
+  "search": {
+    "prompt": "How can I help you with the API?",
+    "placeholder": "Ask about authentication, endpoints, or SDKs..."
+  }
+}
+```
+
+**Search Scope:**
+```json
+{
+  "search": {
+    "scope": ["api", "guides"],
+    "exclude": ["internal", "deprecated"]
+  }
+}
+```
+
+## llms.txt
+
+Optimize documentation for LLM consumption and indexing.
+
+### What is llms.txt?
+
+Special file format that makes documentation machine-readable for AI models:
+- Structured content for LLMs
+- Optimized token usage
+- Hierarchical organization
+- Metadata for context
+
+### Auto-Generation
+
+Mintlify automatically generates `llms.txt` from your documentation.
+
+**Access:** `https://docs.example.com/llms.txt`
+
+### Manual Configuration
+
+Customize llms.txt generation:
+
+```json
+{
+  "ai": {
+    "llmsTxt": {
+      "enabled": true,
+      "include": ["introduction", "api/*", "guides/*"],
+      "exclude": ["internal/*", "deprecated/*"],
+      "format": "structured"
+    }
+  }
+}
+```
+
+### llms.txt Format
+
+Generated file structure:
+
+```
+# Product Name Documentation
+
+## Overview
+Brief description of product and documentation
+
+## Getting Started
+> /introduction
+Quick introduction to get started
+
+> /quickstart
+Step-by-step quickstart guide
+
+## API Reference
+> /api/authentication
+Authentication methods and API keys
+
+> /api/users
+User management endpoints
+
+> /api/posts
+Post creation and management
+
+## Guides
+> /guides/deployment
+Deployment guide for production
+
+> /guides/security
+Security best practices
+```
+
+### Use Cases
+
+**Feed to LLMs:**
+- Provide entire docs context to ChatGPT, Claude, etc.
+- Enable AI to answer questions about your product
+- Generate code examples based on documentation
+
+**RAG Systems:**
+- Index for retrieval-augmented generation
+- Build custom AI assistants
+- Create documentation chatbots
+
+## skill.md
+
+Make documentation agent-ready with skill definitions.
+
+### What is skill.md?
+
+Defines your API/product as a "skill" that AI agents can execute:
+- Function signatures
+- Parameter schemas
+- Authentication requirements
+- Example usage
+
+### Generation
+
+Mintlify auto-generates `skill.md` from OpenAPI specs.
+
+**Access:** `https://docs.example.com/skill.md`
+
+### Format
+
+```markdown
+# API Skills
+
+## Create User
+
+Create a new user account
+
+**Function:** `createUser`
+
+**Parameters:**
+- `email` (string, required) - User email address
+- `name` (string, required) - Full name
+- `password` (string, required) - Password (min 8 chars)
+
+**Returns:** User object with ID and timestamps
+
+**Example:**
+```json
+{
+  "email": "user@example.com",
+  "name": "John Doe",
+  "password": "SecurePass123"
+}
+```
+
+**Response:**
+```json
+{
+  "id": "usr_abc123",
+  "email": "user@example.com",
+  "name": "John Doe",
+  "created_at": "2024-01-15T10:30:00Z"
+}
+```
+
+## List Users
+
+Retrieve paginated list of users
+
+**Function:** `listUsers`
+
+**Parameters:**
+- `page` (number, optional) - Page number (default: 1)
+- `limit` (number, optional) - Items per page (default: 10)
+- `sort` (string, optional) - Sort field (default: created_at)
+
+**Returns:** Array of user objects with pagination metadata
+```
+
+### Configuration
+
+Customize skill.md generation:
+
+```json
+{
+  "ai": {
+    "skillMd": {
+      "enabled": true,
+      "includeExamples": true,
+      "includeErrors": true,
+      "format": "agent-ready"
+    }
+  }
+}
+```
+
+### Use Cases
+
+**AI Agents:**
+- Claude Code, Cursor, Windsurf
+- Auto-discover API capabilities
+- Generate correct API calls
+- Handle errors appropriately
+
+**Documentation Tools:**
+- Auto-complete in IDEs
+- API client generation
+- Testing frameworks
+
+## MCP (Model Context Protocol)
+
+Expose documentation through Model Context Protocol for AI tools.
+
+### What is MCP?
+
+Protocol that allows AI tools to access and interact with documentation:
+- Standardized interface
+- Real-time doc access
+- Function calling support
+- Resource discovery
+
+### Configuration
+
+Enable MCP in `docs.json`:
+
+```json
+{
+  "contextual": {
+    "options": ["mcp"]
+  },
+  "ai": {
+    "mcp": {
+      "enabled": true,
+      "endpoint": "/mcp",
+      "capabilities": ["read", "search", "navigate"]
+    }
+  }
+}
+```
+
+### MCP Capabilities
+
+**Resources:**
+- List all documentation pages
+- Read page content
+- Access metadata
+
+**Search:**
+- Full-text search
+- Semantic search
+- Filter by section
+
+**Navigation:**
+- Get navigation structure
+- Find related pages
+- Access breadcrumbs
+
+### MCP Client Integration
+
+**Claude Desktop:**
+```json
+{
+  "mcpServers": {
+    "docs": {
+      "url": "https://docs.example.com/mcp",
+      "apiKey": "optional-key"
+    }
+  }
+}
+```
+
+**VSCode with Continue:**
+```json
+{
+  "contextProviders": [
+    {
+      "name": "docs",
+      "type": "mcp",
+      "url": "https://docs.example.com/mcp"
+    }
+  ]
+}
+```
+
+## Contextual Menu Options
+
+Quick access to AI tools from documentation pages.
+
+### Configuration
+
+```json
+{
+  "contextual": {
+    "options": [
+      "copy",
+      "view",
+      "chatgpt",
+      "claude",
+      "perplexity",
+      "mcp",
+      "cursor",
+      "vscode"
+    ]
+  }
+}
+```
+
+### Available Options
+
+**copy** - Copy page content to clipboard
+```
+Copies: Markdown content with frontmatter
+Use: Paste into any editor or tool
+```
+
+**view** - View raw markdown source
+```
+Opens: Raw .mdx file content
+Use: See exact markdown structure
+```
+
+**chatgpt** - Open in ChatGPT
+```
+Action: Opens ChatGPT with page context
+Prompt: "Explain this documentation: [content]"
+```
+
+**claude** - Open in Claude
+```
+Action: Opens Claude.ai with page context
+Prompt: "Help me understand: [content]"
+```
+
+**perplexity** - Open in Perplexity
+```
+Action: Search Perplexity with page topic
+Query: Key concepts from page
+```
+
+**mcp** - Copy MCP resource URI
+```
+Copies: MCP resource identifier
+Use: Reference in MCP-enabled tools
+```
+
+**cursor** - Open in Cursor editor
+```
+Action: cursor://open?url=[page-url]
+Use: Edit in Cursor IDE
+```
+
+**vscode** - Open in VS Code
+```
+Action: vscode://file/[local-path]
+Use: Edit in VS Code
+```
+
+### Custom Options
+
+Add custom contextual menu items:
+
+```json
+{
+  "contextual": {
+    "custom": [
+      {
+        "name": "Open in Notion",
+        "icon": "notion",
+        "url": "https://notion.so/import?url={pageUrl}"
+      },
+      {
+        "name": "Translate",
+        "icon": "language",
+        "url": "https://translate.google.com/?text={content}"
+      }
+    ]
+  }
+}
+```
+
+## Discord Bot
+
+AI-powered Discord bot for documentation queries.
+
+### Setup
+
+1. **Enable Bot:**
+   - Go to Mintlify dashboard
+   - Navigate to Integrations > Discord
+   - Click "Enable Discord Bot"
+
+2. **Add to Server:**
+   - Copy bot invite URL
+   - Open in browser
+   - Select Discord server
+   - Authorize permissions
+
+3. **Configure:**
+   ```json
+   {
+     "integrations": {
+       "discord": {
+         "enabled": true,
+         "channelIds": ["123456789", "987654321"],
+         "prefix": "!docs",
+         "permissions": ["read", "search"]
+       }
+     }
+   }
+   ```
+
+### Usage
+
+**Search Documentation:**
+```
+!docs search authentication
+!docs how to create API key
+!docs what is rate limiting
+```
+
+**Get Page:**
+```
+!docs page introduction
+!docs link api/users
+```
+
+**Ask Questions:**
+```
+!docs What authentication methods are supported?
+!docs How do I paginate results?
+!docs Show me example of creating a user
+```
+
+### Bot Features
+
+- Natural language search
+- Code example formatting
+- Inline documentation links
+- Contextual answers
+- Source citations
+- Slash commands support
+
+## Slack Bot
+
+AI assistant for Slack workspaces.
+
+### Setup
+
+1. **Enable Integration:**
+   - Go to Mintlify dashboard
+   - Navigate to Integrations > Slack
+   - Click "Add to Slack"
+
+2. **Authorize:**
+   - Select workspace
+   - Approve permissions
+   - Configure channels
+
+3. **Configuration:**
+   ```json
+   {
+     "integrations": {
+       "slack": {
+         "enabled": true,
+         "channels": ["#engineering", "#support"],
+         "notifyUpdates": true,
+         "dailyDigest": true
+       }
+     }
+   }
+   ```
+
+### Usage
+
+**Ask Questions:**
+```
+@DocsBot How do I authenticate API requests?
+@DocsBot Show me user creation example
+@DocsBot What's the rate limit for /users endpoint?
+```
+
+**Search:**
+```
+/docs search webhooks
+/docs find deployment guide
+```
+
+**Get Updates:**
+```
+/docs subscribe api-updates
+/docs notifications on
+```
+
+### Features
+
+- Conversational interface
+- Code snippet formatting
+- Direct message support
+- Channel subscriptions
+- Documentation update notifications
+- Daily digest summaries
+
+## Agent Automation
+
+AI agent for automated documentation tasks.
+
+### Configuration
+
+```json
+{
+  "ai": {
+    "agent": {
+      "enabled": true,
+      "capabilities": [
+        "suggest-improvements",
+        "detect-outdated",
+        "generate-examples",
+        "fix-broken-links"
+      ],
+      "schedule": "daily",
+      "notifications": {
+        "slack": "#docs-updates",
+        "email": "team@example.com"
+      }
+    }
+  }
+}
+```
+
+### Capabilities
+
+**Suggest Improvements:**
+- Identify unclear explanations
+- Suggest better wording
+- Recommend additional examples
+- Highlight missing sections
+
+**Detect Outdated Content:**
+- Compare with codebase
+- Check API version compatibility
+- Flag deprecated features
+- Identify stale examples
+
+**Generate Examples:**
+- Auto-generate code examples
+- Create usage scenarios
+- Build tutorial content
+- Produce troubleshooting guides
+
+**Fix Broken Links:**
+- Scan for 404s
+- Update redirected URLs
+- Fix internal references
+- Validate external links
+
+### Slack Integration
+
+Receive agent suggestions in Slack:
+
+```
+Agent Report - Daily Digest
+
+Suggestions (3):
+- Add Python example to /api/authentication
+- Update rate limits in /api/overview (changed in v2.5)
+- Clarify webhook signature verification in /webhooks
+
+Broken Links (1):
+- /guides/deployment links to removed page /setup
+
+Outdated Content (2):
+- /api/users references deprecated `user_type` field
+- /quickstart shows old authentication method
+```
+
+### Workflow Automation
+
+Configure automated workflows:
+
+```json
+{
+  "ai": {
+    "workflows": [
+      {
+        "name": "Weekly Review",
+        "trigger": "schedule",
+        "schedule": "0 9 * * MON",
+        "actions": [
+          "detect-outdated",
+          "broken-links",
+          "suggest-improvements"
+        ],
+        "output": "slack"
+      },
+      {
+        "name": "PR Review",
+        "trigger": "pull_request",
+        "actions": [
+          "validate-changes",
+          "suggest-examples",
+          "check-consistency"
+        ],
+        "output": "github"
+      }
+    ]
+  }
+}
+```
+
+## AI API Access
+
+Programmatic access to AI features.
+
+### Endpoints
+
+**Search:**
+```bash
+curl -X POST https://api.mintlify.com/v1/ai/search \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "How do I authenticate?",
+    "scope": "api"
+  }'
+```
+
+**Ask Question:**
+```bash
+curl -X POST https://api.mintlify.com/v1/ai/ask \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "question": "What are the rate limits?",
+    "context": ["api/overview", "api/rate-limits"]
+  }'
+```
+
+**Generate Example:**
+```bash
+curl -X POST https://api.mintlify.com/v1/ai/generate \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "code_example",
+    "endpoint": "POST /users",
+    "language": "python"
+  }'
+```
+
+### SDK Usage
+
+**JavaScript:**
+```javascript
+import { MintlifyAI } from '@mintlify/ai';
+
+const ai = new MintlifyAI({ apiKey: 'YOUR_API_KEY' });
+
+const answer = await ai.ask({
+  question: 'How do I authenticate API requests?',
+  context: ['api/authentication']
+});
+
+console.log(answer.response);
+console.log(answer.sources);
+```
+
+**Python:**
+```python
+from mintlify import MintlifyAI
+
+ai = MintlifyAI(api_key='YOUR_API_KEY')
+
+answer = ai.ask(
+    question='How do I authenticate API requests?',
+    context=['api/authentication']
+)
+
+print(answer.response)
+print(answer.sources)
+```
+
+## Analytics and Insights
+
+Track AI feature usage and effectiveness.
+
+### AI Metrics
+
+**Search Analytics:**
+- Popular queries
+- Query success rate
+- Zero-result searches
+- Click-through rates
+
+**Question Analytics:**
+- Most asked questions
+- Response accuracy
+- User satisfaction ratings
+- Follow-up questions
+
+**Usage Patterns:**
+- Peak usage times
+- User segments
+- Feature adoption
+- Integration usage
+
+### Dashboard
+
+View AI analytics in Mintlify dashboard:
+- AI > Analytics
+- Filter by date range
+- Export reports
+- Track trends
+
+### Configuration
+
+```json
+{
+  "ai": {
+    "analytics": {
+      "enabled": true,
+      "trackQueries": true,
+      "trackClicks": true,
+      "collectFeedback": true
+    }
+  }
+}
+```