@blamejs/exceptd-skills 0.11.13 → 0.11.14

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.11.14 — 2026-05-13
+
+**Patch: items 129-134 + freshness surface — claims-vs-reality gap closure + opt-in registry-check.**
+
+### New: freshness surface (all opt-in, all offline-safe)
+
+- **`doctor --registry-check`.** Queries the npm registry for the latest published version + publish date. Reports `local_version`, `latest_version`, `days_since_latest_publish`, and a `behind` / `same` / `ahead` flag. Routed through a child process so the call is bounded by a hard timeout; offline degrades to a structured warning, not a hang. Opt-in: doctor without the flag stays offline.
+
+- **`run --upstream-check`.** Same registry call, fires before phase-4 detect. Surfaces an `upstream_check` block on the run result + a visible stderr warning when the local catalog is behind. Operators wiring CI gates can read `result.upstream_check.behind` to decide whether to trust today's findings. Doesn't fetch the catalog — only compares timestamps.
+
+- **`refresh --network`.** Fetches the latest signed catalog snapshot from the maintainer's npm-published tarball, verifies every skill's Ed25519 signature against the `keys/public.pem` already in the operator's install, and swaps `data/` + `skills/` + `manifest.json` in place. Same trust anchor as `npm update -g`; only the data slice changes, so CLI/lib code stays pinned. Refuses the swap on public-key fingerprint mismatch (key rotation requires explicit `npm update -g` so the trust transition is auditable). Refuses when the install dir isn't writable (typical global installs) and points operators at `npm update -g` instead. Includes `--dry-run` for verifying signatures without applying. Backs up the prior `data/` to a timestamped dir so rollback is one `mv` away.
+
+All three honor `EXCEPTD_REGISTRY_FIXTURE` env var (path to a JSON file mimicking the registry response) so test runners and air-gapped operators can exercise the freshness paths offline.
+
+### Bugs
+
+- **#129 air-gap workflow is now operator-accessible.** Pre-0.11.14 the docs implied `refresh --from-cache` worked offline but the cache-population path wasn't surfaced; an empty cache produced a stack trace. Now `refresh --prefetch` is the operator-facing alias for the prefetch script (legacy `--no-network` retained). Missing-cache errors emit a structured hint that names the exact command: "(1) on connected host: `exceptd refresh --prefetch`, (2) copy `.cache/upstream/`, (3) offline: `exceptd refresh --from-cache --apply`." Help text rewritten to document the workflow.
+
+- **#130 `exceptd path copy` writes to the clipboard.** Previously the `copy` argument was silently consumed and the path was just printed — operators wondering "did anything happen?" had no signal. Now the verb invokes the platform clipboard tool (`clip` on Windows, `pbcopy` on macOS, `wl-copy` / `xclip` / `xsel` on Linux), confirms the copy on stderr, and still prints the path on stdout so shell consumers like `cd "$(exceptd path)"` continue to work. When no clipboard tool is available, a clear warning fires instead of a silent fallthrough.
+
+- **#131 `run <skill-name>` suggests the right playbook.** 13 playbooks vs 38 skills with a many-to-many relationship: operators routinely typed `run kernel-lpe-triage` (a skill) and got "Playbook not found." Now the error names the playbook(s) that load the skill (e.g. `kernel`), distinguishes skill-vs-playbook semantics, and suggests both `exceptd run <playbook>` (execute) and `exceptd skill <name>` (read). Near-matches on unknown ids also surface (`run secret` → "Did you mean: secrets?"). Landing site updated to clarify the distinction near the skills grid.
+
+- **#134 `ci` exit-code matrix puts BLOCKED before FAIL.** Pre-0.11.14 a preflight halt produced exit 2 (FAIL) — indistinguishable from "playbook detected a real problem." Operators wiring CI gates against `exit 2` couldn't separate "we never executed" from "we executed and found something." Now the precedence is BLOCKED (4) → FAIL (2) → NO-DATA (3) → PASS (0). The earlier `if (fail)` short-circuit was rearranged so blocked counts take precedence.
+
+### Website (operator-facing)
+
+- **#132** `exceptd build-indexes` references replaced with `exceptd refresh --indexes-only`.
+- **#133** "13-gate predeploy" feature card relabeled "13-gate release hygiene" and explicitly disambiguated from the operator-facing `exceptd ci` verb.
+- **#131** Skills grid header clarifies "skills are read-only; playbooks execute" with the three relevant verbs.
+- **#129** Operator persona card shows the actual air-gap workflow: `refresh --prefetch` → copy → `refresh --from-cache --apply`.
+
+### Tests
+
+7 new regression cases. 354 total. Notable: `#125/#134` now triggers a REAL preflight halt by submitting `repo-context: false` keyed by playbook id (autoDetectPreconditions can't override an explicit submission), and asserts `r.status === 4` not just non-zero — the earlier test only caught "not 0" which my v0.11.12 "fix" passed by coincidence (no-evidence → exit 3, also non-zero).
+
+### Lesson codified
+
+When a "fix" passes a regression test by coincidence (any non-zero exit satisfies "not 0"), the test is too weak. Tests must assert the EXACT contract — exit 4, not "any non-zero." Added to CLAUDE.md.
+
 ## 0.11.13 — 2026-05-13
 
 **Patch: the final two stragglers — universal `ok:false` exit and empty-submission diff counters.**

package/bin/exceptd.js

@@ -71,6 +71,7 @@ const COMMANDS = {
   "-h":            null,
   prefetch:        () => path.join(PKG_ROOT, "lib", "prefetch.js"),
   refresh:         () => path.join(PKG_ROOT, "lib", "refresh-external.js"),
+  "refresh-network": () => path.join(PKG_ROOT, "lib", "refresh-network.js"),
   "build-indexes": () => path.join(PKG_ROOT, "scripts", "build-indexes.js"),
   verify:          () => path.join(PKG_ROOT, "lib", "verify.js"),
   scan:            () => path.join(PKG_ROOT, "orchestrator", "index.js"),
@@ -196,6 +197,9 @@ v0.11.0 canonical surface
                              --ci                   exit-code gate (use \`exceptd ci\` instead)
                              --operator <name>      bind attestation to identity
                              --ack                  explicit jurisdiction-consent
+                             --upstream-check       (v0.11.14) opt-in registry freshness
+                                                    check before detect; warns if local
+                                                    catalog is behind latest published
                              --session-id <id>      reuse session id (collision refused)
                              --force-overwrite      override session collision refusal
                              --session-key <hex>    HMAC sign evidence_package
@@ -218,6 +222,8 @@ v0.11.0 canonical surface
   doctor                     Health check: signatures + currency + cve catalog
                              + rfc catalog + attestation-signing status.
                              --signatures | --currency | --cves | --rfcs
+                             --registry-check       (v0.11.14) opt-in: query npm registry
+                                                    for latest published version + days behind
 
   ci                         One-shot CI gate. Exit codes: 0 PASS, 2 detected/escalate,
                              3 ran-but-no-evidence, 4 blocked (ok:false), 1 framework error.
@@ -242,6 +248,13 @@ v0.11.0 canonical surface
 
   refresh [args]             Refresh upstream catalogs + indexes. Replaces
                              prefetch + refresh + build-indexes.
+                             --network              (v0.11.14) fetch latest signed
+                                                    catalog snapshot from npm registry,
+                                                    verify against local keys/public.pem,
+                                                    swap data/ in place (no CLI/lib reload)
+                             --prefetch             populate offline cache
+                             --from-cache           consume offline cache
+                             --indexes-only         rebuild indexes only
 
 v0.10.x compatibility (will be removed in v0.12)
 ────────────────────────────────────────────────
@@ -321,6 +334,35 @@ function main() {
     process.exit(0);
   }
   if (cmd === "path") {
+    // v0.11.14 (#130): `path copy` was silently consuming the `copy` arg and
+    // printing the path. Operators on Windows / Linux saw no clipboard write.
+    // Now: implement clipboard copy on the three host platforms (clip on
+    // Windows, pbcopy on macOS, xclip|wl-copy|xsel on Linux). If no usable
+    // tool is found, fall through to print + stderr-warn (so STDOUT still
+    // gives the path for shell consumers like `cd "$(exceptd path)"`).
+    const wantCopy = rest.includes("copy") || rest.includes("--copy");
+    if (wantCopy) {
+      const { spawnSync } = require("child_process");
+      const platform = process.platform;
+      const candidates = platform === "win32" ? [["clip"]]
+        : platform === "darwin" ? [["pbcopy"]]
+        : [["wl-copy"], ["xclip", "-selection", "clipboard"], ["xsel", "-bi"]];
+      let copied = false;
+      let tried = [];
+      for (const [bin, ...argv] of candidates) {
+        tried.push(bin);
+        const res = spawnSync(bin, argv, { input: PKG_ROOT, encoding: "utf8" });
+        if (res.status === 0 && !res.error) { copied = true; break; }
+      }
+      if (copied) {
+        process.stderr.write(`[exceptd path] copied to clipboard: ${PKG_ROOT}\n`);
+        process.stdout.write(PKG_ROOT + "\n");
+        process.exit(0);
+      }
+      process.stderr.write(`[exceptd path] copy: no clipboard tool available (tried: ${tried.join(", ")}). Path printed to stdout instead.\n`);
+      process.stdout.write(PKG_ROOT + "\n");
+      process.exit(0);
+    }
     process.stdout.write(PKG_ROOT + "\n");
     process.exit(0);
   }
@@ -356,12 +398,22 @@ function main() {
   // here so the deprecation pointer actually works.
   let effectiveCmd = cmd;
   let effectiveRest = rest;
-  if (cmd === "refresh" && rest.includes("--no-network")) {
+  if (cmd === "refresh" && (rest.includes("--no-network") || rest.includes("--prefetch"))) {
+    // v0.11.14 (#129): --prefetch is the operator-facing name for the
+    // cache-population path. --no-network retained as alias for back-compat.
     effectiveCmd = "prefetch";
-    effectiveRest = rest.filter(a => a !== "--no-network");
+    effectiveRest = rest.filter(a => a !== "--no-network" && a !== "--prefetch");
   } else if (cmd === "refresh" && rest.includes("--indexes-only")) {
     effectiveCmd = "build-indexes";
     effectiveRest = rest.filter(a => a !== "--indexes-only");
+  } else if (cmd === "refresh" && rest.includes("--network")) {
+    // v0.11.14: --network fetches a fresh signed catalog snapshot from the
+    // maintainer's npm-published tarball, verifies signatures against the
+    // public key already shipped in the operator's install, and swaps
+    // data/ in place. Same trust boundary as `npm update -g`; fresher
+    // data slice without requiring a full package upgrade.
+    effectiveCmd = "refresh-network";
+    effectiveRest = rest.filter(a => a !== "--network");
   }
 
   const resolver = COMMANDS[effectiveCmd];
@@ -594,10 +646,55 @@ function dispatchPlaybook(cmd, argv) {
       case "ci":     return cmdCi(runner, args, runOpts, pretty);
     }
   } catch (e) {
+    // v0.11.14 (#131): when the operator typed a skill name (kernel-lpe-triage)
+    // and got "Playbook not found," surface the playbooks that load that skill.
+    // 13 playbooks vs 38 skills with many-to-many: operators routinely confuse
+    // the two because the website (and AGENTS.md) describe both as runnable.
+    const m = e && e.message && e.message.match(/^Playbook not found: ([^\s(]+)/);
+    if (m) {
+      const wanted = m[1];
+      const hint = buildSkillToPlaybookHint(runner, wanted);
+      if (hint) {
+        return emitError(`Playbook not found: "${wanted}". ${hint}`, { verb: cmd, wanted, type: "playbook_not_found" }, pretty);
+      }
+    }
     emitError(e.message, { verb: cmd }, pretty);
   }
 }
 
+function buildSkillToPlaybookHint(runner, wanted) {
+  try {
+    const ids = runner.listPlaybooks ? runner.listPlaybooks() : [];
+    const matches = [];
+    for (const id of ids) {
+      let pb;
+      try { pb = runner.loadPlaybook(id); } catch { continue; }
+      const skills = new Set();
+      const collect = (val) => {
+        if (Array.isArray(val)) val.forEach(collect);
+        else if (val && typeof val === "object") Object.values(val).forEach(collect);
+        else if (typeof val === "string") skills.add(val);
+      };
+      collect(pb.phases?.govern?.skill_preload);
+      for (const d of (pb.directives || [])) {
+        collect(d.phase_overrides?.govern?.skill_preload);
+      }
+      if (skills.has(wanted)) matches.push(id);
+    }
+    if (matches.length > 0) {
+      return `That is a SKILL (read-only knowledge unit), not a PLAYBOOK (executable). Skill "${wanted}" is loaded by playbook${matches.length === 1 ? "" : "s"}: ${matches.join(", ")}. ` +
+             `To execute: \`exceptd run ${matches[0]}\`. To read the skill: \`exceptd skill ${wanted}\`. ` +
+             `Tip: \`exceptd plan\` lists all 13 playbooks; \`exceptd watchlist\` lists skills.`;
+    }
+    // No matching skill either — provide nearest-playbook suggestions.
+    const near = ids.filter(id => id.includes(wanted) || wanted.includes(id)).slice(0, 3);
+    if (near.length > 0) {
+      return `Did you mean: ${near.join(", ")}? Run \`exceptd plan\` for the full list.`;
+    }
+    return `Run \`exceptd plan\` to list the 13 playbooks.`;
+  } catch { return null; }
+}
+
 function printPlaybookVerbHelp(verb) {
   const cmds = {
     plan: `plan — list playbooks + directives, grouped by scope.
@@ -1303,7 +1400,30 @@ function cmdRun(runner, args, runOpts, pretty) {
     }
   }
 
+  // v0.11.14: opt-in `--upstream-check` queries the npm registry BEFORE
+  // detect to warn operators if their local catalog is behind the latest
+  // published version. Opt-in so the runner stays offline by default.
+  // Network bounded by an 8s timeout; degrades gracefully when offline.
+  let upstreamCheck = null;
+  if (args["upstream-check"]) {
+    try {
+      const cliPath = path.join(PKG_ROOT, "lib", "upstream-check-cli.js");
+      const res = spawnSync(process.execPath, [cliPath, "--timeout", "5000"], {
+        encoding: "utf8",
+        cwd: PKG_ROOT,
+        timeout: 8000,
+      });
+      try { upstreamCheck = JSON.parse((res.stdout || "").trim()); } catch { /* fall through */ }
+      if (upstreamCheck && upstreamCheck.behind) {
+        process.stderr.write(`[exceptd run --upstream-check] STALE: local v${upstreamCheck.local_version} < published v${upstreamCheck.latest_version} (published ${upstreamCheck.latest_published_at}, ${upstreamCheck.days_since_latest_publish}d ago). Continuing with local catalog. Run \`npm update -g @blamejs/exceptd-skills\` or \`exceptd refresh --network\` to consume the latest.\n`);
+      }
+    } catch (e) {
+      upstreamCheck = { ok: false, error: e.message, source: "offline" };
+    }
+  }
+
   const result = runner.run(playbookId, directiveId, submission, runOpts);
