docs: document direct and transitive dependency versions

website/docs/how-remediation-works.mdx

@@ -473,6 +473,71 @@ The same package name appearing twice in your scan output is not a duplicate —
 
 ---
 
+## Direct and transitive versions of the same package
+
+The same package name can appear as both a direct dependency and a transitive dependency when different versions are installed. These are independent installs, and each installed version must be classified independently.
+
+A version is direct only when that specific installed version matches the dependency declared by the project. Another installed version with the same package name can still be transitive when it arrives through unrelated parent packages.
+
+For example, a project may declare `uuid@14.0.1` directly, while packages such as `@compodoc/live-server`, `nyc`, and `codecov` introduce a vulnerable `uuid@8.3.2` transitively:
+
+```mermaid
+flowchart TD
+    P(["Your project"])
+    P --> D["uuid@14.0.1\ndirect dependency"]
+    P --> L["@compodoc/live-server\nparent package"]
+    P --> N["nyc\nparent package"]
+    P --> C["codecov\nparent package"]
+    L --> V["uuid@8.3.2\ntransitive and vulnerable"]
+    N --> V
+    C --> V
+
+    style P fill:#1e3a5f,color:#93c5fd,stroke:#3b82f6,padding:12px
+    style D fill:#14532d,color:#86efac,stroke:#22c55e,padding:12px
+    style L fill:#1e293b,color:#cbd5e1,stroke:#475569,padding:12px
+    style N fill:#1e293b,color:#cbd5e1,stroke:#475569,padding:12px
+    style C fill:#1e293b,color:#cbd5e1,stroke:#475569,padding:12px
+    style V fill:#7f1d1d,color:#fca5a5,stroke:#ef4444,padding:12px
+```
+
+Running `npm install uuid@9.0.0` is the wrong fix in this scenario. It can install a third version of `uuid` and conflict with the already declared `uuid@14.0.1`, while the vulnerable transitive `uuid@8.3.2` may still remain in the lockfile.
+
+Because the vulnerable `uuid@8.3.2` is controlled by the parent package or dependency path that introduced it, remediation should target that parent instead of the unrelated direct `uuid@14.0.1` dependency.
+
+If the parent's declared range already allows a non-vulnerable version, refreshing the lockfile may resolve the finding. If it does not, the parent package may need to be upgraded to a version with a compatible, non-vulnerable dependency range.
+
+When multiple parent packages introduce the same vulnerable transitive version, CVE Lite CLI selects the most actionable upgrade path based on the dependency paths it resolves in your lockfile. In this example, the generated command targets `nyc` as the selected parent upgrade path.
+
+**Generated command:**
+
+<Tabs groupId="package-manager">
+  <TabItem value="npm" label="npm" default>
+    ```bash
+    npm install nyc@18.0.0
+    ```
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+    ```bash
+    pnpm add nyc@18.0.0
+    ```
+  </TabItem>
+  <TabItem value="yarn" label="yarn">
+    ```bash
+    yarn add nyc@18.0.0
+    ```
+  </TabItem>
+  <TabItem value="bun" label="bun">
+    ```bash
+    bun add nyc@18.0.0
+    ```
+  </TabItem>
+</Tabs>
+
+The generated command targets a parent package that controls the vulnerable transitive `uuid@8.3.2`, not the unrelated direct `uuid@14.0.1` dependency. The exact parent and version depend on the dependency path CVE Lite CLI can verify.
+
+---
+
+
 ## Offline mode
 
 When running with `--offline` or `--offline-db`, CVE Lite CLI cannot make registry calls. This affects transitive remediation: