docs: explain remediation target selection

Author: sonukapoor

README.md

@@ -82,6 +82,7 @@ No account. No configuration. No source code leaves your machine.
 
 - **Produces copy-and-run fix commands** — every finding comes with a package-manager-aware install command you can run immediately
 - **Distinguishes direct from transitive risk** — shows whether the vulnerability is in something you installed or buried three levels deep in a dependency chain
+- **Explains parent update paths** — for transitive npm findings, recommends `npm update <parent>` when the current parent range can resolve a known non-vulnerable child, or a parent upgrade when the range itself must change
 - **Usage-aware reachability** — optionally uses static analysis to detect whether vulnerable packages are actually imported in your code, cutting noise with `--usage` and `--only-used`
 - **Offline advisory DB** — sync advisory data ahead of time and scan with zero runtime API calls, designed for enterprise and air-gapped environments
 - **Interactive HTML report** — generate a self-contained dashboard with severity cards, a searchable findings table, and copy-ready fix commands (`--report`)
@@ -157,12 +158,15 @@ For full CI patterns including offline workflows, git hooks, and scripted automa
 | Usage-aware reachability scanning | ✅ | ❌ | ❌ | ✅ | ⚠️ |
 | Direct vs transitive visibility | ✅ | ⚠️ | ✅ | ✅ | ✅ |
 | Copy-and-run fix commands | ✅ | ❌ | ❌ | ✅ | ⚠️ |
+| Transitive parent update guidance | ✅ | ❌ | ⚠️ | ⚠️ | ⚠️ |
 | Suggested remediation plan | ✅ | ❌ | ⚠️ | ✅ | ⚠️ |
 | JSON output | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Offline/local advisory DB | ✅ | ❌ | ⚠️ | ❌ | ❌ |
 
 <sub>✅ = built-in strength · ⚠️ = partial or workflow-dependent · ❌ = not a core strength</sub>
 
+The transitive parent guidance is a key difference: CVE Lite CLI avoids recommending direct installs for packages that are only present transitively. For npm lockfiles, it can identify when `npm update <parent>` is enough to re-resolve a known non-vulnerable child within the current parent range, and when the parent package itself needs an upgrade.
+
 For detailed per-tool analysis, see [Comparison with other tools](docs/comparison.md).
 
 ## Real-world validation
@@ -288,6 +292,8 @@ npx cve-lite-cli /path/to/project --fix
 
 See the [Fix mode guide](docs/fix-mode.md) for output details and interpretation.
 
+For a deeper explanation of how the CLI chooses direct upgrades, parent upgrades, and npm `update` recommendations for transitive findings, see the [Remediation Strategy guide](docs/remediation-strategy.md).
+
 ## HTML vulnerability report (`--report`)
 
 Generate a self-contained HTML dashboard from any scan — severity cards, an interactive findings table with search, copy-ready fix commands, and breaking-change indicators on upgrades — all written to a local directory and opened automatically in your browser.
@@ -357,6 +363,8 @@ See [troubleshooting.md](docs/troubleshooting.md) for common issues: no lockfile
 
 See [parser-coverage.md](docs/parser-coverage.md) for supported lockfile formats, selection priority, the `package.json` fallback, and known edge cases including monorepos and private registries.
 
+See [remediation-strategy.md](docs/remediation-strategy.md) for how CVE Lite CLI chooses package upgrade targets and parent update paths.
+
 ## Contributing
 
 Feedback on output clarity, remediation guidance, ecosystem coverage, and CI usage is especially valuable.

docs/comparison.md

@@ -27,6 +27,7 @@ CVE Lite CLI is not trying to be everything for everyone. It is designed to be o
 | Usage-aware reachability scanning | ✅ | ❌ | ❌ | ❌ | ✅ | ⚠️ |
 | Direct vs transitive visibility | ✅ | ⚠️ | ⚠️ | ✅ | ✅ | ✅ |
 | Validated copy-and-run fix commands | ✅ | ❌ | ❌ | ❌ | ✅ | ⚠️ |
+| Transitive parent update guidance | ✅ | ❌ | ⚠️ | ⚠️ | ⚠️ | ⚠️ |
 | Fix version validation before suggesting | ✅ | ❌ | ❌ | ❌ | ⚠️ | ❌ |
 | Clear top-priority fix guidance | ✅ | ❌ | ❌ | ❌ | ✅ | ⚠️ |
 | Suggested remediation plan | ✅ | ❌ | ❌ | ⚠️ | ✅ | ⚠️ |
@@ -36,6 +37,8 @@ CVE Lite CLI is not trying to be everything for everyone. It is designed to be o
 
 <sub>✅ = built-in strength · ⚠️ = partial or workflow-dependent · ❌ = not a core strength</sub>
 
+Transitive parent update guidance is one of CVE Lite CLI's core differentiators. Instead of telling users to install a vulnerable transitive package directly, the CLI points at the parent package that controls the dependency path. For npm lockfiles, it can distinguish between `npm update <parent>` when the current parent range can absorb a known non-vulnerable child and `npm install <parent>@<version>` when the parent range itself must change.
+
 ---
 
 ## Offline support

docs/how-it-works.md

