@blamejs/exceptd-skills 0.13.126 → 0.14.0

package/AGENTS.md

@@ -156,7 +156,7 @@ Cross-cutting playbook `framework` is the natural correlation layer — many pla
 
 | Verb | What it does |
 |---|---|
-| `exceptd brief --all` | Grouped-by-scope summary of all 23 playbooks. `--scope <type>` filters. `--directives` expands directive IDs/titles per playbook. `--flat` for non-grouped. `exceptd plan` was removed in v0.13.0; invoking it returns a structured `ok:false` refusal pointing at this command. |
+| `exceptd brief --all` | Grouped-by-scope summary of all 24 playbooks. `--scope <type>` filters. `--directives` expands directive IDs/titles per playbook. `--flat` for non-grouped. `exceptd plan` was removed in v0.13.0; invoking it returns a structured `ok:false` refusal pointing at this command. |
 | `exceptd brief <pb>` | Phase 2 threat-context briefing — threat context, RWEP thresholds, skill chain, token budget, jurisdiction obligations. |
 | `exceptd run <pb> --evidence <file>` | Phases 5-7 (analyze + validate + close) from agent evidence. Auto-detect cwd when no playbook positional. `--vex <file>` drops CycloneDX/OpenVEX `not_affected` CVEs. `--diff-from-latest` for drift mode. `--force-stale` overrides currency hard-block. |
 | `exceptd ai-run <pb>` | Streaming variant of `run` for AI agents; emits phase-by-phase NDJSON. |
