[TEC-468] Semgrep Assistant: document which findings are automatically analyzed

docs/semgrep-assistant/analyze.md

@@ -14,7 +14,7 @@ Once you've [enabled Assistant](/docs/semgrep-assistant/getting-started), you ca
 
 ![Assistant Analyze button on Findings page](/img/scp-assistant.png#md-width)
 
-To analyze your findings with Assistant:
+## How to analyze your findings with Assistant
 
 1. On the [Findings](https://semgrep.dev/orgs/-/findings?tab=open) page, select the findings that you want Assistant to analyze.
 2. Click **Analyze**.
@@ -27,21 +27,47 @@ The amount of time required to analyze your findings varies. Before running the
 :::info
 - For Team tier users with less than 10 contributors: There is a cap of 50 Assistant runs per month using the **Analyze** button.
 - For Team or Enterprise users with an active subscription: There is a cap of 10,000 Assistant runs per month using the **Analyze** button. It is rate-limited to 1,000 Assistant runs per hour.
-- For users of any tier: Assistant runs against pull requests and merge requests do not count against this limit.
+- For users of any tier: Assistant runs against pull requests (PRs) and merge requests (MRs) do not count against this limit.
 :::
 
-## View recommendations
+
+
+## When Assistant auto-analyzes findings
+
+Assistant will automatically generate an analysis for any new finding on a **full scan** that is:
+- Critical or High severity, or
+- High or Medium confidence.
+
+On a **PR or MR**, it will analyze up to 10 new findings, regardless of severity or confidence.
+
+
+## Findings that are not auto-analyzed
+
+Assistant won't automatically analyze:
+
+- Updated findings: Findings that are updates to existing issues rather than new findings
+- Duplicate findings: Findings that are duplicates of existing findings
+- Historical findings: Findings that were created before automatic analysis was enabled for your deployment. Automatic analysis for full scans was enabled in November 2025.
+- Additional PR or MR findings: The eleventh finding or later on the same PR or MR (only the first 10 are automatically analyzed)
+
+## Request analysis for existing findings
+
+If you want Assistant analyses for findings that weren't automatically analyzed (as described above), you can request them in bulk through Semgrep AppSec Platform.
+
+If you need assistance with bulk analysis requests or have questions about backfilling analyses for your findings, contact [Semgrep Support](/support).
+
+## View Assistant recommendations
 
 You can [view all of Semgrep Assistant's recommendations](/semgrep-code/findings/#filter-findings) by going to the Semgrep **Findings** page and filtering by **Recommendation** or **Component**.
 
-## Feedback
+## Provide feedback on Assistant recommendations
 
-Semgrep Assistant prompts you for feedback whenever it suggests that a finding is a false positive. Because Assistant content is generated by language models (LLMs), your feedback helps the Semgrep team improve Assistant.
+Semgrep Assistant prompts you for feedback whenever it suggests that a finding is a false positive. Because Assistant content is generated by large language models (LLMs), your feedback helps the Semgrep team improve Assistant.
 
 Semgrep Assistant lets you leave feedback in the following places:
 
 * In Semgrep AppSec Platform: the Assistant recommendation appears in Semgrep Code's **Finding Details** page under **Activity**, along with **Agree and ignore** or **Disagree** buttons. 
 * In Slack notifications: the **Agree** and **Disagree** buttons appear under the Assistant recommendation message.
-* In GitHub pull requests: you can leave feedback using `/semgrep assistant agree|disagree`.
+* In GitHub PRs: you can leave feedback using `/semgrep assistant agree|disagree`.
 
 If Semgrep Assistant suggests that a finding is a true positive and supplies an autofix suggestion, there is no automated mechanism to leave feedback on this outcome. Feel free to contact [Semgrep Support](/support) to let us know your thoughts.

docs/semgrep-assistant/overview.md

@@ -28,6 +28,11 @@ Semgrep Assistant:
   - GitHub Cloud and GitHub Enterprise Server (self-hosted)
   - GitLab, including SaaS and self-managed plans
 - Requires the Semgrep AppSec Platform for its use
+- Auto-analyzes many but not all findings during scans 
+  - For full scans, all *new* issues that are either:
+    - High or Critical severity, or
+    - High or Medium confidence 
+  - For diff-aware scans (pull pequest or merge request scans), up to 10 new issues are auto-analyzed per scan
 
 ## Features
 
@@ -37,7 +42,7 @@ Semgrep Assistant can provide remediation advice and autofixes, or suggested fix
 
 #### Guidance
 
-With Assistant enabled, every PR or MR comment Semgrep pushes includes remediation guidance with information on fixing the issue. Assistant's remediation guidance provides step-by-step instructions on how to remediate the finding identified by Semgrep Code.
+With Assistant enabled, PR or MR comments from Semgrep include step-by-step instructions for remedying the finding identified by Semgrep Code. 
 
 ![PR comments with remediation advice](/img/assistant-guidance.png#md-width)
 _**Figure.** PR comment displaying the rule message followed by a comment that contains Assistant-generated remediation guidance._