Docs refactor for better readability, dedicated guides for CLI + CI/CD usage

Signed-off-by: lelia <lelia@socket.dev>

Author: lelia

README.md

@@ -79,14 +79,19 @@ socketcli \
   --disable-blocking
 ```
 
-## Scope and behavior matrix
+## Choose your mode
 
-| Goal | Key flags | Notes |
+| Use case | Recommended mode | Key flags |
 |:--|:--|:--|
-| Match dashboard-style reachable view | `--sarif-scope full --sarif-grouping alert --sarif-reachability reachable` | Best parity path for customer evaluations |
-| Capture all reachability findings | `--sarif-scope full --sarif-grouping instance --sarif-reachability all` | Most verbose output |
-| Gate only on new findings | `--sarif-scope diff` | Diff mode can validly return empty SARIF |
-| Filter to reachable only (legacy syntax) | `--sarif-reachable-only` | Backward-compatible alias for `--sarif-reachability reachable` |
+| Basic policy enforcement in CI | Diff-based policy check | `--strict-blocking` |
+| Reachable-focused SARIF for reporting | Full-scope grouped SARIF | `--reach --sarif-scope full --sarif-grouping alert --sarif-reachability reachable --sarif-file <path>` |
+| Detailed reachability export for investigations | Full-scope instance SARIF | `--reach --sarif-scope full --sarif-grouping instance --sarif-reachability all --sarif-file <path>` |
+| Net-new PR findings only | Diff-scope SARIF | `--reach --sarif-scope diff --sarif-reachability reachable --sarif-file <path>` |
+
+Dashboard parity note:
+- Full-scope SARIF is the closest match for dashboard-style filtering.
+- Exact result counts can still differ from the dashboard due to backend/API consolidation differences and grouping semantics.
+- See [`docs/troubleshooting.md#dashboard-vs-cli-result-counts`](docs/troubleshooting.md#dashboard-vs-cli-result-counts).
 
 ## Config files (`--config`)
 
@@ -108,6 +113,21 @@ sarif_reachability = "reachable"
 sarif_file = "reachable.sarif"
 ```
 
+Equivalent JSON:
+
+```json
+{
+  "socketcli": {
+    "repo": "example-repo",
+    "reach": true,
+    "sarif_scope": "full",
+    "sarif_grouping": "alert",
+    "sarif_reachability": "reachable",
+    "sarif_file": "reachable.sarif"
+  }
+}
+```
+
 Run:
 
 ```bash
@@ -116,10 +136,16 @@ socketcli --config .socketcli.toml --target-path .
 
 Reference sample configs:
 
+TOML:
 - [`examples/config/sarif-dashboard-parity.toml`](examples/config/sarif-dashboard-parity.toml)
 - [`examples/config/sarif-instance-detail.toml`](examples/config/sarif-instance-detail.toml)
 - [`examples/config/sarif-diff-ci-cd.toml`](examples/config/sarif-diff-ci-cd.toml)
 
+JSON:
+- [`examples/config/sarif-dashboard-parity.json`](examples/config/sarif-dashboard-parity.json)
+- [`examples/config/sarif-instance-detail.json`](examples/config/sarif-instance-detail.json)
+- [`examples/config/sarif-diff-ci-cd.json`](examples/config/sarif-diff-ci-cd.json)
+
 ## CI/CD examples
 
 Prebuilt workflow examples:

docs/ci-cd.md

@@ -29,7 +29,7 @@ socketcli \
 
 ## Config file usage in CI
 
-Use `--config .socketcli.toml` to keep pipeline commands small.
+Use `--config .socketcli.toml` or `--config .socketcli.json` to keep pipeline commands small.
 
 Precedence order:
 
