Merge pull request #90 from sonukapoor/feature/issue-75-workflow-integration-guidance

[Docs] Add developer workflow integration guidance

Author: sonukapoor

README.md

@@ -530,6 +530,86 @@ cve-lite advisories sync --output ./.cache/advisories.db
 cve-lite . --offline-db ./.cache/advisories.db --json > cve-lite-report.json
 ```
 
+## Recommended workflow patterns
+
+CVE Lite CLI is most useful when teams make it part of an explicit workflow instead of relying on developers to remember a one-off command.
+
+The recommended pattern is:
+
+1. choose a scan command that matches your environment
+2. wire it into scripts, hooks, CI, or scheduled refresh jobs
+3. keep the behavior explicit so developers and security reviewers can see exactly when scans run and whether network access is involved
+
+### Package scripts
+
+Add a simple script to the consuming project so developers have a memorable command:
+
+```json
+{
+  "scripts": {
+    "security:scan": "cve-lite .",
+    "security:scan:offline": "cve-lite . --offline"
+  }
+}
+```
+
+This is the best default for most teams because it is visible, easy to document, and easy to reuse in local development and CI.
+
+### Opt-in postinstall usage
+
+Some teams want dependency scanning to run immediately after packages are installed. CVE Lite CLI supports that workflow, but it is recommended as an explicit opt-in in the consuming project rather than hidden default behavior in the tool itself.
+
+For example:
+
+```json
+{
+  "scripts": {
+    "postinstall": "cve-lite . --offline || true"
+  }
+}
+```
+
+Why this is opt-in:
+
+- install hooks should be visible to the team using them
+- controlled environments often prefer offline scanning for install-time checks
+- explicit project scripts are easier to review, tune, and disable than implicit package behavior
+
+### Git hooks
+
+For teams that want a lightweight local gate before code leaves a workstation, a git hook can be a good fit:
+
+```bash
+cve-lite . --fail-on high
+```
+
+This works well in `pre-push` or another team-approved hook if you want to catch high-severity dependency issues before changes are shared.
+
+### CI pipelines
+
+For CI, a strong baseline is:
+
+```bash
+cve-lite . --verbose --fail-on high
+```
+
+For controlled or restricted environments, sync the advisory DB separately and then scan offline:
+
+```bash
+cve-lite advisories sync --output ./.cache/advisories.db
+cve-lite . --offline-db ./.cache/advisories.db --verbose --fail-on high
+```
+
+### Scheduled advisory DB refresh
+
+If you use offline mode, keep the advisory DB fresh with a scheduler such as cron, CI, or an internal automation system:
+
+```bash
+cve-lite advisories sync --output /path/to/advisories.db
+```
+
+This keeps offline scans current without forcing every developer machine or build runner to make live advisory API calls during the scan itself.
+
 ## Comparison with other tools
 
 CVE Lite CLI is not trying to be everything for everyone. It is designed to be one of the easiest and most actionable vulnerability scanners for JavaScript and TypeScript developers who want fast release-time checks without the cost and complexity of a full security platform.

src/docs/network-and-privacy.md

@@ -1,6 +1,6 @@
 # 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.
+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 it supports stricter environments today.
 
 ## Overview
 
@@ -56,38 +56,45 @@ Some teams, especially in enterprise, regulated, or restricted CI environments,
 
 This document exists to make that behavior explicit and reviewable.
 
-## Planned support for stricter environments
+## Support for stricter environments
 
-CVE Lite CLI is being extended to better support environments with stricter network controls.
-
-Planned capabilities include:
+CVE Lite CLI already supports multiple patterns for teams with stricter network controls.
 
 ### 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.
+Offline scans can run with zero outbound advisory API calls by using a local advisory database.
+
+Example workflow:
+
+    cve-lite advisories sync
+    cve-lite . --offline
 
-Example target workflow:
+Or with an explicit DB path:
 
-    cve-lite scan --offline
+    cve-lite advisories sync --output /path/to/advisories.db
+    cve-lite . --offline-db /path/to/advisories.db
 
 ### 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.
+Organizations can route standard online advisory lookups through an internal proxy or mirrored service with `--osv-url`.
 
-Example target workflow:
+Example workflow:
 
-    cve-lite scan --osv-url https://security.company.internal/osv
+    cve-lite . --osv-url https://security.company.internal/osv
 
-### Local advisory database input
+### Advisory DB freshness
 
-A future local advisory database option is intended to support controlled environments where advisory data is supplied from an approved internal source.
+Offline scans report advisory DB freshness and warn when the local DB appears stale or is missing sync metadata.
 
-Example target workflow:
+This makes the tradeoff explicit:
 
-    cve-lite scan --advisory-db ./internal-advisories.json
+- offline scans avoid runtime advisory API calls
+- advisory data is only as current as the last successful sync
 
-## Roadmap note
+### Operational model
 
-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.
+For many teams, the recommended model is:
 
-The goal is to preserve the same local-first developer experience while giving security-conscious organizations clearer deployment options.
+- sync advisory data on a schedule from a connected environment
+- distribute the local advisory DB where needed
+- run offline scans in controlled developer, CI, or restricted-network environments