diff --git a/ai/agent.mdx b/ai/agent.mdx
index 04a362618..329760cb9 100644
--- a/ai/agent.mdx
+++ b/ai/agent.mdx
@@ -52,6 +52,27 @@ Use the agent in Slack to collaborate with your team on documentation updates.
    - Send a direct message to it.
    - Mention it with `@mintlify` in a channel.
 
+## Use the agent on GitHub pull requests
+
+Mention `@mintlify` in comments on any GitHub pull request to create documentation updates in your docs repository. The agent analyzes the PR context and creates a documentation PR with relevant changes.
+
+<Note>
+  The GitHub App must be installed and configured to use the agent on pull requests. See [GitHub integration](/deploy/github) for setup instructions.
+</Note>
+
+To use the agent on GitHub:
+
+1. Open any pull request in a repository where you have the Mintlify GitHub App installed.
+1. Add a comment mentioning `@mintlify` with your documentation request.
+1. The agent creates a pull request in your documentation repository with the requested changes.
+
+The agent works on pull requests in any repository, not just your documentation repository. This lets you update docs directly from feature PRs, bug fixes, or any code changes.
+
+For example:
+- `@mintlify Update the API docs to reflect the new authentication flow in this PR`
+- `@mintlify Add a guide showing how to use this new feature`
+- `@mintlify Update the changelog with these changes`
+
 ## Connect your GitHub account
 
 By default, the agent opens pull requests attributed to the Mintlify bot. To attribute pull requests to you, connect your GitHub account on the [My profile](https://dashboard.mintlify.com/settings/account) page of the dashboard.
@@ -118,7 +139,9 @@ Use broad prompts for general content maintenance like fixing typos, updating re
 
 ## Specify a domain name
 
-If you have multiple documentation sites, include the `subdomain` parameter in your message to specify which documentation set the agent should work on.
+If you have multiple documentation sites, the agent automatically selects the correct deployment based on your prompt context. In most cases, you don't need to manually specify which documentation set to update.
+
+If you need to explicitly specify a deployment, include the `subdomain` parameter in your message.
 
 To find your domain name, look at your dashboard URL for the documentation set you want to update. The domain name is the last part after your organization name. For example, if your dashboard URL is `https://dashboard.mintlify.com/org-name/domain-name`, your domain name is `domain-name`.
 
diff --git a/deploy/github.mdx b/deploy/github.mdx
index 1aa7a99a1..d7caead4b 100644
--- a/deploy/github.mdx
+++ b/deploy/github.mdx
@@ -52,7 +52,11 @@ The app only accesses repositories that you explicitly grant it access to. If yo
 
 ## Manage repository access
 
-When installing the GitHub App, you can grant access to all of your repositories or specific ones. We recommend only granting access to your documentation repository and any repositories that you want to provide as context for the agent. You can modify this selection anytime in your [GitHub App settings](https://github.com/apps/mintlify/installations/new).
+When installing the GitHub App, you can grant access to all of your repositories or specific ones. We recommend only granting access to your documentation repository and any repositories that you want to provide as context for the agent. 
+
+Grant the agent access to additional repositories to enable `@mintlify` mentions in pull requests across your organization. When you mention `@mintlify` in a PR comment on any repository with the GitHub App installed, the agent creates documentation updates in your docs repository.
+
+You can modify repository access anytime in your [GitHub App settings](https://github.com/apps/mintlify/installations/new).
 
 ## Configure docs source