Enhanced agent documentation with pull request workflow details

ai/agent.mdx

@@ -9,6 +9,8 @@
 
 The agent creates pull requests with proposed changes to your documentation based on your prompts. When you send a request to the agent, 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.
 
+Each agent request creates a new pull request in your documentation repository with a descriptive title and branch name. The agent commits all changes to this branch and provides a link to the pull request so you can review, request changes, or merge the updates.
+
 Use the agent to:
 
 - Write new content based on your prompts, links to pull requests, or Slack threads
@@ -21,7 +23,7 @@
 ## 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.
@@ -36,9 +38,34 @@
 
 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).
 
+## Review and manage pull requests
+
+After the agent completes a task, it responds with a link to the pull request it created. You can review the changes, leave comments, request modifications, or merge the PR directly from GitHub.
+
+### Pull request workflow
+
+1. The agent creates a new branch with a descriptive name based on your prompt.
+2. All documentation changes are committed to this branch.
+3. A pull request is opened automatically with a summary of the changes.
+4. Review the PR in GitHub to see the full diff of all modified files.
+5. Merge the PR when you're satisfied with the changes, or continue iterating with the agent in the Slack thread.
+
+### Request changes to a pull request
+
+If the agent's pull request needs adjustments, mention `@mintlify` in the same Slack thread with your feedback. The agent will update the existing pull request with new commits based on your instructions.
+
+For example:
+- `@mintlify The code example needs to use TypeScript instead of JavaScript`
+- `@mintlify Add a note about rate limits to this section`
+- `@mintlify Move the new section to appear before the authentication section`
+
+### Close or abandon a pull request
+
+If you no longer need the changes from an agent pull request, close it directly in GitHub. The agent will not reopen closed pull requests unless you create a new request.
+
 ## Embed the agent via API
 
-Use the agent endpoints to [create jobs](/api-reference/agent/create-agent-job), [get a specific job](/api-reference/agent/get-agent-job), and [get all jobs](/api-reference/agent/get-all-jobs).
+Use the agent endpoints to [create jobs](/api-reference/agent/create-agent-job), [get a specific job](/api-reference/agent/get-agent-job), and [get all jobs](/api-reference/agent/get-all-jobs). Each job creates a pull request that you can manage through the GitHub API or web interface.
 
 ## Write effective prompts
 
@@ -81,19 +108,19 @@
 
 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.
+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. The agent's pull request will show both the agent's commits and your manual commits together.
 
 ### Update docs when merging feature changes
 
-When you merge a feature pull request, share the PR link with the agent to update relevant docs.
+When you merge a feature pull request, share the PR link with the agent to update relevant docs. The agent will analyze the code changes in the pull request and create a new documentation pull request with the appropriate updates.
 
-For example: `@mintlify This PR adds a new authentication method. Update the docs to include the new auth flow: [PR link]`.
+For example: `@mintlify This PR adds a new authentication method. Update the docs to include the new auth flow: [PR link]`. The agent will read the pull request diff, understand the changes, and create a documentation PR that reflects the new authentication method.
 
 ### Generate release notes from a pull request
 
-Prompt the agent with a specific pull request to generate release notes or changelog updates based on the commit history.
+Prompt the agent with a specific pull request to generate release notes or changelog updates based on the commit history. The agent will create a pull request that adds the release notes to your changelog or creates a new changelog entry.
 
-For example: `@mintlify Generate release notes for this PR: [PR link]`.
+For example: `@mintlify Generate release notes for this PR: [PR link]`. The agent will analyze the pull request's commits, changes, and description to create comprehensive release notes.
 
 ### Generate code examples