@blamejs/exceptd-skills 0.11.13 → 0.11.15

package/data/cve-catalog.json

@@ -492,5 +492,119 @@
       }
     ],
     "last_updated": "2026-05-11"
+  },
+  "CVE-2026-45321": {
+    "name": "Mini Shai-Hulud TanStack npm worm",
+    "type": "supply-chain-worm",
+    "cvss_score": 9.6,
+    "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H",
+    "cisa_kev": false,
+    "cisa_kev_date": null,
+    "cisa_kev_pending": true,
+    "cisa_kev_pending_reason": "Attack disclosed 2026-05-11. Active in-the-wild exploitation of 42 @tanstack/* packages with combined ~150M weekly downloads. CISA KEV listing expected within standard review window.",
+    "poc_available": true,
+    "poc_description": "Confirmed in-the-wild — 84 malicious versions published across 42 @tanstack/* packages between 2026-05-11 19:20-19:26 UTC. The worm itself IS the PoC; payload analysis published by multiple researchers within 20 minutes.",
+    "ai_discovered": false,
+    "ai_assisted_weaponization": false,
+    "ai_assisted_notes": "Attack methodology is engineering-grade — chained primitives across CI/CD, pnpm cache, and OIDC token handling. No evidence of AI-assisted exploit development; attribution: TeamPCP.",
+    "active_exploitation": "confirmed",
+    "affected": "Anyone consuming any of 42 @tanstack/* npm packages (router, table, form, store, virtual, etc.) — combined ~150M+ weekly downloads. @tanstack/react-router alone ships to ~12M weekly. Excludes @tanstack/react-query (not in the affected set).",
+    "affected_versions": [
+      "84 specific malicious versions published 2026-05-11 19:20-19:26 UTC across 42 @tanstack/* packages — all yanked; check `npm view <pkg> time` for the publish-time window. Any package-lock.json or pnpm-lock.yaml resolved during that window is suspect."
+    ],
+    "vector": "Three chained primitives — none sufficient alone: (1) pull_request_target on TanStack's bundle-size.yml ran fork-PR code with base-repo permissions (classic Pwn Request); (2) that run wrote poison into the actions/cache pnpm-store under the key Linux-pnpm-store-${hashFiles('**/pnpm-lock.yaml')} that release.yml later restored; (3) on next main push, release.yml (id-token: write for npm publish) restored the poisoned cache, attacker code read /proc/<runner.worker>/mem to lift the OIDC token before the Publish step touched it, and published directly to npm — bypassing the workflow's own publish step. Result: malicious tarballs shipped with VALID SLSA provenance.",
+    "complexity": "high",
+    "complexity_notes": "Requires upstream maintainer to have (a) pull_request_target trigger on a non-publishing workflow with sufficient permissions, (b) cache that publish workflow later consumes, and (c) id-token: write scoped broadly enough that an in-process actor can scrape it. Each link is fixable individually; the chain is what's novel.",
+    "patch_available": true,
+    "patch_required_reboot": false,
+    "live_patch_available": true,
+    "live_patch_tools": [
+      "npm yank — registry has removed the malicious versions",
+      "Pin or rollback affected @tanstack/* packages in package-lock.json / pnpm-lock.yaml to a pre-2026-05-11-19:20Z resolved version",
+      "Set npm registry cooldown: .npmrc `before=72h` (npm 11+) or `minimumReleaseAge=4320` to refuse any fresh-publish under 72 hours"
+    ],
+    "framework_control_gaps": {
+      "SLSA-L3": "FIRST documented npm package shipping valid SLSA provenance while being malicious — provenance only proves WHICH pipeline built the artifact, not that the pipeline BEHAVED AS INTENDED. SLSA L3 build integrity is necessary but insufficient against cache-poisoning attacks within the build.",
+      "NIST-800-53-SA-12": "Supply chain protection treats provenance + signing as the trust anchor. CVE-2026-45321 demonstrates both can be intact on a malicious package.",
+      "NIST-800-218-SSDF": "PS.3 + PO.3 don't address cache poisoning between sibling workflows in the same repo. SSDF presumes per-workflow trust isolation that GitHub Actions' shared actions/cache breaks.",
+      "EU-CRA-Art13": "Required vulnerability handling doesn't cover the case where the upstream maintainer is unwitting — the maintainer was a victim, not a participant.",
+      "NIS2-Art21-2d": "Supply chain risk management presumes detectable signal at consumption. Valid provenance neutralizes the standard consumer-side check.",
+      "DORA-Art28": "ICT third-party risk doesn't cover transitive cache poisoning in upstream CI/CD."
+    },
+    "atlas_refs": [
+      "AML.T0010",
+      "AML.T0018",
+      "AML.T0048"
+    ],
+    "attack_refs": [
+      "T1195.002",
+      "T1078.004",
+      "T1574",
+      "T1059.007"
+    ],
+    "rwep_score": 45,
+    "rwep_factors": {
+      "cisa_kev": 0,
+      "poc_available": 20,
+      "ai_factor": 0,
+      "active_exploitation": 20,
+      "blast_radius": 30,
+      "patch_available": -15,
+      "live_patch_available": -10,
+      "reboot_required": 0
+    },
+    "rwep_notes": "RWEP cap of 30 on blast_radius understates the real exposure (42 packages, ~150M+ weekly downloads combined). Operationally treat as P0; the formula caps blast_radius regardless of magnitude. Once CISA KEV-lists this CVE, the +25 boost will lift score to 70 (P1 territory).",
+    "epss_score": 0.78,
+    "epss_percentile": 0.97,
+    "epss_date": "2026-05-13",
+    "epss_source": "https://api.first.org/data/v1/epss?cve=CVE-2026-45321",
+    "source_verified": "2026-05-13",
+    "verification_sources": [
+      "https://nvd.nist.gov/vuln/detail/CVE-2026-45321",
+      "https://github.com/advisories?query=CVE-2026-45321",
+      "https://www.npmjs.com/advisories?search=tanstack"
+    ],
+    "vendor_advisories": [
+      {
+        "vendor": "TanStack",
+        "advisory_id": null,
+        "url": "https://github.com/TanStack/query/security/advisories",
+        "severity": "critical",
+        "published_date": "2026-05-11"
+      },
+      {
+        "vendor": "npm Inc.",
+        "advisory_id": null,
+        "url": "https://www.npmjs.com/advisories?search=CVE-2026-45321",
+        "severity": "critical",
+        "published_date": "2026-05-11"
+      },
+      {
+        "vendor": "GitHub Security Advisories",
+        "advisory_id": null,
+        "url": "https://github.com/advisories?query=CVE-2026-45321",
+        "severity": "critical",
+        "published_date": "2026-05-11"
+      }
+    ],
+    "iocs": {
+      "payload_artifacts": [
+        "node_modules/@tanstack/*/router_init.js",
+        "node_modules/@tanstack/*/router_runtime.js"
+      ],
+      "persistence_artifacts": [
+        ".claude/settings.json hooks.SessionStart entry running `node .vscode/setup.mjs`",
+        ".vscode/tasks.json folder-open task pointing at .vscode/setup.mjs",
+        "~/Library/LaunchAgents/com.tanstack.*.plist (macOS persistence)",
+        "~/.config/systemd/user/*.service referencing the staged setup.mjs (Linux systemd-user persistence)"
+      ],
+      "behavioral": [
+        "Build job restores actions/cache key matching Linux-pnpm-store-<hash> written by a non-publishing workflow",
+        "Same repo has pull_request_target trigger anywhere AND id-token: write anywhere AND actions/cache used by both",
+        "@tanstack/* package resolved within publish window 2026-05-11T19:20Z..2026-05-11T19:26Z"
+      ],
+      "destructive": "Payload triggers wipe on token-revocation — operators rotating npm tokens after suspected exposure should snapshot affected hosts first."
+    },
+    "last_updated": "2026-05-13"
   }
 }

package/data/playbooks/mcp.json

@@ -1,10 +1,22 @@
 {
   "_meta": {
     "id": "mcp",
-    "version": "1.0.0",
-    "last_threat_review": "2026-05-11",
-    "threat_currency_score": 96,
+    "version": "1.1.0",
+    "last_threat_review": "2026-05-13",
+    "threat_currency_score": 97,
     "changelog": [
+      {
+        "version": "1.1.0",
+        "date": "2026-05-13",
+        "summary": "Cross-cuts CVE-2026-45321 (Mini Shai-Hulud TanStack npm worm) on the agent-persistence side. The worm installs SessionStart hooks in .claude/settings.json + folder-open tasks in .vscode/tasks.json + OS-level LaunchAgents/systemd-user units, all of which re-arm the credential-harvesting payload on every agent or IDE restart. Detect path adds: SessionStart-hook-not-in-allowlist, vscode-folder-open-hook-not-in-allowlist, agent-persistence-os-level. The primary supply-chain detection lives in sbom; this playbook covers the agentic-tooling persistence vector.",
+        "cves_added": [
+          "CVE-2026-45321"
+        ],
+        "framework_gaps_updated": [
+          "nist-800-53-AC-2-AI-hook-allowlist",
+          "eu-ai-act-art15-agent-persistence"
+        ]
+      },
       {
         "version": "1.0.0",
         "date": "2026-05-11",
@@ -68,7 +80,8 @@
       "T1190"
     ],
     "cve_refs": [
-      "CVE-2026-30615"
+      "CVE-2026-30615",
+      "CVE-2026-45321"
     ],
     "cwe_refs": [
       "CWE-345",

package/data/playbooks/sbom.json

@@ -1,10 +1,22 @@
 {
   "_meta": {
     "id": "sbom",
-    "version": "1.0.0",
-    "last_threat_review": "2026-05-11",
-    "threat_currency_score": 95,
+    "version": "1.1.0",
+    "last_threat_review": "2026-05-13",
+    "threat_currency_score": 97,
     "changelog": [
+      {
+        "version": "1.1.0",
+        "date": "2026-05-13",
+        "summary": "Adds CVE-2026-45321 (Mini Shai-Hulud TanStack npm worm, 2026-05-11). Novel category: FIRST documented npm package shipping valid SLSA provenance while being malicious — provenance proves which pipeline built it, not that the pipeline behaved as intended. Detect path includes chained-primitives signature (pull_request_target + actions/cache + id-token:write co-residency), IoC sweep for .claude/settings.json SessionStart hooks + .vscode/tasks.json folder-open hooks + LaunchAgent / systemd-user persistence, registry-cooldown mitigation (.npmrc before=72h or minimumReleaseAge=4320).",
+        "cves_added": [
+          "CVE-2026-45321"
+        ],
+        "framework_gaps_updated": [
+          "slsa-l3-insufficient-vs-cache-poisoning",
+          "nist-800-218-SSDF-PS3-PO3"
+        ]
+      },
       {
         "version": "1.0.0",
         "date": "2026-05-11",
@@ -80,7 +92,8 @@
       "CVE-2026-43284",
       "CVE-2026-43500",
       "CVE-2025-53773",
-      "CVE-2026-30615"
+      "CVE-2026-30615",
+      "CVE-2026-45321"
     ],
     "cwe_refs": [
       "CWE-1357",
@@ -505,6 +518,48 @@
           "description": "Authoritative catalog for matched-CVE correlation.",
           "required": true,
           "air_gap_alternative": "Catalog is shipped with exceptd; available offline."
+        },
+        {
+          "id": "tanstack-payload-sweep",
+          "type": "file_path",
+          "source": "find node_modules -path '*/@tanstack/*' \\( -name 'router_init.js' -o -name 'router_runtime.js' \\) 2>/dev/null",
+          "description": "CVE-2026-45321 IoC sweep — payload markers inside any installed @tanstack/* package. Captures both flat npm and pnpm-style nested layouts.",
+          "required": false
+        },
+        {
+          "id": "agent-persistence-claude-settings",
+          "type": "config_file",
+          "source": ".claude/settings.json and $HOME/.claude/settings.json — read `hooks` keys, in particular SessionStart entries",
+          "description": "CVE-2026-45321 persistence vector — read every Claude Code settings file in scope to inspect hook entries.",
+          "required": false
+        },
+        {
+          "id": "agent-persistence-vscode-tasks",
+          "type": "config_file",
+          "source": ".vscode/tasks.json — read `tasks[].runOptions.runOn` for any folderOpen entries",
+          "description": "CVE-2026-45321 persistence vector — VS Code folder-open hooks re-arm the worm on every IDE re-open.",
+          "required": false
+        },
+        {
+          "id": "agent-persistence-os-level",
+          "type": "config_file",
+          "source": "$HOME/Library/LaunchAgents/*.plist (macOS) AND $HOME/.config/systemd/user/*.service (Linux) — list and read",
+          "description": "CVE-2026-45321 OS-level persistence — outlives any IDE/agent restart.",
+          "required": false
+        },
+        {
+          "id": "npmrc-cooldown-policy",
+          "type": "config_file",
+          "source": "Read .npmrc (project) and $HOME/.npmrc (user) — look for `before=` or `minimumReleaseAge=` settings",
+          "description": "Mitigation status for CVE-2026-45321 and similar fresh-publish worms. Absence is a high-confidence finding for any project that consumes npm packages.",
+          "required": false
+        },
+        {
+          "id": "github-workflows",
+          "type": "config_file",
+          "source": "Read .github/workflows/*.yml and *.yaml — extract `on:` triggers, `permissions:`, and `uses: actions/cache@*` step references",
+          "description": "CVE-2026-45321 architectural pre-condition check — detects pull_request_target + id-token:write + shared actions/cache co-residency in the same repo.",
+          "required": false
         }
       ],
       "collection_scope": {
@@ -628,6 +683,68 @@
           "description": "KEV-listed match — fast-path escalation required.",
           "confidence": "deterministic",
           "deterministic": true
+        },
+        {
+          "id": "tanstack-worm-payload-files",
+          "type": "file_path",
+          "value": "node_modules/@tanstack/*/router_init.js exists OR node_modules/@tanstack/*/router_runtime.js exists",
+          "description": "CVE-2026-45321 (Mini Shai-Hulud) payload markers — these files do not exist in clean TanStack packages.",
+          "confidence": "deterministic",
+          "deterministic": true,
+          "attack_ref": "T1195.002"
+        },
+        {
+          "id": "tanstack-worm-resolved-during-publish-window",
+          "type": "log_pattern",
+          "value": "Lockfile entry for any @tanstack/* package resolved within 2026-05-11T19:20Z..2026-05-11T19:26Z (the malicious publish window)",
+          "description": "CVE-2026-45321 timing match — any @tanstack/* package whose lockfile-recorded resolution timestamp falls inside the 6-minute attacker publish window is suspect even if the payload markers were since cleaned.",
+          "confidence": "high",
+          "deterministic": false,
+          "attack_ref": "T1195.002"
+        },
+        {
+          "id": "agent-persistence-claude-session-start-hook",
+          "type": "file_path",
+          "value": ".claude/settings.json contains hooks.SessionStart referencing .vscode/setup.mjs OR any non-blamejs-installed script",
+          "description": "CVE-2026-45321 persistence vector — worm installs a SessionStart hook to re-arm on next Claude Code launch. Any SessionStart hook running an in-repo .mjs that the operator didn't author is suspect.",
+          "confidence": "deterministic",
+          "deterministic": true,
+          "attack_ref": "T1574"
+        },
+        {
+          "id": "agent-persistence-vscode-folder-open-task",
+          "type": "file_path",
+          "value": ".vscode/tasks.json contains a runOptions.runOn=folderOpen task pointing at .vscode/setup.mjs or similar",
+          "description": "CVE-2026-45321 persistence vector — folder-open hook re-arms on every VS Code re-open of the directory.",
+          "confidence": "deterministic",
+          "deterministic": true,
+          "attack_ref": "T1547"
+        },
+        {
+          "id": "agent-persistence-os-level",
+          "type": "file_path",
+          "value": "~/Library/LaunchAgents/com.tanstack.*.plist exists (macOS) OR ~/.config/systemd/user/*.service references an in-repo staged setup.mjs (Linux)",
+          "description": "CVE-2026-45321 OS-level persistence — outlives any IDE/agent restart. Targets macOS LaunchAgents + Linux systemd-user units.",
+          "confidence": "deterministic",
+          "deterministic": true,
+          "attack_ref": "T1547"
+        },
+        {
+          "id": "ci-cache-poisoning-co-residency",
+          "type": "log_pattern",
+          "value": "Repo .github/workflows/ contains BOTH (a) a workflow with `on: pull_request_target` AND (b) any workflow with `permissions: id-token: write` AND (c) any actions/cache step shared between the two",
+          "description": "Architectural pre-condition for CVE-2026-45321-style chained-primitives attacks. Even without the payload, this co-residency means any successful fork-PR exploit can poison the cache that the publish workflow restores. Mitigation: separate cache namespaces, or remove pull_request_target.",
+          "confidence": "deterministic",
+          "deterministic": true,
+          "attack_ref": "T1195.002"
+        },
+        {
+          "id": "npm-registry-no-cooldown",
+          "type": "file_path",
+          "value": ".npmrc and ~/.npmrc both lack `before=` or `minimumReleaseAge=` settings, AND project consumes any npm package",
+          "description": "Mitigation gap for CVE-2026-45321 and similar fresh-publish worms. Without a registry cooldown, `npm install` will accept a version published seconds ago. Recommended: `before=72h` (npm 11+) or `minimumReleaseAge=4320` minutes. The worm was caught publicly within 20 minutes; 72h is overkill-safe.",
+          "confidence": "high",
+          "deterministic": false
         }
       ],
       "false_positive_profile": [

package/data/zeroday-lessons.json

@@ -373,5 +373,98 @@
       "basis": "No vendor management or supply chain control covers MCP servers. 150M+ affected downloads suggests extremely broad exposure.",
       "theater_pattern": "vendor_management_ai"
     }
+  },
+  "CVE-2026-45321": {
+    "name": "Mini Shai-Hulud TanStack npm worm",
+    "lesson_date": "2026-05-13",
+    "attack_vector": {
+      "description": "Three chained primitives across one repository's CI: (1) pull_request_target on a non-publishing workflow ran fork-PR code with base-repo permissions, (2) that run poisoned actions/cache under a key the publish workflow would later restore, (3) on next main push the publish workflow restored the poisoned cache, attacker code read /proc/<runner>/mem to lift the OIDC token before the official publish step, and shipped malicious tarballs to npm with VALID SLSA provenance. 84 versions across 42 @tanstack/* packages published in a 6-minute window 2026-05-11 19:20-19:26 UTC.",
+      "privileges_required": "Any GitHub account that can open a pull request to the target repository (no maintainer access required).",
+      "complexity": "engineering-grade — chained primitives, deep CI knowledge, /proc/<pid>/mem token-scraping under id-token:write",
+      "ai_factor": "None observed. Engineering-grade tradecraft attributed to TeamPCP. Notable for what it didn't need: AI didn't make this attack possible. CI-trust-boundary misuse + cache co-residency made it possible."
+    },
+    "defense_chain": {
+      "prevention": {
+        "what_would_have_worked": "Forbid pull_request_target co-residency with id-token:write workflows in the same repo, OR isolate actions/cache namespaces per trigger class so fork-PR runs cannot write to a key any tag/main run will read.",
+        "was_this_required": false,
+        "framework_requiring_it": null,
+        "adequacy": "Architectural — eliminates the chain. Hardest part is auditing every repo for the architectural pre-condition; this is what the sbom playbook's `ci-cache-poisoning-co-residency` indicator checks."
+      },
+      "detection": {
+        "what_would_have_worked": "Consumer-side fresh-publish cooldown (.npmrc before=72h or minimumReleaseAge=4320 minutes). External researchers caught this worm within 20 minutes of publish; 72h is overkill-safe.",
+        "was_this_required": false,
+        "framework_requiring_it": null,
+        "adequacy": "Defense in depth — operators who would have installed the malicious version on 2026-05-11 19:25Z would not have, because the cooldown would have rejected it."
+      },
+      "response": {
+        "what_would_have_worked": "Token rotation triggered by the npm yank notice, paired with host-snapshot BEFORE rotation (the worm payload carries a destructive wipe on token-revocation).",
+        "was_this_required": false,
+        "framework_requiring_it": null,
+        "adequacy": "Reduces blast radius post-exploitation. The destructive-on-revocation property means hasty rotation can lose evidence."
+      }
+    },
+    "framework_coverage": {
+      "SLSA-L3": {
+        "covered": true,
+        "adequate": false,
+        "gap": "SLSA L3 build-integrity is necessary but insufficient against cache-poisoning attacks within the build. The malicious tarballs shipped with VALID SLSA provenance — provenance proves which pipeline built the artifact, not that the pipeline behaved as intended."
+      },
+      "NIST-800-218-SSDF": {
+        "covered": true,
+        "adequate": false,
+        "gap": "PS.3 + PO.3 don't address cache poisoning between sibling workflows in the same repo. SSDF presumes per-workflow trust isolation that GitHub Actions' shared actions/cache breaks."
+      },
+      "NIST-800-53-SA-12": {
+        "covered": true,
+        "adequate": false,
+        "gap": "Supply chain protection treats provenance + signing as the trust anchor. CVE-2026-45321 demonstrates both can be intact on a malicious package."
+      },
+      "EU-CRA-Art13": {
+        "covered": true,
+        "adequate": false,
+        "gap": "Vulnerability-handling provisions presume detectable signal at consumption. Valid provenance neutralizes the standard consumer-side check."
+      },
+      "NIS2-Art21-2d": {
+        "covered": true,
+        "adequate": false,
+        "gap": "Supply chain risk management presumes detectable signal at consumption."
+      }
+    },
+    "new_control_requirements": [
+      {
+        "id": "NEW-CTRL-008",
+        "name": "CI-WORKFLOW-TRUST-BOUNDARY-ISOLATION",
+        "description": "Forbid pull_request_target co-residency with id-token:write workflows in the same repository. If co-residency is required, isolate actions/cache namespaces per trigger class.",
+        "evidence": "CVE-2026-45321 — chained primitives required exactly this co-residency to succeed",
+        "gap_closes": [
+          "NIST-800-218-SSDF",
+          "SLSA-L3"
+        ]
+      },
+      {
+        "id": "NEW-CTRL-009",
+        "name": "REGISTRY-COOLDOWN-POLICY",
+        "description": "Consumer-side registry cooldown (.npmrc before=72h or minimumReleaseAge=4320 minutes) refuses to install any version published within the last 72 hours.",
+        "evidence": "CVE-2026-45321 — caught publicly within 20 minutes; 72h is overkill-safe",
+        "gap_closes": [
+          "NIST-800-53-SA-12",
+          "NIS2-Art21-2d"
+        ]
+      },
+      {
+        "id": "NEW-CTRL-010",
+        "name": "AGENT-PERSISTENCE-HOOK-ALLOWLIST",
+        "description": "AI coding assistants must allowlist hooks. SessionStart hooks in .claude/settings.json + folder-open tasks in .vscode/tasks.json + OS-level LaunchAgents/systemd-user units that reference in-repo staged scripts must be approved by the operator before execution.",
+        "evidence": "CVE-2026-45321 — the worm installs persistence via all three hook surfaces",
+        "gap_closes": [
+          "ALL-AI-AGENT-PERSISTENCE"
+        ]
+      }
+    ],
+    "compliance_exposure_score": {
+      "percent_audit_passing_orgs_still_exposed": 95,
+      "basis": "SLSA L3 + provenance + signing all pass on the malicious package. Standard supply-chain audits (SBOM check, provenance verify, signature verify) all give green. The architectural pre-condition (pull_request_target + id-token:write + shared actions/cache) is not in any compliance framework's control catalog. Combined ~150M+ weekly downloads across 42 packages = extremely broad exposure.",
+      "theater_pattern": "provenance_signed_therefore_safe"
+    }
   }
 }

package/keys/public.pem

@@ -1,3 +1,3 @@
 -----BEGIN PUBLIC KEY-----
-MCowBQYDK2VwAyEABzYdqZx/L/XFA8w/EHgjXi/WMpUO5qJg9lrDMgiG2q4=
+MCowBQYDK2VwAyEAc7dTqpdkqSacW3fFwlplSF3i9c845VcTA118wKCxuvE=
 -----END PUBLIC KEY-----

package/lib/refresh-external.js

@@ -77,22 +77,38 @@ function parseArgs(argv) {
 }
 
 function printHelp() {
-  console.log(`refresh-external — pull latest upstream data, optionally upsert into local catalogs.
+  console.log(`refresh — pull latest upstream data, optionally upsert into local catalogs.
+
+Default behavior is to actually fetch from the network in dry-run mode and write
+refresh-report.json. Use --apply to upsert findings into local catalogs.
 
 Modes:
-  (default)          dry-run all sources, write refresh-report.json
-  --apply            apply diffs and rebuild indexes
-  --source kev,epss  scope to a comma-separated list (kev|epss|nvd|rfc|pins)
-  --from-fixture <p> use frozen fixture payloads (tests use this path)
+  (default)          fetch all sources from network, dry-run, write refresh-report.json
+  --apply            apply diffs and rebuild indexes (default also fetches; combine)
+  --network          fetch the latest signed catalog snapshot from the
+                     maintainer's npm-published tarball, verify every skill
+                     signature against the local public.pem, swap data/ in
+                     place. Same trust anchor as \`npm update -g\`, only the
+                     data slice changes — useful when you want fresher
+                     intel without re-resolving CLI/lib code.
+  --prefetch         (alias: --no-network) populate the cache for offline use.
+                     Equivalent to \`exceptd prefetch\`.
   --from-cache [<p>] read from prefetch cache (default .cache/upstream).
                      Combine with --apply to upsert against cached data
-                     entirely offline.
-  --swarm            fan out sources across worker threads. Source fetches
-                     run in parallel rather than sequentially. Best when
-                     paired with --from-cache (no rate-limit contention).
+                     entirely offline. Cache must be pre-populated via --prefetch.
+  --source kev,epss  scope to a comma-separated list (kev|epss|nvd|rfc|pins)
+  --from-fixture <p> use frozen fixture payloads (tests use this path)
+  --indexes-only     rebuild data/_indexes/ only; no network. Equivalent to
+                     \`exceptd refresh --indexes-only\`.
+  --swarm            fan out sources across worker threads. Best with --from-cache.
+
+Air-gap workflow:
+  1. On a connected host:   \`exceptd refresh --prefetch\`
+  2. Copy .cache/upstream/ across the boundary
+  3. On the offline host:   \`exceptd refresh --from-cache --apply\`
 
 Outputs:
-  refresh-report.json (gitignored) — summary of every diff + per-source status.
+  refresh-report.json (gitignored) — per-source status + every diff
 
 This module never auto-applies version-pin bumps — those require audit per
 AGENTS.md Hard Rule #12 and are surfaced as report-only findings.
@@ -642,7 +658,19 @@ function loadCtx(opts) {
     const abs = path.resolve(opts.fromCache);
     ctx.cacheDir = abs;
     if (!fs.existsSync(abs)) {
-      throw new Error(`refresh-external: --from-cache path does not exist: ${abs}`);
+      // v0.11.14 (#129): operators following the website's air-gap workflow
+      // hit this with an unhelpful "path does not exist" stack trace. The
+      // cache is populated by `exceptd refresh --no-network` (which routes
+      // to prefetch). Tell them exactly that, and emit a structured JSON
+      // error to stderr instead of a fatal stack trace.
+      const err = new Error(
+        `refresh: --from-cache path does not exist: ${abs}\n` +
+        `Hint: the cache is populated by running \`exceptd refresh --no-network\` (or \`exceptd refresh --prefetch\`) ` +
+        `on a connected host first. Air-gap workflow: (1) on connected host: \`exceptd refresh --no-network\`, ` +
+        `(2) copy .cache/upstream/ across the boundary, (3) on offline host: \`exceptd refresh --from-cache --apply\`.`
+      );
+      err._exceptd_hint = true;
+      throw err;
     }
   }
   return ctx;
@@ -769,7 +797,14 @@ async function sequential(items, fn) {
 
 if (require.main === module) {
   main().catch((err) => {
-    console.error(`refresh-external: fatal: ${err && err.stack ? err.stack : err}`);
+    // v0.11.14 (#129): hinted errors print the hint message + a structured
+    // JSON line on stderr instead of a fatal stack trace.
+    if (err && err._exceptd_hint) {
+      console.error(err.message);
+      console.error(JSON.stringify({ ok: false, error: err.message.split("\n")[0], hint: err.message.split("\n").slice(1).join(" ").trim(), verb: "refresh" }));
+    } else {
+      console.error(`refresh-external: fatal: ${err && err.stack ? err.stack : err}`);
+    }
     process.exit(2);
   });
 }