nsauditor-ai-agent-skill 0.2.47 → 0.2.49

package/CHANGELOG.md

@@ -4,6 +4,51 @@ Release notes for **`nsauditor-ai-agent-skill`** — installable knowledge packa
 
 ---
 
+## 0.2.49 (2026-09-04) — the client-report release
+
+Paired with **Enterprise 0.44.0 / Community 0.2.51**. **NOT a floor bump: Community stays `>= 0.2.49`.**
+
+- **New teaching: the Pro `report` subcommand.** `nsauditor-ai report --from <dir> --format
+  executive|jira` turns a completed run into a client-facing HTML report or a Jira-importer CSV, with
+  `--run`, `--brand`, `--out` and `--allow-partial`. Two limits an agent must state rather than
+  discover: the Jira import mapping has not been verified against a live Jira instance, and a
+  value-less flag is a fatal error rather than a silent default.
+- **New teaching: an S3 audit-trail gap now means BOTH streams are missing.** Plugin 1020
+  cross-checks CloudTrail data-event coverage before reporting a missing server access log, and emits
+  positive substrate naming the covering trail instead. A gap disappearing after upgrade on a covered
+  bucket is the fix working. Every uncertain answer — denied read, absent optional SDK, stopped trail,
+  delivery error, prefix-scoped or one-sided selector — keeps the finding unchanged.
+- Plugin catalog unchanged at 29 EE; all eight coverage matrices unchanged.
+
+---
+
+## 0.2.48 (2026-09-02) — paired with EE 0.43.0: teach what a provider badge means, and what an evidence gap must not say
+
+**Two teaching changes, both about how to READ a scan rather than how to run one.**
+
+**A provider badge is now trustworthy, and the assistant should say why it was not.** Until
+EE 0.43.0, an Enterprise scan whose cloud SDK failed to load reported that provider as
+**audited** — eighteen refusals across seventeen AWS and GCP plugins returned `up: false` with
+the cause written only into `warnings`, and the Community plugin manager derives
+`auditedProviders` from plugins that *ran*. Teach: **`auditedProviders` and `providerStatus`
+are now answerable questions** — `{ran, skipped, errored}` per provider — and a cloud whose SDK
+is missing appears as `errored`, not as audited. If a user reports a provider missing from
+`auditedProviders` after upgrading, that is the fix working, not a regression.
+
+**An evidence gap states a CAUSE, never an instruction.** The engine quotes a plugin's reason
+into the *"could not run"* sentence of every control that plugin evidences. It used to quote the
+whole thrown message, and the SDK loaders throw remediation inside it, so `Install: npm install
+<pkg>@latest` reached the gap text of 7 SOC 2, 2 GDPR and 12 NIST SP 800-171 controls. Teach the
+split: **the report says what was not evidenced; the operator channel says how to change it** —
+and never quote an evidence-gap line to a user as a remediation step. ⚠️ Especially for
+**air-gapped** deployments, where an `npm install` instruction cannot be followed at all.
+
+**Also taught:** the two causes are now distinct in the gap text — `plugin skipped: <reason>`
+(fix with `--host` / `CLOUD_PROVIDER`) versus `scanner error: <cause>` (fix a dependency or a
+credential); and a GDPR Art. 32 report now fails closed when an Azure scan refuses, where it
+previously failed nothing. Plugin catalog UNCHANGED at 29 EE; all eight coverage matrices
+UNCHANGED; **peer floor UNCHANGED at CE >= 0.2.49** — not a bump.
+
 ## 0.2.47 (2026-08-27) — paired with EE 0.42.0: the sovereign-cloud release
 
 Requires **CE >= 0.2.49** (raised from 0.2.45 — Enterprise 0.42.0 needs the new partition detection).

package/README.md

@@ -11,7 +11,11 @@ Works with **Claude Code**, **Claude Desktop**, **Cursor**, **Windsurf**, **VS C
 
 ## Current release
 
