agentverify 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to the `agentverify` CLI/SDK package are documented here.
+
+## [1.4.0] - Unreleased
+
+### Changed — CI exit codes now distinguish a security failure from an execution error (behavior change)
+
+Previously, `--ci` mode used exit code `1` for **both** a real `NOT_VERIFIED` verdict **and** any execution error (missing/invalid API key, network failure, missing file). That made it impossible for a pipeline to tell "the agent failed the security check" apart from "the scan itself couldn't run."
+
+New exit codes:
+
+| Code | Meaning | Previously |
+| --- | --- | --- |
+| `0` | All scanned files verified | `0` (unchanged) |
+| `1` | `NOT_VERIFIED` — a real security/verification failure | `1` (unchanged) |
+| `2` | `NOT_ASSESSED` — insufficient evidence for a verdict | `2` (unchanged) |
+| `3` | **New.** Execution error — bad/missing API key, network failure, missing file, unknown command | was `1` |
+
+**If your pipeline only checks `exit code != 0` to block a deployment, this is not a breaking change** — every previously-non-zero case is still non-zero. **If your pipeline branches on the exact code `1`**, an execution error will now surface as `3` instead — update any such logic to treat both `1` and `3` as failures, or to react differently to `3` (an infrastructure problem, not a security finding).
+
+### Fixed
+
+- Scanner: findings that reference a detected credential no longer include the live secret value in `evidence` — only a redacted preview (e.g. `api_key: "sk_l****" (redacted)`). Affects report evidence produced by any scan, including those made public via report sharing.
+
+## [1.3.0] - 2026-07-13
+
+Initial public release. See git history for prior changes.

package/README.md

@@ -2,7 +2,7 @@
 
 **Execution trust analysis for AI agents — CLI and SDK**
 
-Scan AI agent configurations for security issues, credential exposure, and governance gaps. Results save automatically to your Agent Verify dashboard.
+Scan AI agent configurations for security issues, credential exposure, and governance gaps. Saved CLI reports appear in your Agent Verify dashboard when API report save succeeds.
 
 ## Install
 
@@ -37,6 +37,31 @@ agentverify scan ./agents
 agentverify scan . --key av_your_key --json
 ```
 
+### Markdown summary
+
+```bash
+agentverify scan ./agents --markdown
+```
+
+### CI mode
+
+```bash
+agentverify scan ./agents --ci
+```
+
+Normal scans print findings without failing the shell just because issues exist. CI mode is stricter: it exits non-zero when an agent is `NOT_VERIFIED`, when a scan errors, or when submitted content cannot be assessed.
+
+Exit codes distinguish a security/verification result from an application error, so a pipeline can tell "the agent failed the check" apart from "the scan itself couldn't run":
+
+| Code | Meaning |
+| --- | --- |
+| `0` | All scanned files verified |
+| `1` | `NOT_VERIFIED` — a security/verification check failed |
+| `2` | `NOT_ASSESSED` — insufficient evidence for a verdict (see `--allow-not-assessed`) |
+| `3` | Execution error — the scan itself could not run (bad key, network failure, missing file) |
+
+All non-zero codes still fail a pipeline step by default, so an existing `if [ $? -ne 0 ]`-style check keeps working unchanged.
+
 ## SDK Usage
 
 ```ts
@@ -51,7 +76,7 @@ const result = await scan(
   { apiKey: process.env.AGENTVERIFY_API_KEY }
 )
 
-result.verdict    // 'VERIFIED' | 'NOT VERIFIED'
+result.verdict    // 'VERIFIED' | 'NOT_VERIFIED' | 'NOT_ASSESSED'
 result.riskScore  // 0-100
 result.findings   // Array of security findings
 ```
@@ -73,10 +98,28 @@ const results = await scanMany(
 ### GitHub Actions
 
 ```yaml
