Merge docs/polish into main (mdBook + examples + README refresh)

Author: Metbcy

.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping in-flight runs but always
+# letting the most recent push reach production. Manually-dispatched runs
+# fall outside the cancel-in-progress to support targeted re-deploys.
+concurrency:
+  group: docs-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: docs-mdbook
+          shared-key: docs
+
+      - name: Install mdBook
+        shell: bash
+        run: |
+          # Pin to a specific minor version for build reproducibility.
+          # Bump deliberately (and review the rendered diff) when upstream
+          # ships a meaningful new feature.
+          cargo install --locked --version 0.5.2 mdbook
+
+      - name: Build the book
+        shell: bash
+        run: mdbook build docs
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/book
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -6,3 +6,6 @@
 .DS_Store
 .vscode/
 .idea/
+
+# mdBook output (regenerated by .github/workflows/docs.yml on push to main)
+/docs/book

Cargo.toml

@@ -6,7 +6,7 @@ rust-version = "1.85"
 description = "SBOM diff with supply-chain risk signals (CVEs, typosquats, maintainer-age)."
 license = "Apache-2.0"
 repository = "https://github.com/Metbcy/bomdrift"
-homepage = "https://github.com/Metbcy/bomdrift"
+homepage = "https://metbcy.github.io/bomdrift/"
 readme = "README.md"
 keywords = ["sbom", "security", "supply-chain", "cyclonedx", "spdx"]
 categories = ["command-line-utilities", "development-tools"]

README.md