+  if (result && upstreamCheck) result.upstream_check = upstreamCheck;
 
   // v0.11.9 (#113/#114): surface --operator and --ack in the run result so
   // operators see the attribution + consent state without inspecting the
@@ -2699,6 +2819,41 @@ function cmdDoctor(runner, args, runOpts, pretty) {
     }
   }
 
+  // v0.11.14: opt-in `--registry-check` queries the npm registry for the
+  // latest published version + publish date and computes "days behind."
+  // Opt-in (not on every doctor invocation) so offline use + air-gap
+  // workflows aren't disturbed. Routed through a child process to keep
+  // cmdDoctor synchronous + bound the network timeout cleanly.
+  if (args["registry-check"]) {
+    try {
+      const cliPath = path.join(PKG_ROOT, "lib", "upstream-check-cli.js");
+      const res = spawnSync(process.execPath, [cliPath, "--timeout", "5000"], {
+        encoding: "utf8",
+        cwd: PKG_ROOT,
+        timeout: 8000,
+      });
+      let parsed = null;
+      try { parsed = JSON.parse((res.stdout || "").trim()); } catch { /* fall through */ }
+      if (parsed) {
+        checks.registry = {
+          ok: parsed.ok && (parsed.same || parsed.ahead),
+          severity: parsed.behind ? "warn" : (parsed.ok ? "info" : "warn"),
+          ...parsed,
+        };
+      } else {
+        checks.registry = {
+          ok: false,
+          severity: "warn",
+          error: "upstream-check did not return JSON",
+          exit_code: res.status,
+          raw: ((res.stderr || res.stdout || "")).slice(0, 200),
+        };
+      }
+    } catch (e) {
+      checks.registry = { ok: false, severity: "warn", error: e.message };
+    }
+  }
+
   // Walk every check and split: errors (severity error/missing/fail) vs warnings
   // (severity warn). all_green is true ONLY when zero errors AND zero warnings.
   const warnList = [];