-**0.2.47** — paired with **Enterprise 0.42.0 / Community 0.2.49**. ⚠️ **A real floor bump: Community >= 0.2.49.**
+**0.2.49** — paired with **Enterprise 0.44.0 / Community 0.2.51**. ⚠️ **NOT a floor bump: Community stays >= 0.2.49.** New in this release's teaching: **there is a Pro `report` subcommand** (`nsauditor-ai report --from <dir> --format executive|jira`) that turns a completed run into a client-facing HTML report or a Jira-importer CSV — with two limits an agent should state rather than let a user discover: the Jira import mapping has not been verified against a live Jira instance, and a value-less flag is a fatal error rather than a silent default; and **an S3 audit-trail gap now means BOTH streams are missing** (plugin 1020 cross-checks CloudTrail data-event coverage before reporting a missing server access log, so a gap disappearing after upgrade on a covered bucket is the fix working, while every uncertain answer — denied read, absent optional SDK, stopped trail, delivery error, prefix-scoped or one-sided selector — keeps the finding unchanged).
+
+**Prior: 0.2.48** — paired with **Enterprise 0.43.0 / Community 0.2.50**. ⚠️ **NOT a floor bump: Community stays >= 0.2.49**, derived rather than reflexive — the one Community behaviour the Enterprise fix depends on already shipped there. New in this release's teaching: **a provider badge is now trustworthy** (an Enterprise scan whose cloud SDK failed to load used to report that provider as *audited*, because a plugin result carrying neither an error nor a skip flag falls through to `ran` and `auditedProviders` derives from `ran`; eighteen refusals across seventeen AWS and GCP plugins now carry their cause, so such a provider reads `errored` and drops out — a provider disappearing after upgrade is the fix, not a regression), and **an evidence gap states a cause, never an instruction** (the engine quoted whole thrown messages, so the loaders' `Install: npm install <pkg>@latest` reached the gap text of 7 SOC 2 / 2 GDPR / 12 NIST SP 800-171 controls — never quote a gap line to a user as remediation, and note that under air-gapped operation it cannot be followed at all). The two causes are now distinct — `plugin skipped:` vs `scanner error:` — because the remedies differ; and a GDPR Art. 32 report now fails closed on an Azure refusal where it previously failed nothing.
+
+**Prior: 0.2.47** — paired with **Enterprise 0.42.0 / Community 0.2.49**. ⚠️ **A real floor bump: Community >= 0.2.49.**
 New in this release's teaching: non-commercial AWS partitions (GovCloud, China, the ISO partitions and
 the European Sovereign Cloud) and Azure sovereign clouds are first-class, and both **refuse rather than
 silently reporting on the wrong estate**. An agent driving a sovereign scan should expect findings that
@@ -92,7 +96,7 @@ nsauditor-ai-agent-skill/
 ├── references/
 │   ├── workflows.md                  # Multi-step workflow recipes (full audit, CI/CD, CTEM)
 │   ├── schemas.md                    # Complete data structures (scan results, CVEs, findings)
-│   └── plugins.md                    # Full plugin catalog (55 scanners with ports & protocols — 27 Community + 28 Enterprise)
+│   └── plugins.md                    # Full plugin catalog (56 scanners with ports & protocols — 27 Community + 29 Enterprise)
 ├── examples/
 │   └── agent-interactions.md         # Example agent reasoning chains (9 scenarios)
 ├── package.json
@@ -149,7 +153,7 @@ When an AI agent loads this skill, it gains:
 | **Workflow patterns** | Multi-step chains: scan → CVE lookup → remediation report |
 | **Schema knowledge** | Complete data structures for parsing and presenting results |
 | **CPE construction** | How to map detected services to NVD vulnerability lookups |