@@ -3,8 +3,12 @@
 > SBOM diff with supply-chain risk signals — flags **new CVEs**, **typosquats**, **multi-major version jumps**, and **young maintainers** on added or upgraded dependencies, surfaced as a GitHub PR comment.
 
 [![CI](https://github.com/Metbcy/bomdrift/actions/workflows/ci.yml/badge.svg)](https://github.com/Metbcy/bomdrift/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/Metbcy/bomdrift?sort=semver&display_name=tag)](https://github.com/Metbcy/bomdrift/releases/latest)
+[![Docs](https://img.shields.io/badge/docs-mdbook-blue)](https://metbcy.github.io/bomdrift/)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
 
+**Quick links:** [Why?](#why) · [Install](#install) · [Usage](#usage) · [Example output](#example-output) · [Features](#features) · [Release signing](#release-signing) · [Docs site](https://metbcy.github.io/bomdrift/) · [Examples](./examples/)
+
 ## Why?
 
 The most actionable supply-chain question on a pull request is:
@@ -46,23 +50,29 @@ jobs:
         with:
           before-sbom: before.json
           after-sbom:  after.json
+          fail-on:     critical-cve   # optional: exit 2 on HIGH/CRITICAL advisories
 ```
 
+The `@v1` mutable tag tracks the latest v0.x release; pin to a specific version (`@v0.3.0`) if you prefer reproducible builds. See the [Action reference](https://metbcy.github.io/bomdrift/github-action.html) for every input.
+
 ### As a binary (local / CI)
 
-Download a signed release archive for your platform from the [Releases page](https://github.com/Metbcy/bomdrift/releases/latest) and verify it with cosign — see [Release signing](#release-signing) below.
+Download a signed release archive for your platform from the [Releases page](https://github.com/Metbcy/bomdrift/releases/latest) and verify it with cosign — see [Release signing](#release-signing) below. Pre-built binaries cover **Linux x86_64 + aarch64**, **macOS aarch64**, and **Windows x86_64**.
 
 ```bash
-# Linux x86_64 example
-curl -sSL -o bomdrift.tar.gz https://github.com/Metbcy/bomdrift/releases/latest/download/bomdrift-v0.1.0-x86_64-unknown-linux-gnu.tar.gz
+# Linux x86_64 example (replace VERSION/TARGET as needed)
+VERSION=v0.3.0
+TARGET=x86_64-unknown-linux-gnu
+curl -sSL -o bomdrift.tar.gz \
+  "https://github.com/Metbcy/bomdrift/releases/download/${VERSION}/bomdrift-${VERSION}-${TARGET}.tar.gz"
 tar -xzf bomdrift.tar.gz
-./bomdrift-v0.1.0-x86_64-unknown-linux-gnu/bomdrift --version
+./bomdrift-${VERSION}-${TARGET}/bomdrift --version
 ```
 
 ### From source
 
 ```bash
-cargo install --locked --git https://github.com/Metbcy/bomdrift --tag v0.1.0 bomdrift
+cargo install --locked --git https://github.com/Metbcy/bomdrift --tag v0.3.0 bomdrift
 ```
 
 ## Usage
@@ -74,40 +84,98 @@ bomdrift diff before.json after.json
 # Offline mode (no OSV / no GitHub-API maintainer-age lookups)
 bomdrift diff before.json after.json --no-osv --no-maintainer-age
 
-# Machine-readable JSON for downstream tooling
+# Machine-readable formats for downstream tooling
 bomdrift diff before.json after.json --output json
+bomdrift diff before.json after.json --output sarif
+
+# Exit 2 on findings (the action wraps this for PR-comment workflows)
+bomdrift diff before.json after.json --fail-on critical-cve
 
-# Refresh the bundled npm popular-package list (used by the typosquat enricher)
-bomdrift refresh-typosquat --ecosystem npm
+# Suppress findings already present in a baseline snapshot
+bomdrift diff before.json after.json --baseline previous-diff.json
+
+# Refresh the bundled popular-package lists (used by the typosquat enricher)
+bomdrift refresh-typosquat                     # all ecosystems
+bomdrift refresh-typosquat --ecosystem pypi    # one specific list
 ```
 
-`bomdrift diff` exits 0 on success regardless of findings. It emits Markdown by default when stdout is piped/redirected (the PR-comment path), and ANSI-colored terminal output when stdout is a TTY. `--output markdown|json|terminal` overrides detection.
+`bomdrift diff` exits 0 on success regardless of findings unless `--fail-on` is set — then it exits 2 when the threshold trips. Stdout is Markdown by default when piped/redirected (the PR-comment path) and ANSI-colored when stdout is a TTY. `--output markdown|json|terminal|sarif` overrides detection.
+
+See the [`examples/`](./examples/) directory for end-to-end scenarios (axios incident, multi-ecosystem typosquats, version jumps, baseline suppression).
+
+## Example output
+
+Running `bomdrift diff` against the bundled axios-incident fixture pair (`tests/fixtures/cdx-minimal.json` → `tests/fixtures/cdx-after.json`) produces:
+
+```markdown
+## SBOM diff
+
+| Change | Count |
+|---|---:|
+| Added | 1 |
+| Removed | 1 |
+| Version changed | 1 |
+| License changed | 0 |
+| Possible typosquats | 1 |
+
+### Added
+| Ecosystem | Name | Version |
+|---|---|---|
+| npm | plain-crypto-js | 4.2.1 |
+
+### Version changed
+| Ecosystem | Name | Before | After |
+|---|---|---|---|
+| npm | axios | 1.14.0 | 1.14.1 |
+
+### Possible typosquats
+| Ecosystem | Name | Version | Similar to | Similarity |
+|---|---|---|---|---:|
+| npm | plain-crypto-js | 4.2.1 | crypto-js | 0.95 |
+```
+
+With network access, the **Vulnerabilities** section additionally lists each advisory ID (CVE / GHSA / MAL) per affected component, alongside its OSV.dev-sourced severity.
 
 ## Features
 
 - Diff **CycloneDX 1.5/1.6**, **SPDX 2.3**, and **Syft** JSON SBOMs against each other (any combination), via a unified component model.
-- For added & upgraded packages, enrich with **OSV.dev CVE data** through the `/v1/querybatch` endpoint.
-- Flag possible **typosquats** via Jaro-Winkler similarity to top-1000 npm packages, with a suffix-containment boost rule that catches the `plain-crypto-js` → `crypto-js` pattern that pure JW alone misses.
+- For added & upgraded packages, enrich with **OSV.dev CVE data** through `/v1/querybatch`, then a per-advisory `/v1/vulns/{id}` follow-up to populate **severity** (Critical / High / Medium / Low).
+- 24h on-disk **OSV severity cache** (`<XDG_CACHE_HOME>/bomdrift/osv/`) so reruns within a working day don't re-fetch — opt out with `--no-osv-cache`.
+- Flag possible **typosquats** across **npm**, **PyPI**, **Cargo**, and **Maven** via Jaro-Winkler similarity (Levenshtein for Maven artifactIds), with a suffix-containment boost rule that catches the `plain-crypto-js` → `crypto-js` pattern that pure JW alone misses. Refreshable from each ecosystem's canonical upstream via `bomdrift refresh-typosquat`.
 - Flag deps whose **top GitHub maintainer joined the project recently** (the xz-style takeover signal). Honors `GITHUB_TOKEN`, rate-limit-aware, skipped when the repo has > 50 contributors.
 - Flag **multi-major version jumps** (≥ 2 majors) in a single diff — often correlates with takeover swaps and namespace reuse.
-- Output formats: terminal (colored, TTY-aware), Markdown (PR comment), JSON. SARIF planned for v0.2.
-- Ships as a single Rust binary **and** a composite GitHub Action — no Docker.
-- Releases are signed with [cosign keyless](https://docs.sigstore.dev/) — eat-your-own-supply-chain-dogfood.
+- **Output formats**: terminal (colored, TTY-aware), Markdown (PR comment), **JSON**, and **SARIF v2.1.0** for GitHub Code Scanning ingestion.
+- **`--fail-on`** thresholds (`cve` / `critical-cve` / `typosquat` / `any`) exit code 2 on trip while still emitting the comment body, so the PR comment posts even when the workflow step fails.
+- **`--baseline <path.json>`** suppresses findings already captured in a previously stored `bomdrift diff --output json` snapshot — adopt bomdrift on a project with pre-existing findings without drowning the first PR.
+- **`--summary-only`** + automatic comment-size fallback (default 60 KB) keeps big SBOM diffs under GitHub's 65,536-char comment-body cap.
+- Ships as a **single Rust binary** (~3.4 MB, stripped + LTO) **and** a composite GitHub Action — no Docker.
+- Releases are **cosign-signed** keyless via Sigstore + GitHub OIDC — eat-your-own-supply-chain-dogfood.
 
 ## Release signing
 
 Every release archive is signed with cosign keyless via Sigstore (GitHub OIDC).
 
 ```bash
+# Replace VERSION + TARGET with your downloaded archive's pair
+VERSION=v0.3.0
+TARGET=x86_64-unknown-linux-gnu
+ARCHIVE=bomdrift-${VERSION}-${TARGET}.tar.gz
+
 cosign verify-blob \
-  --certificate-identity 'https://github.com/Metbcy/bomdrift/.github/workflows/release.yml@refs/tags/v0.1.0' \
+  --certificate-identity "https://github.com/Metbcy/bomdrift/.github/workflows/release.yml@refs/tags/${VERSION}" \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com \
-  --certificate bomdrift-v0.1.0-x86_64-unknown-linux-gnu.tar.gz.pem \
-  --signature  bomdrift-v0.1.0-x86_64-unknown-linux-gnu.tar.gz.sig \
-  bomdrift-v0.1.0-x86_64-unknown-linux-gnu.tar.gz
+  --certificate "${ARCHIVE}.pem" \
+  --signature  "${ARCHIVE}.sig" \
+  "${ARCHIVE}"
 ```
 
-The Action verifies signatures automatically when cosign is available on the runner.
+The Action verifies signatures automatically by default. Set `verify-signatures: false` on trusted mirrors to skip the cosign install step (~15s saved per run).
+
+## Documentation
+
+- **[Docs site (mdBook)](https://metbcy.github.io/bomdrift/)** — full reference: CLI flags, every action input, output-format anatomy, per-enricher deep dives, architecture notes, roadmap.
+- **[`examples/`](./examples/)** — runnable scenarios with synthetic SBOM pairs.
+- **[CHANGELOG](./CHANGELOG.md)** — release notes per version, including breaking-change migration notes.
 
 ## Non-goals
 

docs/book.toml

@@ -0,0 +1,28 @@
+[book]
+title = "bomdrift"
+description = "SBOM diff with supply-chain risk signals"
+authors = ["Amir B."]
+language = "en"
+src = "src"
+
+[output.html]
+default-theme = "rust"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/Metbcy/bomdrift"
+edit-url-template = "https://github.com/Metbcy/bomdrift/edit/main/docs/{path}"
+site-url = "/bomdrift/"
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.search]
+enable = true
+limit-results = 30
+teaser-word-count = 30
+use-boolean-and = true
+boost-title = 2
+boost-hierarchy = 1
+boost-paragraph = 1
+expand = true
+heading-split-level = 3

docs/src/SUMMARY.md

@@ -0,0 +1,32 @@
+# Summary
+
+[Introduction](./introduction.md)
+
+# Getting started
+
+- [Quickstart](./quickstart.md)
+- [GitHub Action](./github-action.md)
+- [CLI reference](./cli-reference.md)
+
+# Output
+
+- [Output formats](./output-formats.md)
+- [Baseline & suppression](./baseline.md)
+
+# Enrichers
+
+- [Overview](./enrichers/overview.md)
+- [OSV.dev CVE lookup](./enrichers/osv-cve.md)
+- [Typosquat detection](./enrichers/typosquat.md)
+- [Multi-major version jumps](./enrichers/version-jump.md)
+- [Maintainer age signal](./enrichers/maintainer-age.md)
+
+# Operations
+
+- [Release signing](./release-signing.md)
+- [Architecture](./architecture.md)
+
+# Project
+
+- [Roadmap](./roadmap.md)
+- [Contributing](./contributing.md)