Update documentation for package enrichment and vulnerability scanning features

Author: andrew

README.md

@@ -10,7 +10,9 @@ Your lockfile shows what dependencies you have, but it doesn't show how you got
 
 For best results, commit your lockfiles. Manifests show version ranges but lockfiles show what actually got installed, including transitive dependencies.
 
-It works across many ecosystems (Gemfile, package.json, Dockerfile, GitHub Actions workflows) giving you one unified history instead of separate tools per ecosystem. Everything runs locally and offline with no external services or network calls, and the database lives in your `.git` directory where you can use it in CI to catch dependency changes in pull requests.
+It works across many ecosystems (Gemfile, package.json, Dockerfile, GitHub Actions workflows) giving you one unified history instead of separate tools per ecosystem. The database lives in your `.git` directory where you can use it in CI to catch dependency changes in pull requests.
+
+The core commands (`list`, `history`, `blame`, `diff`, `stale`, etc.) work entirely from your git history with no network access. Additional commands fetch external data: `vulns` checks [OSV](https://osv.dev) for known CVEs, while `outdated` and `licenses` query [ecosyste.ms](https://packages.ecosyste.ms/) for registry metadata. See [docs/enrichment.md](docs/enrichment.md) for details on external data.
 
 ## Installation
 
@@ -256,11 +258,33 @@ This shows dependencies grouped by type (runtime, development, etc).
 git pkgs stale                  # list deps by how long since last touched
 git pkgs stale --days=365       # only show deps untouched for a year
 git pkgs stale --ecosystem=npm  # filter by ecosystem
-git pkgs outdated               # alias for stale
 ```
 
 Shows dependencies sorted by how long since they were last changed in your repo. Useful for finding packages that may have been forgotten or need review.
 
+### Find outdated dependencies
+
+```bash
+git pkgs outdated               # show packages with newer versions available
+git pkgs outdated --major       # only major version updates
+git pkgs outdated --minor       # minor and major updates (skip patch)
+git pkgs outdated --stateless   # no database needed
+```
+
+Checks package registries (via [ecosyste.ms](https://packages.ecosyste.ms/)) to find dependencies with newer versions available. Major updates are shown in red, minor in yellow, patch in cyan.
+
+### Check licenses
+
+```bash
+git pkgs licenses               # show license for each dependency
+git pkgs licenses --permissive  # flag copyleft licenses
+git pkgs licenses --allow=MIT,Apache-2.0  # explicit allow list
+git pkgs licenses --group       # group output by license
+git pkgs licenses --stateless   # no database needed
+```
+
+Fetches license information from package registries. Exits with code 1 if violations are found, making it suitable for CI. See [docs/enrichment.md](docs/enrichment.md) for all options.
+
 ### Vulnerability scanning
 
 Scan dependencies for known CVEs using the [OSV database](https://osv.dev). Because git-pkgs tracks the full history of every dependency change, it provides context that static scanners can't: who introduced a vulnerability, when it was fixed, and how long you were exposed.

docs/README.md

@@ -4,7 +4,8 @@ Technical documentation for git-pkgs maintainers and contributors.
 
 - [internals.md](internals.md) - Architecture overview, how commands work, key algorithms
 - [schema.md](schema.md) - Database tables and relationships
-- [vulns.md](vulns.md) - Vulnerability scanning commands and OSV integration
+- [vulns.md](vulns.md) - Vulnerability scanning via OSV
+- [enrichment.md](enrichment.md) - Package metadata via ecosyste.ms (outdated, licenses)
 - [benchmarking.md](benchmarking.md) - Performance profiling tools
 
 For user-facing documentation, see the main [README](../README.md).

docs/enrichment.md

@@ -1,6 +1,8 @@
 # Package Enrichment
 
-git-pkgs can fetch additional metadata about your dependencies from the [ecosyste.ms Packages API](https://packages.ecosyste.ms/). This powers the `outdated` and `licenses` commands.
+Most git-pkgs commands work entirely from your git history. Your manifests and lockfiles tell us which packages you depend on, who added them, and when. But some questions require data that isn't in your repository: what's the latest version available? what license does this package use? has a security vulnerability been disclosed?
+
+The `outdated` and `licenses` commands fetch this external metadata from the [ecosyste.ms Packages API](https://packages.ecosyste.ms/), which aggregates data from npm, RubyGems, PyPI, and other registries. See also [vulns.md](vulns.md) for vulnerability scanning via OSV.
 
 ## outdated
 

docs/internals.md

@@ -2,6 +2,8 @@
 
 git-pkgs walks a repository's commit history, parses manifest files at each commit, and stores dependency changes in a SQLite database. This lets you query what changed, when, and who did it.
 
+The tool works with two types of data. Intrinsic data comes from your git history: dependency names, versions from manifests, who added them, when, and why. Commands like `list`, `history`, `blame`, `diff`, and `stale` use only intrinsic data and require no network access. Extrinsic data comes from external sources: vulnerability info from [OSV](https://osv.dev), and registry metadata (latest versions, licenses) from [ecosyste.ms](https://packages.ecosyste.ms/). Commands like `vulns`, `outdated`, and `licenses` fetch and cache this external data.
+
 ## Entry Point
 
 The executable at [`exe/git-pkgs`](../exe/git-pkgs) loads [`lib/git/pkgs.rb`](../lib/git/pkgs.rb) and calls `Git::Pkgs::CLI.run`. The [CLI class](../lib/git/pkgs/cli.rb) parses the first argument as a command name and dispatches to the corresponding class in [`lib/git/pkgs/commands/`](../lib/git/pkgs/commands/). Each command handles its own option parsing with [OptionParser](https://docs.ruby-lang.org/en/master/OptionParser.html).

docs/vulns.md

@@ -1,6 +1,8 @@
 # Vulnerability Scanning
 
-git-pkgs can scan your dependencies for known vulnerabilities using the OSV (Open Source Vulnerabilities) database. Because git-pkgs already tracks the full history of every dependency change, it can provide context that static scanners can't: who introduced a vulnerability, when, and why.
+git-pkgs can scan your dependencies for known vulnerabilities using the [OSV](https://osv.dev) database. This is one of the commands that fetches external data (see also `outdated` and `licenses` in [enrichment.md](enrichment.md)).
+
+Because git-pkgs already tracks the full history of every dependency change, it can provide context that static scanners can't: who introduced a vulnerability, when, and why.
 
 ## Basic Usage