Merge pull request #142 from sonukapoor/feature/issue-141-verbose-output-guide

docs: add how-to-read verbose output guide

Author: sonukapoor

README.md

@@ -37,6 +37,7 @@
       <a href="#why-offline-mode-matters">Why offline mode matters</a><br/>
       <a href="docs/case-studies/owasp-juice-shop.md">OWASP Juice Shop case study</a><br/>
       <a href="docs/case-studies/nestjs.md">NestJS case study</a><br/>
+      <a href="docs/how-to-read-verbose-output.md">How to read verbose output</a><br/>
       <a href="#what-it-looks-like">What it looks like</a><br/>
       <a href="#why-this-tool-exists">Why this tool exists</a><br/>
       <a href="#project-scope-and-differentiation">Project scope and differentiation</a>
@@ -81,6 +82,7 @@ It is designed to be:
 - capable of zero-runtime-network scans through a local advisory database
 
 For real-world remediation examples, see the [OWASP Juice Shop case study](docs/case-studies/owasp-juice-shop.md) and the [NestJS case study](docs/case-studies/nestjs.md).
+If you are new to verbose mode, use the [How to read verbose output guide](docs/how-to-read-verbose-output.md).
 
 ## New here? Start here
 
@@ -90,6 +92,7 @@ For real-world remediation examples, see the [OWASP Juice Shop case study](docs/
 4. check a real walkthrough:
    - [OWASP Juice Shop case study](docs/case-studies/owasp-juice-shop.md)
    - [NestJS case study](docs/case-studies/nestjs.md)
+5. use the [How to read verbose output guide](docs/how-to-read-verbose-output.md) to convert scan sections into next steps
 
 If CVE Lite CLI helps your release workflow, a GitHub star helps more developers discover it: [Star CVE Lite CLI](https://github.com/sonukapoor/cve-lite-cli).
 
@@ -268,6 +271,7 @@ The final status line also gives the scan a clear ending, which makes terminal u
 See the example below using OWASP Juice Shop for real output samples.
 
 For real-world case studies, see the [OWASP Juice Shop case study](docs/case-studies/owasp-juice-shop.md) and the [NestJS case study](docs/case-studies/nestjs.md).
+For a section-by-section walkthrough of the terminal output, see [How to read verbose output](docs/how-to-read-verbose-output.md).
 
 If you maintain an open-source JavaScript or TypeScript project and want CVE Lite CLI evaluated on it, open an issue and share the repository. Strong candidates may be turned into future public case studies.
 

docs/how-to-read-verbose-output.md

@@ -0,0 +1,94 @@
+# How to Read Verbose Output
+
+This guide explains how to read CVE Lite CLI verbose output quickly and turn it into next actions.
+
+Use this command:
+
+```bash
+npx cve-lite-cli /path/to/project --verbose --all
+```
+
+The screenshots below use a real OWASP Juice Shop scan.
+
+## 1) Start with the summary
+
+The top of verbose output tells you how much risk you are dealing with and where it sits.
+
+![Juice Shop verbose summary and top priority fixes](https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/owasp-juice-shop-1.png)
+
+What to read first:
+
+- severity totals (`critical`, `high`, `medium`, `low`)
+- direct vs transitive split in `Quick take`
+- unique advisories count
+
+What to do next:
+
+- if `critical` or `high` is non-zero, move straight to `Copy And Run These Fix Commands`
+
+## 2) Use command groups for first-pass fixes
+
+Verbose mode groups runnable commands by severity and fix type.
+
+![Juice Shop copy-and-run command groups](https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/owasp-juice-shop-2.png)
+
+How to use this section:
+
+- run critical/high command groups first
+- run direct fix groups next
+- rescan after each command group
+
+Why this helps:
+
+- you avoid manual package-by-package trial and error
+- you get package-manager-native commands ready to copy and run
+
+## 3) Read validation tables for confidence
+
+Direct fix tables include scanned/excluded counts when target validation was possible.
+
+![Juice Shop direct fix validation table](https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/owasp-juice-shop-3.png)
+
+How to interpret:
+
+- `Versions scanned`: candidate versions checked above current
+- `Still known vulnerable`: versions rejected because they remained vulnerable
+- `Recommended target`: selected upgrade target from the evaluated set
+
+What this means:
+
+- higher scanned/excluded counts usually mean the tool saved repeated install-rescan cycles
+
+## 4) Use parent-upgrade tables for transitive issues
+
+Transitive issues often require upgrading parent packages, not the vulnerable nested package directly.
+
+![Juice Shop parent-upgrade table](https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/owasp-juice-shop-4.png)
+
+How to use this section:
+
+- read `Package` and `Current` to understand what you control
+- use `Recommended target` as the next parent upgrade candidate
+- use `Context` to see which vulnerable dependency that upgrade addresses
+
+## 5) Confirm with priority list and paths
+
+The bottom sections explain remaining risk and exact dependency chains.
+
+![Juice Shop dependency path hints and remaining risk](https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/owasp-juice-shop-5.png)
+
+What to use:
+
+- `Top priority fixes`: urgency order
+- `Suggested fix plan`: staged remediation sequence
+- `Dependency paths to inspect`: parent chain verification
+
+## 10-minute workflow
+
+1. Run `--verbose --all`.
+2. Apply critical/high command groups.
+3. Apply direct command groups with validated targets.
+4. Apply parent-upgrade command groups for transitive paths.
+5. Rescan and repeat until urgent findings are reduced.
+
+This approach keeps remediation practical: start with executable commands, then handle deeper dependency decisions with path context.

docs/index.html

@@ -196,6 +196,7 @@ <h3>Real-world case studies</h3>
             <p class="link-list">
               <a href="https://github.com/sonukapoor/cve-lite-cli/blob/main/docs/case-studies/owasp-juice-shop.md">OWASP Juice Shop</a>
               <a href="https://github.com/sonukapoor/cve-lite-cli/blob/main/docs/case-studies/nestjs.md">NestJS</a>
+              <a href="https://github.com/sonukapoor/cve-lite-cli/blob/main/docs/how-to-read-verbose-output.md">How to read verbose output</a>
             </p>
           </article>
           <article class="card">