diff --git a/skills/corgea/SKILL.md b/skills/corgea/SKILL.md
index 9925150..07a7977 100644
--- a/skills/corgea/SKILL.md
+++ b/skills/corgea/SKILL.md
@@ -131,6 +131,52 @@ Agent environments default to compact TSV; force output with `--format human|age
 Notes: `deps scan --out-format table|json|sarif` is the report/export selector; do not combine it with `deps scan --format`.
 <!-- END GENERATED CORGEA DEPS SKILL -->
 
+### Advisories — `corgea advisories check`
+
+Query Corgea's vulnerability database for a package **before** choosing or
+installing it. Read-only: it reports, never blocks. Network access to the
+vuln-api is required. The package-level form needs no token; the versioned
+form uses the same auth story as the install gate (a Corgea token is
+attached automatically when logged in on the default vuln-api, and the
+production version-check route may require one — a tokenless 401 exits 2
+with a clear message).
+
+**Before adding or choosing a dependency version, run
+`corgea advisories check <ecosystem> <package>` to see its advisory history,
+then `corgea advisories check <ecosystem> <package>@<version>` once you have
+a candidate version. Pick the safe version the output steers to. The install
+gate (`corgea npm|pip|...`) remains the backstop.**
+
+```bash
+corgea advisories check npm axios            # axios's advisory history (up to 100 most recent)
+corgea advisories check npm axios@1.0.0      # verdict for one exact version
+corgea advisories check pypi requests@2.31.0 # pypi (pip is accepted as an alias)
+corgea advisories check pypi requests==2.31.0  # pip-style separator also accepted; extras ([security]) are ignored
+corgea advisories check npm axios@1.0.0 --json  # stable machine-readable document
+```
+
+| Exit code | Meaning |
+|-----------|---------|
+| 0 | Clean: no advisories for the version, no advisories for the package, or package unknown to the database |
+| 1 | Advisories found (versioned: vulnerable; unversioned: at least one advisory linked) |
+| 2 | Error: network, auth, parse, or bad arguments |
+
+Versions must be exact (`1.2.3`, not `^1.2`). The versioned form gives the
+same verdict the install gate enforces — advisory IDs, severities,
+`fixed in <version>` notes, and a `→ safe version:` steer when every
+advisory has a fix. The unversioned form lists the package's advisory
+history (id, severity, cvss, tier, kev/malware markers) so you can pick a
+version with a clean record; it has no fix data, so follow up with the
+versioned form. `--json` emits one `schema_version: 1` document on stdout
+(`verdict` object for the versioned form — same vocabulary as the install
+gate's `--json`; `found` + `advisories[]` + `possibly_truncated` for the
+unversioned form — the listing caps at 100 advisories and
+`possibly_truncated: true` means more may exist). Errors after arguments
+parse (network, auth, unknown package spec, bad version) emit
+`{"schema_version":1,"error":...}` on stdout and exit 2; malformed
+command-line usage (missing arguments, unknown flags) gets the CLI's
+standard usage text on stderr instead, also exit 2.
+
 ### Install Wrappers — `corgea pip|npm|yarn|pnpm|uv <args...>`
 
 Run a package manager through Corgea's install gate. Install commands with
diff --git a/src/advisories.rs b/src/advisories.rs
new file mode 100644
index 0000000..2e90fa4
--- /dev/null
+++ b/src/advisories.rs
@@ -0,0 +1,518 @@
+//! `corgea advisories` — read-only pre-decision queries against the vuln-api.
+//!
+//! Reports, never refuses: the install-wrap gate (`corgea npm|pip|...`)
+//! remains the enforcement backstop. Exit codes: 0 clean / no advisories,
+//! 1 advisories found, 2 error (network, auth, parse, guard, bad args).
+
+use clap::Subcommand;
+
+/// Advisories JSON schema version — independent of precheck's
+/// render::SCHEMA_VERSION so the two document families evolve separately.
+const SCHEMA_VERSION: u32 = 1;
+
+#[derive(Subcommand, Debug, Clone)]
+pub enum AdvisoriesSubcommand {
+    /// Query known advisories for a package, optionally for one exact version
+    Check {
+        /// Registry ecosystem: npm or pypi (pip is accepted as an alias)
+        ecosystem: String,
+        /// Package spec: <package> or <package>@<version> (exact versions only)
+        spec: String,
+        /// Emit a stable machine-readable JSON document instead of text
+        #[arg(long)]
+        json: bool,
+    },
+}
+
+/// Connection options resolved by the binary crate (base URL + optional
+/// token) — the same base-URL/token-isolation selection the install wrap
+/// uses. `token: None` is public mode; the command must work tokenless.
+pub struct AdvisoriesOptions {
+    pub base_url: String,
+    pub token: Option<String>,
+}
+
+pub fn run(cmd: AdvisoriesSubcommand, opts: AdvisoriesOptions) -> i32 {
+    let AdvisoriesSubcommand::Check {
+        ecosystem,
+        spec,
+        json,
+    } = cmd;
+    match run_check(&ecosystem, &spec, json, &opts) {
+        Ok(code) => code,
+        Err(e) => {
+            report_error(&e.to_string(), json);
+            2
+        }
+    }
+}
+
+/// Report a failure. In json mode the error document goes to stdout
+/// (mirroring precheck's pre-report error documents); otherwise human text
+/// goes to stderr. Exit code stays 2 either way. Scope: only post-clap
+/// failures reach here — clap-level usage errors abort before `run` sees
+/// `--json` and keep clap's own stderr text.
+fn report_error(message: &str, json: bool) {
+    if json {
+        let doc = serde_json::json!({ "schema_version": SCHEMA_VERSION, "error": message });
+        println!("{}", serde_json::to_string_pretty(&doc).unwrap());
+    } else {
+        eprintln!("error: {message}");
+    }
+}
+
+fn run_check(
+    ecosystem: &str,
+    spec: &str,
+    json: bool,
+    opts: &AdvisoriesOptions,
+) -> Result<i32, Box<dyn std::error::Error>> {
+    let ecosystem = parse_ecosystem(ecosystem)?;
+    let (name, version) = parse_package_spec(ecosystem, spec)?;
+    let client = crate::vuln_api::http_client()?;
+    match version {
+        Some(version) => {
+            let resp = crate::vuln_api::check_package_version(
+                &client,
+                &opts.base_url,
+                opts.token.as_deref(),
+                ecosystem,
+                &name,
+                &version,
+            )?;
+            Ok(render_version_verdict(
+                ecosystem, &name, &version, &resp, json,
+            ))
+        }
+        None => {
+            let profile = crate::vuln_api::fetch_package_profile(
+                &client,
+                &opts.base_url,
+                opts.token.as_deref(),
+                ecosystem,
+                &name,
+            )?;
+            Ok(render_profile(ecosystem, &name, profile.as_ref(), json))
+        }
+    }
+}
+
+/// npm|pypi, case-insensitive; `pip` accepted as an alias for pypi.
+fn parse_ecosystem(raw: &str) -> Result<crate::vuln_api::Ecosystem, String> {
+    match raw.trim().to_ascii_lowercase().as_str() {
+        "npm" => Ok(crate::vuln_api::Ecosystem::Npm),
+        "pypi" | "pip" => Ok(crate::vuln_api::Ecosystem::Pypi),
+        other => Err(format!("unknown ecosystem '{other}' (expected: npm, pypi)")),
+    }
+}
+
+/// Split `<package>[@<version>]` on the LAST `@` at index > 0, so scoped
+/// npm names survive: `@scope/pkg@1.2.3` → ("@scope/pkg", Some("1.2.3")),
+/// `@scope/pkg` → ("@scope/pkg", None). For pypi the pip-native spelling is
+/// also accepted: `requests==2.31.0` splits at the leftmost `==` (`===`,
+/// PEP 440 arbitrary equality, reads as exact too) and extras are stripped
+/// (`requests[security]` → `requests`) — they select install features, not
+/// the registry name. Bare `@`, trailing separators, and empty specs are
+/// usage errors. Versions must be exact — range syntax, tags, and (npm)
+/// partial versions are rejected.
+fn parse_package_spec(
+    ecosystem: crate::vuln_api::Ecosystem,
+    spec: &str,
+) -> Result<(String, Option<String>), String> {
+    let spec = spec.trim();
+    if spec.is_empty() {
+        return Err("package spec is empty".to_string());
+    }
+    let is_pypi = ecosystem == crate::vuln_api::Ecosystem::Pypi;
+    let (name, version, sep) = match spec.split_once("==") {
+        Some((n, v)) if is_pypi => (n, Some(v.strip_prefix('=').unwrap_or(v)), "=="),
+        _ => match spec.rfind('@') {
+            Some(0) | None => (spec, None, "@"),
+            Some(pos) => (&spec[..pos], Some(&spec[pos + 1..]), "@"),
+        },
+    };
+    let name = if is_pypi {
+        name.split_once('[').map_or(name, |(n, _)| n)
+    } else {
+        name
+    };
+    // PEP 508 allows spaces around the operator (`requests == 2.31.0`), so
+    // trim each half after splitting.
+    let name = name.trim();
+    if name.is_empty() || name == "@" {
+        return Err(format!("invalid package spec '{spec}'"));
+    }
+    match version.map(str::trim) {
+        None => Ok((name.to_string(), None)),
+        Some("") => Err(format!(
+            "invalid package spec '{spec}': trailing '{sep}' (write <package> or <package>{sep}<version>)"
+        )),
+        Some(v) => {
+            require_exact_version(ecosystem, v)?;
+            Ok((name.to_string(), Some(v.to_string())))
+        }
+    }
+}
+
+/// Reject anything that isn't a single exact version literal, per
+/// ecosystem's own rules:
+///
+/// * npm — strict semver parse. This is what "exact" means to npm, and it
+///   rejects ranges, dist-tags (`latest`), and partial versions in one
+///   check: npm itself treats `1.2` as the x-range `1.2.x`
+///   (see `verify_deps::registry::parse_version_or_x_range`), so a partial
+///   is NOT an exact version there.
+/// * pypi — PEP 440 versions are too varied for a strict parse (epochs
+///   `2!1.0`, `1.0rc1`, `.post1`, `.dev2`, and `1.2` IS exact), so gate on
+///   range syntax instead: operator prefixes, whitespace joins, specifier
+///   sets, and wildcards. Unrecognized literals pass through and the
+///   server answers for that exact string.
+fn require_exact_version(ecosystem: crate::vuln_api::Ecosystem, v: &str) -> Result<(), String> {
+    let exact_err = |detail: &str| {
+        Err(format!(
+            "version '{v}' is not an exact version ({detail}; pass one exact version)"
+        ))
+    };
+    match ecosystem {
+        crate::vuln_api::Ecosystem::Npm => {
+            if semver::Version::parse(v).is_ok() {
+                Ok(())
+            } else {
+                exact_err(
+                    "npm versions must be full semver like 1.2.3 — no ranges, tags, or partials",
+                )
+            }
+        }
+        crate::vuln_api::Ecosystem::Pypi => {
+            // Range operators and joins: PEP 440 prefixes (== != >= <= > < ~=),
+            // whitespace, "," specifier sets, "||"; wildcard components.
+            if v.starts_with(['^', '~', '>', '<', '=', '!'])
+                || v.chars().any(char::is_whitespace)
+                || v.contains("||")
+                || v.contains(',')
+                || v == "*"
+                || v.split('.')
+                    .any(|p| p == "*" || p.eq_ignore_ascii_case("x"))
+            {
+                exact_err("ranges are not supported")
+            } else {
+                Ok(())
+            }
+        }
+    }
+}
+
+/// Render the versioned-form verdict (text or `--json`) and return the exit
+/// code. `ecosystem` is used only by the json document.
+fn render_version_verdict(
+    ecosystem: crate::vuln_api::Ecosystem,
+    name: &str,
+    version: &str,
+    resp: &crate::vuln_api::VulnCheckResponse,
+    json: bool,
+) -> i32 {
+    if json {
+        let doc = version_verdict_json(ecosystem, name, version, resp);
+        println!("{}", serde_json::to_string_pretty(&doc).unwrap());
+        return if resp.is_vulnerable { 1 } else { 0 };
+    }
+    if resp.is_vulnerable {
+        println!(
+            "{name}@{version}: vulnerable ({} advisories)",
+            resp.matches.len()
+        );
+        for m in &resp.matches {
+            println!("  {} ({}){}", m.advisory_id, m.severity_level, fix_note(m));
+        }
+        if let Some(safe) = crate::vuln_api::safe_version(&resp.matches) {
+            println!("  → safe version: {name}@{safe}");
+        }
+        1
+    } else {
+        println!("{name}@{version}: clean — no known advisories");
+        0
+    }
+}
+
+/// CLI-owned, schema-versioned document for the versioned form. The
+/// `verdict` object reuses the gate's `verdict_json` vocabulary
+/// (`status`/`matches`/`remediation`) so both document families read alike.
+fn version_verdict_json(
+    ecosystem: crate::vuln_api::Ecosystem,
+    name: &str,
+    version: &str,
+    resp: &crate::vuln_api::VulnCheckResponse,
+) -> serde_json::Value {
+    let verdict = if resp.is_vulnerable {
+        serde_json::json!({
+            "status": "vulnerable",
+            "matches": resp.matches,
+            "remediation": crate::vuln_api::safe_version(&resp.matches),
+        })
+    } else {
+        serde_json::json!({ "status": "clean" })
+    };
+    serde_json::json!({
+        "schema_version": SCHEMA_VERSION,
+        "ecosystem": ecosystem.path_segment(),
+        "package": name,
+        "version": version,
+        "verdict": verdict,
+    })
+}
+
+/// Same wording as the gate's fix suffix (precheck/render.rs::fix_note),
+/// kept local: one format string, not worth a cross-module export.
+fn fix_note(m: &crate::vuln_api::VulnMatch) -> String {
+    match &m.fixed_version {
+        Some(v) => format!(" — fixed in {v}"),
+        None => " — no fixed version known".to_string(),
+    }
+}
+
+/// The route's `LIMIT 100`: exactly 100 rows means "possibly more exist",
+/// never provably truncated (the route serves no total).
+const PROFILE_LISTING_CAP: usize = 100;
+
+/// Truncate `s` to `max` chars (char-boundary safe, ellipsis when cut).
+fn truncate_summary(s: &str, max: usize) -> String {
+    match s.char_indices().nth(max) {
+        Some((idx, _)) => format!("{}…", &s[..idx]),
+        None => s.to_string(),
+    }
+}
+
+/// Render the unversioned (package profile) form and return the exit code.
+/// `None` = the route answered 404 (package unknown to the database).
+fn render_profile(
+    ecosystem: crate::vuln_api::Ecosystem,
+    name: &str,
+    profile: Option<&crate::vuln_api::PackageProfile>,
+    json: bool,
+) -> i32 {
+    let advisories: &[crate::vuln_api::AdvisorySummary] =
+        profile.map(|p| p.advisories.as_slice()).unwrap_or(&[]);
+    let found = profile.is_some();
+
+    if json {
+        let doc = serde_json::json!({
+            "schema_version": SCHEMA_VERSION,
+            "ecosystem": ecosystem.path_segment(),
+            "package": name,
+            "found": found,
+            "advisories": advisories,
+            "possibly_truncated": advisories.len() == PROFILE_LISTING_CAP,
+        });
+        println!("{}", serde_json::to_string_pretty(&doc).unwrap());
+        return if advisories.is_empty() { 0 } else { 1 };
+    }
+
+    if advisories.is_empty() {
+        if found {
+            println!("{name}: no known advisories");
+        } else {
+            println!("{name}: not found in the advisory database (no known advisories)");
+        }
+        return 0;
+    }
+
+    let cap_note = if advisories.len() == PROFILE_LISTING_CAP {
+        format!(" (listing capped at {PROFILE_LISTING_CAP}; more may exist)")
+    } else {
+        String::new()
+    };
+    println!("{name}: {} known advisories{cap_note}", advisories.len());
+    for a in advisories {
+        println!("  {}{}", a.id, advisory_detail(a));
+        if let Some(summary) = &a.summary {
+            let summary = summary.trim();
+            if !summary.is_empty() {
+                println!("    {}", truncate_summary(summary, 100));
+            }
+        }
+    }
+    println!(
+        "note: package-level listing; run `corgea advisories check {} {name}@<version>` for a version verdict.",
+        ecosystem.path_segment()
+    );
+    1
+}
+
+/// The parenthesized detail group plus flag markers for one advisory line:
+/// `(high, cvss 7.5, tier 1) [kev] [malware] published 2023-01-12`. Each
+/// element is included only when present.
+fn advisory_detail(a: &crate::vuln_api::AdvisorySummary) -> String {
+    let mut group: Vec<String> = Vec::new();
+    if let Some(sev) = &a.severity {
+        group.push(sev.clone());
+    }
+    if let Some(cvss) = a.cvss_score {
+        group.push(format!("cvss {cvss}"));
+    }
+    if let Some(tier) = a.tier {
+        group.push(format!("tier {tier}"));
+    }
+    let mut out = String::new();
+    if !group.is_empty() {
+        out.push_str(&format!(" ({})", group.join(", ")));
+    }
+    if a.kev == Some(true) {
+        out.push_str(" [kev]");
+    }
+    if a.malware == Some(true) {
+        out.push_str(" [malware]");
+    }
+    if let Some(published) = &a.published_at {
+        out.push_str(&format!(" published {published}"));
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::vuln_api::Ecosystem;
+
+    #[test]
+    fn parse_ecosystem_accepts_known_values() {
+        assert_eq!(parse_ecosystem("npm"), Ok(Ecosystem::Npm));
+        assert_eq!(parse_ecosystem("NPM"), Ok(Ecosystem::Npm));
+        assert_eq!(parse_ecosystem("pypi"), Ok(Ecosystem::Pypi));
+        assert_eq!(parse_ecosystem("PyPI"), Ok(Ecosystem::Pypi));
+        assert_eq!(parse_ecosystem("pip"), Ok(Ecosystem::Pypi));
+    }
+
+    #[test]
+    fn parse_ecosystem_rejects_unknown() {
+        let err = parse_ecosystem("rubygems").expect_err("unknown ecosystem must error");
+        assert!(err.contains("npm"), "err lists valid values: {err}");
+        assert!(err.contains("pypi"), "err lists valid values: {err}");
+    }
+
+    #[test]
+    fn parse_spec_unscoped_with_and_without_version() {
+        assert_eq!(
+            parse_package_spec(Ecosystem::Npm, "leftpad"),
+            Ok(("leftpad".to_string(), None))
+        );
+        assert_eq!(
+            parse_package_spec(Ecosystem::Npm, "leftpad@1.0.0"),
+            Ok(("leftpad".to_string(), Some("1.0.0".to_string())))
+        );
+    }
+
+    #[test]
+    fn parse_spec_scoped_with_and_without_version() {
+        assert_eq!(
+            parse_package_spec(Ecosystem::Npm, "@scope/pkg"),
+            Ok(("@scope/pkg".to_string(), None))
+        );
+        assert_eq!(
+            parse_package_spec(Ecosystem::Npm, "@scope/pkg@1.2.3"),
+            Ok(("@scope/pkg".to_string(), Some("1.2.3".to_string())))
+        );
+    }
+
+    #[test]
+    fn parse_spec_pypi_accepts_pip_style_separators() {
+        for spec in [
+            "requests==2.31.0",
+            "requests===2.31.0",
+            "requests == 2.31.0",
+        ] {
+            assert_eq!(
+                parse_package_spec(Ecosystem::Pypi, spec),
+                Ok(("requests".to_string(), Some("2.31.0".to_string()))),
+                "spec: {spec:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn parse_spec_pypi_strips_extras() {
+        assert_eq!(
+            parse_package_spec(Ecosystem::Pypi, "requests[security]"),
+            Ok(("requests".to_string(), None))
+        );
+        assert_eq!(
+            parse_package_spec(Ecosystem::Pypi, "requests[security]==2.31.0"),
+            Ok(("requests".to_string(), Some("2.31.0".to_string())))
+        );
+        assert_eq!(
+            parse_package_spec(Ecosystem::Pypi, "requests[security]@2.31.0"),
+            Ok(("requests".to_string(), Some("2.31.0".to_string())))
+        );
+    }
+
+    #[test]
+    fn parse_spec_pypi_rejects_bad_pip_forms() {
+        let err =
+            parse_package_spec(Ecosystem::Pypi, "requests==").expect_err("trailing == is an error");
+        assert!(err.contains("trailing"), "err: {err}");
+        assert!(parse_package_spec(Ecosystem::Pypi, "[security]==1.0").is_err());
+        assert!(parse_package_spec(Ecosystem::Pypi, "requests==2.31.*").is_err());
+    }
+
+    #[test]
+    fn parse_spec_rejects_trailing_at() {
+        let err = parse_package_spec(Ecosystem::Npm, "foo@").expect_err("trailing @ is an error");
+        assert!(err.contains("trailing"), "err: {err}");
+    }
+
+    #[test]
+    fn parse_spec_rejects_bare_and_empty() {
+        assert!(parse_package_spec(Ecosystem::Npm, "@").is_err());
+        assert!(parse_package_spec(Ecosystem::Npm, "").is_err());
+        assert!(parse_package_spec(Ecosystem::Npm, "   ").is_err());
+    }
+
+    #[test]
+    fn npm_rejects_non_exact_versions() {
+        for bad in [
+            "^1.0",
+            "~1.0",
+            ">=1.0",
+            "1.0.0 - 2.0.0",
+            "1.0 || 2.0",
+            "*",
+            "1.x",
+            "1.2",
+            "latest",
+        ] {
+            assert!(
+                require_exact_version(Ecosystem::Npm, bad).is_err(),
+                "npm should reject {bad:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn npm_accepts_exact_semver() {
+        for good in ["1.2.3", "1.2.3-beta.1", "1.2.3+build.5"] {
+            assert!(
+                require_exact_version(Ecosystem::Npm, good).is_ok(),
+                "npm should accept {good:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn pypi_rejects_range_syntax() {
+        for bad in ["==1.0", ">=1.0,<2.0", "~=1.4", "!=1.0", "1.*", "1.0 || 2.0"] {
+            assert!(
+                require_exact_version(Ecosystem::Pypi, bad).is_err(),
+                "pypi should reject {bad:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn pypi_accepts_exact_literals() {
+        for good in ["1.2", "2!1.0", "1.0rc1", "1.0.post1"] {
+            assert!(
+                require_exact_version(Ecosystem::Pypi, good).is_ok(),
+                "pypi should accept {good:?}"
+            );
+        }
+    }
+}
diff --git a/src/lib.rs b/src/lib.rs
index 498e83d..821548f 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,4 @@
+pub mod advisories;
 pub mod deps;
 pub mod precheck;
 pub mod verify_deps;
diff --git a/src/main.rs b/src/main.rs
index 14b6900..2e709e5 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -211,6 +211,11 @@ enum Commands {
         #[command(subcommand)]
         command: corgea::deps::run::DepsSubcommand,
     },
+    /// Look up a package's known advisories before choosing or installing it
+    Advisories {
+        #[command(subcommand)]
+        command: corgea::advisories::AdvisoriesSubcommand,
+    },
     /// Wrap `npm` commands: gate install targets on Corgea's vuln verdicts, then run npm.
     Npm(InstallWrapArgs),
     /// Wrap `yarn` commands: gate install targets on Corgea's vuln verdicts, then run yarn.
@@ -246,10 +251,20 @@ struct InstallWrapArgs {
     cmd: Vec<String>,
 }
 
-fn install_wrap_options(
-    args: &InstallWrapArgs,
-    config: &Config,
-) -> corgea::precheck::PrecheckOptions {
+/// The vuln-api access policy shared by the install gate and `advisories`:
+/// which base URL to hit and whether the Corgea token travels with the
+/// request. `has_token` reports whether the user is logged in, independent
+/// of the isolation decision that may keep the token off a custom URL.
+struct VulnApiAccess {
+    base_url: String,
+    mode: corgea::precheck::VerdictMode,
+    has_token: bool,
+}
+
+/// Resolve the shared vuln-api access policy once so both surfaces apply the
+/// same base-URL/token-isolation rule (never send a token to a custom URL
+/// without explicit opt-in).
+fn resolve_vuln_api_access(config: &Config) -> VulnApiAccess {
     let token = config.get_token();
     let token = token.trim();
     let base_url = config::vuln_api_url();
@@ -257,14 +272,25 @@ fn install_wrap_options(
     let send_token_to_custom =
         utils::generic::get_env_var_if_exists("CORGEA_VULN_API_SEND_TOKEN_TO_CUSTOM_URL")
             .is_some_and(|v| v.trim() == "1");
-    let mode = select_verdict_mode(token, custom_vuln_api_url, send_token_to_custom);
+    VulnApiAccess {
+        mode: select_verdict_mode(token, custom_vuln_api_url, send_token_to_custom),
+        base_url,
+        has_token: !token.is_empty(),
+    }
+}
+
+fn install_wrap_options(
+    args: &InstallWrapArgs,
+    config: &Config,
+) -> corgea::precheck::PrecheckOptions {
+    let access = resolve_vuln_api_access(config);
     corgea::precheck::PrecheckOptions {
         force: args.force,
         json: args.json,
         verdict: Some(corgea::precheck::VerdictConfig {
-            base_url,
-            mode,
-            public_login_hint: token.is_empty(),
+            base_url: access.base_url,
+            mode: access.mode,
+            public_login_hint: !access.has_token,
         }),
         npm_registry: utils::generic::get_env_var_if_exists("CORGEA_NPM_REGISTRY"),
         pypi_registry: utils::generic::get_env_var_if_exists("CORGEA_PYPI_REGISTRY"),
@@ -276,6 +302,20 @@ fn install_wrap_options(
     }
 }
 
+/// Advisories connection options. No token gate — tokenless (public) mode
+/// must work — but the same isolation policy as the install wrap.
+fn advisories_options(config: &Config) -> corgea::advisories::AdvisoriesOptions {
+    let access = resolve_vuln_api_access(config);
+    let token = match access.mode {
+        corgea::precheck::VerdictMode::Authenticated { token } => Some(token),
+        corgea::precheck::VerdictMode::Public => None,
+    };
+    corgea::advisories::AdvisoriesOptions {
+        base_url: access.base_url,
+        token,
+    }
+}
+
 /// A token enables authenticated (fail-closed) verdicts — but never against
 /// a custom vuln-api URL unless the user explicitly opts in to sending the
 /// token there.
@@ -672,6 +712,12 @@ fn main() {
             // Offline: no token / network. Exit code propagates fail-on policy.
             std::process::exit(i32::from(corgea::deps::run::run(command.clone())));
         }
+        Some(Commands::Advisories { command }) => {
+            std::process::exit(corgea::advisories::run(
+                command.clone(),
+                advisories_options(&corgea_config),
+            ));
+        }
         // Install wrappers: no auth gate. Public CVE checks run without a
         // token and fail open on lookup outages.
         Some(Commands::Npm(args)) => {
diff --git a/src/precheck/render.rs b/src/precheck/render.rs
index 2c85e75..8ee6d62 100644
--- a/src/precheck/render.rs
+++ b/src/precheck/render.rs
@@ -1,6 +1,7 @@
 //! Report rendering: text output, refusal line, fix/steer helpers.
 
 use crate::verify_deps;
+use crate::vuln_api::{highest_fix, safe_version};
 
 use super::{
     PackageManager, PrecheckOptions, PrecheckReport, TargetOutcome, TreeOrigin, TreeReport,
@@ -126,45 +127,6 @@ fn fix_note(m: &crate::vuln_api::VulnMatch) -> String {
     }
 }
 
-/// Highest of `fixes` after sort/dedup: a single distinct value is returned
-/// as-is (no parsing — preserves odd-but-unambiguous forms); several distinct
-/// values compare by lenient semver. With `all_must_parse`, one unparsable
-/// candidate among several poisons the answer (`None`); otherwise unparsable
-/// candidates are skipped.
-fn highest_fix(mut fixes: Vec<&str>, all_must_parse: bool) -> Option<String> {
-    fixes.sort_unstable();
-    fixes.dedup();
-    match fixes.as_slice() {
-        [] => None,
-        [only] => Some((*only).to_string()),
-        many => {
-            let mut parsed = Vec::with_capacity(many.len());
-            for raw in many {
-                match semver::Version::parse(&verify_deps::registry::normalize_for_semver(raw)) {
-                    Ok(v) => parsed.push((v, *raw)),
-                    Err(_) if all_must_parse => return None,
-                    Err(_) => {}
-                }
-            }
-            parsed
-                .into_iter()
-                .max_by(|(a, _), (b, _)| a.cmp(b))
-                .map(|(_, raw)| raw.to_string())
-        }
-    }
-}
-
-/// The one version certified to clear every match. Requires every match to
-/// carry a `fixed_version`; any match without one — or an unparsable
-/// candidate among several — means no version can be certified, so `None`.
-fn safe_version(matches: &[crate::vuln_api::VulnMatch]) -> Option<String> {
-    let fixes: Vec<&str> = matches
-        .iter()
-        .map(|m| m.fixed_version.as_deref())
-        .collect::<Option<_>>()?;
-    highest_fix(fixes, true)
-}
-
 /// Highest `fixed_version` the advisories advertise, by lenient semver.
 /// Unlike `safe_version` this is *not* a certification: matches without a
 /// fix are ignored, so the result may still be vulnerable to them. `None`
@@ -652,61 +614,6 @@ mod tests {
     use super::super::TreeOutcome;
     use super::*;
 
-    #[test]
-    fn safe_version_single_fix() {
-        assert_eq!(
-            safe_version(&[vm("A-1", Some("2.0.0"))]),
-            Some("2.0.0".to_string())
-        );
-    }
-
-    #[test]
-    fn safe_version_duplicate_fixes_collapse_without_parsing() {
-        // "1.0rc1" is unparsable, but a single distinct value needs no parse.
-        assert_eq!(
-            safe_version(&[vm("A-1", Some("1.0rc1")), vm("A-2", Some("1.0rc1"))]),
-            Some("1.0rc1".to_string())
-        );
-    }
-
-    #[test]
-    fn safe_version_picks_highest_of_distinct_fixes() {
-        // Semver order, not lexical ("1.2.0" > "1.10.0" lexically).
-        assert_eq!(
-            safe_version(&[vm("A-1", Some("1.2.0")), vm("A-2", Some("1.10.0"))]),
-            Some("1.10.0".to_string())
-        );
-    }
-
-    #[test]
-    fn safe_version_two_component_versions_normalize() {
-        assert_eq!(
-            safe_version(&[vm("A-1", Some("4.0")), vm("A-2", Some("3.2.5"))]),
-            Some("4.0".to_string())
-        );
-    }
-
-    #[test]
-    fn safe_version_mixed_fix_and_none_is_none() {
-        assert_eq!(
-            safe_version(&[vm("A-1", Some("2.0.0")), vm("A-2", None)]),
-            None
-        );
-    }
-
-    #[test]
-    fn safe_version_unparsable_among_distinct_is_none() {
-        assert_eq!(
-            safe_version(&[vm("A-1", Some("2!1.0")), vm("A-2", Some("1.0.0"))]),
-            None
-        );
-    }
-
-    #[test]
-    fn safe_version_empty_matches_is_none() {
-        assert_eq!(safe_version(&[]), None);
-    }
-
     #[test]
     fn error_prefix_strips_parenthesized_detail() {
         // The reqwest network-failure shape: per-package URL in parens.
diff --git a/src/vuln_api/mod.rs b/src/vuln_api/mod.rs
index cc043b5..7b714a1 100644
--- a/src/vuln_api/mod.rs
+++ b/src/vuln_api/mod.rs
@@ -108,6 +108,47 @@ impl VulnMatch {
     }
 }
 
+/// Highest of `fixes` after sort/dedup: a single distinct value is returned
+/// as-is (no parsing — preserves odd-but-unambiguous forms); several distinct
+/// values compare by lenient semver. With `all_must_parse`, one unparsable
+/// candidate among several poisons the answer (`None`); otherwise unparsable
+/// candidates are skipped.
+pub(crate) fn highest_fix(mut fixes: Vec<&str>, all_must_parse: bool) -> Option<String> {
+    fixes.sort_unstable();
+    fixes.dedup();
+    match fixes.as_slice() {
+        [] => None,
+        [only] => Some((*only).to_string()),
+        many => {
+            let mut parsed = Vec::with_capacity(many.len());
+            for raw in many {
+                match semver::Version::parse(&crate::verify_deps::registry::normalize_for_semver(
+                    raw,
+                )) {
+                    Ok(v) => parsed.push((v, *raw)),
+                    Err(_) if all_must_parse => return None,
+                    Err(_) => {}
+                }
+            }
+            parsed
+                .into_iter()
+                .max_by(|(a, _), (b, _)| a.cmp(b))
+                .map(|(_, raw)| raw.to_string())
+        }
+    }
+}
+
+/// The one version certified to clear every match. Requires every match to
+/// carry a `fixed_version`; any match without one — or an unparsable
+/// candidate among several — means no version can be certified, so `None`.
+pub fn safe_version(matches: &[VulnMatch]) -> Option<String> {
+    let fixes: Vec<&str> = matches
+        .iter()
+        .map(|m| m.fixed_version.as_deref())
+        .collect::<Option<_>>()?;
+    highest_fix(fixes, true)
+}
+
 /// `corgea-cli/<version> (<label>)` user-agent string.
 pub(crate) fn user_agent(label: &str) -> String {
     format!("corgea-cli/{} ({label})", env!("CARGO_PKG_VERSION"))
@@ -300,6 +341,73 @@ fn send_package_check_with_retry(
     }
 }
 
+/// Map the HTTP statuses shared by every vuln-api route to a stable error
+/// message, returning the response unchanged on success so the caller can
+/// read its body. Tests assert these strings — keep them stable. 404 is
+/// NOT handled here: each route assigns it its own meaning (/check treats it
+/// as a misconfigured URL, the profile route as "package not found"), so
+/// callers handle 404 before calling this.
+fn shared_status_error(
+    response: reqwest::blocking::Response,
+    token: Option<&str>,
+) -> Result<reqwest::blocking::Response, Box<dyn std::error::Error>> {
+    let status = response.status();
+    match status.as_u16() {
+        401 if token.is_some() => {
+            Err("vuln-api rejected the Corgea token (run `corgea login` to refresh)".into())
+        }
+        401 => Err("vuln-api requires authentication".into()),
+        403 => Err("vuln-api access denied (check your Corgea plan/permissions)".into()),
+        429 => Err("vuln-api rate-limited this request (retry later)".into()),
+        code @ 500..=599 => Err(format!("vuln-api unavailable (HTTP {})", code).into()),
+        code if !status.is_success() => {
+            let suffix = error_body_suffix(response);
+            Err(format!("vuln-api returned unexpected HTTP {}{}", code, suffix).into())
+        }
+        _ => Ok(response),
+    }
+}
+
+/// Confused-deputy guard shared by the check and profile routes: refuse to
+/// attribute a response to a different `(ecosystem, name)` than requested.
+/// The current server echoes the request path verbatim, so this can only
+/// fire on a tampering or misbehaving intermediary — defense in depth, not a
+/// live server contract. Empty echoes are skipped. Comparisons are
+/// case-insensitive, and the name comparison applies the ecosystem's
+/// canonical rule (PEP 503) to BOTH sides so a response echoing the stored
+/// spelling (`flask_cors` for a `flask-cors` request) is not a false
+/// mismatch — that would fail closed for valid pypi packages with `_`/`.`
+/// in their names. Callers apply any route-specific guards (version,
+/// is_vulnerable contradiction) separately.
+fn verify_response_identity(
+    ecosystem: Ecosystem,
+    resp_ecosystem: &str,
+    resp_name: &str,
+    requested_name: &str,
+) -> Result<(), Box<dyn std::error::Error>> {
+    if !resp_ecosystem.is_empty() && !resp_ecosystem.eq_ignore_ascii_case(ecosystem.path_segment())
+    {
+        return Err(format!(
+            "vuln-api response ecosystem '{}' does not match request '{}'",
+            resp_ecosystem,
+            ecosystem.path_segment()
+        )
+        .into());
+    }
+    if !resp_name.is_empty()
+        && !ecosystem
+            .normalize_name(resp_name)
+            .eq_ignore_ascii_case(&ecosystem.normalize_name(requested_name))
+    {
+        return Err(format!(
+            "vuln-api response package '{}' does not match request '{}'",
+            resp_name, requested_name
+        )
+        .into());
+    }
+    Ok(())
+}
+
 /// One HTTP request per `(name, version)`. A 1000-package lockfile makes
 /// 1000 requests (through the verdict pool's bounded concurrency); the
 /// future optimization is a server-side batch endpoint, not client tricks.
@@ -334,31 +442,13 @@ pub fn check_package_version(
 
     let response = send_package_check_with_retry(client, &url, token)?;
 
-    let status = response.status();
-    // Fixed messages for recognized statuses — tests assert these strings,
-    // keep them stable. The /check route answers 200 (empty matches) for
-    // unknown packages; a 404 can only mean a wrong base URL or route, and
-    // treating it as "clean" would silently disable the gate on a
-    // misconfigured endpoint.
-    match status.as_u16() {
-        401 if token.is_some() => {
-            return Err(
-                "vuln-api rejected the Corgea token (run `corgea login` to refresh)".into(),
-            );
-        }
-        401 => return Err("vuln-api requires authentication".into()),
-        403 => return Err("vuln-api access denied (check your Corgea plan/permissions)".into()),
-        429 => return Err("vuln-api rate-limited this request (retry later)".into()),
-        code @ 500..=599 => return Err(format!("vuln-api unavailable (HTTP {})", code).into()),
-        404 => {
-            return Err("vuln-api route not found (HTTP 404) — check CORGEA_VULN_API_URL".into());
-        }
-        code if !status.is_success() => {
-            let suffix = error_body_suffix(response);
-            return Err(format!("vuln-api returned unexpected HTTP {}{}", code, suffix).into());
-        }
-        _ => {}
+    // The /check route answers 200 (empty matches) for unknown packages; a
+    // 404 can only mean a wrong base URL or route, and treating it as "clean"
+    // would silently disable the gate on a misconfigured endpoint.
+    if response.status().as_u16() == 404 {
+        return Err("vuln-api route not found (HTTP 404) — check CORGEA_VULN_API_URL".into());
     }
+    let response = shared_status_error(response, token)?;
 
     let response_text = response.text()?;
     let parsed: VulnCheckResponse = serde_json::from_str(&response_text).map_err(|e| {
@@ -371,41 +461,8 @@ pub fn check_package_version(
     })?;
 
     // Confused-deputy guard: refuse to attribute advisories to a different
-    // (name, version, ecosystem) than what we asked about. The current
-    // server echoes ecosystem/name/version verbatim from the request path
-    // (worker.js `packageVersionCheckCliHandler`), so this can only fire on
-    // a tampering or misbehaving intermediary — defense in depth, not a live
-    // server contract. Comparisons stay case-insensitive to tolerate a
-    // future server that echoes a stored spelling/casing instead.
-    if !parsed.ecosystem.is_empty()
-        && !parsed
-            .ecosystem
-            .eq_ignore_ascii_case(ecosystem.path_segment())
-    {
-        return Err(format!(
-            "vuln-api response ecosystem '{}' does not match request '{}'",
-            parsed.ecosystem,
-            ecosystem.path_segment()
-        )
-        .into());
-    }
-    // Apply the ecosystem's canonical-name rule (PEP 503) to BOTH sides
-    // before comparing: `name` carries the wire spelling (dots/underscores
-    // preserved), and a response that echoes the registry/stored spelling
-    // (`flask_cors` for a `flask-cors` request, PEP 503-equivalent) must
-    // not be a hard failure — that would fail the gate closed for valid
-    // pypi packages with `_`/`.` in their names.
-    if !parsed.package_name.is_empty()
-        && !ecosystem
-            .normalize_name(&parsed.package_name)
-            .eq_ignore_ascii_case(&ecosystem.normalize_name(name))
-    {
-        return Err(format!(
-            "vuln-api response package '{}' does not match request '{}'",
-            parsed.package_name, name
-        )
-        .into());
-    }
+    // (name, ecosystem) than what we asked about (see verify_response_identity).
+    verify_response_identity(ecosystem, &parsed.ecosystem, &parsed.package_name, name)?;
     if !parsed.version.is_empty() && parsed.version != version {
         return Err(format!(
             "vuln-api response version '{}' does not match request '{}'",
@@ -430,12 +487,196 @@ pub fn check_package_version(
     Ok(parsed)
 }
 
+/// Package profile from `/v1/packages/:eco/:name` (no auth on the worker,
+/// but the token is still attached when the caller has one — same header
+/// policy as every route). Up to the 100 most recently modified advisories
+/// linked to the package (the worker's LIMIT 100 — no total, no
+/// pagination); note: this route carries NO fixed_versions.
+#[derive(Debug, Clone, Deserialize)]
+pub struct PackageProfile {
+    pub package: ProfilePackage,
+    #[serde(default)]
+    pub advisories: Vec<AdvisorySummary>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct ProfilePackage {
+    #[serde(default)]
+    pub ecosystem: String,
+    #[serde(default)]
+    pub name: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AdvisorySummary {
+    pub id: String,
+    #[serde(default)]
+    pub alias: Option<String>,
+    #[serde(default)]
+    pub summary: Option<String>,
+    #[serde(default)]
+    pub severity: Option<String>,
+    #[serde(default)]
+    pub cvss_score: Option<f64>,
+    #[serde(default)]
+    pub tier: Option<u8>,
+    #[serde(default)]
+    pub kev: Option<bool>,
+    #[serde(default)]
+    pub malware: Option<bool>,
+    #[serde(default)]
+    pub published_at: Option<String>,
+    #[serde(default)]
+    pub modified_at: Option<String>,
+}
+
+/// The worker's package-miss sentinel (worker.js `packageProfileHandler`:
+/// `{"error":"Package not found"}`). Matched on the parsed `error` field,
+/// not the raw string, so field order/whitespace can't break it. Pinned
+/// against staging by the vuln_api_contract tests.
+fn is_package_not_found_body(body: &str) -> bool {
+    serde_json::from_str::<serde_json::Value>(body)
+        .ok()
+        .and_then(|v| v.get("error").and_then(|e| e.as_str()).map(String::from))
+        .is_some_and(|e| e == "Package not found")
+}
+
+/// GET /v1/packages/:eco/:name. `Ok(None)` = the package has no row in the
+/// advisory database (the route's sentinel 404) — a legitimate data answer,
+/// unlike /check where 404 can only mean a misconfigured URL. A 404 without
+/// the sentinel body is an error.
+pub fn fetch_package_profile(
+    client: &reqwest::blocking::Client,
+    base_url: &str,
+    token: Option<&str>,
+    ecosystem: Ecosystem,
+    name: &str,
+) -> Result<Option<PackageProfile>, Box<dyn std::error::Error>> {
+    let base = validated_base(base_url)?;
+    let name = &ecosystem.request_name(name);
+    let encoded_name = encode_package_name(ecosystem, name);
+    let url = format!(
+        "{}/v1/packages/{}/{}",
+        base,
+        ecosystem.path_segment(),
+        encoded_name
+    );
+    debug(&format!("Sending vuln-api request to URL: {}", url));
+
+    let response = send_package_check_with_retry(client, &url, token)?;
+    // Unlike /check, a 404 here CAN be a legitimate data answer — but only
+    // when it carries the route's own package-miss sentinel body. Any other
+    // 404 (wrong host, older deployment without the route, proxy/CDN) must
+    // surface as an error, not read as a clean package.
+    if response.status().as_u16() == 404 {
+        let body = response.text().unwrap_or_default();
+        if is_package_not_found_body(&body) {
+            return Ok(None);
+        }
+        return Err(format!(
+            "vuln-api route not found (HTTP 404) — check CORGEA_VULN_API_URL. Body: {}",
+            body_snippet(&body, ERROR_BODY_SNIPPET_LEN)
+        )
+        .into());
+    }
+    let response = shared_status_error(response, token)?;
+
+    let response_text = response.text()?;
+    let parsed: PackageProfile = serde_json::from_str(&response_text).map_err(|e| {
+        debug(&format!(
+            "Failed to parse vuln-api response: {}. Body: {}",
+            e,
+            body_snippet(&response_text, ERROR_BODY_SNIPPET_LEN)
+        ));
+        format!("Failed to parse vuln-api response: {}", e)
+    })?;
+
+    // The route has no version and no is_vulnerable flag, so only the
+    // (ecosystem, name) identity guard applies — not the version/contradiction
+    // guards that check_package_version adds.
+    verify_response_identity(
+        ecosystem,
+        &parsed.package.ecosystem,
+        &parsed.package.name,
+        name,
+    )?;
+    Ok(Some(parsed))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
     use crate::vuln_api_stub::{self, header_value, spawn_capturing_vuln_api_stub, PackageKey};
     use std::collections::{HashMap, HashSet};
 
+    /// Local `VulnMatch` builder for the `safe_version` suite — avoids a
+    /// cross-module dependency on precheck's `#[cfg(test)]` test_support.
+    fn vm(advisory: &str, fixed: Option<&str>) -> VulnMatch {
+        VulnMatch {
+            advisory_id: advisory.to_string(),
+            severity_level: "high".to_string(),
+            tier: Some(1),
+            vulnerable_version_range: None,
+            fixed_version: fixed.map(str::to_string),
+            malware: false,
+        }
+    }
+
+    #[test]
+    fn safe_version_single_fix() {
+        assert_eq!(
+            safe_version(&[vm("A-1", Some("2.0.0"))]),
+            Some("2.0.0".to_string())
+        );
+    }
+
+    #[test]
+    fn safe_version_duplicate_fixes_collapse_without_parsing() {
+        // "1.0rc1" is unparsable, but a single distinct value needs no parse.
+        assert_eq!(
+            safe_version(&[vm("A-1", Some("1.0rc1")), vm("A-2", Some("1.0rc1"))]),
+            Some("1.0rc1".to_string())
+        );
+    }
+
+    #[test]
+    fn safe_version_picks_highest_of_distinct_fixes() {
+        // Semver order, not lexical ("1.2.0" > "1.10.0" lexically).
+        assert_eq!(
+            safe_version(&[vm("A-1", Some("1.2.0")), vm("A-2", Some("1.10.0"))]),
+            Some("1.10.0".to_string())
+        );
+    }
+
+    #[test]
+    fn safe_version_two_component_versions_normalize() {
+        assert_eq!(
+            safe_version(&[vm("A-1", Some("4.0")), vm("A-2", Some("3.2.5"))]),
+            Some("4.0".to_string())
+        );
+    }
+
+    #[test]
+    fn safe_version_mixed_fix_and_none_is_none() {
+        assert_eq!(
+            safe_version(&[vm("A-1", Some("2.0.0")), vm("A-2", None)]),
+            None
+        );
+    }
+
+    #[test]
+    fn safe_version_unparsable_among_distinct_is_none() {
+        assert_eq!(
+            safe_version(&[vm("A-1", Some("2!1.0")), vm("A-2", Some("1.0.0"))]),
+            None
+        );
+    }
+
+    #[test]
+    fn safe_version_empty_matches_is_none() {
+        assert_eq!(safe_version(&[]), None);
+    }
+
     fn lodash_key() -> PackageKey {
         vuln_api_stub::key("npm", "lodash", "4.17.20")
     }