-| **Plugin awareness** | 55 scanner plugins (27 Community + 28 Enterprise) with protocols, ports, capabilities, and multi-framework (SOC 2 · HIPAA §164.312 · NIST CSF 2.0 · PCI DSS v4.0.1 · ISO/IEC 27001:2022 · CIS Controls v8 · GDPR Art. 32 · NIST SP 800-171 Rev 2) substrate-evidence dimensions |
+| **Plugin awareness** | 56 scanner plugins (27 Community + 29 Enterprise) with protocols, ports, capabilities, and multi-framework (SOC 2 · HIPAA §164.312 · NIST CSF 2.0 · PCI DSS v4.0.1 · ISO/IEC 27001:2022 · CIS Controls v8 · GDPR Art. 32 · NIST SP 800-171 Rev 2) substrate-evidence dimensions |
 | **Compliance frameworks** | **Eight frameworks, one scan** — SOC 2 (AICPA TSC 2017) · HIPAA Security Rule §164.312 Technical Safeguards (HHS Required/Addressable discipline per control) · NIST CSF 2.0 (Subcategory-level) · PCI DSS v4.0.1 (QSA RoC sub-requirement-level) · ISO/IEC 27001:2022 (per-Annex-A-code, SoA discipline) · CIS Controls v8 (per-Safeguard; Implementation Group IG1/IG2/IG3 cumulative discipline) · GDPR Article 32 (sub-measure-level; **Art. 32 infrastructure substrate only, NOT GDPR compliance**) · NIST SP 800-171 Rev 2 (requirement-level for the matrix, SP 800-171A determination-statement level for evidence; **examine-method evidence substrate for CMMC Level 2 preparation — never a CMMC certification and never a MET/NOT MET verdict**). All via `--compliance all`, or any CSV subset via `--compliance soc2,hipaa,nist-csf,pci-dss,iso-27001,cis-v8,gdpr,nist-800-171`. Zero BAA required for HIPAA — ePHI never leaves customer infrastructure. |
 | **Security rules** | ZDE, SSRF protection, redaction, scan authorization requirements |
 | **Error handling** | License gates, SSRF blocks, timeout resolution, CPE format errors |
@@ -190,7 +194,7 @@ This package provides **knowledge about** NSAuditor AI. To actually **run** scan
 |---------|-------|-----------|
 | **Community** | Free / MIT | 27 plugins (service probes + host/network discovery + intelligence/meta), basic AI, SARIF, CTEM, scan history |
 | **Pro** | $49/mo | + CVE matching, risk scoring, and intelligence-enriched AI prompts (CVE + MITRE ATT&CK context injected) |
