diff --git a/agent/agent-v2.mdx b/agent/agent-v2.mdx
new file mode 100644
index 000000000..479cafa6e
--- /dev/null
+++ b/agent/agent-v2.mdx
@@ -0,0 +1,199 @@
+---
+title: "Agent v2"
+description: "Claude-powered autonomous documentation agent for creating, updating, and maintaining your documentation."
+keywords: ["agent v2", "automation", "AI", "claude", "autonomous", "documentation"]
+---
+
+
+ Agent v2 is available on [Enterprise plans](https://mintlify.com/pricing?ref=agent) and is currently powered by Anthropic's Claude 4.5 Sonnet model.
+
+
+Agent v2 is an autonomous technical writer powered by Claude 4.5 Sonnet. It creates pull requests with documentation changes based on your prompts, references your codebase and Slack conversations, and follows technical writing best practices.
+
+## Core capabilities
+
+The agent can:
+
+- **Write new documentation**: Create pages from scratch based on prompts, pull requests, or Slack threads
+- **Update existing content**: Search and revise documentation to keep it current
+- **Review code changes**: Reference connected repositories to document new features or API changes
+- **Answer questions**: Provide information about your docs and technical writing best practices
+- **Maintain consistency**: Follow your documentation style and Mintlify schema automatically
+
+## How the agent works
+
+When you send a request, the agent:
+
+1. **Researches**: Reads your existing documentation, connected repositories, and relevant context
+2. **Plans**: Creates a structured task list for complex documentation work
+3. **Writes**: Generates or updates content following technical writing standards
+4. **Validates**: Runs Mintlify CLI checks to ensure documentation builds correctly
+5. **Creates PR**: Opens a pull request with proposed changes for human review
+
+All changes go through pull requests. The agent never commits directly to your main branch.
+
+## Tools and capabilities
+
+The agent has access to specialized tools for documentation work:
+
+### File operations
+- **Read**: Access any file in your repository with line number references
+- **Edit**: Make precise changes to existing documentation
+- **Write**: Create new documentation pages
+- **Search**: Find files by pattern (glob) or content (grep)
+- **File upload**: Process files and images attached to Slack messages or uploaded through the dashboard
+
+### Git and GitHub
+- **Branch management**: Create and switch branches
+- **Commit changes**: Stage and commit updates with descriptive messages
+- **Pull requests**: Open PRs with clear descriptions
+- **Issue tracking**: Reference and update GitHub issues
+
+### Mintlify CLI validation
+- **mint validate**: Check documentation structure and configuration
+- **mint broken-links**: Verify internal links are correct
+- **mint dev**: Preview changes locally (requires manual setup)
+
+### Specialized agents
+The agent can launch sub-agents for specific tasks:
+- **Explore agent**: Navigate large codebases and find relevant files
+- **General agent**: Handle complex multi-step documentation tasks
+
+### Task management and interaction
+- **TodoWrite**: Track multi-step documentation work and show progress
+- **Interactive prompts**: Agent can ask clarifying questions during execution using the Question tool
+- **Progress tracking**: Shows progress through todo lists and Slack reactions as it works
+- **Session management**: Maintains conversation context across multiple interactions
+- Prevents goal drift during complex updates
+- Provides visibility into what's being worked on
+
+## Configuration with AGENTS.md
+
+Customize the agent's behavior by adding an `AGENTS.md` file to your repository. This file defines:
+
+- **Working relationship**: How the agent communicates and asks for clarification
+- **Content strategy**: Documentation philosophy and principles
+- **Writing standards**: Voice, tone, formatting conventions
+- **Workflow requirements**: Git practices, validation steps, PR guidelines
+
+The agent automatically reads and follows instructions in this file. See the [customize](/agent/customize) page for details.
+
+## Where to use agent v2
+
+- **Dashboard**: Press ⌘+I (macOS) or Ctrl+I (Windows/Linux) from any dashboard page
+- **Slack**: Mention `@mintlify` in any channel where the agent is installed. You can also attach files and images directly in your Slack messages for the agent to process
+- **API**: Integrate with custom applications using [agent endpoints](/api/agent/create-agent-job)
+
+## Slack integration features
+
+When using the agent in Slack, you get additional capabilities:
+
+- **File attachments**: Upload images, diagrams, code snippets, or documents directly in your message. The agent automatically processes these files and can:
+ - Add images to documentation pages
+ - Reference code from uploaded files
+ - Extract information from documents
+ - Include diagrams in your docs
+- **Thread context**: Agent reads entire thread history to understand conversation context
+- **User mentions**: Automatically resolves Slack user mentions for better collaboration
+- **Progress updates**: Provides real-time updates using Slack reactions as it works through tasks
+- **PR notifications**: Sends links to created pull requests and Mintlify editor previews
+
+### Using file uploads in Slack
+
+Attach files to your message when mentioning the agent:
+
+```
+@mintlify Add this diagram to the architecture overview page
+[attach: architecture-diagram.png]
+```
+
+```
+@mintlify Document the API endpoints shown in this code file
+[attach: endpoints.ts]
+```
+
+The agent automatically fetches, processes, and includes the files in your documentation.
+
+## Key differences from v1
+
+Agent v2 introduces:
+
+- **Autonomous planning**: Creates task lists and manages complex multi-step documentation work
+- **Better validation**: Runs Mintlify CLI checks before creating pull requests
+- **Enhanced research**: Can explore connected repositories and reference source code
+- **Tool specialization**: Access to dedicated file operations instead of relying only on bash commands
+- **Configurable behavior**: Respects AGENTS.md configuration files in your repository
+- **Task visibility**: Shows progress through todo lists as it works
+- **File processing**: Direct file and image uploads through Slack or dashboard
+
+## Best practices
+
+### Writing effective prompts
+
+Be specific about what you want:
+
+```
+Bad: "Update the docs"
+Good: "Add a section to /api-playground/overview explaining how to add authentication headers to API requests"
+```
+
+Provide context when needed:
+
+```
+Good: "Document the new rate limiting feature. See PR #123 for implementation details."
+```
+
+Reference specific files or sections:
+
+```
+Good: "Update /agent/quickstart to include the new keyboard shortcuts"
+```
+
+### Working with the agent
+
+- **Review PRs carefully**: The agent flags uncertainties with TODO comments
+- **Provide feedback**: Iterate on drafts by requesting specific changes
+- **Link to sources**: Reference pull requests, issues, or Slack threads for context
+- **Check validation**: The agent runs checks, but preview changes with `mint dev` locally
+
+### Configuration tips
+
+Add an `AGENTS.md` file to:
+- Define your documentation voice and tone
+- Specify formatting preferences
+- Set git workflow requirements
+- Establish validation criteria
+
+See [customize documentation](/agent/customize) for examples.
+
+## Limitations
+
+The agent:
+
+- Cannot preview visual changes (requires manual `mint dev` check)
+- May need clarification for complex or ambiguous requests
+- Adds TODO comments when uncertain about technical details
+- Requires human review before changes merge
+
+## Technical details
+
+- **Model**: Claude 4.5 Sonnet by Anthropic
+- **Context window**: Up to 200K tokens
+- **Validation**: Runs `mint validate` before creating PRs
+- **Git workflow**: Creates feature branches and never commits to main directly
+- **Security**: Respects repository permissions and cannot access secrets
+
+## Next steps
+
+
+Start using agent v2 in your dashboard.
+
+
+Add the agent to your Slack workspace.
+
+
+Configure the agent with an AGENTS.md file.
+
+
+Get better results with focused prompts.
+
diff --git a/agent/index.mdx b/agent/index.mdx
index 13dfb5d5f..f2f1458e2 100644
--- a/agent/index.mdx
+++ b/agent/index.mdx
@@ -4,6 +4,10 @@ description: "Automate documentation updates with the agent. Create updates from
keywords: ["automation", "automate", "AI", "autoupdate", "maintenance"]
---
+
+ This documentation describes agent v1, which is deprecated. Please refer to [agent v2](/agent/agent-v2) for the latest version with enhanced capabilities and autonomous planning.
+
+
The agent is available on [Enterprise plans](https://mintlify.com/pricing?ref=agent) for anyone with access to your dashboard.
diff --git a/docs.json b/docs.json
index 68f6c27e2..4f90a8815 100644
--- a/docs.json
+++ b/docs.json
@@ -78,6 +78,7 @@
{
"group": "Agent",
"pages": [
+ "agent/agent-v2",
"agent/index",
"agent/quickstart",
"agent/slack",