docs: expand npm audit comparison with concrete examples and structured sections

website/docs/comparison.md

@@ -109,15 +109,70 @@ Use CVE Lite CLI during development — before you push — to understand what i
 
 ## CVE Lite CLI vs npm audit
 
-`npm audit` is the built-in default for npm users, which makes it convenient when your workflow is entirely npm-based.
+`npm audit` is built into npm and requires no installation. For teams working entirely within the npm ecosystem, it is a convenient first line of defence. But its output model and fix guidance have real limitations that become apparent on any non-trivial project.
 
-CVE Lite CLI stands out when you want:
+### Why finding counts differ
+
+`npm audit` counts every node in a vulnerable dependency chain as a separate finding. If `react-router-dom` depends on `react-router` which depends on the vulnerable `path-to-regexp`, npm audit reports three high severity vulnerabilities. CVE Lite CLI reports one — the root cause — and tells you which parent to upgrade.
+
+In practice this means `npm audit` routinely overstates the number of issues on a project. A project with five root-cause vulnerabilities might show fifteen or twenty findings. Developers learn to discount the count, which is the opposite of what a security tool should train.
+
+### Fix suggestion quality
+
+`npm audit` suggests `npm audit fix --force` when a non-breaking fix is not available. `--force` installs whatever version resolves the dependency tree, regardless of whether it breaks your API contract or whether that version is itself still vulnerable.
+
+CVE Lite validates the suggested fix version against OSV before presenting it. You get a single, scoped command — `npm install package@X.Y.Z` — where `X.Y.Z` has been checked against the advisory database. You know what you are running before you run it.
+
+### Transitive dependency guidance
+
+`npm audit` identifies that a transitive package is vulnerable but offers limited guidance on what to actually change. The fix path — upgrade the parent that controls the version — is left to the developer to work out.
+
+CVE Lite identifies the vulnerable package, traces it to the parent that introduced it, and hands you the upgrade command for the parent. For npm lockfiles it goes one step further: if the current parent version range can already absorb a non-vulnerable child version, it suggests `npm update <parent>` instead of a full version bump.
+
+**npm audit output — transitive finding:**
+```
+path-to-regexp  0.2.0 - 1.8.0
+Severity: high
+path-to-regexp outputs backtracking regular expressions
+  react-router
+  Depends on vulnerable versions of path-to-regexp
+    react-router-dom 5.2.0
+    Depends on vulnerable versions of react-router
+
+3 high severity vulnerabilities
+To address all issues, run: npm audit fix --force
+```
+
+**CVE Lite CLI output — same project:**
+```
+HIGH     path-to-regexp@1.7.0
+         Transitive dependency
+         Fix: upgrade react-router-dom to 5.2.1
+
+> npm install react-router-dom@5.2.1
+```
+
+### Output noise
+
+`npm audit` lists every individual CVE advisory for a package as a separate line. A single package with ten known CVEs produces ten entries. CVE Lite groups all findings under the package, shows the severity that matters, and gives one fix command. The signal is the same; the noise is not.
+
+### Where npm audit has the edge
+
+- **No installation required**: Built into npm. If npm is installed, `npm audit` works with no setup.
+- **Ecosystem-native**: Understands npm's dependency graph structure natively and integrates with `npm audit fix` for simple cases.
+- **Works offline against a local registry**: In fully air-gapped npm setups with a local registry, npm audit can work without any additional tooling.
+
+### Where CVE Lite CLI goes further
+
+- **pnpm and Yarn support**: npm audit is npm-only. CVE Lite scans `pnpm-lock.yaml`, `yarn.lock`, and `bun.lock` with the same output model.
+- **Validated fix commands**: Fix versions are checked against OSV before being presented — not just whatever resolves the tree.
+- **Root-cause finding counts**: One vulnerable package = one finding, regardless of how deep the dependency chain runs.
+- **Transitive parent guidance**: Tells you which parent to upgrade and gives you the exact command, not just which transitive package is affected.
+- **Offline advisory DB**: Sync once, scan indefinitely with no outbound calls — not limited to npm's own registry connectivity.
+
+### Recommended approach
 
-- support across npm, pnpm, Yarn, and Bun lockfiles in a single tool
-- cleaner, more guided console output with a priority-first view
-- validated copy-and-run fix commands and a suggested remediation plan
-- parent-aware transitive remediation — not just a list of vulnerable packages
-- a focused pre-release scanning experience for JS/TS teams, maintained as an OWASP project
+If your project is npm-only and the findings are simple direct dependencies, `npm audit fix` handles the common case well. Reach for CVE Lite CLI when you want to understand the real scope of what needs fixing, when you are working with pnpm or Yarn, when you need validated fix commands before touching a production dependency, or when transitive findings make the npm audit output hard to act on.
 
 ---