@@ -856,6 +1097,153 @@ mod tests {
         assert!(!m.malware);
     }
 
+    #[test]
+    fn fixture_package_profile_deserializes_tolerant_subset() {
+        // The fixture carries the full server serialization (14 advisory
+        // fields + the full package block); the CLI subset must deserialize
+        // it, ignoring the fields it doesn't model.
+        let parsed: PackageProfile =
+            serde_json::from_str(fixture!("package_profile.json")).unwrap();
+        assert_eq!(parsed.package.ecosystem, "npm");
+        assert_eq!(parsed.package.name, "axios");
+        assert_eq!(parsed.advisories.len(), 2);
+        let ghsa = &parsed.advisories[0];
+        assert_eq!(ghsa.id, "GHSA-xxxx-yyyy-zzzz");
+        assert_eq!(ghsa.severity.as_deref(), Some("high"));
+        assert_eq!(ghsa.cvss_score, Some(7.5));
+        assert_eq!(ghsa.tier, Some(1));
+        assert_eq!(ghsa.malware, Some(false));
+        let mal = &parsed.advisories[1];
+        assert!(mal.id.starts_with("MAL-"));
+        assert_eq!(mal.malware, Some(true));
+        assert_eq!(mal.cvss_score, None);
+    }
+
+    fn fetch_profile_with_stub(
+        stub: &vuln_api_stub::VulnApiStub,
+        ecosystem: Ecosystem,
+        name: &str,
+    ) -> Result<Option<PackageProfile>, Box<dyn std::error::Error>> {
+        let client = http_client().expect("test client");
+        fetch_package_profile(&client, &stub.base_url, None, ecosystem, name)
+    }
+
+    #[test]
+    fn fetch_package_profile_parses_body() {
+        let profiles = HashMap::from([(
+            vuln_api_stub::profile_key("npm", "axios"),
+            fixture!("package_profile.json").to_string(),
+        )]);
+        let stub = vuln_api_stub::spawn_with_profiles(
+            HashMap::new(),
+            HashMap::new(),
+            profiles,
+            HashMap::new(),
+        );
+        let profile = fetch_profile_with_stub(&stub, Ecosystem::Npm, "axios")
+            .expect("profile fetch should succeed")
+            .expect("known package should be Some");
+        assert_eq!(profile.advisories.len(), 2);
+    }
+
+    #[test]
+    fn fetch_package_profile_404_is_none() {
+        // Unknown profile key → 404 → Ok(None), a legitimate data answer.
+        let stub = vuln_api_stub::spawn_with_profiles(
+            HashMap::new(),
+            HashMap::new(),
+            HashMap::new(),
+            HashMap::new(),
+        );
+        let profile =
+            fetch_profile_with_stub(&stub, Ecosystem::Npm, "no-such-pkg").expect("404 is Ok(None)");
+        assert!(profile.is_none());
+    }
+
+    #[test]
+    fn fetch_package_profile_identity_mismatch_is_error() {
+        let profiles = HashMap::from([(
+            vuln_api_stub::profile_key("npm", "axios"),
+            vuln_api_stub::profile_body("npm", "left-pad", "[]"),
+        )]);
+        let stub = vuln_api_stub::spawn_with_profiles(
+            HashMap::new(),
+            HashMap::new(),
+            profiles,
+            HashMap::new(),
+        );
+        let err = fetch_profile_with_stub(&stub, Ecosystem::Npm, "axios")
+            .expect_err("echoed name mismatch should fail");
+        assert!(err.to_string().contains("does not match request"));
+    }
+
+    #[test]
+    fn fetch_package_profile_alternate_pypi_spelling_passes_guard() {
+        // The wire name for `Flask_Cors` is `flask_cors`; a response echoing
+        // a PEP 503-equivalent spelling must NOT trip the identity guard.
+        let profiles = HashMap::from([(
+            vuln_api_stub::profile_key("pypi", "flask_cors"),
+            vuln_api_stub::profile_body("PyPI", "Flask-Cors", "[]"),
+        )]);
+        let stub = vuln_api_stub::spawn_with_profiles(
+            HashMap::new(),
+            HashMap::new(),
+            profiles,
+            HashMap::new(),
+        );
+        let profile = fetch_profile_with_stub(&stub, Ecosystem::Pypi, "Flask_Cors")
+            .expect("alternate spelling must pass the guard")
+            .expect("known package should be Some");
+        assert!(profile.advisories.is_empty());
+    }
+
+    #[test]
+    fn fetch_package_profile_500_is_unavailable() {
+        let profile_statuses =
+            HashMap::from([(vuln_api_stub::profile_key("npm", "axios"), 500u16)]);
+        let stub = vuln_api_stub::spawn_with_profiles(
+            HashMap::new(),
+            HashMap::new(),
+            HashMap::new(),
+            profile_statuses,
+        );
+        let err =
+            fetch_profile_with_stub(&stub, Ecosystem::Npm, "axios").expect_err("500 should fail");
+        assert!(err.to_string().contains("unavailable"));
+    }
+
+    #[test]
+    fn fetch_package_profile_generic_404_is_an_error() {
+        // A 404 without the worker's package-miss sentinel body (wrong host,
+        // older deployment, proxy/CDN) must not read as a clean package.
+        // Status-only script: the stub answers 404 with a non-sentinel body.
+        let profile_statuses =
+            HashMap::from([(vuln_api_stub::profile_key("npm", "axios"), 404u16)]);
+        let stub = vuln_api_stub::spawn_with_profiles(
+            HashMap::new(),
+            HashMap::new(),
+            HashMap::new(),
+            profile_statuses,
+        );
+        let err = fetch_profile_with_stub(&stub, Ecosystem::Npm, "axios")
+            .expect_err("non-sentinel 404 should fail");
+        assert!(err.to_string().contains("CORGEA_VULN_API_URL"));
+    }
+
+    #[test]
+    fn package_not_found_body_matches_sentinel_only() {
+        assert!(is_package_not_found_body(
+            r#"{"error":"Package not found"}"#
+        ));
+        // Field order/extra fields don't matter; other errors and non-JSON do.
+        assert!(is_package_not_found_body(
+            r#"{ "status": 404, "error": "Package not found" }"#
+        ));
+        assert!(!is_package_not_found_body(r#"{"error":"Invalid url"}"#));
+        assert!(!is_package_not_found_body("<html>404</html>"));
+        assert!(!is_package_not_found_body(""));
+    }
+
     #[test]
     fn fixture_check_malware_deserializes() {
         // Malware surfaces through /check as an ordinary is_vulnerable:true match
diff --git a/src/vuln_api_stub/mod.rs b/src/vuln_api_stub/mod.rs
index a385971..2b554f0 100644
--- a/src/vuln_api_stub/mod.rs
+++ b/src/vuln_api_stub/mod.rs
@@ -5,6 +5,21 @@ use std::thread;
 
 pub type PackageKey = (String, String, String);
 
+pub type ProfileKey = (String, String);
+
+/// `(ecosystem, name)` key for the profile route table — same
+/// lowercase+trim rule as `key()`.
+pub fn profile_key(eco: &str, name: &str) -> ProfileKey {
+    (eco.to_string(), name.trim().to_lowercase())
+}
+
+/// Profile body helper for tests: a package block plus `advisories`.
+pub fn profile_body(ecosystem: &str, name: &str, advisories_json: &str) -> String {
+    format!(
+        r#"{{"package":{{"ecosystem":"{ecosystem}","name":"{name}"}},"advisories":{advisories_json}}}"#
+    )
+}
+
 /// `(ecosystem, name, version)` key for the stub's route tables. Applies the
 /// REAL server's normalization (worker.js `normalizePackageName`: lowercase
 /// and trim, NOT PEP 503) on both the fixture and lookup sides. The stub
@@ -86,6 +101,30 @@ pub fn spawn_with_retry_once(
         status_overrides,
         retry_once,
         HashMap::new(),
+        HashMap::new(),
+        HashMap::new(),
+        None,
+    )
+}
+
+/// Like [`spawn_with_statuses`], plus a profile route table for
+/// `/v1/packages/{eco}/{name}`. Unknown profile keys answer 404
+/// ("Package not found"), matching the real handler — unlike /check's
+/// synthesized clean. `profile_statuses` overrides the status for a
+/// scripted key (e.g. 500), like `status_overrides` does for /check.
+pub fn spawn_with_profiles(
+    package_checks: HashMap<PackageKey, String>,
+    status_overrides: HashMap<PackageKey, u16>,
+    package_profiles: HashMap<ProfileKey, String>,
+    profile_statuses: HashMap<ProfileKey, u16>,
+) -> VulnApiStub {
+    spawn(
+        package_checks,
+        status_overrides,
+        HashSet::new(),
+        HashMap::new(),
+        package_profiles,
+        profile_statuses,
         None,
     )
 }
@@ -106,6 +145,8 @@ pub fn spawn_with_drops(
         status_overrides,
         HashSet::new(),
         drops,
+        HashMap::new(),
+        HashMap::new(),
         None,
     )
 }
@@ -120,6 +161,8 @@ pub fn spawn_capturing_vuln_api_stub() -> (String, std::sync::Arc<std::sync::Mut
         HashMap::new(),
         HashSet::new(),
         HashMap::new(),
+        HashMap::new(),
+        HashMap::new(),
         Some(std::sync::Arc::clone(&requests)),
     );
     // Dropping the stub's join handle detaches the listener thread; the
@@ -127,11 +170,14 @@ pub fn spawn_capturing_vuln_api_stub() -> (String, std::sync::Arc<std::sync::Mut
     (stub.base_url, requests)
 }
 
+#[allow(clippy::too_many_arguments)]
 fn spawn(
     package_checks: HashMap<PackageKey, String>,
     status_overrides: HashMap<PackageKey, u16>,
     retry_once: HashSet<PackageKey>,
     drops: HashMap<PackageKey, usize>,
+    package_profiles: HashMap<ProfileKey, String>,
+    profile_statuses: HashMap<ProfileKey, u16>,
     capture: Option<std::sync::Arc<std::sync::Mutex<Vec<String>>>>,
 ) -> VulnApiStub {
     let listener = TcpListener::bind("127.0.0.1:0").expect("bind stub");
@@ -151,6 +197,8 @@ fn spawn(
                 &status_overrides,
                 &mut pending_retries,
                 &mut pending_drops,
+                &package_profiles,
+                &profile_statuses,
                 capture.as_deref(),
             );
         }
@@ -203,12 +251,15 @@ pub fn read_http_request(stream: &mut std::net::TcpStream) -> Vec<u8> {
     buf
 }
 
+#[allow(clippy::too_many_arguments)]
 fn handle_connection(
     stream: &mut std::net::TcpStream,
     package_checks: &HashMap<PackageKey, String>,
     status_overrides: &HashMap<PackageKey, u16>,
     pending_retries: &mut HashSet<PackageKey>,
     pending_drops: &mut HashMap<PackageKey, usize>,
+    package_profiles: &HashMap<ProfileKey, String>,
+    profile_statuses: &HashMap<ProfileKey, u16>,
     capture: Option<&std::sync::Mutex<Vec<String>>>,
 ) {
     let buf = read_http_request(stream);
@@ -253,6 +304,29 @@ fn handle_connection(
                     let status = status_overrides.get(&key).copied().unwrap_or(200);
                     (status, body, false)
                 }
+            } else if parts.len() >= 4
+                && parts[0] == "v1"
+                && parts[1] == "packages"
+                && !(parts.len() >= 6 && parts[parts.len() - 2] == "versions")
+            {
+                // Version-route shape excluded by position, not by segment
+                // value, so a package literally named "versions" still
+                // resolves as a profile (matching the worker's catch-all).
+                let name = urlencoding::decode(&parts[3..].join("/"))
+                    .unwrap_or_default()
+                    .into_owned();
+                let key = profile_key(parts[2], &name);
+                match package_profiles.get(&key) {
+                    Some(body) => {
+                        let status = profile_statuses.get(&key).copied().unwrap_or(200);
+                        (status, body.clone(), false)
+                    }
+                    None => match profile_statuses.get(&key) {
+                        // Status-only script (e.g. 500 with a canned error body).
+                        Some(&status) => (status, r#"{"error":"scripted"}"#.to_string(), false),
+                        None => (404, r#"{"error":"Package not found"}"#.to_string(), false),
+                    },
+                }
             } else {
                 (404, NOT_FOUND_BODY.to_string(), false)
             }
@@ -374,4 +448,33 @@ mod tests {
         );
         assert!(resp.contains(r#""is_vulnerable":false"#), "resp: {resp}");
     }
+
+    #[test]
+    fn scripted_profile_and_status_override() {
+        let profiles = HashMap::from([(
+            profile_key("npm", "axios"),
+            profile_body("npm", "axios", r#"[{"id":"GHSA-test"}]"#),
+        )]);
+        let profile_statuses = HashMap::from([(profile_key("npm", "flaky"), 500u16)]);
+        let stub = spawn_with_profiles(HashMap::new(), HashMap::new(), profiles, profile_statuses);
+
+        // Scripted body → 200.
+        let resp = get(&stub.base_url, "/v1/packages/npm/axios");
+        assert!(resp.starts_with("HTTP/1.1 200"), "resp: {resp}");
+        assert!(resp.contains("GHSA-test"), "resp: {resp}");
+
+        // Unknown key → 404 "Package not found" (not default-clean).
+        let resp = get(&stub.base_url, "/v1/packages/npm/unknown");
+        assert!(resp.starts_with("HTTP/1.1 404"), "resp: {resp}");
+        assert!(resp.contains("Package not found"), "resp: {resp}");
+
+        // Status-only override → 500.
+        let resp = get(&stub.base_url, "/v1/packages/npm/flaky");
+        assert!(resp.starts_with("HTTP/1.1 500"), "resp: {resp}");
+
+        // A package literally named "versions" is a profile, not a version route.
+        let resp = get(&stub.base_url, "/v1/packages/npm/versions");
+        assert!(resp.starts_with("HTTP/1.1 404"), "resp: {resp}");
+        assert!(resp.contains("Package not found"), "resp: {resp}");
+    }
 }
diff --git a/tests/cli_advisories.rs b/tests/cli_advisories.rs
new file mode 100644
index 0000000..155947c
--- /dev/null
+++ b/tests/cli_advisories.rs
@@ -0,0 +1,417 @@
+#![cfg(unix)]
+mod common;
+
+use corgea::vuln_api_stub::{self, key};
+use std::collections::HashMap;
+
+/// Run `corgea advisories check <args>` against `stub_url` in an isolated env.
+fn advisories_check(stub_url: &str, args: &[&str]) -> std::process::Output {
+    let (mut cmd, _home) = common::corgea_isolated();
+    cmd.env("CORGEA_VULN_API_URL", stub_url)
+        .arg("advisories")
+        .arg("check")
+        .args(args);
+    cmd.output().expect("run corgea advisories")
+}
+
+fn stdout(out: &std::process::Output) -> String {
+    String::from_utf8_lossy(&out.stdout).into_owned()
+}
+
+fn stderr(out: &std::process::Output) -> String {
+    String::from_utf8_lossy(&out.stderr).into_owned()
+}
+
+#[test]
+fn vulnerable_version_exits_1_with_advisory_lines() {
+    let body = vuln_api_stub::vulnerable_body(
+        "npm",
+        "leftpad",
+        "1.0.0",
+        "GHSA-aaaa-bbbb-cccc",
+        Some("2.0.0"),
+    );
+    let stub = vuln_api_stub::spawn_with_statuses(
+        HashMap::from([(key("npm", "leftpad", "1.0.0"), body)]),
+        HashMap::new(),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "leftpad@1.0.0"]);
+    assert_eq!(out.status.code(), Some(1), "stderr: {}", stderr(&out));
+    let s = stdout(&out);
+    assert!(s.contains("GHSA-aaaa-bbbb-cccc"), "stdout: {s}");
+    assert!(s.contains("critical"), "stdout: {s}");
+    assert!(s.contains("fixed in 2.0.0"), "stdout: {s}");
+    assert!(s.contains("→ safe version: leftpad@2.0.0"), "stdout: {s}");
+}
+
+#[test]
+fn clean_version_exits_0() {
+    // Unscripted key → stub default clean 200.
+    let stub = vuln_api_stub::spawn_with_statuses(HashMap::new(), HashMap::new());
+    let out = advisories_check(&stub.base_url, &["npm", "leftpad@1.0.0"]);
+    assert_eq!(out.status.code(), Some(0), "stderr: {}", stderr(&out));
+    assert!(stdout(&out).contains("clean"), "stdout: {}", stdout(&out));
+}
+
+#[test]
+fn scoped_npm_spec_parses() {
+    // Scripted scoped key proves the last-`@` split reached the wire correctly.
+    let body =
+        vuln_api_stub::vulnerable_body("npm", "@scope/pkg", "1.0.0", "GHSA-scope", Some("1.2.0"));
+    let stub = vuln_api_stub::spawn_with_statuses(
+        HashMap::from([(key("npm", "@scope/pkg", "1.0.0"), body)]),
+        HashMap::new(),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "@scope/pkg@1.0.0"]);
+    assert_eq!(out.status.code(), Some(1), "stderr: {}", stderr(&out));
+    assert!(
+        stdout(&out).contains("GHSA-scope"),
+        "stdout: {}",
+        stdout(&out)
+    );
+}
+
+#[test]
+fn server_error_exits_2() {
+    let stub = vuln_api_stub::spawn_with_statuses(
+        HashMap::new(),
+        HashMap::from([(key("npm", "leftpad", "1.0.0"), 500u16)]),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "leftpad@1.0.0"]);
+    assert_eq!(out.status.code(), Some(2), "stdout: {}", stdout(&out));
+    assert!(
+        stderr(&out).contains("vuln-api unavailable"),
+        "stderr: {}",
+        stderr(&out)
+    );
+}
+
+#[test]
+fn auth_required_exits_2() {
+    // 401 with no token in the isolated env: tokenless user gets a clear
+    // error, not a false clean.
+    let stub = vuln_api_stub::spawn_with_statuses(
+        HashMap::new(),
+        HashMap::from([(key("npm", "leftpad", "1.0.0"), 401u16)]),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "leftpad@1.0.0"]);
+    assert_eq!(out.status.code(), Some(2), "stdout: {}", stdout(&out));
+    assert!(
+        stderr(&out).contains("vuln-api requires authentication"),
+        "stderr: {}",
+        stderr(&out)
+    );
+}
+
+#[test]
+fn bad_args_exit_2_without_network() {
+    // Dead port proves parsing fails before any dial.
+    let dead = "http://127.0.0.1:9";
+    for args in [
+        vec!["rubygems", "foo@1.0.0"], // unknown ecosystem
+        vec!["npm", "foo@"],           // trailing @
+        vec!["npm", "foo@^1.0"],       // range
+    ] {
+        let out = advisories_check(dead, &args);
+        assert_eq!(
+            out.status.code(),
+            Some(2),
+            "args {args:?} should exit 2; stdout: {}",
+            stdout(&out)
+        );
+        assert!(
+            !stderr(&out).is_empty(),
+            "args {args:?} should print a stderr message"
+        );
+    }
+}
+
+#[test]
+fn json_vulnerable_document() {
+    let body = vuln_api_stub::vulnerable_body(
+        "npm",
+        "leftpad",
+        "1.0.0",
+        "GHSA-aaaa-bbbb-cccc",
+        Some("2.0.0"),
+    );
+    let stub = vuln_api_stub::spawn_with_statuses(
+        HashMap::from([(key("npm", "leftpad", "1.0.0"), body)]),
+        HashMap::new(),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "leftpad@1.0.0", "--json"]);
+    assert_eq!(out.status.code(), Some(1), "stderr: {}", stderr(&out));
+    let doc: serde_json::Value =
+        serde_json::from_slice(&out.stdout).expect("stdout is a single json document");
+    assert_eq!(doc["schema_version"], 1);
+    assert_eq!(doc["ecosystem"], "npm");
+    assert_eq!(doc["package"], "leftpad");
+    assert_eq!(doc["version"], "1.0.0");
+    assert_eq!(doc["verdict"]["status"], "vulnerable");
+    assert_eq!(
+        doc["verdict"]["matches"][0]["advisory_id"],
+        "GHSA-aaaa-bbbb-cccc"
+    );
+    assert_eq!(doc["verdict"]["matches"][0]["fixed_version"], "2.0.0");
+    assert_eq!(doc["verdict"]["remediation"], "2.0.0");
+}
+
+#[test]
+fn json_clean_document() {
+    let stub = vuln_api_stub::spawn_with_statuses(HashMap::new(), HashMap::new());
+    let out = advisories_check(&stub.base_url, &["npm", "leftpad@1.0.0", "--json"]);
+    assert_eq!(out.status.code(), Some(0), "stderr: {}", stderr(&out));
+    let doc: serde_json::Value =
+        serde_json::from_slice(&out.stdout).expect("stdout is a single json document");
+    assert_eq!(doc["schema_version"], 1);
+    assert_eq!(doc["verdict"]["status"], "clean");
+    assert!(
+        doc["verdict"].get("matches").is_none(),
+        "clean verdict has no matches key: {doc}"
+    );
+}
+
+#[test]
+fn json_error_document_on_500() {
+    let stub = vuln_api_stub::spawn_with_statuses(
+        HashMap::new(),
+        HashMap::from([(key("npm", "leftpad", "1.0.0"), 500u16)]),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "leftpad@1.0.0", "--json"]);
+    assert_eq!(out.status.code(), Some(2), "stderr: {}", stderr(&out));
+    let doc: serde_json::Value =
+        serde_json::from_slice(&out.stdout).expect("stdout is a single json document");
+    assert_eq!(doc["schema_version"], 1);
+    assert!(
+        doc["error"]
+            .as_str()
+            .unwrap_or_default()
+            .contains("unavailable"),
+        "error document: {doc}"
+    );
+}
+
+#[test]
+fn json_error_document_on_bad_spec() {
+    let dead = "http://127.0.0.1:9";
+    let out = advisories_check(dead, &["npm", "foo@", "--json"]);
+    assert_eq!(out.status.code(), Some(2), "stdout: {}", stdout(&out));
+    let doc: serde_json::Value =
+        serde_json::from_slice(&out.stdout).expect("stdout is a single json document");
+    assert_eq!(doc["schema_version"], 1);
+    assert!(doc["error"].is_string(), "error document: {doc}");
+}
+
+#[test]
+fn json_stdout_is_exactly_one_document() {
+    // The strongest purity assertion: parsing the ENTIRE stdout as one json
+    // value fails on any trailing junk.
+    let body = vuln_api_stub::vulnerable_body(
+        "npm",
+        "leftpad",
+        "1.0.0",
+        "GHSA-aaaa-bbbb-cccc",
+        Some("2.0.0"),
+    );
+    let stub = vuln_api_stub::spawn_with_statuses(
+        HashMap::from([(key("npm", "leftpad", "1.0.0"), body)]),
+        HashMap::new(),
+    );
+    for args in [
+        vec!["npm", "leftpad@1.0.0", "--json"], // vulnerable
+        vec!["npm", "other@1.0.0", "--json"],   // clean (unscripted key)
+    ] {
+        let out = advisories_check(&stub.base_url, &args);
+        serde_json::from_slice::<serde_json::Value>(&out.stdout)
+            .unwrap_or_else(|e| panic!("args {args:?}: stdout not one json document: {e}"));
+    }
+}
+
+// ---- unversioned form (package profile listing) ----
+
+const TWO_ADVISORIES: &str = r#"[{"id":"GHSA-aaaa-bbbb-cccc","severity":"high","cvss_score":7.5,"tier":1},
+        {"id":"MAL-2024-0001","severity":"critical","malware":true}]"#;
+
+#[test]
+fn package_with_advisories_exits_1() {
+    let body = vuln_api_stub::profile_body("npm", "axios", TWO_ADVISORIES);
+    let stub = vuln_api_stub::spawn_with_profiles(
+        HashMap::new(),
+        HashMap::new(),
+        HashMap::from([(vuln_api_stub::profile_key("npm", "axios"), body)]),
+        HashMap::new(),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "axios"]);
+    assert_eq!(out.status.code(), Some(1), "stderr: {}", stderr(&out));
+    let s = stdout(&out);
+    assert!(s.contains("GHSA-aaaa-bbbb-cccc"), "stdout: {s}");
+    assert!(s.contains("MAL-2024-0001"), "stdout: {s}");
+    assert!(s.contains("high"), "stdout: {s}");
+    assert!(s.contains("[malware]"), "stdout: {s}");
+}
+
+#[test]
+fn package_with_advisories_json() {
+    let body = vuln_api_stub::profile_body("npm", "axios", TWO_ADVISORIES);
+    let stub = vuln_api_stub::spawn_with_profiles(
+        HashMap::new(),
+        HashMap::new(),
+        HashMap::from([(vuln_api_stub::profile_key("npm", "axios"), body)]),
+        HashMap::new(),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "axios", "--json"]);
+    assert_eq!(out.status.code(), Some(1), "stderr: {}", stderr(&out));
+    let doc: serde_json::Value =
+        serde_json::from_slice(&out.stdout).expect("stdout is a single json document");
+    assert_eq!(doc["schema_version"], 1);
+    assert_eq!(doc["ecosystem"], "npm");
+    assert_eq!(doc["package"], "axios");
+    assert_eq!(doc["found"], true);
+    assert_eq!(doc["advisories"].as_array().unwrap().len(), 2);
+    assert_eq!(doc["advisories"][0]["id"], "GHSA-aaaa-bbbb-cccc");
+    assert_eq!(doc["possibly_truncated"], false);
+}
+
+#[test]
+fn package_with_no_advisories_exits_0() {
+    let body = vuln_api_stub::profile_body("npm", "axios", "[]");
+    let stub = vuln_api_stub::spawn_with_profiles(
+        HashMap::new(),
+        HashMap::new(),
+        HashMap::from([(vuln_api_stub::profile_key("npm", "axios"), body)]),
+        HashMap::new(),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "axios"]);
+    assert_eq!(out.status.code(), Some(0), "stderr: {}", stderr(&out));
+    assert!(
+        stdout(&out).contains("no known advisories"),
+        "stdout: {}",
+        stdout(&out)
+    );
+
+    let out = advisories_check(&stub.base_url, &["npm", "axios", "--json"]);
+    assert_eq!(out.status.code(), Some(0), "stderr: {}", stderr(&out));
+    let doc: serde_json::Value =
+        serde_json::from_slice(&out.stdout).expect("stdout is a single json document");
+    assert_eq!(doc["found"], true);
+    assert_eq!(doc["advisories"].as_array().unwrap().len(), 0);
+}
+
+#[test]
+fn unknown_package_exits_0_with_note() {
+    // Unscripted profile key → 404 → Ok(None), a legitimate "clean" answer.
+    let stub = vuln_api_stub::spawn_with_profiles(
+        HashMap::new(),
+        HashMap::new(),
+        HashMap::new(),
+        HashMap::new(),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "no-such-pkg"]);
+    assert_eq!(out.status.code(), Some(0), "stderr: {}", stderr(&out));
+    assert!(
+        stdout(&out).contains("not found in the advisory database"),
+        "stdout: {}",
+        stdout(&out)
+    );
+
+    let out = advisories_check(&stub.base_url, &["npm", "no-such-pkg", "--json"]);
+    assert_eq!(out.status.code(), Some(0), "stderr: {}", stderr(&out));
+    let doc: serde_json::Value =
+        serde_json::from_slice(&out.stdout).expect("stdout is a single json document");
+    assert_eq!(doc["found"], false);
+    assert_eq!(doc["advisories"].as_array().unwrap().len(), 0);
+}
+
+#[test]
+fn profile_generic_404_exits_2() {
+    // A 404 without the worker's package-miss sentinel (wrong host, older
+    // deployment, proxy/CDN) is an error, not a clean "no advisories" answer.
+    let stub = vuln_api_stub::spawn_with_profiles(
+        HashMap::new(),
+        HashMap::new(),
+        HashMap::new(),
+        HashMap::from([(vuln_api_stub::profile_key("npm", "axios"), 404u16)]),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "axios"]);
+    assert_eq!(out.status.code(), Some(2), "stdout: {}", stdout(&out));
+    assert!(
+        stderr(&out).contains("CORGEA_VULN_API_URL"),
+        "stderr: {}",
+        stderr(&out)
+    );
+}
+
+#[test]
+fn profile_identity_mismatch_exits_2() {
+    let body = vuln_api_stub::profile_body("npm", "left-pad", "[]");
+    let stub = vuln_api_stub::spawn_with_profiles(
+        HashMap::new(),
+        HashMap::new(),
+        HashMap::from([(vuln_api_stub::profile_key("npm", "axios"), body)]),
+        HashMap::new(),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "axios"]);
+    assert_eq!(out.status.code(), Some(2), "stdout: {}", stdout(&out));
+    assert!(
+        stderr(&out).contains("does not match request"),
+        "stderr: {}",
+        stderr(&out)
+    );
+}
+
+#[test]
+fn profile_server_error_exits_2() {
+    let stub = vuln_api_stub::spawn_with_profiles(
+        HashMap::new(),
+        HashMap::new(),
+        HashMap::new(),
+        HashMap::from([(vuln_api_stub::profile_key("npm", "axios"), 500u16)]),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "axios"]);
+    assert_eq!(out.status.code(), Some(2), "stdout: {}", stdout(&out));
+    assert!(
+        stderr(&out).contains("vuln-api unavailable"),
+        "stderr: {}",
+        stderr(&out)
+    );
+}
+
+#[test]
+fn exactly_100_advisories_flags_possible_truncation() {
+    let advisories: Vec<String> = (0..100)
+        .map(|i| format!(r#"{{"id":"GHSA-{i:04}","severity":"high"}}"#))
+        .collect();
+    let arr = format!("[{}]", advisories.join(","));
+    let body = vuln_api_stub::profile_body("npm", "axios", &arr);
+    let stub = vuln_api_stub::spawn_with_profiles(
+        HashMap::new(),
+        HashMap::new(),
+        HashMap::from([(vuln_api_stub::profile_key("npm", "axios"), body)]),
+        HashMap::new(),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "axios"]);
+    assert_eq!(out.status.code(), Some(1), "stderr: {}", stderr(&out));
+    assert!(
+        stdout(&out).contains("listing capped at 100; more may exist"),
+        "stdout: {}",
+        stdout(&out)
+    );
+
+    let out = advisories_check(&stub.base_url, &["npm", "axios", "--json"]);
+    let doc: serde_json::Value =
+        serde_json::from_slice(&out.stdout).expect("stdout is a single json document");
+    assert_eq!(doc["possibly_truncated"], true);
+
+    // A 2-advisory case must NOT flag truncation.
+    let body = vuln_api_stub::profile_body("npm", "small", TWO_ADVISORIES);
+    let stub = vuln_api_stub::spawn_with_profiles(
+        HashMap::new(),
+        HashMap::new(),
+        HashMap::from([(vuln_api_stub::profile_key("npm", "small"), body)]),
+        HashMap::new(),
+    );
+    let out = advisories_check(&stub.base_url, &["npm", "small", "--json"]);
+    let doc: serde_json::Value =
+        serde_json::from_slice(&out.stdout).expect("stdout is a single json document");
+    assert_eq!(doc["possibly_truncated"], false);
+}
diff --git a/tests/fixtures/vuln_api/README.md b/tests/fixtures/vuln_api/README.md
index 1731924..c9b1cee 100644
--- a/tests/fixtures/vuln_api/README.md
+++ b/tests/fixtures/vuln_api/README.md
@@ -11,6 +11,12 @@ Committed JSON bodies matching the authoritative server serialization
 | `check_vulnerable.json` | one advisory with `fixed_version` remediation |
 | `check_malware.json` | `MAL-*` advisory, no version range, no fix, `malware: true` wire flag |
 | `check_unknown.json` | unknown package — `/check` answers 200 clean, not 404 |
+| `package_profile.json` | `/v1/packages/:eco/:name` profile — full server serialization (all 14 `formatAdvisorySummary` fields + full `package` block), two advisories (GHSA + `MAL-*`) |
+| `package_profile_not_found.json` | profile route 404 body — `{"error":"Package not found"}` |
+
+The profile fixtures track `packageProfileHandler` (vuln-api repo:
+`cve_worker/src/worker.js`, ~lines 484-541); the CLI deserializes a tolerant
+subset and ignores the extra fields.
 
 ## Deterministic staging targets
 
diff --git a/tests/fixtures/vuln_api/package_profile.json b/tests/fixtures/vuln_api/package_profile.json
new file mode 100644
index 0000000..597ca88
--- /dev/null
+++ b/tests/fixtures/vuln_api/package_profile.json
@@ -0,0 +1,47 @@
+{
+  "package": {
+    "ecosystem": "npm",
+    "name": "axios",
+    "purl": "pkg:npm/axios",
+    "registry_url": "https://www.npmjs.com/package/axios",
+    "metadata_url": "https://registry.npmjs.org/axios",
+    "downloads_30d": 1234567890,
+    "downloads_total": 98765432100,
+    "popularity_rank": 12,
+    "last_metadata_sync_at": "2026-07-16T00:00:00Z"
+  },
+  "advisories": [
+    {
+      "id": "GHSA-xxxx-yyyy-zzzz",
+      "alias": "CVE-2023-45857",
+      "ecosystem": "npm",
+      "summary": "axios is vulnerable to Server-Side Request Forgery when following a redirect to a crafted URL, leaking sensitive data.",
+      "severity": "high",
+      "severity_badge": "High",
+      "cvss_score": 7.5,
+      "tier": 1,
+      "tier_score": 92,
+      "kev": false,
+      "malware": false,
+      "published_at": "2023-01-12T00:00:00Z",
+      "modified_at": "2023-06-01T00:00:00Z",
+      "llm_summary": "SSRF via redirect; upgrade to a patched release."
+    },
+    {
+      "id": "MAL-2024-0001",
+      "alias": null,
+      "ecosystem": "npm",
+      "summary": "Malicious code detected in this package version; exfiltrates environment variables on install.",
+      "severity": "critical",
+      "severity_badge": "Critical",
+      "cvss_score": null,
+      "tier": 0,
+      "tier_score": null,
+      "kev": false,
+      "malware": true,
+      "published_at": "2024-03-01T00:00:00Z",
+      "modified_at": "2024-03-02T00:00:00Z",
+      "llm_summary": null
+    }
+  ]
+}
diff --git a/tests/fixtures/vuln_api/package_profile_not_found.json b/tests/fixtures/vuln_api/package_profile_not_found.json
new file mode 100644
index 0000000..b6fb94d
--- /dev/null
+++ b/tests/fixtures/vuln_api/package_profile_not_found.json
@@ -0,0 +1 @@
+{"error":"Package not found"}
diff --git a/tests/vuln_api_contract.rs b/tests/vuln_api_contract.rs
index c27a692..3db206b 100644
--- a/tests/vuln_api_contract.rs
+++ b/tests/vuln_api_contract.rs
@@ -16,8 +16,13 @@
 
 mod common;
 
-use corgea::vuln_api::{check_package_version, http_client, Ecosystem, VulnCheckResponse};
-use corgea::vuln_api_stub::{key, spawn_with_statuses, vulnerable_body};
+use corgea::vuln_api::{
+    check_package_version, fetch_package_profile, http_client, Ecosystem, PackageProfile,
+    VulnCheckResponse,
+};
+use corgea::vuln_api_stub::{
+    key, profile_key, spawn_with_profiles, spawn_with_statuses, vulnerable_body,
+};
 use std::collections::HashMap;
 
 const STAGING_URL: &str = "https://cve-worker-staging.corgea.workers.dev";
@@ -124,6 +129,41 @@ fn stub_server_error_surfaces_as_unavailable() {
     assert!(err.to_string().contains("unavailable (HTTP 503)"));
 }
 
+#[test]
+fn fixture_package_profile_deserializes() {
+    // The committed profile fixture (full server serialization) must
+    // deserialize into the CLI's tolerant subset — ignored fields and all.
+    let parsed: PackageProfile =
+        serde_json::from_str(&fixture_body("package_profile.json")).expect("parse profile fixture");
+    assert_eq!(parsed.package.ecosystem, "npm");
+    assert_eq!(parsed.package.name, "axios");
+    assert_eq!(parsed.advisories.len(), 2);
+    assert!(parsed.advisories.iter().any(|a| a.malware == Some(true)));
+}
+
+#[test]
+fn stub_profile_roundtrip_and_not_found() {
+    let stub = spawn_with_profiles(
+        HashMap::new(),
+        HashMap::new(),
+        HashMap::from([(
+            profile_key("npm", "axios"),
+            fixture_body("package_profile.json"),
+        )]),
+        HashMap::new(),
+    );
+    let client = http_client().expect("client");
+    let profile = fetch_package_profile(&client, &stub.base_url, None, Ecosystem::Npm, "axios")
+        .unwrap()
+        .expect("known package should be Some");
+    assert_eq!(profile.advisories.len(), 2);
+
+    let missing =
+        fetch_package_profile(&client, &stub.base_url, None, Ecosystem::Npm, "no-such-pkg")
+            .unwrap();
+    assert!(missing.is_none(), "unknown package profile is Ok(None)");
+}
+
 // ---- staging (network, deterministic targets) ----
 
 fn assert_staging_vulnerable(ecosystem: Ecosystem, name: &str, version: &str) {
@@ -163,6 +203,24 @@ fn staging_mezzanine_6_0_0_is_vulnerable() {
     assert_staging_vulnerable(Ecosystem::Pypi, "mezzanine", "6.0.0");
 }
 
+#[test]
+#[ignore = "network: hits the staging vuln-api"]
+fn staging_unknown_package_profile_is_not_found() {
+    // Pins the worker's package-miss sentinel body: fetch_package_profile
+    // maps a 404 to Ok(None) only when it carries {"error":"Package not
+    // found"}, so this fails if the worker ever changes that body.
+    let client = http_client().expect("client");
+    let missing = fetch_package_profile(
+        &client,
+        STAGING_URL,
+        None,
+        Ecosystem::Npm,
+        "corgea-contract-test-nonexistent",
+    )
+    .unwrap();
+    assert!(missing.is_none(), "sentinel 404 should map to Ok(None)");
+}
+
 #[test]
 #[ignore = "network: hits the staging vuln-api"]
 fn staging_unknown_package_is_clean() {
@@ -176,3 +234,31 @@ fn staging_unknown_package_is_clean() {
     assert!(!verdict.is_vulnerable);
     assert!(verdict.matches.is_empty());
 }
+
+#[test]
+#[ignore = "network: hits the staging vuln-api"]
+fn staging_axios_profile_lists_advisories() {
+    let client = http_client().expect("client");
+    let profile = fetch_package_profile(&client, STAGING_URL, None, Ecosystem::Npm, "axios")
+        .unwrap()
+        .expect("axios should have a profile row");
+    assert!(
+        !profile.advisories.is_empty(),
+        "axios profile should list advisories"
+    );
+}
+
+#[test]
+#[ignore = "network: hits the staging vuln-api"]
+fn staging_unknown_package_profile_is_none() {
+    let client = http_client().expect("client");
+    let profile = fetch_package_profile(
+        &client,
+        STAGING_URL,
+        None,
+        Ecosystem::Npm,
+        "corgea-contract-test-nonexistent",
+    )
+    .unwrap();
+    assert!(profile.is_none(), "unknown package profile is Ok(None)");
+}