diff --git a/src/content/docs/docs/configuring-promptless/triggers/git-hub-p-rs.mdx b/src/content/docs/docs/configuring-promptless/triggers/git-hub-p-rs.mdx
index ca91f2fc..2df37d66 100644
--- a/src/content/docs/docs/configuring-promptless/triggers/git-hub-p-rs.mdx
+++ b/src/content/docs/docs/configuring-promptless/triggers/git-hub-p-rs.mdx
@@ -10,11 +10,28 @@ import Info from '@components/fern/Info.astro';
 import Note from '@components/fern/Note.astro';
 import Warning from '@components/fern/Warning.astro';
 
-Promptless automatically monitors your GitHub repositories for new pull requests. When a PR is opened, the system analyzes the changes to determine if documentation updates are needed.
+Promptless monitors your GitHub repositories for pull requests. You can choose when documentation updates trigger: when a PR is opened or when it receives its first approval.
+
+## Trigger Modes
+
+GitHub PR triggers support two modes:
+
+### Opened (Default)
+
+Triggers when a pull request is opened. This works well for teams that want documentation suggestions ready alongside code changes, giving reviewers time to evaluate both.
+
+### First Approval
+
+Triggers when a pull request receives its first approval from a reviewer. Use this mode when you want documentation updates to start only after code has been reviewed, so Promptless analyzes final changes rather than work in progress.
+
+<Info>
+The first-approval mode only triggers once per PR—on the first approval. Subsequent approvals or re-approvals after requested changes do not trigger additional documentation updates.
+</Info>
+
 
 ## How It Works
 
-When a pull request is opened in your monitored repositories:
+When a pull request event occurs in your monitored repositories (either opened or first approval, depending on your configuration):
 
 1. **Automatic Detection**: Promptless receives notification of the new PR
 2. **Analysis**: The system processes the code diff, PR title, and PR description to understand the context
@@ -22,7 +39,7 @@ When a pull request is opened in your monitored repositories:
 4. **Suggestion Creation**: If relevant, Promptless creates documentation suggestions
 
 <Note>
-Information from PRs is processed in real-time and not stored by Promptless. The analysis happens only when the PR is created or updated.
+Information from PRs is processed in real-time and not stored by Promptless. The analysis happens only when the configured trigger event occurs.
 </Note>
 
 ## Configuration
@@ -30,12 +47,13 @@ Information from PRs is processed in real-time and not stored by Promptless. The
 Configure GitHub PR triggers in your [project settings](https://app.gopromptless.ai/projects):
 
 1. Select GitHub as your trigger source
-2. Choose which repositories to monitor
-3. Optionally configure directory-specific triggers (see below)
-4. Set auto-publish preferences
+2. Choose the trigger mode: **When PR opens** (default) or **After first approval**
+3. Choose which repositories to monitor
+4. Optionally configure directory-specific triggers (see below)
+5. Set auto-publish preferences
 
-<Frame>
-  <img src="/assets/github-project.png" alt="GitHub project configuration showing trigger repository selection" />
+<Frame caption="GitHub PR trigger configuration with timing options">
+  <img src="https://promptless-customer-doc-assets.s3.us-east-2.amazonaws.com/docs-images/org_2lvkgU9erOFxYhtEVVC0ymPrPdF/github-pr-trigger-mode-27bc0fb4.png" alt="Edit Project modal showing PR trigger timing dropdown with 'When PR opens' and 'After first approval' options" />
 </Frame>
 
 ## Directory-Specific Triggers