docs: add network behavior and privacy documentation

README.md

@@ -154,6 +154,22 @@ Its role is narrower and workflow-focused:
 
 This section is here to make the scope clear. CVE Lite CLI aims to complement the broader security ecosystem by being a practical, low-friction option for JS/TS dependency checks close to release time.
 
+## Network behavior and privacy
+
+CVE Lite CLI is a local-first scanner. It parses dependency information locally, uses local caching to reduce repeated lookups, and in standard mode queries OSV for advisory data needed for matching.
+
+It does not require a hosted account, cloud dashboard, or source code upload.
+
+For the full explanation, see [Network Behavior and Privacy](./docs/network-and-privacy.md).
+
+### Planned support for stricter environments
+
+Support for stricter network-controlled environments is planned on the roadmap, including:
+
+- offline scanning mode with zero outbound calls
+- custom advisory endpoint support for internal mirrors or proxies
+- local advisory database input for controlled or air-gapped workflows
+
 ## How it works
 
 ### Architectural Philosophy

src/docs/network-and-privacy.md

@@ -0,0 +1,93 @@
+# Network Behavior and Privacy
+
+CVE Lite CLI is a local-first dependency vulnerability scanner for JavaScript and TypeScript projects. This document explains what it does locally, when it makes external calls, and how support for stricter environments is planned.
+
+## Overview
+
+CVE Lite CLI scans project dependency data on the machine where you run it. It is intended for developers and teams who want a practical vulnerability check close to release time, without adopting a larger hosted security platform.
+
+The tool does not require a hosted account or external dashboard.
+
+## What happens locally
+
+When you run CVE Lite CLI, the following work happens locally:
+
+- reading supported lockfiles  
+- extracting dependency package information  
+- classifying findings as direct or transitive  
+- prioritizing fix candidates  
+- generating CLI, JSON, or SARIF output  
+- using local cache data where available  
+
+This local-first design keeps the workflow simple and helps teams understand what the tool is doing.
+
+## External calls in standard mode
+
+In its standard mode, CVE Lite CLI queries OSV for advisory data used in vulnerability matching.
+
+This means the scanner may make outbound network requests during a scan in order to retrieve vulnerability information for the dependencies it is checking.
+
+## Current outbound destination
+
+In standard mode, CVE Lite CLI retrieves advisory data from OSV over HTTPS.
+
+Current base URL:
+- https://api.osv.dev/
+
+This is the default public advisory service used by the tool today.
+
+## What is not uploaded
+
+CVE Lite CLI is not designed as a source-code upload service.
+
+- application source code is not uploaded  
+- the tool does not require a hosted dashboard  
+- the tool does not require a user account  
+
+## Local cache behavior
+
+CVE Lite CLI uses local caching to reduce repeated advisory lookups and improve scan speed.
+
+This helps keep repeat scans fast and reduces unnecessary network activity.
+
+## Why this documentation exists
+
+Some teams, especially in enterprise, regulated, or restricted CI environments, need to understand exactly when a tool makes outbound calls.
+
+This document exists to make that behavior explicit and reviewable.
+
+## Planned support for stricter environments
+
+CVE Lite CLI is being extended to better support environments with stricter network controls.
+
+Planned capabilities include:
+
+### Offline mode
+
+A future offline mode is intended to allow scans with zero outbound network calls, using only locally available advisory data or cache content.
+
+Example target workflow:
+
+    cve-lite scan --offline
+
+### Custom advisory endpoint support
+
+A future custom endpoint option is intended to allow organizations to route advisory lookups through an internal proxy or mirrored service.
+
+Example target workflow:
+
+    cve-lite scan --osv-url https://security.company.internal/osv
+
+### Local advisory database input
+
+A future local advisory database option is intended to support controlled environments where advisory data is supplied from an approved internal source.
+
+Example target workflow:
+
+    cve-lite scan --advisory-db ./internal-advisories.json
+
+## Roadmap note
+
+These stricter execution modes are planned so teams can adopt CVE Lite CLI even when direct outbound access to public services is limited or disallowed.
+
+The goal is to preserve the same local-first developer experience while giving security-conscious organizations clearer deployment options.