@@ -46,6 +46,20 @@ sarif_reachability = "reachable"
 sarif_file = "results.sarif"
 ```
 
+Equivalent JSON:
+
+```json
+{
+  "socketcli": {
+    "reach": true,
+    "sarif_scope": "full",
+    "sarif_grouping": "alert",
+    "sarif_reachability": "reachable",
+    "sarif_file": "results.sarif"
+  }
+}
+```
+
 ## Platform examples
 
 ### GitHub Actions
@@ -98,7 +112,7 @@ Prebuilt examples in this repo:
 
 ## CI gotchas
 
-- `--strict-blocking` changes pass/fail policy, not SARIF dataset semantics.
+- `--strict-blocking` enables strict diff behavior (`new + unchanged`) for blocking evaluation and diff-based output selection.
 - `--sarif-scope full` requires `--reach`.
 - `--sarif-grouping alert` currently applies to `--sarif-scope full`.
 - Diff-based SARIF can validly be empty when there are no matching net-new alerts.

docs/cli-reference.md

@@ -122,13 +122,13 @@ This will simultaneously generate:
 - SARIF report to `results.sarif` (and stdout)
 - GitLab Security Dashboard report to `gl-dependency-scanning-report.json`
 
-> **Note:** `--enable-sarif` prints SARIF to stdout only. Use `--sarif-file <path>` to save to a file (this also implies `--enable-sarif`). Add `--sarif-reachable-only` (requires `--reach`) to filter results down to only reachable findings. Use `--sarif-scope diff|full` to choose between diff alerts (default) and full reachability facts scope. These flags are independent from `--enable-gitlab-security`, which produces a separate GitLab-specific Dependency Scanning report.
+> **Note:** `--enable-sarif` prints SARIF to stdout only. Use `--sarif-file <path>` to save to a file (this also implies `--enable-sarif`). Use `--sarif-reachability` (requires `--reach` when not `all`) to filter by reachability state. Use `--sarif-scope diff|full` to choose between diff alerts (default) and full reachability facts scope. These flags are independent from `--enable-gitlab-security`, which produces a separate GitLab-specific Dependency Scanning report.
 >
-> `--strict-blocking` affects pass/fail behavior, not SARIF result population.
+> In diff scope, `--strict-blocking` expands selection to include `new + unchanged` diff alerts for evaluation/output paths.
 >
 > SARIF scope examples:
-> - Diff-only reachable findings: `socketcli --reach --sarif-file out.sarif --sarif-scope diff --sarif-reachable-only`
-> - Full reachability scope, reachable only: `socketcli --reach --sarif-file out.sarif --sarif-scope full --sarif-reachable-only`
+> - Diff-only reachable findings: `socketcli --reach --sarif-file out.sarif --sarif-scope diff --sarif-reachability reachable`
+> - Full reachability scope, reachable only: `socketcli --reach --sarif-file out.sarif --sarif-scope full --sarif-reachability reachable`
 > - Full reachability scope, all reachability states: `socketcli --reach --sarif-file out.sarif --sarif-scope full`
 > - Dashboard-style grouping (one result per alert key): `socketcli --reach --sarif-file out.sarif --sarif-scope full --sarif-grouping alert --sarif-reachability reachable`
 >
@@ -149,7 +149,7 @@ socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--workspace WORKSPACE] [--
           [--target-path TARGET_PATH] [--sbom-file SBOM_FILE] [--license-file-name LICENSE_FILE_NAME] [--save-submitted-files-list SAVE_SUBMITTED_FILES_LIST]
           [--save-manifest-tar SAVE_MANIFEST_TAR] [--files FILES] [--sub-path SUB_PATH] [--workspace-name WORKSPACE_NAME]
           [--excluded-ecosystems EXCLUDED_ECOSYSTEMS] [--default-branch] [--pending-head] [--generate-license] [--enable-debug]
-          [--enable-json] [--enable-sarif] [--sarif-file <path>] [--sarif-reachable-only] [--sarif-scope {diff,full}] [--sarif-grouping {instance,alert}] [--sarif-reachability {all,reachable,potentially,reachable-or-potentially}] [--enable-gitlab-security] [--gitlab-security-file <path>]
+          [--enable-json] [--enable-sarif] [--sarif-file <path>] [--sarif-scope {diff,full}] [--sarif-grouping {instance,alert}] [--sarif-reachability {all,reachable,potentially,reachable-or-potentially}] [--enable-gitlab-security] [--gitlab-security-file <path>]
           [--disable-overview] [--exclude-license-details] [--allow-unverified] [--disable-security-issue]
           [--ignore-commit-files] [--disable-blocking] [--enable-diff] [--scm SCM] [--timeout TIMEOUT] [--include-module-folders]
           [--reach] [--reach-version REACH_VERSION] [--reach-timeout REACH_ANALYSIS_TIMEOUT]
@@ -219,7 +219,6 @@ If you don't want to provide the Socket API Token every time then you can use th
 | `--enable-json`             | False    | False   | Output in JSON format                                                             |
 | `--enable-sarif`            | False    | False   | Enable SARIF output of results instead of table or JSON format (prints to stdout) |
 | `--sarif-file`              | False    |         | Output file path for SARIF report (implies --enable-sarif). Use this to save SARIF output to a file for upload to GitHub Code Scanning, SonarQube, VS Code, or other SARIF-compatible tools |
-| `--sarif-reachable-only`    | False    | False   | Filter SARIF output to only include reachable findings (requires --reach)         |
 | `--sarif-scope`             | False    | diff    | SARIF source scope: `diff` for net-new diff alerts, or `full` for full reachability facts scope (requires --reach for full) |
 | `--sarif-grouping`          | False    | instance| SARIF grouping mode: `instance` (one entry per package/version/advisory instance) or `alert` (grouped alert-style output, full scope only) |
 | `--sarif-reachability`      | False    | all     | SARIF reachability selector: `all`, `reachable`, `potentially`, or `reachable-or-potentially` (requires --reach when not `all`) |
@@ -273,6 +272,29 @@ sarif_reachability = "reachable"
 sarif_file = "reachable.sarif"
 ```
 
+Equivalent `socketcli.json`:
+
+```json
+{
+  "socketcli": {
+    "repo": "example-repo",
+    "reach": true,
+    "sarif_scope": "full",
+    "sarif_grouping": "alert",
+    "sarif_reachability": "reachable",
+    "sarif_file": "reachable.sarif"
+  }
+}
+```
+
+Sample config files:
+- [`../examples/config/sarif-dashboard-parity.toml`](../examples/config/sarif-dashboard-parity.toml)
+- [`../examples/config/sarif-dashboard-parity.json`](../examples/config/sarif-dashboard-parity.json)
+- [`../examples/config/sarif-instance-detail.toml`](../examples/config/sarif-instance-detail.toml)
+- [`../examples/config/sarif-instance-detail.json`](../examples/config/sarif-instance-detail.json)
+- [`../examples/config/sarif-diff-ci-cd.toml`](../examples/config/sarif-diff-ci-cd.toml)
+- [`../examples/config/sarif-diff-ci-cd.json`](../examples/config/sarif-diff-ci-cd.json)
+
 ### CI/CD usage tips
 
 For CI-specific examples and guidance, see [`ci-cd.md`](ci-cd.md).
@@ -407,7 +429,7 @@ export SOCKET_SLACK_BOT_TOKEN="xoxb-your-bot-token-here"
 **Configuration Options:**
 
 Webhook mode (`url_configs`):
-- `reachability_alerts_only` (boolean, default: false): When `--reach` is enabled, only send blocking alerts (error=true) from diff scans
+- `reachability_alerts_only` (boolean, default: false): When `--reach` is enabled, only send reachable vulnerabilities from the selected diff alert set (uses reachability facts when available; otherwise falls back to blocking-status behavior)
 - `repos` (array): Only send alerts for specific repositories (e.g., `["owner/repo1", "owner/repo2"]`)
 - `alert_types` (array): Only send specific alert types (e.g., `["malware", "typosquat"]`)
 - `severities` (array): Only send alerts with specific severities (e.g., `["high", "critical"]`)

docs/troubleshooting.md

@@ -2,11 +2,34 @@
 
 ## Common gotchas
 
-- `--strict-blocking` changes pass/fail policy, not SARIF dataset source.
+- In diff scope, `--strict-blocking` uses a stricter alert set (`new + unchanged`) for blocking checks and diff-based output selection.
 - `--sarif-scope full` requires `--reach`.
 - In `--sarif-scope full` with `--sarif-file`, SARIF JSON is written to file and stdout JSON is suppressed.
 - `--sarif-grouping alert` currently applies to `--sarif-scope full`.
 
+## Dashboard vs CLI result counts
+
+Differences in result counts can be valid, even when filtering appears similar.
+
+Common reasons:
+
+- `diff` vs `full` data source:
+  - `--sarif-scope diff` is based on diff alerts (typically net-new in the compared scan context).
+  - `--sarif-scope full` is based on full reachability facts data.
+- Consolidation differences:
+  - Dashboard and API/CLI can apply different consolidation/grouping rules.
+  - `--sarif-grouping alert` and `--sarif-grouping instance` intentionally produce different row counts.
+- Policy vs dataset:
+  - `--strict-blocking` only affects diff-scope behavior and does not make diff output equivalent to full dashboard data.
+- Reachability data availability:
+  - If reachability analysis partially fails and falls back to precomputed tiers, counts can shift.
+
+Recommended comparison path:
+
+1. Use full-scope SARIF for parity-oriented comparisons.
+2. Keep grouping fixed (`alert` for dashboard-style rollups, `instance` for detailed exports).
+3. Compare reachability filters with the same mode and grouping across runs.
+
 ## Save submitted file list
 
 Use `--save-submitted-files-list` to inspect exactly what was sent for scanning.