@@ -11,6 +11,7 @@ CVE Lite CLI is a **local-first, metadata-only** scanner. It operates directly w
 - [Trust boundary and privacy](#trust-boundary-and-privacy)
 - [Lockfile-driven accuracy](#lockfile-driven-accuracy)
 - [Direct vs transitive triage](#direct-vs-transitive-triage)
+- [Remediation strategy](#remediation-strategy)
 - [Performance and caching](#performance-and-caching)
 - [Offline advisory flow](#offline-advisory-flow)
 - [Standards-based output](#standards-based-output)
@@ -46,6 +47,14 @@ This separation enables a "fix the root" strategy. Instead of chasing every nest
 
 ---
 
+## Remediation strategy
+
+CVE Lite CLI turns findings into package-manager-native commands when the available metadata supports a confident path. Direct findings use validated package upgrades. Transitive findings prefer the parent package that introduced the vulnerable dependency, including npm-specific `npm update <parent>` recommendations when a known non-vulnerable child version already fits within the current parent range.
+
+See the [Remediation Strategy guide](remediation-strategy.md) for the full decision model and package-manager notes.
+
+---
+
 ## Performance and caching
 
 A local TTL cache stores advisory results. This ensures that subsequent scans — common in iterative development or CI/CD retry loops — are near-instant and respect external API rate limits.

docs/index.html

@@ -80,6 +80,7 @@
     <nav>
       <a href="#quick-start">Quick Start</a>
       <a href="#features">Features</a>
+      <a href="#parent-aware">Parent-aware fixes</a>
       <a href="#fix-mode">Fix Mode</a>
       <a href="#workflow">Workflow</a>
       <a href="#speed">Speed</a>
@@ -130,6 +131,7 @@ <h1>Scan. Understand. Fix.</h1>
           <li>Usage-aware reachability scanning</li>
           <li>Offline scans with local advisory DB</li>
           <li>Copy-and-run direct fix commands</li>
+          <li>Parent-aware transitive guidance</li>
           <li>Conservative auto-remediation with `--fix`</li>
         </ul>
         <div class="pillars">
@@ -272,6 +274,51 @@ <h3>Developer-first by default</h3>
       </div>
     </section>
 
+    <section class="container parent-aware-section" id="parent-aware">
+      <div class="spotlight-card">
+        <div>
+          <p class="eyebrow">Parent-aware remediation</p>
+          <h2>Fix the package that controls the vulnerable dependency path.</h2>
+          <p>
+            Transitive CVEs are easy to mis-handle. Installing the vulnerable child directly can change your manifest
+            without changing the dependency path that introduced it. CVE Lite CLI points at the parent instead.
+          </p>
+        </div>
+        <div class="command-compare">
+          <div>
+            <span class="compare-label muted-label">Avoid</span>
+            <pre><code>npm install vulnerable-child@fixed</code></pre>
+          </div>
+          <div>
+            <span class="compare-label">Prefer when range allows it</span>
+            <pre><code>npm update parent-package</code></pre>
+          </div>
+          <div>
+            <span class="compare-label">Or when the range must change</span>
+            <pre><code>npm install parent-package@target</code></pre>
+          </div>
+        </div>
+      </div>
+      <div class="grid three">
+        <article class="card">
+          <h3>Understands npm parent ranges</h3>
+          <p>For npm lockfiles, the CLI checks whether a known non-vulnerable child can be resolved inside the current
+            parent range before recommending a parent upgrade.</p>
+        </article>
+        <article class="card">
+          <h3>Works with workspace hoisting</h3>
+          <p>Workspace-local package context is preserved, so hoisted npm packages can still be mapped back to their
+            logical parent chain.</p>
+        </article>
+        <article class="card">
+          <h3>Documents the decision model</h3>
+          <p><a href="https://github.com/OWASP/cve-lite-cli/blob/main/docs/remediation-strategy.md">Read the
+              remediation strategy</a> to see when the CLI recommends direct upgrades, parent updates, or parent
+            upgrades.</p>
+        </article>
+      </div>
+    </section>
+
     <section class="container" id="workflow">
       <h2>Three Workflow Modes</h2>
       <div class="grid three">
@@ -326,6 +373,8 @@ <h3>Real-world case studies</h3>
             <a href="https://github.com/OWASP/cve-lite-cli/blob/main/docs/case-studies/nestjs.md">NestJS</a>
             <a href="https://github.com/OWASP/cve-lite-cli/blob/main/docs/case-studies/analog.md">Analog</a>
             <a href="https://github.com/OWASP/cve-lite-cli/blob/main/docs/fix-mode.md">Fix mode guide (--fix)</a>
+            <a href="https://github.com/OWASP/cve-lite-cli/blob/main/docs/remediation-strategy.md">Remediation
+              strategy</a>
             <a href="https://github.com/OWASP/cve-lite-cli/blob/main/docs/html-report.md">HTML report guide (--report)</a>
             <a href="https://github.com/OWASP/cve-lite-cli/blob/main/docs/how-to-read-verbose-output.md">How to
               read verbose output</a>
@@ -370,6 +419,8 @@ <h3>Guides and deep dives</h3>
             <a href="https://github.com/OWASP/cve-lite-cli/blob/main/docs/comparison.md">Comparison with other
               tools</a>
             <a href="https://github.com/OWASP/cve-lite-cli/blob/main/docs/how-it-works.md">How it works</a>
+            <a href="https://github.com/OWASP/cve-lite-cli/blob/main/docs/remediation-strategy.md">Remediation
+              strategy</a>
             <a href="https://github.com/OWASP/cve-lite-cli/blob/main/docs/roadmap.md">Roadmap</a>
           </p>
         </article>