chore: update docs

Author: epipav

services/apps/git_integration/src/crowdgit/services/vulnerability_scanner/README.md

@@ -20,9 +20,14 @@ The binary follows the same **subprocess + JSON stdout** pattern used by the `so
 
 ## Key design decisions
 
-### OSV Scanner returns a non-nil error when vulnerabilities are found
+### OSV Scanner uses sentinel errors for expected outcomes
 
-This is counterintuitive but intentional — OSV Scanner behaves like `grep`: it returns a non-zero/error when it finds matches. We treat this as success and only propagate the error if no results came back alongside it.
+OSV Scanner returns sentinel errors for two non-failure cases:
+
+- `ErrVulnerabilitiesFound` — the scanner found vulnerabilities. Like `grep` returning exit code 1 on a match, this is an expected outcome. We treat it as success and surface the results normally.
+- `ErrNoPackagesFound` — the repo contains no scannable package manifests (e.g. a pure C or shell project). This is not a failure — the scanner ran correctly and determined there is nothing to check. The scan record gets status `no_packages_found` and the Python side does not treat it as an error.
+
+Any other non-nil error from the scanner is a real failure.
 
 ### Vulnerability identity: (repo_url, vulnerability_id, package_name, source_path)
 
@@ -59,9 +64,19 @@ On each scan, rather than deleting all previous findings and inserting fresh one
 
 This preserves history. You can tell when a vulnerability was first detected, when it was last seen, and when it went away — without needing a separate audit log. It also makes it cheap to compute `new_count` (rows that were truly inserted, not updated) and `resolved_count` (rows still carrying the newly-set `resolved_at` after the upsert pass).
 
+### Transitive dependency scanning
+
+By default the scanner resolves the full transitive dependency graph, not just direct dependencies declared in lockfiles. This catches vulnerabilities in indirect deps that the project never explicitly references.
+
+Transitive scanning is expensive for repos with large or deep package ecosystems — projects like ML frameworks with hundreds of transitive Python dependencies can exhaust the 3-minute scan timeout. The scanner handles this automatically:
+
+1. **First scan**: attempt with transitive=true. If it times out, retry immediately with transitive=false (direct deps only). The result of whichever mode succeeded is stored.
+2. **Subsequent scans**: reuse the same mode as the previous completed scan (`transitive_deps_scanned` stored per scan record). This avoids flip-flopping between modes and keeps results comparable across scans.
+
+
 ### Scan tracking
 
-Every invocation creates a row in `vulnerability_scans` before the scan starts (status: running) and updates it on completion with duration, counts, and any error. This makes it possible to detect stalled or crashed scans and gives a simple history of scan health per repo.
+Every invocation creates a row in `vulnerability_scans` before the scan starts (status: `running`) and updates it on completion with duration, counts, and any error. Terminal statuses are `success`, `no_packages_found`, and `failure`. This makes it possible to detect stalled or crashed scans and gives a simple history of scan health per repo.
 
 ## Building
 
@@ -85,3 +100,8 @@ Output is a JSON object on stdout:
 ```json
 { "status": "success", "error_code": null, "error_message": null }
 ```
+
+On repos with no scannable package manifests:
+```json
+{ "status": "no_packages_found", "error_code": null, "error_message": null }
+```