@@ -372,7 +372,7 @@ This split costs every consumer the same translation work on every invocation. C
 exceptd collect secrets | exceptd run secrets --evidence -
 ```
 
-The collector library is small and grows as playbooks are touched. Thirteen reference collectors ship today (`lib/collectors/secrets.js`, `lib/collectors/kernel.js`, `lib/collectors/sbom.js`, `lib/collectors/containers.js`, `lib/collectors/library-author.js`, `lib/collectors/crypto-codebase.js`, `lib/collectors/cred-stores.js`, `lib/collectors/hardening.js`, `lib/collectors/runtime.js`, `lib/collectors/ai-api.js`, `lib/collectors/mcp.js`, `lib/collectors/crypto.js`, `lib/collectors/cicd-pipeline-compromise.js`); the rest are written when each playbook needs them. Until a playbook has a collector, the AI/operator owns evidence collection as before.
+The collector library is small and grows as playbooks are touched. Fourteen reference collectors ship today (`lib/collectors/secrets.js`, `lib/collectors/kernel.js`, `lib/collectors/sbom.js`, `lib/collectors/containers.js`, `lib/collectors/library-author.js`, `lib/collectors/crypto-codebase.js`, `lib/collectors/cred-stores.js`, `lib/collectors/hardening.js`, `lib/collectors/runtime.js`, `lib/collectors/ai-api.js`, `lib/collectors/mcp.js`, `lib/collectors/crypto.js`, `lib/collectors/cicd-pipeline-compromise.js`, `lib/collectors/citation-hygiene.js`); the rest are written when each playbook needs them. Code-scope collectors share `lib/collectors/scan-excludes.js`, which skips dependency/build caches, agent scratch (`.claude`), and linked git worktrees so a tree holding detached worktree copies isn't scanned N times. Until a playbook has a collector, the AI/operator owns evidence collection as before.
 
 ### Precision target for new `look.artifacts[].source` strings
 

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.14.0 — 2026-05-26
+
+New playbook — `citation-hygiene`. Validates a codebase's own cited security references: it scans source, comments, and docs for CVE and RFC citations and flags fabricated CVE IDs (the non-numeric `CVE-2024-XXXX` form), catalog-rejected/disputed CVEs, and RFC number-vs-title mismatches. Well-formed CVE IDs absent from the curated catalog are routed to an inconclusive "needs external verification" result rather than a false clear or a false fabrication flag. Ships with a companion collector — `exceptd collect citation-hygiene | exceptd run citation-hygiene --evidence -`. The catalog now holds 24 playbooks.
+
+Unknown flags are refused on every verb. Previously only `doctor` rejected an unrecognized flag; every other verb silently ignored it, so a typo like `--max-rweap 70` or `--fromat sarif` looked like it applied a cap or a format when it did nothing. Each verb now exits 1 with the accepted-flag list and a did-you-mean suggestion. A flag that is valid on another verb (e.g. `--csaf-status` on `brief`) still gets its tailored "that flag belongs on a run-class verb" guidance instead of a blanket refusal.
+
+`exceptd run --format json` now emits the full run result. It previously discarded the result and printed a short "unknown format" stub with a success exit code. SARIF, CSAF, and OpenVEX bundles are now emitted as spec-conformant documents — the internal `ok` envelope key is no longer prepended, so strict validators (GitHub code-scanning SARIF upload, CSAF trusted-provider checks) accept the output. Passing several `--format` values prints a note to stderr pointing at `bundles_by_format` rather than silently dropping all but the first.
+
+`exceptd collect <pb> | exceptd run <pb> --evidence -` works again. `collect` now emits JSON when its stdout is a pipe (the human summary is reserved for an interactive terminal), so the documented one-liner no longer feeds a prose summary into `run`.
+
+`exceptd refresh --check-advisories` polls the primary-source advisory feeds as documented (report-only; emits `diffs[]`) instead of being silently ignored.
+
+`skill --help` and `framework-gap --help` print usage instead of erroring.
+
+`exceptd attest list --limit <n>` caps the inventory; the JSON envelope reports the unfiltered total alongside the shown count.
+
+Code-scope collectors skip agent scratch (`.claude`) and linked git worktrees. A working tree holding detached worktree copies was scanned once per copy, inflating hash and secret counts with duplicates of the same files. The `library-author` collector now recognizes release-time SBOM generation, npm provenance, and sigstore/cosign signing, and `id-token: write` declared at job scope — so a well-run publisher no longer gets false "SBOM absent" or "no OIDC" findings from artifacts that are produced at release time.
+
+Documentation: the `ci` exit-code contract (0–5), the `osv` refresh source, and the full `--format` vocabulary are corrected in `--help` and README; the deprecated-alias help no longer claims a one-time banner it does not emit, and `reattest` / `list-attestations` are documented as canonical short forms rather than deprecated aliases.
+
 ## 0.13.126 — 2026-05-26
 
 CVE catalog — n8n Git-node RCE. Adds **CVE-2026-21877**, completing the n8n critical cluster. In versions ≥ 0.123.0 and < 1.121.3, an authenticated user abuses the Git node to write a file of a dangerous type to an arbitrary path, which is then executed — yielding remote code execution and full compromise of both self-hosted and Cloud instances (CWE-434 unrestricted upload chained to CWE-94; GitHub CNA CVSS v3.1 9.9). Fixed in 1.121.3. Reuses the AI-app-builder execution-endpoint auth-and-sandbox control (NEW-CTRL-103), which now also covers file-writing workflow nodes as code-execution sinks. CVE count 419 → 420.

package/README.md

@@ -30,7 +30,7 @@ This platform surfaces what is actually happening right now. Every skill explici
 
 ## Status
 
-Pre-1.0. Latest release lives on [GitHub Releases](https://github.com/blamejs/exceptd-skills/releases) and on npm as [`@blamejs/exceptd-skills`](https://www.npmjs.com/package/@blamejs/exceptd-skills) with signed npm provenance attestation and Ed25519-signed skill bodies. The package ships 42 skills across kernel LPE, MCP supply chain, AI-as-C2, prompt injection, post-quantum crypto, SBOM integrity, identity-incident response, and 35 other AI/security domains, plus 10 intelligence catalogs (CVE / ATLAS / ATT&CK / CWE / D3FEND / DLP / RFC / framework gaps / global frameworks / zero-day lessons) covering 35 jurisdictions — the CVE catalog has grown past 400 entries, its size anchored by a v0.13.17 CISA KEV bulk-intake of `dateAdded >= 2024-01-01` actively-exploited vulnerabilities that took it from 68 to 312 in a single pass. 23 investigation playbooks (kernel, MCP, AI-API, framework, SBOM, runtime, hardening, secrets, cred-stores, containers, crypto, plus `webhook-callback-abuse`, `cicd-pipeline-compromise`, `identity-sso-compromise`, `llm-tool-use-exfil`, `post-quantum-migration`, `ai-discovered-cve-triage`, `supply-chain-recovery`, and more), a CLI for discovery and seven-phase investigation runs (`govern → direct → look → detect → analyze → validate → close`), and a nightly auto-refresh job that pulls KEV / NVD / EPSS / GHSA / OSV / IETF deltas plus 15 primary-source advisory + research-blog + tech-press feeds (Qualys TRU, Red Hat RHSA, Ubuntu USN, ZDI, kernel.org, oss-security, JFrog, CISA, Microsoft Security Blog, Sysdig, Trail of Bits, Embrace the Red, BleepingComputer security, The Hacker News, and a GitLab activity-feed tracker for the Nightmare-Eclipse researcher handle that anchors NEW-CTRL-073) into auto-PRs for editorial review. v0.13.17 also ships `lib/cve-regression-watcher.js` (NEW-CTRL-074) — a complementary detection method that surfaces poller-diff historical-CVE references as candidate silent-regression cases, the class anchored by MiniPlasma (a 2026 PoC drop that re-broke CVE-2020-17103 without any new ID being assigned).
+Pre-1.0. Latest release lives on [GitHub Releases](https://github.com/blamejs/exceptd-skills/releases) and on npm as [`@blamejs/exceptd-skills`](https://www.npmjs.com/package/@blamejs/exceptd-skills) with signed npm provenance attestation and Ed25519-signed skill bodies. The package ships 42 skills across kernel LPE, MCP supply chain, AI-as-C2, prompt injection, post-quantum crypto, SBOM integrity, identity-incident response, and 35 other AI/security domains, plus 10 intelligence catalogs (CVE / ATLAS / ATT&CK / CWE / D3FEND / DLP / RFC / framework gaps / global frameworks / zero-day lessons) covering 35 jurisdictions — the CVE catalog has grown past 400 entries, its size anchored by a v0.13.17 CISA KEV bulk-intake of `dateAdded >= 2024-01-01` actively-exploited vulnerabilities that took it from 68 to 312 in a single pass. 24 investigation playbooks (kernel, MCP, AI-API, framework, SBOM, runtime, hardening, secrets, cred-stores, containers, crypto, plus `webhook-callback-abuse`, `cicd-pipeline-compromise`, `identity-sso-compromise`, `llm-tool-use-exfil`, `post-quantum-migration`, `ai-discovered-cve-triage`, `supply-chain-recovery`, `citation-hygiene`, and more), a CLI for discovery and seven-phase investigation runs (`govern → direct → look → detect → analyze → validate → close`), and a nightly auto-refresh job that pulls KEV / NVD / EPSS / GHSA / OSV / IETF deltas plus 15 primary-source advisory + research-blog + tech-press feeds (Qualys TRU, Red Hat RHSA, Ubuntu USN, ZDI, kernel.org, oss-security, JFrog, CISA, Microsoft Security Blog, Sysdig, Trail of Bits, Embrace the Red, BleepingComputer security, The Hacker News, and a GitLab activity-feed tracker for the Nightmare-Eclipse researcher handle that anchors NEW-CTRL-073) into auto-PRs for editorial review. v0.13.17 also ships `lib/cve-regression-watcher.js` (NEW-CTRL-074) — a complementary detection method that surfaces poller-diff historical-CVE references as candidate silent-regression cases, the class anchored by MiniPlasma (a 2026 PoC drop that re-broke CVE-2020-17103 without any new ID being assigned).
 
 ---
 
@@ -156,13 +156,13 @@ Fresh-disclosure workflow (v0.12.0): the nightly auto-PR job pulls KEV / NVD / E
 
 Primary-source advisory polling: `exceptd refresh --check-advisories` polls 15 vendor and coordinated-disclosure feeds — 8 advisory/coordinated-disclosure venues (Qualys TRU, Red Hat RHSA, Ubuntu USN, Zero Day Initiative, kernel.org commits, oss-security mailing list, JFrog SecOps, CISA current advisories), 4 vendor security research blogs added in v0.13.14 (Microsoft Security Blog, Sysdig, Trail of Bits, Embrace the Red), and 3 additions in v0.13.17 (BleepingComputer security, The Hacker News, and a GitLab activity-feed tracker for the Nightmare-Eclipse researcher handle that anchors NEW-CTRL-073). Combined coverage publishes CVE IDs at T+0 to T+1 — typically 3–14 days ahead of NVD enrichment. The command is report-only: it returns a structured `diffs[]` listing each newly-seen CVE ID with its source attributions and advisory URLs, but does not mutate the catalog. v0.13.17 also adds a complementary detection method (NEW-CTRL-074 / `lib/cve-regression-watcher.js`): the watcher cross-checks poller diffs for historical-CVE references (year ≤ currentYear − 2) and surfaces candidate silent-regression cases — the class anchored by MiniPlasma (a 2026 PoC drop that re-broke CVE-2020-17103 without any new ID being assigned). Operators triage the output and route promising IDs through `exceptd refresh --advisory <CVE-ID> --apply`. Pairs naturally with the daily scheduled remote agent below.
 
-CVE-class alert surfacing: `exceptd watchlist --alerts` matches the live `cve-catalog.json` against five operational patterns (`kernel_lpe_with_poc`, `supply_chain_family`, `ai_discovered_kev`, `active_exploitation_unpatched`, `recent_poc_no_kev_yet`) and returns the matches sorted critical-severity-first, then by RWEP. Use as a fast operational triage on a refreshed catalog without scanning every entry by hand.
+CVE-class alert surfacing: `exceptd watch --alerts` matches the live `cve-catalog.json` against five operational patterns (`kernel_lpe_with_poc`, `supply_chain_family`, `ai_discovered_kev`, `active_exploitation_unpatched`, `recent_poc_no_kev_yet`) and returns the matches sorted critical-severity-first, then by RWEP. Use as a fast operational triage on a refreshed catalog without scanning every entry by hand.
 
-GitHub repo-pattern monitoring: `exceptd watchlist --org-scan --org <login>` probes GitHub Search for repositories matching known threat-actor naming patterns ("A Gift From TeamPCP", "Shai-Hulud", "TeamPCP") scoped to one org. Custom patterns via repeatable `--pattern <s>`. Implements the canonical detection for the Shai-Hulud / TeamPCP supply-chain framework class — the attacker uses GitHub itself as the exfil channel. Set `GITHUB_TOKEN` for private-repo coverage and rate-limit headroom; public-repo search works without auth.
+GitHub repo-pattern monitoring: `exceptd watch --org-scan --org <login>` probes GitHub Search for repositories matching known threat-actor naming patterns ("A Gift From TeamPCP", "Shai-Hulud", "TeamPCP") scoped to one org. Custom patterns via repeatable `--pattern <s>`. Implements the canonical detection for the Shai-Hulud / TeamPCP supply-chain framework class — the attacker uses GitHub itself as the exfil channel. Set `GITHUB_TOKEN` for private-repo coverage and rate-limit headroom; public-repo search works without auth.
 
 AI-assistant config-file audit: `exceptd doctor --ai-config` walks `~/.claude`, `~/.cursor`, `~/.codeium`, `~/.aider`, and `~/.continue`, flagging sensitive files (`settings.json`, `mcp.json`, `*.mcp_config.json`, `api_key*`, `*.token`, `*.credentials`) not at mode 0600 on POSIX. On Windows the mode bits aren't load-bearing; each finding is surfaced with an info-level "manual ACL review" note. Catches the AI-config-credential-exfil class that the Shai-Hulud framework targets. Opt-in — does not run as part of the default no-flag `doctor` pass.
 
-Evidence-collection layer: `exceptd collect <playbook>` invokes a companion script under `lib/collectors/<playbook>.js` that walks cwd, applies the catalogued regex set, stats permissions, and emits the submission JSON in the same shape `exceptd run --evidence -` accepts. 13 of 23 playbooks have collectors today (`ai-api`, `cicd-pipeline-compromise`, `containers`, `cred-stores`, `crypto`, `crypto-codebase`, `hardening`, `kernel`, `library-author`, `mcp`, `runtime`, `sbom`, `secrets`); the remaining 10 are policy-skipped per AGENTS.md (judgement-shaped incident / governance / pure-analyze playbooks where AI-driven evidence collection is the design). Canonical operator pipe: `exceptd collect <pb> | exceptd run <pb> --evidence -`. `exceptd doctor --collectors` enumerates the layer; `exceptd discover` tags applicable playbooks with `[collector]` when one ships. `cicd-pipeline-compromise` requires `--attest-ownership` on the collect call (the playbook's `operator-owns-ci-fleet` precondition is opt-in to prevent unauthorized CI assessments).
+Evidence-collection layer: `exceptd collect <playbook>` invokes a companion script under `lib/collectors/<playbook>.js` that walks cwd, applies the catalogued regex set, stats permissions, and emits the submission JSON in the same shape `exceptd run --evidence -` accepts. 14 of 24 playbooks have collectors today (`ai-api`, `cicd-pipeline-compromise`, `citation-hygiene`, `containers`, `cred-stores`, `crypto`, `crypto-codebase`, `hardening`, `kernel`, `library-author`, `mcp`, `runtime`, `sbom`, `secrets`); the remaining 10 are policy-skipped per AGENTS.md (judgement-shaped incident / governance / pure-analyze playbooks where AI-driven evidence collection is the design). Canonical operator pipe: `exceptd collect <pb> | exceptd run <pb> --evidence -`. `exceptd doctor --collectors` enumerates the layer; `exceptd discover` tags applicable playbooks with `[collector]` when one ships. `cicd-pipeline-compromise` requires `--attest-ownership` on the collect call (the playbook's `operator-owns-ci-fleet` precondition is opt-in to prevent unauthorized CI assessments).
 
 Daily scheduled threat intake: a `routine: exceptd-threat-intake` (claude.ai remote agent) runs daily at 14:00 UTC. Sequence: `npm install` → `refresh --check-advisories` → `watchlist --alerts` → `refresh --apply` → `refresh --advisory <CVE-ID>` for up to 5 new CVE IDs from the primary-source feeds → re-sign + rebuild-indexes if the catalog mutated → commit on `intake/<YYYY-MM-DD>` branch with the full diff in the report. Closes the cadence gap that previously left fresh disclosures dependent on operator-triggered intake. Operator-managed at <https://claude.ai/code/routines>.
 
@@ -281,7 +281,7 @@ exceptd collect <playbook>            Walk cwd + invoke the companion collector
                                       under lib/collectors/<playbook>.js. Emits
                                       a submission JSON ready to pipe into
                                       `exceptd run <playbook> --evidence -`.
-                                      13/23 playbooks have collectors; the rest
+                                      14/24 playbooks have collectors; the rest
                                       are AI-driven by design (incident /
                                       governance / pure-analyze — see
                                       AGENTS.md).
@@ -330,8 +330,11 @@ exceptd doctor                        One-shot health check.
                                       Opt-in; not part of the default doctor
                                       pass.
 
-exceptd ci                            One-shot CI gate. Exits 2 on detected or
-                                      rwep ≥ rwep_threshold.escalate.
+exceptd ci                            One-shot CI gate. Exit codes: 0 PASS,
+                                      1 framework error, 2 detected/escalate
+                                      (or rwep ≥ rwep_threshold.escalate),
+                                      3 ran-but-no-evidence, 4 blocked
+                                      (ok:false), 5 jurisdiction clock started.
   --all | --scope <type>              Pick playbooks; auto-detect if neither.
   --max-rwep <n>                      Cap below playbook default.
   --block-on-jurisdiction-clock       Fail when notification clock fires.
@@ -385,7 +388,7 @@ Packages dataset (`MAL-*` keys). New IDs land as drafts that the catalog
 validator treats as warnings, not errors — editorial review (framework
 gaps, IoCs, ATLAS/ATT&CK refs) is still required.
 
-exceptd watchlist                     Default mode: aggregate every skill's
+exceptd watch                         Default mode: aggregate every skill's
                                       forward_watch entries (upcoming standards,
                                       RFC publications, new TTPs to monitor).
                                       `--by-skill` inverts the grouping.
@@ -536,7 +539,7 @@ If your tool has a conventional auto-load filename not listed here and you'd lik
 - **`theater-fingerprints.json`** — structured records for the 7 compliance theater patterns: claim, audit evidence, reality, fast detection test, controls implicated.
 - **`_meta.json`** — sha256 of every source file. The `validate-indexes` predeploy gate fails if any source changed after the last build; `build-indexes --changed` reads this to know what to rebuild.
 
-Regenerate with `exceptd build-indexes` (full) or `exceptd build-indexes --changed --parallel` (incremental).
+Regenerate with `exceptd refresh --indexes-only`.
 
 ## For skill authors — `agents/`
 

package/bin/exceptd.js

@@ -65,7 +65,17 @@ const PKG_ROOT = path.resolve(__dirname, "..");
 // behavior share the same source of truth.
 const { EXIT_CODES, listExitCodes } = require(path.join(PKG_ROOT, "lib", "exit-codes.js"));
 const { validateIdComponent } = require(path.join(PKG_ROOT, "lib", "id-validation.js"));
-const { suggestFlag, flagsFor } = require(path.join(PKG_ROOT, "lib", "flag-suggest.js"));
+const { suggestFlag, flagsFor, VERB_FLAG_ALLOWLIST } = require(path.join(PKG_ROOT, "lib", "flag-suggest.js"));
+
+// Union of every flag known to ANY verb. A flag that is valid somewhere but
+// not on the active verb (e.g. `--csaf-status` on `brief`) is cross-verb
+// misuse, not a typo — it falls through to the verb handler, which emits a
+// tailored "that flag belongs on a run-class verb" message. Only a flag that
+// is unknown EVERYWHERE is refused outright as a typo/garbage at the
+// dispatcher. Kept module-scope so it is computed once.
+const ALL_KNOWN_FLAGS = new Set(
+  Object.values(VERB_FLAG_ALLOWLIST).flat()
+);
 
 /**
  * Factor the EXPECTED_FINGERPRINT pin check used by
@@ -384,7 +394,7 @@ Canonical verbs
                              --evidence <file|->    flat or nested submission
                              --evidence-dir <dir>   per-playbook submission files
                              --vex <file>           CycloneDX / OpenVEX filter
-                             --format <fmt> ...     csaf-2.0 | sarif | openvex | markdown | summary
+                             --format <fmt> ...     csaf-2.0 | sarif | openvex | markdown | summary | json
                              --diff-from-latest     drift vs prior attestation
                              --ci                   exit-code gate (use \`exceptd ci\` instead)
                              --operator <name>      bind attestation to identity
@@ -458,8 +468,10 @@ Canonical verbs
                              --prefetch             populate offline cache
                              --from-cache           consume offline cache
                              --indexes-only         rebuild indexes only
-                             Sources: kev|epss|nvd|rfc|pins|ghsa (v0.12.0).
+                             Sources: kev|epss|nvd|rfc|pins|ghsa|osv.
                                                     ghsa drafts pass validator as warnings.
+                             --check-advisories     poll primary-source advisory
+                                                    feeds; report-only diffs[].
 
 Removed verbs (refused — these now error with a pointer to the replacement)
 ───────────────────────────────────────────────────────────────────────────
@@ -476,12 +488,10 @@ here so old scripts know where each moved:
 Deprecated aliases (still work — prefer the canonical verb)
 ───────────────────────────────────────────────────────────
 
-These still run but emit a one-time deprecation banner. The [DEPRECATED]
-prefix keeps them out of the active-verbs list that
-\`exceptd help | grep '^  [a-z]'\` surfaces. Each maps to a canonical verb:
+These still run. The [DEPRECATED] prefix keeps them out of the active-verbs
+list that \`exceptd help | grep '^  [a-z]'\` surfaces. Each maps to a canonical
+verb:
 
-  [DEPRECATED] reattest <sid>    → attest diff <sid>
-  [DEPRECATED] list-attestations → attest list
   [DEPRECATED] scan              → discover --scan-only
   [DEPRECATED] dispatch          → discover
   [DEPRECATED] currency          → doctor --currency
@@ -492,6 +502,11 @@ prefix keeps them out of the active-verbs list that
   [DEPRECATED] prefetch          → refresh --no-network
   [DEPRECATED] build-indexes     → refresh --indexes-only
 
+Accepted short forms (canonical — not deprecated):
+
+  reattest <sid>        short form of \`attest diff <sid>\`
+  list-attestations     short form of \`attest list\`
+
 Output: default human-readable (v0.11.0). --json for machine output.
         --pretty for indented JSON.
 
@@ -711,6 +726,24 @@ function main() {
     return;
   }
 
+  // `skill` and `framework-gap` are spawned subcommands that never reach the
+  // in-process per-verb --help, and (unlike `refresh`/`prefetch`, which print
+  // their own help) the orchestrator forwards `--help` as a positional —
+  // `skill --help` tried to resolve a skill literally named "--help"
+  // ("Skill not found: --help") and `framework-gap --help` errored on missing
+  // args. Intercept --help for just these so they honor it. Scoped to the
+  // verbs that lack their own help handler, so spawns that do (refresh,
+  // prefetch) keep their detailed usage.
+  const SPAWN_HELP_USAGE = {
+    skill: "exceptd skill <name>          Show the full context document for one skill.",
+    "framework-gap": "exceptd framework-gap <framework> <cve-or-scenario>   One-framework gap analysis.",
+    "framework-gap-analysis": "exceptd framework-gap <framework> <cve-or-scenario>   One-framework gap analysis.",
+  };
+  if ((effectiveRest.includes("--help") || effectiveRest.includes("-h")) && SPAWN_HELP_USAGE[effectiveCmd]) {
+    process.stdout.write(SPAWN_HELP_USAGE[effectiveCmd] + "\n  Full reference: exceptd help\n");
+    return;
+  }
+
   // Orchestrator subcommands need the subcommand name preserved as argv[0]
   // for orchestrator/index.js's switch statement.
   const finalArgs = ORCHESTRATOR_PASSTHROUGH.has(effectiveCmd) ? [script, effectiveCmd, ...effectiveRest] : [script, ...effectiveRest];
@@ -1203,6 +1236,7 @@ function dispatchPlaybook(cmd, argv) {
     "publisher-namespace", "mode", "scope", "playbook", "phase", "tlp",
     "against", "since", "bundle-epoch", "attestation-root", "format",
     "cwd",  // exceptd collect <pb> --cwd <path>
+    "limit",  // exceptd attest list --limit <n>
   ]);
   const verbAllowlist = flagsFor(cmd);
   const allowlistSet = new Set(verbAllowlist);
@@ -1242,21 +1276,29 @@ function dispatchPlaybook(cmd, argv) {
       }
       continue;
     }
-    // Refuse only when a close suggestion exists (likely typo). Unknown
-    // flags with no near-match fall through to verb-level handling so a
-    // future addition doesn't require an allowlist edit in this file
-    // before it can ship. The PASSTHROUGH_FLAGS list above plus the
-    // per-verb allowlist in lib/flag-suggest.js together cover every
-    // shipped flag; anything that misses both AND has a typo suggestion
-    // is the case operators benefit from refusing.
+    // A flag valid on SOME other verb (e.g. `--csaf-status` on `brief`) is
+    // cross-verb misuse — fall through so the verb handler can emit its
+    // tailored "that flag belongs on a run-class verb" guidance rather than
+    // a blanket refusal here.
+    if (ALL_KNOWN_FLAGS.has(key)) continue;
+    // Unknown everywhere — refuse it as a typo / unsupported flag. Silently
+    // ignoring an unrecognized flag let a mistyped cap or output-format flag
+    // look like it applied when it did nothing. Surface a suggestion
+    // when one is close, and always list the accepted flags so the operator
+    // can self-correct. Adding a new flag to a verb means appending it to
+    // that verb's allowlist (or PASSTHROUGH_FLAGS) — the test suite exercises
+    // every shipped flag, so a missing registration fails CI rather than
+    // silently breaking the flag.
     const suggestion = suggestFlag(key, verbAllowlist);
-    if (suggestion) {
-      return emitError(
-        `unknown flag --${key}`,
-        { verb: cmd, suggested: suggestion },
-        pretty
-      );
-    }
+    return emitError(
+      `${cmd}: unknown flag --${key}`,
+      {
+        verb: cmd,
+        unknown_flags: [{ flag: `--${key}`, did_you_mean: suggestion ? [`--${suggestion}`] : [] }],
+        known_flags: verbAllowlist.filter((f) => typeof f === "string").sort().map((f) => `--${f}`),
+      },
+      pretty
+    );
   }
   const runOpts = {
     // Air-gap can be requested via the explicit flag OR the
@@ -1798,10 +1840,14 @@ Flags:
                           or not_affected | fixed (OpenVEX) drop out of
                           analyze.matched_cves. The disposition is preserved
                           under analyze.vex.dropped_cves.
-  --format <fmt> ...      Emit the close.evidence_package bundle in additional
-                          formats. Repeatable. Supported: csaf-2.0 | sarif |
-                          openvex | markdown. CSAF is always primary; extras
-                          populate close.evidence_package.bundles_by_format.
+  --format <fmt> ...      Transform stdout. Supported: summary | markdown |
+                          csaf-2.0 | csaf | sarif | openvex | json (json = the
+                          full run result). Standardized bundles (csaf/sarif/
+                          openvex) are emitted as spec-conformant documents.
+                          Repeatable, but only ONE document goes to stdout — the
+                          first; every requested bundle is embedded under
+                          close.evidence_package.bundles_by_format (see via
+                          --json). Passing several prints a note to stderr.
   --explain               Dry-run: emit preconditions, required artifacts,
                           recognized signal keys, and a submission skeleton.
                           Does not run detect/analyze/validate/close.
@@ -2390,7 +2436,14 @@ function cmdCollect(runner, args, runOpts, pretty) {
   // Spread `submission` first, then explicit fields, so a submission key
   // named `air_gap_mode` (currently always undefined but defensive against
   // future collector contracts) can't clobber the envelope marker.
-  emit({ verb: "collect", playbook_id: playbookId, ...submission, air_gap_mode: collectAirGap }, pretty, (obj) => {
+  const collectBody = { verb: "collect", playbook_id: playbookId, ...submission, air_gap_mode: collectAirGap };
+  // collect's primary purpose is the pipe `exceptd collect <pb> | exceptd run
+  // <pb> --evidence -`. When stdout is NOT a TTY (a pipe / redirect), emit JSON
+  // so that one-liner just works; the human summary is only for an interactive
+  // operator at a terminal. Explicit --json / --pretty force JSON regardless.
+  // Without this gate, emit()'s default-human behavior printed a prose summary
+  // into the pipe and the downstream `run --evidence -` failed to parse it.
+  const collectHuman = process.stdout.isTTY ? (obj) => {
     const lines = [];
     const meta = obj.collector_meta || {};
     lines.push(`collect: ${obj.playbook_id}  (${meta.collector_version || "?"} on ${meta.platform || "?"})`);
@@ -2427,10 +2480,11 @@ function cmdCollect(runner, args, runOpts, pretty) {
       }
       if (errs.length > 5) lines.push(`  … ${errs.length - 5} more`);
     }