@@ -3449,30 +3604,34 @@ function cmdCi(runner, args, runOpts, pretty) {
   } else {
     emit({ verb: "ci", session_id: sessionId, playbooks_run: ids, summary, results }, pretty);
   }
+  // v0.11.14 (#134): exit-code matrix with BLOCKED before FAIL.
+  // Pre-0.11.14 the `if (fail)` check fired first for blocked runs (because
+  // the loop pushed blocked entries onto failReasons), so blocked runs got
+  // exit 2 (FAIL/detected) instead of exit 4 (BLOCKED/didn't-execute).
+  // Operators wiring CI gates couldn't distinguish "playbook detected a
+  // problem" from "playbook never executed because preflight halted."
+  //
+  // Exit-code matrix (final, documented in --help):
+  //   0  PASS      every playbook produced a result, none detected/escalating
+  //   1  FRAMEWORK engine/parse error (set by emit() when body is ok:false)
+  //   2  FAIL      detected classification OR rwep>=escalate
+  //   3  NO-DATA   ran but no --evidence and all inconclusive
+  //   4  BLOCKED   at least one playbook returned ok:false (preflight halt,
+  //                stale threat intel, missing precondition, mutex contention)
+  // Precedence: BLOCKED > FAIL > NO-DATA > PASS. A blocked playbook didn't
+  // actually evaluate signals, so it can't be a true detection.
+  if (summary.blocked > 0) {
+    const blockedReasons = failReasons.filter(r => r.includes("blocked"));
+    process.stderr.write(`[exceptd ci] BLOCKED: ${summary.blocked}/${summary.total} playbook(s) halted before detect. Exit 4. Reasons:\n  ${blockedReasons.join("\n  ")}\n`);
+    process.exitCode = 4;
+    return;
+  }
   if (fail) {
     process.stderr.write(`[exceptd ci] FAIL: ${failReasons.join("; ")}\n`);
-    // v0.11.11: use exitCode + return instead of process.exit() so the
-    // structured stdout JSON has a chance to flush when stdout is piped.
-    // process.exit() can truncate buffered async stdout writes.
+    // v0.11.11: exitCode + return so emit()'s stdout flushes.
     process.exitCode = 2;
     return;
   }