-- name: Scan agents
-  run: npx agentverify scan ./agents --key ${{ secrets.AGENTVERIFY_API_KEY }} --json
+- name: Agent Verify
+  run: npx agentverify scan ./agents --ci
+  env:
+    AGENTVERIFY_API_KEY: ${{ secrets.AGENTVERIFY_API_KEY }}
+```
+
+Use this in pull requests to block merges when an agent is `NOT_VERIFIED`. The CLI prints score, verdict, risk level, top blocker, fix-first guidance, threat categories, A2SPA docs, and the canonical report URL:
+
+```text
+https://aimodularity.com/agentverify/report/?id=REPORT_ID
 ```
 
+For PR comments, run with `--markdown` and post the output with your preferred GitHub Action. For machine-readable pipelines, run with `--json`.
+
+The workflow requires a valid `AGENTVERIFY_API_KEY`. The local Worker code path fails closed for missing, malformed, invalid, disabled, or revoked keys before findings are returned; validate the deployed API path before relying on this as production enforcement. Wire the workflow into branch protection so the non-zero `--ci` exit code blocks merges when an agent is `NOT_VERIFIED`, not assessed, or the API key is unauthorized.
+
+Saved CLI reports sync to the dashboard through the API `cliReports` save path. If the API cannot save the report, the CLI still prints local scan output and tells you dashboard sync did not complete.
+
+Verified reports can expose a README badge from the report page. A packaged Agent Verify GitHub Action (`AI-Blockchain-Ventures/agentverify@v1`) already exists and produces text/Markdown/JSON output plus an optional workflow artifact — see below. Automatically posting that output as a PR comment (rather than just producing it for you to post) is still a planned enhancement, not yet built.
+
+See the full GitHub Action guide at `docs/github-action.md` for composite action inputs, JSON/Markdown examples, branch protection, optional PR comments, and badge guidance.
+
 ## Get your API key
 
 Sign up at https://aimodularity.com/agentverify/dashboard and go to Dashboard -> API

package/dist/chunk-XVA2M2HS.mjs

@@ -0,0 +1,131 @@
+// src/sdk.ts
+var DEFAULT_API_URL = "https://agentverify-api.agentverify.workers.dev/v1/scan";
+var DEFAULT_TIMEOUT = 3e4;
+function normalizeVerdict(value) {
+  if (value === "VERIFIED") return "VERIFIED";
+  if (value === "NOT_ASSESSED" || value === "NOT ASSESSED") return "NOT_ASSESSED";
+  return "NOT_VERIFIED";
+}
+function normalizeScanResult(data) {
+  const findings = Array.isArray(data.findings) ? data.findings : [];
+  const riskScore = typeof data.riskScore === "number" ? data.riskScore : 0;
+  return {
+    ...data,
+    reportId: typeof data.reportId === "string" ? data.reportId : "",
+    verdict: normalizeVerdict(data.verdict),
+    riskScore,
+    riskLevel: data.riskLevel ?? "High Risk",
+    confidence: typeof data.confidence === "number" ? data.confidence : riskScore > 0 ? 80 : 0,
+    optimizationScore: typeof data.optimizationScore === "number" ? data.optimizationScore : 0,
+    reportInsights: data.reportInsights,
+    threatCategories: Array.isArray(data.threatCategories) ? data.threatCategories : [],
+    findings,
+    categoryScores: Array.isArray(data.categoryScores) ? data.categoryScores : [],
+    bom: data.bom ?? {
+      detectedLanguage: "Unknown",
+      detectedFramework: null,
+      detectedPlatform: null,
+      agentName: null,
+      toolAccessLevel: "Unknown",
+      credentialExposure: "Not Detected",
+      memoryPersistence: "Unknown",
+      auditLogging: "Unknown",
+      humanGates: "Unknown",
+      rateLimiting: "Unknown",
+      promptInjectionSurface: "Unknown",
+      delegationScope: "Unknown"
+    },
+    metadata: data.metadata ?? {
+      schemaVersion: "1.3.0",
+      scannerVersion: "unknown",
+      fileName: "unknown",
+      fileSize: 0,
+      scannedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      detectedLanguage: "Unknown",
+      detectedFramework: null,
+      selectedPlatform: null,
+      agentName: null,
+      scanDuration: 0
+    },
+    saved: data.saved === true,
+    reportUrl: data.reportUrl ?? null,
+    artifactFingerprint: data.artifactFingerprint,
+    reportIntegrity: data.reportIntegrity,
+    policyProfile: data.policyProfile ?? null,
+    policyResult: data.policyResult ?? null,
+    attestation: data.attestation ?? null
+  };
+}
+async function scan(input, options) {
+  const { apiKey, apiUrl = DEFAULT_API_URL, timeout = DEFAULT_TIMEOUT } = options;
+  if (!apiKey) {
+    throw new Error(
+      "API key required. Generate one at https://aimodularity.com/agentverify/dashboard"
+    );
+  }
+  if (!input.content || input.content.trim().length === 0) {
+    throw new Error("content is required and cannot be empty");
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetch(apiUrl, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        "User-Agent": "agentverify-sdk/1.0.0"
+      },
+      body: JSON.stringify({
+        content: input.content,
+        fileName: input.fileName ?? "agent",
+        platform: input.platform,
+        policyId: input.policyId
+      }),
+      signal: controller.signal
+    });
+    if (response.status === 401) {
+      throw new Error(
+        "Invalid or unauthorized Agent Verify API key. Generate a valid key at https://aimodularity.com/agentverify/dashboard/"
+      );
+    }
+    if (response.status === 400) {
+      const err = await response.json().catch(() => ({}));
+      throw new Error(err.error ?? "Invalid request");
+    }
+    if (!response.ok) {
+      throw new Error(`API error: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    return normalizeScanResult(data);
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new Error(`Request timed out after ${timeout}ms`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function scanMany(inputs, options, concurrency = 3) {
+  const results = [];
+  for (let i = 0; i < inputs.length; i += concurrency) {
+    const batch = inputs.slice(i, i + concurrency);
+    const batchResults = await Promise.allSettled(
+      batch.map((input) => scan(input, options))
+    );
+    batchResults.forEach((res, j) => {
+      if (res.status === "fulfilled") {
+        results.push({ input: batch[j], result: res.value, error: null });
+      } else {
+        results.push({ input: batch[j], result: null, error: res.reason instanceof Error ? res.reason.message : String(res.reason) });
+      }
+    });
+  }
+  return results;
+}
+
+export {
+  scan,
+  scanMany
+};

package/dist/cli.js

@@ -8,6 +8,61 @@ var import_path = require("path");
 // src/sdk.ts
 var DEFAULT_API_URL = "https://agentverify-api.agentverify.workers.dev/v1/scan";
 var DEFAULT_TIMEOUT = 3e4;
+function normalizeVerdict(value) {
+  if (value === "VERIFIED") return "VERIFIED";
+  if (value === "NOT_ASSESSED" || value === "NOT ASSESSED") return "NOT_ASSESSED";
+  return "NOT_VERIFIED";
+}
+function normalizeScanResult(data) {
+  const findings = Array.isArray(data.findings) ? data.findings : [];
+  const riskScore = typeof data.riskScore === "number" ? data.riskScore : 0;
+  return {
+    ...data,
+    reportId: typeof data.reportId === "string" ? data.reportId : "",
+    verdict: normalizeVerdict(data.verdict),
+    riskScore,
+    riskLevel: data.riskLevel ?? "High Risk",
+    confidence: typeof data.confidence === "number" ? data.confidence : riskScore > 0 ? 80 : 0,
+    optimizationScore: typeof data.optimizationScore === "number" ? data.optimizationScore : 0,
+    reportInsights: data.reportInsights,
+    threatCategories: Array.isArray(data.threatCategories) ? data.threatCategories : [],
+    findings,
+    categoryScores: Array.isArray(data.categoryScores) ? data.categoryScores : [],
+    bom: data.bom ?? {
+      detectedLanguage: "Unknown",
+      detectedFramework: null,
+      detectedPlatform: null,
+      agentName: null,
+      toolAccessLevel: "Unknown",
+      credentialExposure: "Not Detected",
+      memoryPersistence: "Unknown",
+      auditLogging: "Unknown",
+      humanGates: "Unknown",
+      rateLimiting: "Unknown",
+      promptInjectionSurface: "Unknown",
+      delegationScope: "Unknown"
+    },
+    metadata: data.metadata ?? {
+      schemaVersion: "1.3.0",
+      scannerVersion: "unknown",
+      fileName: "unknown",
+      fileSize: 0,
+      scannedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      detectedLanguage: "Unknown",
+      detectedFramework: null,
+      selectedPlatform: null,
+      agentName: null,
+      scanDuration: 0
+    },
+    saved: data.saved === true,
+    reportUrl: data.reportUrl ?? null,
+    artifactFingerprint: data.artifactFingerprint,
+    reportIntegrity: data.reportIntegrity,
+    policyProfile: data.policyProfile ?? null,
+    policyResult: data.policyResult ?? null,
+    attestation: data.attestation ?? null
+  };
+}
 async function scan(input, options) {
   const { apiKey, apiUrl = DEFAULT_API_URL, timeout = DEFAULT_TIMEOUT } = options;
   if (!apiKey) {
@@ -31,13 +86,14 @@ async function scan(input, options) {
       body: JSON.stringify({
         content: input.content,
         fileName: input.fileName ?? "agent",
-        platform: input.platform
+        platform: input.platform,
+        policyId: input.policyId
       }),
       signal: controller.signal
     });
     if (response.status === 401) {
       throw new Error(
-        "Invalid API key. Generate one at https://aimodularity.com/agentverify/dashboard"
+        "Invalid or unauthorized Agent Verify API key. Generate a valid key at https://aimodularity.com/agentverify/dashboard/"
       );
     }
     if (response.status === 400) {
@@ -48,7 +104,7 @@ async function scan(input, options) {
       throw new Error(`API error: ${response.status} ${response.statusText}`);
     }
     const data = await response.json();
-    return data;
+    return normalizeScanResult(data);
   } catch (err) {
     if (err instanceof Error && err.name === "AbortError") {
       throw new Error(`Request timed out after ${timeout}ms`);
@@ -60,8 +116,13 @@ async function scan(input, options) {
 }
 
 // src/cli.ts
-var VERSION = "1.2.0";
-var API_URL = "https://agentverify-api.agentverify.workers.dev/v1/scan";
+var VERSION = "1.4.0";
+var API_URL = process.env.AGENTVERIFY_API_URL ?? "https://agentverify-api.agentverify.workers.dev/v1/scan";
+var A2SPA_DOCS_URL = "https://aimodularity.com/A2SPA/docs";
+var EXIT_OK = 0;
+var EXIT_NOT_VERIFIED = 1;
+var EXIT_NOT_ASSESSED = 2;
+var EXIT_EXECUTION_ERROR = 3;
 var c = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
@@ -76,6 +137,7 @@ var c = {
 var write = (value = "") => process.stdout.write(`${value}
 `);
 var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".ts", ".py", ".json", ".yaml", ".yml", ".md", ".mjs", ".cjs"]);
+var MAX_SCAN_FILE_BYTES = 5 * 1024 * 1024;
 var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".next", "vendor", "coverage", ".cache"]);
 function collectFiles(dir) {
   const files = [];
@@ -103,8 +165,13 @@ function parseArgs(argv) {
     key: "",
     file: "",
     json: false,
+    markdown: false,
+    ci: false,
+    allowNotAssessed: false,
     help: false,
-    version: false
+    version: false,
+    policy: "",
+    summaryFile: ""
   };
   if (result.command === "--help" || result.command === "-h") {
     result.command = "";
@@ -119,6 +186,11 @@ function parseArgs(argv) {
     if (arg === "--key" || arg === "-k") result.key = args[++i] ?? "";
     else if (arg === "--file" || arg === "-f") result.file = args[++i] ?? "";
     else if (arg === "--json") result.json = true;
+    else if (arg === "--markdown") result.markdown = true;
+    else if (arg === "--ci") result.ci = true;
+    else if (arg === "--allow-not-assessed") result.allowNotAssessed = true;
+    else if (arg === "--policy") result.policy = args[++i] ?? "";
+    else if (arg === "--summary-file") result.summaryFile = args[++i] ?? "";
     else if (arg === "--help" || arg === "-h") result.help = true;
     else if (arg === "--version" || arg === "-v") result.version = true;
     else if (!arg.startsWith("-")) result.dir = arg;
@@ -142,6 +214,14 @@ ${c.bold}Options:${c.reset}
   --key, -k     API key (or set AGENTVERIFY_API_KEY env var)
   --file, -f    Scan a single file instead of a directory
   --json        Output results as JSON
+  --markdown    Output a Markdown summary
+  --ci          CI mode: concise output and non-zero exit for NOT VERIFIED
+  --allow-not-assessed
+                In CI mode, do not fail only because content is NOT_ASSESSED
+  --policy <id> Evaluate a built-in policy profile against this scan's evidence
+                in addition to the scanner's own verdict (e.g. financial-agent)
+  --summary-file <path>
+                Write results as JSON to this path (in addition to any other output)
   --version, -v Print version
   --help, -h    Show this help message
 
@@ -158,17 +238,123 @@ ${c.bold}Examples:${c.reset}
   ${c.gray}# Output as JSON (useful for CI/CD)${c.reset}
   agentverify scan . --key av_your_key --json
 
+  ${c.gray}# Markdown summary for pull requests${c.reset}
+  agentverify scan . --key av_your_key --markdown
+
+${c.bold}Exit codes (--ci):${c.reset}
+  0   All scanned files verified
+  1   NOT VERIFIED \u2014 a security/verification check failed
+  2   NOT ASSESSED \u2014 insufficient evidence for a verdict (see --allow-not-assessed)
+  3   Execution error \u2014 the scan itself could not run (bad key, network, missing file)
+
 ${c.bold}Get your API key:${c.reset}
   https://aimodularity.com/agentverify/dashboard
 
 ${c.bold}Docs:${c.reset}
   https://github.com/AI-Blockchain-Ventures/agentverify
+
+${c.bold}A2SPA docs:${c.reset}
+  ${A2SPA_DOCS_URL}
+`);
+}
+function getTopBlocker(result) {
+  return result.reportInsights?.topBlocker ?? result.findings[0]?.title ?? "No blocking finding detected";
+}
+function getFixFirst(result) {
+  const fromInsights = result.reportInsights?.fixPriority?.filter((item) => item.priority === "fix_first").map((item) => item.title) ?? [];
+  const fallback = result.findings.slice(0, 3).map((item) => item.title);
+  return (fromInsights.length ? fromInsights : fallback).slice(0, 3);
+}
+function getRelevantThreatCategories(result) {
+  return (result.threatCategories ?? []).filter((item) => item.status !== "not_assessed").slice(0, 6).map((item) => `${item.label} (${item.status.replace("_", " ")})`);
+}
+function criticalCount(result) {
+  return result.findings.filter((f) => f.severity === "critical").length;
+}
+function highCount(result) {
+  return result.findings.filter((f) => f.severity === "high").length;
+}
+function fingerprintPreview(result) {
+  const hash = result.artifactFingerprint?.artifactHash;
+  return hash ? `${hash.slice(0, 12)}\u2026` : null;
+}
+function printDetailedSummary(result, fileName) {
+  const verified = result.verdict === "VERIFIED";
+  const verdictColor = verified ? c.green : result.verdict === "NOT_ASSESSED" ? c.yellow : c.red;
+  write(`
+${c.bold}${c.cyan}Agent Verify${c.reset}`);
+  write(`${c.gray}${fileName}${c.reset}`);
+  write(`${c.bold}Score:${c.reset} ${result.riskScore}/100`);
+  write(`${c.bold}Verdict:${c.reset} ${verdictColor}${result.verdict === "NOT_VERIFIED" ? "NOT VERIFIED" : result.verdict.replace("_", " ")}${c.reset}`);
+  write(`${c.bold}Risk level:${c.reset} ${result.riskLevel}`);
+  write(`${c.bold}Confidence:${c.reset} ${result.confidence}/100`);
+  write(`${c.bold}Critical / High findings:${c.reset} ${criticalCount(result)} / ${highCount(result)}`);
+  if (result.metadata?.scannerVersion) write(`${c.bold}Ruleset version:${c.reset} ${result.metadata.scannerVersion}`);
+  if (fingerprintPreview(result)) write(`${c.bold}Artifact fingerprint:${c.reset} ${fingerprintPreview(result)}`);
+  if (result.policyProfile) write(`${c.bold}Policy (${result.policyProfile}):${c.reset} ${result.policyResult === "PASS" ? `${c.green}PASS${c.reset}` : `${c.red}FAIL${c.reset}`}`);
+  write(`${c.bold}Top blocker:${c.reset} ${getTopBlocker(result)}`);
+  write(`
+${c.bold}Fix first:${c.reset}`);
+  const fixes = getFixFirst(result);
+  if (fixes.length) fixes.forEach((item, index) => write(`  ${index + 1}. ${item}`));
+  else write(`  No blocking fixes detected. Re-scan after any material change.`);
+  if (result.reportInsights?.nextAction) write(`
+${c.bold}Next action:${c.reset} ${result.reportInsights.nextAction}`);
+  const threats = getRelevantThreatCategories(result);
+  if (threats.length) {
+    write(`
+${c.bold}Threat categories:${c.reset}`);
+    threats.forEach((item) => write(`  - ${item}`));
+  }
+  if (result.saved && result.reportId) write(`${c.bold}View report:${c.reset} https://aimodularity.com/agentverify/report/?id=${result.reportId}`);
+  write(`${c.bold}A2SPA docs:${c.reset} ${A2SPA_DOCS_URL}`);
+  write(`${c.gray}Re-scan:${c.reset} agentverify scan --file ${fileName} --key $AGENTVERIFY_API_KEY
 `);
 }
+function markdownSummary(results, summary) {
+  const lines = ["# Agent Verify", "", `Files scanned: ${summary.total}`, `Verified: ${summary.verified}`, `Not verified: ${summary.notVerified}`, `Not assessed: ${summary.notAssessed}`, `Errors: ${summary.errors}`, ""];
+  for (const item of results) {
+    if (!item.result) {
+      lines.push(`## ${item.file}`, "", `Error: ${item.error ?? "Unknown error"}`, "");
+      continue;
+    }
+    lines.push(`## ${item.file}`, "", `Score: ${item.result.riskScore}/100`, `Verdict: ${item.result.verdict === "NOT_VERIFIED" ? "NOT VERIFIED" : item.result.verdict.replace("_", " ")}`, `Risk level: ${item.result.riskLevel}`, `Critical / High findings: ${criticalCount(item.result)} / ${highCount(item.result)}`);
+    if (item.result.metadata?.scannerVersion) lines.push(`Ruleset version: ${item.result.metadata.scannerVersion}`);
+    if (fingerprintPreview(item.result)) lines.push(`Artifact fingerprint: \`${fingerprintPreview(item.result)}\``);
+    if (item.result.policyProfile) lines.push(`Policy (${item.result.policyProfile}): ${item.result.policyResult}`);
+    lines.push(`Top blocker: ${getTopBlocker(item.result)}`, "");
+    const fixes = getFixFirst(item.result);
+    if (fixes.length) lines.push("Fix first:", ...fixes.map((fix, index) => `${index + 1}. ${fix}`), "");
+    const threats = getRelevantThreatCategories(item.result);
+    if (threats.length) lines.push("Threat categories:", ...threats.map((threat) => `- ${threat}`), "");
+    if (item.result.reportId) lines.push(`Report: https://aimodularity.com/agentverify/report/?id=${item.result.reportId}`, "");
+  }
+  lines.push(`A2SPA docs: ${A2SPA_DOCS_URL}`);
+  return lines.join("\n");
+}
+function writeGithubJobSummary(results, summary) {
+  const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+  if (!summaryPath) return;
+  try {
+    (0, import_fs.appendFileSync)(summaryPath, `${markdownSummary(results, summary)}
+`);
+  } catch (e) {
+    console.error(`Warning: could not write GitHub job summary: ${e instanceof Error ? e.message : e}`);
+  }
+}
+function writeSummaryFile(path, results, summary) {
+  if (!path) return;
+  try {
+    (0, import_fs.writeFileSync)(path, JSON.stringify({ results, summary }, null, 2));
+  } catch (e) {
+    console.error(`Warning: could not write summary file: ${e instanceof Error ? e.message : e}`);
+  }
+}
 function printVerdict(result, fileName) {
   const verified = result.verdict === "VERIFIED";
-  const icon = verified ? `${c.green}\u2713${c.reset}` : `${c.red}\u2717${c.reset}`;
-  const verdict = verified ? `${c.green}VERIFIED${c.reset}    ` : `${c.red}NOT VERIFIED${c.reset}`;
+  const notAssessed = result.verdict === "NOT_ASSESSED";
+  const icon = verified ? `${c.green}\u2713${c.reset}` : notAssessed ? `${c.yellow}\u26A0${c.reset}` : `${c.red}\u2717${c.reset}`;
+  const verdict = verified ? `${c.green}VERIFIED${c.reset}    ` : notAssessed ? `${c.yellow}NOT ASSESSED${c.reset}` : `${c.red}NOT VERIFIED${c.reset}`;
   const score = verified ? `${c.green}${result.riskScore}/100${c.reset}` : result.riskScore >= 50 ? `${c.yellow}${result.riskScore}/100${c.reset}` : `${c.red}${result.riskScore}/100${c.reset}`;
   const findings = result.findings.length > 0 ? `${c.gray}\u2014 ${result.findings.length} finding${result.findings.length === 1 ? "" : "s"}${c.reset}` : "";
   const name = fileName.padEnd(30);
@@ -182,20 +368,23 @@ async function runScan(args) {
     console.error(`
 ${c.red}Error:${c.reset} API key required
 `);
-    console.error(`  Set with --key av_your_key or AGENTVERIFY_API_KEY env var`);
-    console.error(`  Get your key at https://aimodularity.com/agentverify/dashboard
+    console.error(`  Set with --key av_your_key or AGENTVERIFY_API_KEY env var.`);
+    console.error(`  Get your key at https://aimodularity.com/agentverify/dashboard/`);
+    console.error(`  Example: AGENTVERIFY_API_KEY=av_your_key agentverify scan .
 `);
-    process.exit(1);
+    process.exit(EXIT_EXECUTION_ERROR);
   }
   let files = [];
   if (args.file) {
     files = [args.file];
   } else {
     const dir = args.dir;
-    write(`
+    if (!args.markdown && !args.json) {
+      write(`
 ${c.bold}Agent Verify${c.reset} ${c.gray}v${VERSION}${c.reset}`);
-    write(`${c.gray}Scanning ${dir}...${c.reset}
+      write(`${c.gray}Scanning ${dir}...${c.reset}
 `);
+    }
     files = collectFiles(dir);
     if (files.length === 0) {
       write(`${c.yellow}No agent files found in ${dir}${c.reset}`);
@@ -207,16 +396,21 @@ ${c.bold}Agent Verify${c.reset} ${c.gray}v${VERSION}${c.reset}`);
   const jsonResults = [];
   let verified = 0;
   let notVerified = 0;
+  let notAssessed = 0;
   let errors = 0;
   const CONCURRENCY = 3;
   for (let i = 0; i < files.length; i += CONCURRENCY) {
     const batch = files.slice(i, i + CONCURRENCY);
     const batchResults = await Promise.allSettled(
       batch.map(async (filePath) => {
+        const fileStat = (0, import_fs.statSync)(filePath);
+        if (fileStat.size > MAX_SCAN_FILE_BYTES) {
+          throw new Error(`File is ${(fileStat.size / 1024 / 1024).toFixed(1)}MB, over the ${MAX_SCAN_FILE_BYTES / 1024 / 1024}MB scan limit \u2014 skipped`);
+        }
         const content = (0, import_fs.readFileSync)(filePath, "utf-8");
         const relPath = (0, import_path.relative)(args.dir === "." ? process.cwd() : args.dir, filePath);
         const result = await scan(
-          { content, fileName: relPath },
+          { content, fileName: relPath, policyId: args.policy || void 0 },
           { apiKey: args.key, apiUrl: API_URL }
         );
         return { filePath, relPath, result };
@@ -226,9 +420,13 @@ ${c.bold}Agent Verify${c.reset} ${c.gray}v${VERSION}${c.reset}`);
       const outcome = batchResults[j];
       if (outcome.status === "fulfilled") {
         const { relPath, result } = outcome.value;
-        if (!args.json) printVerdict(result, relPath);
+        if (!args.json && !args.markdown) {
+          if (args.file && !args.ci) printDetailedSummary(result, relPath);
+          else printVerdict(result, relPath);
+        }
         jsonResults.push({ file: relPath, result, error: null });
         if (result.verdict === "VERIFIED") verified++;
+        else if (result.verdict === "NOT_ASSESSED") notAssessed++;
         else notVerified++;
       } else {
         const filePath = batch[j];
@@ -242,32 +440,58 @@ ${c.bold}Agent Verify${c.reset} ${c.gray}v${VERSION}${c.reset}`);
       }
     }
   }
+  const summary = { total: files.length, verified, notVerified, notAssessed, errors };
+  writeGithubJobSummary(jsonResults, summary);
+  writeSummaryFile(args.summaryFile, jsonResults, summary);
   if (args.json) {
-    write(JSON.stringify({ results: jsonResults, summary: { total: files.length, verified, notVerified, errors } }, null, 2));
+    write(JSON.stringify({ results: jsonResults, summary }, null, 2));
+    if (errors > 0) process.exit(EXIT_EXECUTION_ERROR);
+    if (args.ci) {
+      if (notVerified > 0) process.exit(EXIT_NOT_VERIFIED);
+      if (notAssessed > 0 && !args.allowNotAssessed) process.exit(EXIT_NOT_ASSESSED);
+    }
     return;
   }
+  if (args.markdown) {
+    write(markdownSummary(jsonResults, summary));
+    if (errors > 0) process.exit(EXIT_EXECUTION_ERROR);
+    if (args.ci) {
+      if (notVerified > 0) process.exit(EXIT_NOT_VERIFIED);
+      if (notAssessed > 0 && !args.allowNotAssessed) process.exit(EXIT_NOT_ASSESSED);
+    }
+    return;
+  }
+  const savedReports = jsonResults.filter((item) => item.result?.saved && item.result.reportId).length;
   write(`
 ${c.gray}${"\u2500".repeat(60)}${c.reset}`);
   write(`${c.bold}Agent Verify Scan Complete${c.reset}`);
   write(`${c.gray}Files scanned:${c.reset}   ${files.length}`);
   write(`${c.green}Verified:${c.reset}        ${verified}`);
   if (notVerified > 0) write(`${c.red}Not Verified:${c.reset}    ${notVerified}`);
+  if (notAssessed > 0) write(`${c.yellow}Not Assessed:${c.reset}    ${notAssessed}`);
   if (errors > 0) write(`${c.yellow}Errors:${c.reset}          ${errors}`);
   write(`${c.gray}${"\u2500".repeat(60)}${c.reset}`);
-  write(`
-${c.gray}View reports: https://aimodularity.com/agentverify/dashboard${c.reset}
+  if (savedReports > 0) write(`
+${c.gray}Saved CLI reports appear in your dashboard: https://aimodularity.com/agentverify/dashboard/${c.reset}`);
+  else write(`
+${c.gray}No dashboard report was saved. Check API key access and retry if you need dashboard sync.${c.reset}`);
+  write(`${c.gray}A2SPA docs: ${A2SPA_DOCS_URL}${c.reset}
 `);
-  if (notVerified > 0) process.exit(1);
+  if (errors > 0) process.exit(EXIT_EXECUTION_ERROR);
+  if (args.ci) {
+    if (notVerified > 0) process.exit(EXIT_NOT_VERIFIED);
+    if (notAssessed > 0 && !args.allowNotAssessed) process.exit(EXIT_NOT_ASSESSED);
+  }
 }
 async function main() {
   const args = parseArgs(process.argv);
   if (args.version) {
     write(`agentverify v${VERSION}`);
-    process.exit(0);
+    process.exit(EXIT_OK);
   }
   if (args.help || !args.command) {
     printHelp();
-    process.exit(0);
+    process.exit(EXIT_OK);
   }
   if (args.command === "scan") {
     await runScan(args);
@@ -276,11 +500,11 @@ async function main() {
 ${c.red}Unknown command: ${args.command}${c.reset}`);
     console.error(`Run ${c.cyan}agentverify --help${c.reset} for usage
 `);
-    process.exit(1);
+    process.exit(EXIT_EXECUTION_ERROR);
   }
 }
 main().catch((err) => {
   console.error(`
 ${c.red}Fatal error:${c.reset}`, err instanceof Error ? err.message : err);
-  process.exit(1);
+  process.exit(EXIT_EXECUTION_ERROR);
 });