Agent docs

.vale/styles/Google/Headings.yml

@@ -30,6 +30,7 @@ exceptions:
   - PDF
   - SAML
   - SDK
+  - Slack
   - SSL
   - SSO
   - TLS

ai/agent.mdx

@@ -0,0 +1,79 @@
+---
+title: "Agent"
+description: "The agent helps you write and maintain documentation"
+icon: "pen-line"
+---
+
+<Info>
+  The agent is available to anyone with access to your dashboard.
+</Info>
+
+The agent helps write and maintain your documentation. It references your documentation, connected repositories, and Slack messages to create content that follows technical writing best practices and adheres to the Mintlify schema. Access the agent in your Slack workspace or embed it in custom applications with the API.
+
+Use the agent to:
+
+- Write new content based on your prompts, links to pull requests, or Slack threads
+- Revise outdated code examples and API references
+- Search and update existing content
+- Answer questions about your docs and technical writing topics
+
+To get started, add the agent to your Slack workspace and mention it with `@mintlify` in a channel.
+
+## Add the agent to your Slack workspace
+
+<Note>
+  If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the mintlify app before you connect it.
+</Note>
+
+1. Navigate to the [agent](https://dashboard.mintlify.com/products/agent) page of your dashboard.
+2. Select the **Connect** button.
+3. Follow the Slack prompts to add the `mintlify` app to your workspace.
+4. Test that the agent is working and responds when you:
+  - Send a direct message to it.
+  - Mention it with `@mintlify` in a channel.
+
+## Connect repositories as context
+
+The agent can only access repositories that you connect through the Mintlify GitHub App. Modify which repositories the agent can access in the [GitHub App settings](https://github.com/apps/mintlify/installations/new).
+
+## Embed the agent via API
+TODO: this whole section once the API is finalized
+See the API reference for more info.
+
+## Write effective prompts
+
+Think of the agent as a helpful assistant that needs your guidance to complete tasks. If you give it clear instructions and context, it is more likely to complete the task successfully. More focused tasks are easier to complete, so break down complex projects into smaller steps.
+
+Make your prompts specific and outcome-focused. A prompt like `@mintlify Improve the onboarding page` will have the agent apply general technical writing best practices to the page, but it may not improve the page in a way that truly helps your users.
+
+Try prompts based on outcomes you want your users to achieve or problems that you know they encounter. For example: `@mintlify A lot of users have trouble installing the CLI. Review the onboarding page and update the docs so that users can easily install the CLI` or `@mintlify Developers keep getting 401 errors when following our authentication guide. Review the auth docs and add clearer examples showing how to properly format the API key`.
+
+Use broad prompts for general content maintenance like fixing typos, updating redirects, or renaming a feature throughout your docs. For example: `@mintlify Find and fix all typos in the docs` or `@mintlify change all unordered lists to use * instead of -`.
+
+## Agent workflows
+
+The agent assists with many different documentation tasks. These workflows show some of the ways you can integrate the agent into your documentation process. Try an approach that fits how your team currently works and adapt it to your specific needs.
+
+### Iterate on a prompt in a Slack thread
+Prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates. For example: `@mintlify Our quickstart page needs a new section on inviting collaborators` then `@mintlify The new section should be called "Inviting collaborators"` and any other iterations.
+
+### Start with the agent, finish manually
+Prompt the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then you can take over to complete the task. For example: `@mintlify Update the quickstart page to include information about inviting collaborators` and then checkout the branch to make any additional changes using your preferred method.
+
+### Update docs when merging feature changes
+When you merge a feature pull request, prompt the agent with a link to the pull request to automatically update relevant documentation. For example: `@mintlify This PR adds a new authentication method. Update the docs to include the new auth flow: [PR link]`.
+
+### Generate release notes from commit history
+Prompt the agent with a specific pull request or a time period to generate release notes or changelog updates based on the commit history. For example: `@mintlify Generate release notes for this PR: [PR link]` or `@mintlify Generate release notes for the last month`.
+
+### Generate code examples
+Prompt the agent to generate code examples for features throughout your docs or on specific pages. For example: `@mintlify Generate a code example to make the authentication method easier to understand`.
+
+### Review existing content
+Prompt the agent to review existing content for technical accuracy, style, grammar, or other issues. For example: `@mintlify Review the API rate limiting section. We changed limits last month`.
+
+### Respond to user feedback
+Prompt the agent with feedback from your users to make focused updates to your docs. For example: `@mintlify Users are getting confused by step 3 in the setup guide. What might be making it unclear?`.
+
+### Automate with the API
+Integrate the agent into your existing automation tools to automatically update documentation when code changes occur, trigger content reviews, or sync documentation updates across multiple repositories.

ai/slack-app.mdx

@@ -5,23 +5,23 @@
 ---
 
 <Info>
-  The Slack app is available for [Pro and Enterprise plans](https://mintlify.com/pricing?ref=slack-app).
+  The Slack app is available for [Pro and Custom plans](https://mintlify.com/pricing?ref=slack-app).
 </Info>
 
-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 adds a bot 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 bot's name is `@yourprojectname-assistant`. So if your project name is Mintlify, the bot's name is `@mintlify-assistant`.
 
 The Slack app can incur costs: either using your AI assistant credits or incurring overages.
 
-## Setting up the Slack app
+## Set up the Slack app
 
 <Note>
   If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the Mintlify Slack app before you add it.
 </Note>
 
 1. Navigate to the [Add-ons](https://dashboard.mintlify.com/products/addons) page of your dashboard.
 2. Select **Connect** in the Slack Integration card.
 3. Follow the Slack prompts to add the app to your workspace.
 4. Test that the bot is working and responds when you:
-  - Send a direct message to the Mintlify app.
-  - Mention the bot with `@mintlify` in a channel.
+  - Send a direct message to the bot.
+  - Mention the bot in a channel.
   - Create an `#ask-ai` channel, add the bot, and ask a question.

docs.json

@@ -51,6 +51,7 @@
             "group": "AI optimization",
             "pages": [
               "guides/assistant",
+              "ai/agent",
               "ai/llmstxt",
               "ai/contextual-menu",
               "ai/model-context-protocol",