-    lines.push(`\n→ next: exceptd collect ${obj.playbook_id} --json | exceptd run ${obj.playbook_id} --evidence -`);
+    lines.push(`\n→ next: exceptd collect ${obj.playbook_id} | exceptd run ${obj.playbook_id} --evidence -`);
     lines.push(`Full structured result: --json (or --pretty for indented JSON).`);
     return lines.join("\n");
-  });
+  } : undefined;
+  emit(collectBody, pretty, collectHuman);
 }
 
 function cmdLint(runner, args, runOpts, pretty) {
@@ -3480,7 +3534,8 @@ function cmdRun(runner, args, runOpts, pretty) {
   //   --format csaf-2.0/sarif/openvex → the corresponding bundle from close
   //   (default — no --format) → full JSON result as before
   if (args.format) {
-    const requested = Array.isArray(args.format) ? args.format[0] : args.format;
+    const requestedAll = Array.isArray(args.format) ? args.format : [args.format];
+    const requested = requestedAll[0];
     const VALID = ["summary", "markdown", "csaf-2.0", "csaf", "sarif", "openvex", "json"];
     if (!VALID.includes(requested)) {
       const dym = suggestFlag(String(requested), VALID);
@@ -3491,6 +3546,25 @@ function cmdRun(runner, args, runOpts, pretty) {
         pretty,
       );
     }
+    // Only one document can be written to stdout. When several --format values
+    // are given, emit the first and tell the operator where the rest live so
+    // the extras aren't silently dropped.
+    if (requestedAll.length > 1) {
+      process.stderr.write(
+        `[exceptd] note: ${requestedAll.length} --format values given; emitting "${requested}" to stdout. ` +
+        `All requested bundles are embedded under phases.close.evidence_package.bundles_by_format — ` +
+        `re-run with --json to see them.\n`
+      );
+    }
+    // `json` means "the full run result as JSON" — the same body the default
+    // (no --format) path emits. Without this it fell through to the bundle
+    // lookup, found the runner's "unknown format" stub under
+    // bundles_by_format.json, and emitted that 150-byte stub instead of the
+    // scan — silently discarding the result with a success exit code.
+    if (requested === "json") {
+      emit(result, pretty);
+      return;
+    }
     if (requested === "summary") {
       const cls = result.phases?.detect?.classification;
       const rwep = result.phases?.analyze?.rwep?.adjusted ?? 0;
@@ -3546,7 +3620,15 @@ function cmdRun(runner, args, runOpts, pretty) {
     const bbf = result.phases?.close?.evidence_package?.bundles_by_format || {};
     const body = bbf[formatNorm] || result.phases?.close?.evidence_package?.bundle_body;
     if (body) {
-      emit(body, pretty);
+      // SARIF / CSAF / OpenVEX are self-describing standard documents. Write
+      // them verbatim rather than through emit(), which prepends the tool's
+      // own `ok` envelope key — `ok` is not a permitted top-level property in
+      // any of these schemas and makes strict validators (GitHub code-scanning
+      // SARIF upload, a CSAF trusted-provider check) reject the output. The
+      // namespaced `exceptd_extension` block (CSAF vendor extension carrying
+      // publisher-namespace provenance) is preserved intentionally.
+      const { ok: _ok, ...spec } = body;
+      process.stdout.write(JSON.stringify(spec, null, pretty ? 2 : 0) + "\n");
       return;
     }
     // Fallback: full result
@@ -7040,10 +7122,28 @@ function cmdListAttestations(runner, args, runOpts, pretty) {
     }
   }
   entries.sort((a, b) => (b.captured_at || "").localeCompare(a.captured_at || ""));
+  const total = entries.length;
+  // --limit caps the inventory (newest first). Without it, JSON returns every
+  // session and the human table shows the first 50 with an "… and N more"
+  // footer. With it, both surfaces honor the cap and report `total`.
+  let limitN = null;
+  if (args.limit != null) {
+    limitN = Number(args.limit);
+    if (!Number.isInteger(limitN) || limitN < 0) {
+      return emitError(
+        `attest list: --limit must be a non-negative integer; got ${JSON.stringify(String(args.limit))}.`,
+        { verb: "attest list", provided: args.limit },
+        pretty,
+      );
+    }
+  }
+  const shown = limitN != null ? entries.slice(0, limitN) : entries;
   emit({
     ok: true,
-    attestations: entries,
-    count: entries.length,
+    attestations: shown,
+    count: total,
+    shown: shown.length,
+    limit: limitN,
     filter: { playbook: playbookFilter ? [...playbookFilter] : null, since: args.since || null },
     roots_searched: [...seenRoots],
     // Cycle 11 F5 (v0.12.32): every candidate root + whether it existed,
@@ -7068,10 +7168,17 @@ function cmdListAttestations(runner, args, runOpts, pretty) {
     }
     lines.push(`  ${"session-id".padEnd(20)}  ${"playbook".padEnd(16)}  ${"captured-at".padEnd(20)}  evidence-hash`);
     lines.push(`  ${"-".repeat(20)}  ${"-".repeat(16)}  ${"-".repeat(20)}  ${"-".repeat(20)}`);
-    for (const e of obj.attestations.slice(0, 50)) {
+    // When --limit was given, obj.attestations is already capped; show all of
+    // it. Otherwise show the first 50 and footer the remainder.
+    const rows = obj.limit != null ? obj.attestations : obj.attestations.slice(0, 50);
+    for (const e of rows) {
       lines.push(`  ${(e.session_id || "?").padEnd(20)}  ${(e.playbook_id || "?").padEnd(16)}  ${(e.captured_at || "").slice(0, 19).padEnd(20)}  ${e.evidence_hash || ""}`);
     }
-    if (obj.count > 50) lines.push(`  … and ${obj.count - 50} more (use --json for full list)`);
+    if (obj.limit != null) {
+      if (obj.count > rows.length) lines.push(`  showing ${rows.length} of ${obj.count} (raise --limit or use --json for the full list)`);
+    } else if (obj.count > 50) {
+      lines.push(`  … and ${obj.count - 50} more (use --limit <n> or --json for the full list)`);
+    }
     return lines.join("\n");
   });
 }

package/data/_indexes/_meta.json

@@ -1,10 +1,10 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-05-27T04:33:05.318Z",
+  "generated_at": "2026-05-27T06:54:45.872Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 54,
   "source_hashes": {
-    "manifest.json": "13900334f14a87189b4cda1d1357f2efc6075283f24eb1c149ec4309db01a400",
+    "manifest.json": "b6388ed9b3b0e87f6f65d050c2aef4fb3121e2135892e59313ba05b6fa5090e7",
     "data/atlas-ttps.json": "d24bc02859d40ccf1615db75cca68c077585904e41e0d8f6de448121e9b1abb0",
     "data/attack-techniques.json": "fa193f0d2d248176a8beddb641e9fe56ba4faa9e15dc253ff876dbf0c5d58a77",
     "data/cve-catalog.json": "3d451dda7ac0c7d57a4075ae4bafd3148c6184b35dc1bc59d8b81d1f2641e430",