Merge pull request #218 from sonukapoor/docs/issue-214-usage-docs

docs: update site and readme for usage-aware scanning

Author: sonukapoor

README.md

@@ -10,7 +10,7 @@
   <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/logo-with-title.png" alt="CVE Lite CLI" width="320"/>
 
   <h1>CVE Lite CLI</h1>
-  <p>Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects.<br/>Practical fix guidance. Offline support. Clear direct vs transitive visibility.</p>
+  <p>Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects.<br/>Practical fix guidance. Offline support. Usage-aware reachability. Clear direct vs transitive visibility.</p>
 
   <strong>Scan. Understand. Fix.</strong>
 
@@ -60,6 +60,7 @@ It is built for the moment right before release: fast, local-first, and honest a
 **Key differentiators:**
 
 - **Copy-and-run fix commands** — turns findings into package-manager-aware `npm install`, `pnpm add`, `yarn add`, or `bun add` commands you can run immediately
+- **Usage-aware reachability scanning** — uses static analysis to detect if vulnerable packages are actually imported in your code, cutting alert fatigue with `--usage` and `--only-used`
 - **Direct vs transitive visibility** — shows whether the risk comes from something you installed directly or a nested dependency
 - **Offline advisory DB** — sync advisory data ahead of time and scan with zero runtime API calls, useful for enterprise and restricted-network environments
 - **No account required** — no sign-up, no cloud dashboard, no source code upload
@@ -72,7 +73,8 @@ It is built for the moment right before release: fast, local-first, and honest a
 | JS/TS lockfile scanning | ✅ | ✅ | ✅ | ✅ | ✅ |
 | npm + pnpm + Yarn + Bun support | ✅ | ❌ | ✅ | ✅ | ✅ |
 | No account required | ✅ | ✅ | ✅ | ❌ | ❌ |
-| **Free to use** | ✅ | ✅ | ✅ | ❌ | ❌ |
+| Free to use | ✅ | ✅ | ✅ | ❌ | ❌ |
+| Usage-aware reachability scanning | ✅ | ❌ | ❌ | ✅ | ⚠️ |
 | Direct vs transitive visibility | ✅ | ⚠️ | ✅ | ✅ | ✅ |
 | Copy-and-run fix commands | ✅ | ❌ | ❌ | ✅ | ⚠️ |
 | Suggested remediation plan | ✅ | ❌ | ⚠️ | ✅ | ⚠️ |
@@ -159,6 +161,10 @@ cve-lite /path/to/project --osv-url https://security.company.internal/osv
 cve-lite --version
 ```
 
+### Why is `--usage` an opt-in flag?
+
+CVE Lite CLI is designed to be blazing fast. Scanning a lockfile is nearly instantaneous, whereas running static reachability analysis across thousands of source files takes significantly more time. Furthermore, static analysis can occasionally produce false negatives (e.g., if a package is used in a build script or dynamically imported at runtime). Making `--usage` opt-in ensures the default lockfile scan remains instant and strictly reflects your dependency graph, while giving you the option to aggressively filter out unreachable noise when triaging findings.
+
 ## Auto-fix mode (`--fix`)
 
 `--fix` applies validated direct dependency fixes using your project's package manager, then rescans automatically.

docs/comparison.md

@@ -22,6 +22,7 @@ CVE Lite CLI is not trying to be everything for everyone. It is designed to be o
 | npm + pnpm + Yarn support | ✅ | ❌ | ✅ | ✅ | ✅ |
 | Local-first workflow | ✅ | ✅ | ✅ | ❌ | ❌ |
 | No account required | ✅ | ✅ | ✅ | ❌ | ❌ |
+| Usage-aware reachability scanning | ✅ | ❌ | ❌ | ✅ | ⚠️ |
 | Direct vs transitive visibility | ✅ | ⚠️ | ✅ | ✅ | ✅ |
 | Clear top-priority fix guidance | ✅ | ❌ | ❌ | ✅ | ⚠️ |
 | Suggested remediation plan | ✅ | ❌ | ⚠️ | ✅ | ⚠️ |

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

@@ -51,9 +51,10 @@ The suggested fix plan gives a remediation sequence so teams can execute in orde
 
 How to interpret:
 
+- `Usage`: how many source files import the vulnerable dependency (requires `--usage` flag)
 - `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
+- `Breaking?`: flagged with a `⚠` if the recommended target is a major version bump and may introduce breaking changes
 
 What this means:
 
@@ -68,8 +69,8 @@ The main findings table is your full inventory of affected packages, severity, r
 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
+- use `Usage` to quickly identify if the dependency is actually imported or just noise
+- use `Fixed` to see what the safe target version is
 
 ## 5) Confirm dependency paths and parent upgrades
 

docs/index.html

@@ -109,7 +109,7 @@
         <p class="eyebrow">JavaScript/TypeScript Dependency Scanner</p>
         <h1>Scan. Understand. Fix.</h1>
         <p>
-          CVE Lite CLI gives you a fast, local-first vulnerability scan with practical remediation commands, direct vs
+          CVE Lite CLI gives you a fast, local-first vulnerability scan with practical remediation commands, usage-aware reachability analysis, direct vs
           transitive
           clarity, and offline advisory DB support for restricted environments, so dependency fixes happen in minutes
           instead of
@@ -123,6 +123,7 @@ <h1>Scan. Understand. Fix.</h1>
         <ul class="stats">
           <li>No account required</li>
           <li>npm, pnpm, Yarn, and Bun lockfile support</li>
+          <li>Usage-aware reachability scanning</li>
           <li>Offline scans with local advisory DB</li>
           <li>Copy-and-run direct fix commands</li>
           <li>Conservative auto-remediation with `--fix`</li>
@@ -191,9 +192,13 @@ <h3>Run one-off with npx</h3>
     </section>
 
     <section class="container" id="features">
-      <h2>What Makes It Useful</h2>
-      <div class="grid three">
-        <article class="card" id="fix-mode">
+        <h2>What Makes It Useful</h2>
+        <div class="grid three">
+          <article class="card" id="reachability">
+            <h3>Usage-aware reachability</h3>
+            <p>Cut alert fatigue instantly. The `--usage` scanner statically analyzes your source code to detect if vulnerable packages are actually imported, and `--only-used` aggressively filters out the rest.</p>
+          </article>
+          <article class="card" id="fix-mode">
           <h3>Conservative `--fix` mode</h3>
           <p>Apply validated direct dependency fixes automatically, then rescan immediately with a concise before/after
             summary.</p>