-  // v0.11.12 (#125): ci exit code matrix. Pre-0.11.12 every non-detected
-  // path exited 0 including blocked runs that never executed — CI gates
-  // couldn't distinguish ok:false from ok:true. Now:
-  //   0 PASS — every playbook produced a result, none detected/escalating
-  //   2 FAIL — at least one detected or rwep>=escalate (above)
-  //   3 NO-DATA — ran but no --evidence and all inconclusive
-  //   4 BLOCKED — at least one playbook returned ok:false (preflight halt,
-  //     stale threat intel, missing precondition, mutex contention, etc.)
-  //   1 FRAMEWORK — engine/parse error (set elsewhere)
-  // BLOCKED takes precedence over NO-DATA because a blocked run is a
-  // harder gate failure than "no real data."
-  if (summary.blocked > 0) {
-    process.stderr.write(`[exceptd ci] BLOCKED: ${summary.blocked}/${summary.total} playbook(s) returned ok:false (preflight/mutex/threat-currency/etc.). Exit 4. Inspect results[].reason for each blocked entry.\n`);
-    process.exitCode = 4;
-    return;
-  }
   const suppliedEvidence = args.evidence || args["evidence-dir"];
   const allInconclusive = summary.inconclusive === summary.total && summary.total > 0;
   if (!suppliedEvidence && allInconclusive) {

package/data/_indexes/_meta.json

@@ -1,10 +1,10 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-05-13T01:02:44.048Z",
+  "generated_at": "2026-05-13T02:04:13.785Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 49,
   "source_hashes": {
-    "manifest.json": "15f45ccdd329dd8a1c99905610df970ad44a560c4fadee971c29a6376bfc8eb4",
+    "manifest.json": "75707bfee79c57f6d7c6999c9da7292a574cb33669b17cf60e32160a5a2fa0d2",
     "data/atlas-ttps.json": "1500b5830dab070c4252496964a8c0948e1052a656e2c7c6e1efaf0350645e13",
     "data/cve-catalog.json": "a81d3e4b491b27ccc084596b063a6108ff10c9eb01d7776922fc393980b534fe",
     "data/cwe-catalog.json": "c3367d469b4b3d31e4c56397dd7a8305a0be338ecd85afa27804c0c9ce12157b",

package/keys/public.pem

@@ -1,3 +1,3 @@
 -----BEGIN PUBLIC KEY-----
-MCowBQYDK2VwAyEABzYdqZx/L/XFA8w/EHgjXi/WMpUO5qJg9lrDMgiG2q4=
+MCowBQYDK2VwAyEAbyrz9k9voneYsqY63g6A5y4jTcuiJd0FEDtk4li5uIE=
 -----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);
   });
 }