Correct which runs compare, after the 2.9.0 flow change

#302 moved SCM-integrated non-PR/MR pipelines onto a full scan: create_scm_scan
now sends only a "diff" event type to create_new_diff and everything else,
default-branch pushes included, to create_full_scan_with_report_url.

The permission docs asserted the opposite -- that plain pushes also reach the
diff-scans path -- which was true when they were written against 2.8.1 and is
not true now. Replace the claim with a table of which runs compare, and keep
the old behavior as a note, since the warning still shows up in logs from
pre-2.9.0 runs with no pull request in sight.

Re-verified the rest against 2.9.7: SDK call surface, the four sys.exit(2)
sites, the temporary empty baseline, and the reachability scan ID are all
unchanged.

Author: lelia

CHANGELOG.md

@@ -13,10 +13,11 @@
   Recorded the converse too: `socketcli` makes no triage or security-policy calls, so
   three of the nine scopes that guide lists are not exercised by this CLI.
 - Corrected the scan-comparison guidance. The `APIAccessDenied` fallback was documented
-  as a PR/MR-only condition, but it applies to any run that produces a diff, including
-  plain pushes on the default branch. The guidance also listed `full-scans:list`
-  alongside the two `diff-scans:*` scopes, which points readers at a permission the
-  fallback path demonstrably already has.
+  as a PR/MR-only condition; it applies to any run that produces a diff, which since
+  2.9.0 means PR/MR events and runs without an SCM integration. Added a table of which
+  runs compare, and a note that before 2.9.0 SCM-integrated branch pushes compared too.
+  The guidance also listed `full-scans:list` alongside the two `diff-scans:*` scopes,
+  which points readers at a permission the fallback path demonstrably already has.
 - Documented three outcomes that are expected but read as failures: the temporary empty
   baseline created on a repository's first scan, which does not appear in the dashboard;
   the reachability scan ID being a `tier1ReachabilityScanId` rather than a full scan ID,

docs/troubleshooting.md

@@ -76,19 +76,27 @@ identifiers for them are not published.
 
 ## `APIAccessDenied` on the scan comparison
 
-Any run that produces a diff — PR/MR events, **plain pushes on the default branch**,
-and `--enable-diff` / `--ignore-commit-files` runs without an SCM integration — first
-tries the diff-scans endpoints. A token without the `diff-scans:*` permissions logs a
-warning and silently continues on the older path:
+Any run that produces a diff first tries the diff-scans endpoints. A token without the
+`diff-scans:*` permissions logs a warning and silently continues on the older path:
 
 ```
 Diff scan comparison failed with APIAccessDenied(Insufficient permissions), falling back to the streaming scan comparison
 ```
 
 The scan still succeeds and the diff results are the same, so this is easy to miss.
 
-Note that this is *not* limited to PR/MR runs. A pipeline that only ever scans pushes
-(`--pr-number 0 --default-branch`) still hits it.
+**Which runs produce a diff.** As of 2.9.0:
+
+| Run | Compares? |
+|:---|:---|
+| PR/MR event with `--scm github` / `--scm gitlab` | Yes |
+| Any other event with `--scm github` / `--scm gitlab` (branch and default-branch pushes) | No — creates a full scan |
+| No SCM integration (`--scm api`, the default), including `--enable-diff` and `--ignore-commit-files` | Yes |
+| No supported manifest in the changed-file set | No — falls back to a full scan |
+
+Before 2.9.0 an SCM-integrated branch push also compared, so a pipeline scanning only
+pushes (`--pr-number 0 --default-branch`) hit this too. If you are diagnosing an older
+run, that is why the warning can appear in a log with no pull request in sight.
 
 **Which permission is missing.** The fallback path is `GET orgs/{org}/full-scans/diff`,
 a full-scans read. If you see the fallback produce results, your token already has