-| **Enterprise** | $2k+/yr | + 28 enterprise plugins (1020-1222 range) — 27 cloud-substrate auditors across AWS / Azure / GCP plus `1023 Zero Trust Assessment`, which scores zero-trust posture from a NETWORK-host scan and does not run on a cloud pass, multi-framework evidence-pack (SOC 2 / HIPAA / NIST CSF 2.0 / PCI DSS v4.0.1 / ISO 27001:2022 / CIS Controls v8 / GDPR Art. 32 / NIST SP 800-171 Rev 2), SHA-256 chain-of-custody attestations, the suppression-approval CLI with opt-in Ed25519 signing (reachable from EE 0.35.0, proven 0.36.0, verified per approver holding key material), air-gapped operation (offline licensing + offline CVE matching) |
+| **Enterprise** | $2k+/yr | + 29 enterprise plugins (1020-1230 range) — 28 cloud-substrate auditors across AWS / Azure / GCP plus `1023 Zero Trust Assessment`, which scores zero-trust posture from a NETWORK-host scan and does not run on a cloud pass, multi-framework evidence-pack (SOC 2 / HIPAA / NIST CSF 2.0 / PCI DSS v4.0.1 / ISO 27001:2022 / CIS Controls v8 / GDPR Art. 32 / NIST SP 800-171 Rev 2), SHA-256 chain-of-custody attestations, the suppression-approval CLI with opt-in Ed25519 signing (reachable from EE 0.35.0, proven 0.36.0, verified per approver holding key material), air-gapped operation (offline licensing + offline CVE matching) |
 
 → [Pricing](https://www.nsauditor.com/ai/pricing/)
 

package/SKILL.md

@@ -16,10 +16,63 @@ description: >
 
 # NSAuditor AI — Agent Skill
 
-> **Version:** 0.2.47 (knowledge current as of **EE 0.42.0** · **requires CE ≥ 0.2.49**) — the sovereign-cloud release.
+> **Version:** 0.2.49 (knowledge current as of **EE 0.44.0** · **requires CE ≥ 0.2.49**) — the client-report release.
 >
-> **What this release (EE 0.42.0) teaches:** **Non-commercial AWS partitions and Azure sovereign clouds are now first-class, and both REFUSE rather than silently reporting on the wrong estate.** When you drive a scan against GovCloud, China, an ISO partition or the European Sovereign Cloud, findings that previously read CLEAN now fire: a public S3 access point riding a bucket delegation, IAM privilege-escalation at CRITICAL (it demoted to HIGH before), shadow-admin graph edges that were missing entirely, and the full effective-decrypt severity ladder (it collapsed to `info`). **THE ID→DEFECT MAPPING, HERE ON THE ALWAYS-LOADED SURFACE because a reader asked for it BY ID got "no source confirming there was a partition-side fix" while it sat in an on-demand reference (measured 2026-08-28):** `1020` S3 access point riding a bucket delegation · `1030` IAM privesc severity + shadow-admin edges · `1110` KMS effective-decrypt ladder · `1050` API Gateway policy classification + SSRF parsers · `1200` alerting-destination liveness · `1040` region denominator. ⚠️ Do NOT attribute the S3 case to `1110` or the decrypt ladder to `1050` — those are the pre-fix misattributions. Pre-0.42.0 non-commercial reports are unproven on THOSE FAMILIES; findings outside them stand. For Azure, `AZURE_ENVIRONMENT` / `ARM_ENVIRONMENT` / `AZURE_ARM_ENDPOINT` / `AZURE_AUTHORITY_HOST` now select the cloud — and an unrecognised or self-contradicting selection **refuses the scan and emits an evidence gap naming the variable that fixes it**, because falling back to commercial is how an operator holding both commercial and sovereign credentials gets a real, clean-looking report about an estate they did not mean. **Every Azure scan stamps the estate it addressed — but WHERE it lands is channel-specific and the Desktop channel does NOT carry it.** On the CLI/report path the stamp rides the evidence stream and the concluder summary. Through MCP it does NOT: `get_findings` iterates `result.findings` with no `result.data` fallback, and the cloud summariser short-circuits on a non-nullish `findings[]` (an EMPTY array is non-nullish, so a genuinely clean Azure scan — the exact case you would want it for — still never reaches `data[]`). **So on Desktop you CANNOT name the estate on a clean Azure result: say that you cannot confirm which estate was addressed and that the operator must check the CLI or the selector variables — never guess one.** On the REFUSAL path the estate IS visible, because it is written into the gap finding's own text. Also new: the SBOM gate (`npm run gate:sbom`) emits CycloneDX/SPDX over *the installed package* rather than the source tree — ⚠️ **but it is a MAINTAINER-side repository script: `scripts/` ships ZERO files in the customer tarball, so an installed package CANNOT run that command** (the npm script entry ships; the script it points at does not). **Never hand `npm run gate:sbom` to an end user as something to run against their install** — that is a published instruction that cannot succeed; the SBOM is generated from a repository checkout and provided on request. And `docs/fips-posture.md` states approved *algorithms*, explicitly not a validated *module* — do not let a user infer FIPS 140 validation from it; whether the RUNTIME beneath the product is a validated module is a property of the operator's platform, not of this product. **Plugin count UNCHANGED at 29; all eight coverage matrices UNCHANGED.**
+> **What EE 0.44.0 / CE 0.2.51 teaches, and both items are about what a REPORT may claim.**
+> **(1) There is a `report` subcommand now, and it is Pro-gated.**
+> `nsauditor-ai report --from <dir> --format executive|jira` turns a completed scan run under
+> `--from` into a client-facing deliverable — an HTML report a consultant sends to their
+> customer, or a Jira-importer CSV. `--run <id>` reports a specific run instead of the newest,
+> `--brand <brand.json>` adds cover-page branding to the executive format, `--out <path>`
+> overrides the destination, `--allow-partial` renders an incomplete run with the caveat stated
+> on the cover. Exit **0** rendered · **1** fix the RUN · **2** fix the REQUEST. ⚠️ Two things to
+> teach a user rather than discover for them: **the Jira import mapping is done in Jira and has
+> not been verified against a live Jira instance** (say so when you hand over the CSV), and a
+> value-less `--from`/`--brand`/`--run`/`--out` is a **fatal error, not a silent default**.
+> **(2) An S3 audit-trail gap now means BOTH streams are missing.** Plugin 1020 used to report
+> *"Access logging not enabled – audit trail gap"* from the bucket's own server access log alone,
+> so a bucket whose object reads and writes a CloudTrail data-event trail already recorded was
+> reported as a gap. It now cross-checks CloudTrail and, where a trail positively covers the
+> bucket, emits positive substrate naming that trail instead. ⚠️ **A gap that DISAPPEARS after
+> upgrade on a bucket covered by a trail is the fix working, not a regression** — the same shape
+> as the provider badge below. Every uncertain answer keeps the finding unchanged: a denied
+> CloudTrail read, an absent optional SDK, a stopped trail, a trail with a delivery error, a
+> prefix-scoped or one-sided selector, a region not reached. The cross-check's own status is
+> reported once in the scan summary with its declared limits, so *"the gap persisted"* and *"the
+> cross-check could not run"* are distinguishable. SOC 2 CC7.1, HIPAA §164.312(b) and NIST SP
+> 800-171 3.12.3 rationales were reworded accordingly — they no longer call server access logs
+> the sole record of object-level access.
+> Plugin catalog UNCHANGED at 29 EE; all eight coverage matrices UNCHANGED; **peer floor
+> UNCHANGED at CE ≥ 0.2.49** — derived, not a bump.
+>
+> **Prior: 0.2.48** — what EE 0.43.0 taught, and both items are about READING a scan rather than running one.
+> **(1) A provider badge is now trustworthy, and it was not before.** An Enterprise scan whose
+> cloud SDK failed to load reported that provider as **audited**: eighteen refusals across
+> seventeen AWS and GCP plugins returned `up: false` with the cause written only into
+> `warnings`, and the Community plugin manager derives `auditedProviders` from plugins that
+> *ran* — an envelope carrying neither an error nor a skip flag falls through to *ran*. Teach
+> that `providerStatus` is now answerable per provider (`{ran, skipped, errored}`) and that a
+> provider DISAPPEARING from `auditedProviders` after upgrade is the fix working, not a
+> regression. ⚠️ Compliance verdicts always failed closed, so **never tell a user their controls
+> were passing over an unscanned estate** — they were not; the badge and the reason were wrong,
+> not the verdicts.
+> **(2) An evidence gap states a CAUSE, never an instruction.** The engine quotes a plugin's
+> reason into the *"could not run"* sentence of every control that plugin evidences, and it used
+> to quote the whole thrown message — so the loaders' own `Install: npm install <pkg>@latest`
+> reached the gap text of 7 SOC 2, 2 GDPR and 12 NIST SP 800-171 controls. ⚠️ **NEVER quote an
+> evidence-gap line to a user as a remediation step**, and be aware the old wording is still in
+> packs produced before 0.43.0. Under **air-gapped operation** an `npm install` instruction
+> cannot be followed at all, which is why it was the wrong channel. The two causes are now
+> distinct: `plugin skipped: <reason>` (fix with `--host` / `CLOUD_PROVIDER`) versus
+> `scanner error: <cause>` (fix a dependency or a credential).
+> Also: a GDPR Art. 32 report now fails closed when an Azure scan refuses, where it previously
+> failed nothing. Plugin catalog UNCHANGED at 29 EE; all eight coverage matrices UNCHANGED;
+> **peer floor UNCHANGED at CE ≥ 0.2.49** — derived, not a bump.
+>
+> **What EE 0.42.0 taught:** **Non-commercial AWS partitions and Azure sovereign clouds are now first-class, and both REFUSE rather than silently reporting on the wrong estate.** When you drive a scan against GovCloud, China, an ISO partition or the European Sovereign Cloud, findings that previously read CLEAN now fire: a public S3 access point riding a bucket delegation, IAM privilege-escalation at CRITICAL (it demoted to HIGH before), shadow-admin graph edges that were missing entirely, and the full effective-decrypt severity ladder (it collapsed to `info`). **THE ID→DEFECT MAPPING, HERE ON THE ALWAYS-LOADED SURFACE because a reader asked for it BY ID got "no source confirming there was a partition-side fix" while it sat in an on-demand reference (measured 2026-08-28):** `1020` S3 access point riding a bucket delegation · `1030` IAM privesc severity + shadow-admin edges · `1110` KMS effective-decrypt ladder · `1050` API Gateway policy classification + SSRF parsers · `1200` alerting-destination liveness · `1040` region denominator. ⚠️ Do NOT attribute the S3 case to `1110` or the decrypt ladder to `1050` — those are the pre-fix misattributions. Pre-0.42.0 non-commercial reports are unproven on THOSE FAMILIES; findings outside them stand. For Azure, `AZURE_ENVIRONMENT` / `ARM_ENVIRONMENT` / `AZURE_ARM_ENDPOINT` / `AZURE_AUTHORITY_HOST` now select the cloud — and an unrecognised or self-contradicting selection **refuses the scan and emits an evidence gap naming the variable that fixes it**, because falling back to commercial is how an operator holding both commercial and sovereign credentials gets a real, clean-looking report about an estate they did not mean. **Every Azure scan stamps the estate it addressed — but WHERE it lands is channel-specific and the Desktop channel does NOT carry it.** On the CLI/report path the stamp rides the evidence stream and the concluder summary. Through MCP it does NOT: `get_findings` iterates `result.findings` with no `result.data` fallback, and the cloud summariser short-circuits on a non-nullish `findings[]` (an EMPTY array is non-nullish, so a genuinely clean Azure scan — the exact case you would want it for — still never reaches `data[]`). **So on Desktop you CANNOT name the estate on a clean Azure result: say that you cannot confirm which estate was addressed and that the operator must check the CLI or the selector variables — never guess one.** On the REFUSAL path the estate IS visible, because it is written into the gap finding's own text. Also new: the SBOM gate (`npm run gate:sbom`) emits CycloneDX/SPDX over *the installed package* rather than the source tree — ⚠️ **but it is a MAINTAINER-side repository script: `scripts/` ships ZERO files in the customer tarball, so an installed package CANNOT run that command** (the npm script entry ships; the script it points at does not). **Never hand `npm run gate:sbom` to an end user as something to run against their install** — that is a published instruction that cannot succeed; the SBOM is generated from a repository checkout and provided on request. And `docs/fips-posture.md` states approved *algorithms*, explicitly not a validated *module* — do not let a user infer FIPS 140 validation from it; whether the RUNTIME beneath the product is a validated module is a property of the operator's platform, not of this product. **Plugin count UNCHANGED at 29; all eight coverage matrices UNCHANGED.**
 
+> **Prior:** 0.2.47 (post-EE-0.42.0 · **requires CE ≥ 0.2.49**) — the sovereign-cloud release.
+>
 > **Prior:** 0.2.46 (post-EE-0.41.0 · **requires CE ≥ 0.2.45**) — the DocumentDB release.
 >
 > ⛔ **If tool output reports an EE version NEWER than the knowledge bound above, say this skill's knowledge does not yet cover that version — never guess at capabilities it might add.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsauditor-ai-agent-skill",
-  "version": "0.2.47",
+  "version": "0.2.49",
   "description": "AI Agent Skill for NSAuditor AI \u2014 gives any AI coding agent built-in knowledge of NSAuditor's MCP tools, schemas, plugins, and security audit workflows.",
   "keywords": [
     "nsauditor",

package/references/plugins.md

@@ -215,7 +215,7 @@ listings, and default pages.
 
 | ID | Name | Tier | Purpose | SOC 2 Controls |
 |----|------|------|---------|----------------|
-| 1020 | AWS Cloud Scanner | Enterprise | S3 bucket hardening (PAB, encryption, versioning, Object Lock, MFA Delete, logging) | C1.1 / C1.2 / CC7.1 |
+| 1020 | AWS Cloud Scanner | Enterprise | S3 bucket hardening (PAB, encryption, versioning, Object Lock, MFA Delete) + object-access audit trail as a JOIN of server access logging AND CloudTrail S3 data-event coverage — a bucket a trail records is not a gap; any uncertain answer keeps the finding | C1.1 / C1.2 / CC7.1 |
 | 1021 | GCP Cloud Scanner | Enterprise | Firewall rule audit + IAM bindings + Storage bucket public-access | CC6.1 / CC6.6 / C1.1 |
 | 1022 | Azure Cloud Scanner | Enterprise | NSG rule analysis + RBAC role assignments + Storage account hardening | CC6.1 / CC6.6 / C1.1 |
 | 1023 | Zero Trust Checker | Enterprise | Segmentation + encryption + identity + lateral movement scoring (reads OBSERVED open ports) | CC6.6 |

package/references/workflows.md

@@ -219,6 +219,7 @@ AI_ENABLED=true AI_PROVIDER=openai OPENAI_API_KEY=sk-... OPENAI_REDACT=true \
 | `scan_response_ai_payload.json` | Redacted payload sent to AI |
 | `scan_response_ai.html` | Styled HTML report with CVE links, severity badges |
 | `scan_response_ai.txt` | AI vulnerability assessment in markdown |
+| `scan_run_<runId>.json` | **Per-run scan record** — written at the ROOT of `--out` (one level above the per-host folders) at run start, appended per host, finalized at the end. It is what `report` is built from, and what lets a report cover STATE its coverage (hosts requested / written / reachable) instead of implying it. On the free tier these are pruned after a retention window. |
 
 ### AI Prompt Modes
 
@@ -273,7 +274,18 @@ User wants to...
 ├── Compare two scans                   → CLI: diff the per-run out-dirs (no compare tool)
 ├── State framework COVERAGE            → compliance_matrix (any tier)
 ├── Produce a compliance EVIDENCE PACK  → CLI: --compliance <fw> --out <dir> (not MCP)
-└── Generate a formatted report         → CLI: --output-format sarif|csv|md (not MCP)
+├── Generate a formatted report         → CLI: --output-format sarif|csv|md (not MCP)
+└── Produce a CLIENT-FACING report      → CLI (Pro): nsauditor-ai report --from <dir>
+                                          --format executive  → self-contained print-ready HTML
+                                                                (+ --brand <brand.json> for a branded cover)
+                                          --format jira       → Jira-importer CSV
+                                          --run <id> | --out <path> | --allow-partial
+                                          exit 0 rendered · 1 fix the RUN · 2 fix the REQUEST
+                                          ⚠️ TELL THE USER: the Jira import mapping is done in
+                                          Jira and has NOT been verified against a live Jira
+                                          instance, and the emitted CSV does not carry that
+                                          caveat — you must hand it over with the file.
+                                          ⚠️ --brand with --format jira is REFUSED, not ignored.
 ```
 
 ---