pqcheck 0.14.1 → 0.15.0

package/bin/pqcheck.js

@@ -6,17 +6,34 @@
 // Zero deps (uses node:fetch). Works under `npx pqcheck` without installation.
 // =============================================================================
 
+// R74-confirm BLOCKING #5 (GPT 2026-05-22): Node version startup guard.
+// Native fetch requires Node 18+. Without this guard, pre-Node-18 users see
+// "fetch is not defined" at runtime — confusing because package.json `engines`
+// is not enforced by npm/npx. Fail loud + actionable.
+(() => {
+  const major = Number((process.versions.node || "0").split(".")[0]);
+  if (Number.isFinite(major) && major < 18) {
+    process.stderr.write(
+      `\n  ✗ pqcheck requires Node 18 or newer (you have ${process.versions.node}).\n` +
+      `    Native fetch is unavailable on this version.\n` +
+      `    Install Node 18+ from https://nodejs.org or use nvm: \`nvm install 18 && nvm use 18\`\n` +
+      `    Then retry: \`npx pqcheck <domain>\`\n\n`
+    );
+    process.exit(1);
+  }
+})();
+
 const API_BASE = process.env.PQCHECK_API_BASE || "https://cipherwake.io";
-const VERSION = "0.12.0";
+const VERSION = "0.15.0";
 
 // API-key support — paid tiers (Starter $29 / Growth $79 / Scale $199) get
 // per-account monthly quotas instead of the per-IP rate limit. Set via:
 //   export CIPHERWAKE_API_KEY=qpk_<32-hex>
 // Anonymous CLI use still works (no env var → falls back to IP rate limit).
 //
-// QUANTAPACT_API_KEY is honored as a deprecated fallback for existing users
-// (rebrand 2026-05-15). Will be removed in v1.0; in the meantime no break.
-const QP_API_KEY = (process.env.CIPHERWAKE_API_KEY || process.env.QUANTAPACT_API_KEY || "").trim();
+// Removed QUANTAPACT_API_KEY backwards-compat fallback 2026-05-22.
+// Pre-launch, no customers had it set in production — no break.
+const QP_API_KEY = (process.env.CIPHERWAKE_API_KEY || "").trim();
 
 // Builds headers with optional Authorization. Use for every CLI → API call
 // so a single env-var toggle authenticates every endpoint at once.
@@ -127,6 +144,36 @@ async function main() {
   if (args[0] === "onboard") {
     return runOnboardCommand(args.slice(1));
   }
+  if (args[0] === "guard") {
+    // CLI v0.15.0 — `pqcheck guard --domain X -- <deploy command>`.
+    // Wraps any deploy command: runs deploy-check first, conditionally
+    // executes the deploy command based on ship_decision. The strongest
+    // single artifact for terminal-first AI-coder workflows because the
+    // AI doesn't have to remember two commands.
+    return runGuardCommand(args.slice(1));
+  }
+  if (args[0] === "protocol") {
+    // CLI v0.15.0 — `pqcheck protocol install` opt-in installer with
+    // Rule 17 consent flow. Adds the AI Coder Protocol to ~/.claude/CLAUDE.md
+    // / .cursorrules (with auto/manual/no consent). Never silent.
+    return runProtocolCommand(args.slice(1));
+  }
+  if (args[0] === "setup") {
+    // CLI v0.15.0 — `pqcheck setup --auto --domain <D>` consolidated installer.
+    // One command installs everything: GitHub Action workflow, AI Coder
+    // Protocol across detected rules files, git pre-push hook, and
+    // statusline config. The launch-story command for AI-coder workflows
+    // ("one command sets you up across every AI coder").
+    return runSetupCommand(args.slice(1));
+  }
+  if (args[0] === "debug-network" || args.includes("--debug-network")) {
+    // R74-confirm SHIP #14-15 (GPT 2026-05-22): probe connectivity to every
+    // upstream Cipherwake depends on + report which ones are reachable.
+    // Customer-facing diagnostic for "the scan hung" / "command-not-found"
+    // / "corporate proxy" / "VPN-blocked" failure modes — instead of leaving
+    // them to guess, surface the actual broken hop.
+    return runDebugNetworkCommand();
+  }
 
   // Multi-domain support: positional args are domains.
   // --file reads additional domains from a newline-delimited file.
@@ -188,17 +235,18 @@ async function main() {
   // a cert/key change you just deployed. Subject to a 20/hr per-IP cap on
   // the server side.
   const fresh = args.includes("--fresh") || args.includes("--force");
+  const aiMode = parseAiMode(args);
 
   // One-shot scan(s)
   let worstExit = 0;
   for (const domain of domains) {
-    const exit = await runOneScan({ domain, format, quiet, threshold, webhookUrl, multi: domains.length > 1, fresh });
+    const exit = await runOneScan({ domain, format, quiet, threshold, webhookUrl, multi: domains.length > 1, fresh, aiMode });
     if (exit > worstExit) worstExit = exit;
   }
   process.exit(worstExit);
 }
 
-async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi, fresh }) {
+async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi, fresh, aiMode }) {
   if (!quiet && format === "text") process.stderr.write(color("dim", `Scanning ${domain}${fresh ? " (forcing fresh)" : ""} ...`));
   let report;
   try {
@@ -248,6 +296,71 @@ async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi,
     console.error(`pqcheck: ⚠ ${domain} — using cached score (live probe failed: ${report._meta.degradedReason || "unknown"}; last verified ${report._meta.lastUpdated || "?"})`);
   }
 
+  // AI Coder Mode — three-layer output for Claude Code / Cursor / Aider.
+  // Overrides --format when --ai is set; emits the structured block at the
+  // bottom so downstream agents can parse ship_decision deterministically.
+  if (aiMode) {
+    const findings = Array.isArray(report.findings) ? report.findings : [];
+    const maxSev = highestSeverity(findings);
+    const shipDecision = computeShipDecision({ maxSeverity: maxSev });
+    const topFinding = [...findings].sort((a, b) => severityRank(b.severity) - severityRank(a.severity))[0];
+
+    const topIssue = topFinding
+      ? `[${String(topFinding.severity || "").toUpperCase()}] ${topFinding.title || topFinding.detail || "finding"}`
+      : "No findings at or above LOW severity.";
+    const whyMatters = topFinding?.detail || "DBR scoring measures harvest-now-decrypt-later risk. Findings reflect public-surface signals only.";
+    const nextActions = shipDecision === "pass"
+      ? [`Domain looks healthy. View full report: ${API_BASE}/r/${domain}`]
+      : [
+          `Review finding above and decide if it was intentional.`,
+          `View full report: ${API_BASE}/r/${domain}`,
+          `Re-scan with --fresh after fix: npx pqcheck ${domain} --fresh --ai`,
+        ];
+
+    console.log("");
+    console.log(formatAiBanner({
+      domain,
+      kind: "scan",
+      dbr: report.score,
+      grade: report.grade,
+      maxSeverity: maxSev,
+      shipDecision,
+    }));
+    console.log(formatAiBody({ topIssue, whyMatters, nextActions }));
+    console.log(formatAiFooterBlock({
+      status: shipDecision,
+      domain,
+      kind: "scan",
+      dbr: typeof report.score === "number" ? report.score.toFixed(1) : "",
+      grade: report.grade || "",
+      max_severity: maxSev,
+      ship_decision: shipDecision,
+      top_issue: topFinding?.id || topFinding?.title || "none",
+      findings_high: findings.filter((f) => severityRank(f.severity) === 3).length,
+      findings_critical: findings.filter((f) => severityRank(f.severity) === 4).length,
+      scanned_at: new Date().toISOString(),
+      advisory_only: "true",
+    }));
+    console.log("");
+
+    await writeLastScanFile({
+      domain,
+      kind: "scan",
+      score: typeof report.score === "number" ? report.score : null,
+      grade: report.grade || null,
+      max_severity: maxSev,
+      ship_decision: shipDecision,
+      top_issue: topFinding?.id || topFinding?.title || null,
+    });
+
+    // Threshold check still applies under --ai (script-pipeable). Otherwise
+    // exit code reflects ship_decision so the caller can route on it.
+    if (threshold !== null && typeof report.score === "number" && report.score >= threshold) {
+      return 2;
+    }
+    return shipDecisionExitCode(shipDecision);
+  }
+
   // Output dispatch
   if (quiet) {
     if (multi) {
@@ -405,6 +518,144 @@ function parseWebhook(args) {
   return raw;
 }
 
+// =============================================================================
+// AI Coder Mode — `--ai` / `--agent` output
+// =============================================================================
+// Three-layer output designed for AI-coder workflows (Claude Code / Cursor /
+// Aider / etc.) where the user can't see GitHub PR comments and the chat
+// scrollback buries verbose CLI output:
+//
+//   Layer 1 (top banner)   — un-missable one-liner with status + ship_decision
+//   Layer 2 (body)         — top finding + why it matters + next action (≤12 lines)
+//   Layer 3 (footer block) — machine-readable CIPHERWAKE_AI_GUARD_RESULT block
+//                            that AI agents can deterministically parse to
+//                            decide pass / review / block
+//
+// The `ship_decision` field is advisory only — Cipherwake is a scanner, not
+// an authoritative deploy-blocker. The methodology page documents this
+// explicitly (Rule 1).
+// =============================================================================
+
+function parseAiMode(args) {
+  return args.includes("--ai") || args.includes("--agent");
+}
+
+function severityRank(s) {
+  const map = { critical: 4, high: 3, medium: 2, low: 1, info: 0, none: -1 };
+  return map[String(s || "none").toLowerCase()] ?? 0;
+}
+
+function highestSeverity(findings) {
+  if (!Array.isArray(findings) || findings.length === 0) return "none";
+  let best = "none";
+  for (const f of findings) {
+    if (severityRank(f.severity) > severityRank(best)) best = f.severity;
+  }
+  return best;
+}
+
+// Compute ship_decision: pass | review | block.
+// Used in three contexts:
+//   - one-shot scan: severity-only, no diff baseline
+//   - trust-diff / preview-diff: severity + diff-since-baseline
+//   - deploy-check: same as trust-diff (it's an alias)
+//
+// Decision rules (advisory only):
+//   * `block`  — critical severity present
+//   * `review` — high severity OR diff introduced new high-severity OR DBR drop ≥1.0
+//   * `pass`   — everything else
+function computeShipDecision({ maxSeverity, hasUnexpectedDiff, scoreDelta }) {
+  const sev = String(maxSeverity || "none").toLowerCase();
+  if (sev === "critical") return "block";
+  if (sev === "high") return "review";
+  if (hasUnexpectedDiff) return "review";
+  if (typeof scoreDelta === "number" && scoreDelta <= -1.0) return "review";
+  return "pass";
+}
+
+function aiBannerColor(shipDecision) {
+  if (shipDecision === "pass") return "green";
+  if (shipDecision === "block") return "red";
+  return "yellow"; // review
+}
+
+function aiStatusEmoji(shipDecision) {
+  if (shipDecision === "pass") return "✓";
+  if (shipDecision === "block") return "✗";
+  return "⚠";
+}
+
+function formatAiBanner({ domain, kind, dbr, grade, maxSeverity, shipDecision }) {
+  const emoji = aiStatusEmoji(shipDecision);
+  const statusWord = ({ pass: "PASS", review: "REVIEW", block: "BLOCK" })[shipDecision] || "REVIEW";
+  const c = aiBannerColor(shipDecision);
+  const dbrStr = typeof dbr === "number" ? dbr.toFixed(1) : "—";
+  const gradeStr = grade ? ` ${grade}` : "";
+  const sevStr = maxSeverity && maxSeverity !== "none" ? ` · ${String(maxSeverity).toUpperCase()}` : "";
+  return color(c, `◆ cipherwake · ${kind} · ${emoji} ${statusWord} · ${domain} · DBR ${dbrStr}${gradeStr}${sevStr} · ship_decision=${shipDecision}`);
+}
+
+function formatAiBody({ topIssue, whyMatters, nextActions }) {
+  const lines = [];
+  if (topIssue) {
+    lines.push("");
+    lines.push(color("bold", "Top finding:"));
+    lines.push(`  ${topIssue}`);
+  }
+  if (whyMatters) {
+    lines.push("");
+    lines.push(color("bold", "Why it matters:"));
+    lines.push(`  ${whyMatters}`);
+  }
+  if (Array.isArray(nextActions) && nextActions.length > 0) {
+    lines.push("");
+    lines.push(color("bold", "Recommended next action:"));
+    for (const a of nextActions) {
+      lines.push(`  ${a}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// Emit the machine-readable block. Keys are normalized; values are
+// newline-stripped. AI agents grep between the CIPHERWAKE_AI_GUARD_RESULT
+// and END_CIPHERWAKE_AI_GUARD_RESULT markers and parse key=value lines.
+function formatAiFooterBlock(fields) {
+  const lines = ["", "CIPHERWAKE_AI_GUARD_RESULT"];
+  for (const [k, v] of Object.entries(fields)) {
+    if (v === undefined || v === null) continue;
+    const safeK = String(k).replace(/[\s=]/g, "_");
+    const safeV = String(v).replace(/[\r\n]+/g, " ");
+    lines.push(`${safeK}=${safeV}`);
+  }
+  lines.push("END_CIPHERWAKE_AI_GUARD_RESULT");
+  return color("dim", lines.join("\n"));
+}
+
+// Persist last-scan state to ~/.config/cipherwake/last-scan.json.
+// Feeds the optional cipherwake-statusline script (v0.16.0) so users get
+// persistent ambient state in their AI coder's status line. Best-effort —
+// never throws (a write failure here doesn't break the scan).
+async function writeLastScanFile(payload) {
+  try {
+    const os = await import("node:os");
+    const path = await import("node:path");
+    const fs = await import("node:fs/promises");
+    const dir = path.join(os.homedir(), ".config", "cipherwake");
+    await fs.mkdir(dir, { recursive: true });
+    const file = path.join(dir, "last-scan.json");
+    await fs.writeFile(file, JSON.stringify({ ...payload, written_at: new Date().toISOString() }, null, 2));
+  } catch {
+    // best-effort
+  }
+}
+
+// Map ship_decision → exit code so CI / shell scripts can act on it
+// without parsing the structured block. pass=0, review=1, block=2.
+function shipDecisionExitCode(d) {
+  return d === "block" ? 2 : d === "review" ? 1 : 0;
+}
+
 // ---------- format renderers (CSV + markdown) ----------
 
 let _csvHeaderPrinted = false;
@@ -660,7 +911,7 @@ ${color("bold", "What you'll see:")} a single letter grade (A–F), the score co
 top findings, and a link to the full interactive report.
 
 ${color("bold", "Free + open methodology.")} No account needed for single-domain scans.
-Add ${color("dim", "QUANTAPACT_API_KEY")} env var for higher rate limits + private results
+Add ${color("dim", "CIPHERWAKE_API_KEY")} env var for higher rate limits + private results
 (create one at ${color("dim", "https://cipherwake.io/signin")}).
 `);
 }
@@ -682,7 +933,9 @@ ${color("bold", "Commands:")}
   npx pqcheck watch <domain>                    Add a domain to your watched-domain list (requires CIPHERWAKE_API_KEY)
   npx pqcheck onboard <domain>                  One-command setup wizard (scan + init + vendors + checklist + open browser)
   npx pqcheck init                              Interactive scaffold for .github/workflows/cipherwake.yml
-  npx pqcheck deploy-check <domain>             Pre-deploy trust gate (Trust Diff vs last scan; deploy-friendly framing)
+  npx pqcheck deploy-check <domain>             Pre-deploy trust gate (Trust Diff vs last scan; deploy-friendly framing) — see also: AI Coder Protocol at https://cipherwake.io/methodology/ai-coder-protocol
+  npx pqcheck guard --domain <D> -- <cmd>       NEW: wrap any deploy command. Runs deploy-check first; conditionally runs <cmd> based on ship_decision. The strongest single artifact for AI-coder workflows.
+  npx pqcheck protocol install                  NEW: install the AI Coder Protocol into your CLAUDE.md / .cursorrules (Rule 17 consent flow)
   npx pqcheck release-checklist [domain]        Print a pre-release trust checklist (markdown, offline)
   npx pqcheck vendors export <domain>           Write cipherwake.vendors.json from observed third-party scripts
   npx pqcheck vendors check <domain>            Compare current scan to lockfile; exit 4 on new origins (Free CI gate)
@@ -2021,8 +2274,89 @@ async function runChangesCommand(args) {
  *   2 = fail     — deltas observed at or above fail-on threshold
  *   3 = error    — auth/quota/network failure
  *
- * Requires CIPHERWAKE_API_KEY env var (Free tier: 30 calls/mo at /account#api-keys).
+ * Authentication paths (per server's applyRepoQuota — supports all three):
+ *   • CIPHERWAKE_API_KEY=qpk_... (paid quota, higher cap, off-Actions usage)
+ *   • GITHUB_ACTIONS=true + id-token (OIDC, keyless, Free 100 calls/repo/mo)
+ *   • No auth (anonymous per-IP rate limit — first-use friction-free path)
+ *
+ * R74-confirm friction fix (GPT 2026-05-22): previously the CLI hard-gated
+ * on CIPHERWAKE_API_KEY before even attempting the call, which broke the
+ * frictionless first-use AI-coder funnel. The hard-gate was gratuitous —
+ * the server has supported anonymous calls since the applyRepoQuota
+ * middleware shipped. Now the CLI just attempts the call with whatever
+ * auth context is available; server applies the appropriate quota path.
  */
+// R74-confirm friction fix (GPT 2026-05-22): when deploy-check has no
+// baseline yet (first-deploy of a brand-new domain), fall through to
+// /api/scan and emit ship_decision based on current absolute findings.
+// This makes `pqcheck deploy-check <new-domain> --ai` work on first call
+// with zero setup — no API key, no prior scan, nothing.
+async function runScanBasedDeployCheck(domain, args) {
+  const headers = {
+    "Content-Type": "application/json",
+    "User-Agent": `pqcheck-cli/${VERSION}`,
+  };
+  if (QP_API_KEY) headers["Authorization"] = `Bearer ${QP_API_KEY}`;
+
+  let resp;
+  try {
+    resp = await fetch(`${API_BASE}/api/scan?domain=${encodeURIComponent(domain)}`, { headers });
+  } catch (err) {
+    console.error(color("red", `error: network failure calling /api/scan: ${err.message}`));
+    process.exit(3);
+  }
+  if (!resp.ok) {
+    console.error(color("red", `error: /api/scan returned ${resp.status}`));
+    process.exit(3);
+  }
+  const report = await resp.json();
+  const findings = Array.isArray(report.findings) ? report.findings : [];
+  const maxSev = highestSeverity(findings);
+  const shipDecision = computeShipDecision({ maxSeverity: maxSev });
+  const topFinding = [...findings].sort((a, b) => severityRank(b.severity) - severityRank(a.severity))[0];
+  const topIssue = topFinding
+    ? `[${String(topFinding.severity || "").toUpperCase()}] ${topFinding.title || topFinding.detail || "finding"}`
+    : "No findings at or above LOW severity.";
+  const whyMatters = topFinding?.detail || "DBR scoring measures harvest-now-decrypt-later risk on the public TLS surface.";
+  const nextActions = shipDecision === "pass"
+    ? [`Domain looks healthy on first scan. View full report: ${API_BASE}/r/${domain}`]
+    : [
+        `Review finding above and decide if it was intentional.`,
+        `View full report: ${API_BASE}/r/${domain}`,
+        `Subsequent deploy-checks will diff against this scan as baseline.`,
+      ];
+
+  console.log("");
+  console.log(color("dim", `  ℹ first deploy-check for ${domain} — using current scan state (no baseline yet to diff against)`));
+  console.log("");
+  console.log(formatAiBanner({
+    domain,
+    kind: "scan",
+    dbr: report.score,
+    grade: report.grade,
+    maxSeverity: maxSev,
+    shipDecision,
+  }));
+  console.log(formatAiBody({ topIssue, whyMatters, nextActions }));
+  console.log(formatAiFooterBlock({
+    status: shipDecision === "pass" ? "pass" : "review",
+    domain,
+    kind: "scan",
+    dbr: report.score,
+    grade: report.grade,
+    max_severity: maxSev,
+    ship_decision: shipDecision,
+    top_issue: topFinding ? `findings.${topFinding.id || "unknown"}` : "none",
+    findings_high: findings.filter((f) => severityRank(f.severity) >= severityRank("high")).length,
+    findings_critical: findings.filter((f) => severityRank(f.severity) >= severityRank("critical")).length,
+    scanned_at: new Date().toISOString(),
+    advisory_only: true,
+    note: "first-deploy: no baseline yet, scored on current state",
+  }));
+  // Exit code: 0 on pass, non-zero on review/block (matches deploy-check contract)
+  process.exit(shipDecision === "pass" ? 0 : 1);
+}
+
 async function runTrustDiffCommand(args) {
   const positional = args.filter((a) => !a.startsWith("-") && !isFlagValue(args, a));
   if (positional.length === 0) {
@@ -2035,26 +2369,27 @@ async function runTrustDiffCommand(args) {
     console.error(color("red", `error: invalid domain "${positional[0]}"`));
     process.exit(3);
   }
-  if (!QP_API_KEY) {
-    console.error(color("red", "error: pqcheck trust-diff requires CIPHERWAKE_API_KEY"));
-    console.error(color("dim", "Generate a free key (30 calls/mo) at https://cipherwake.io/account#api-keys"));
-    console.error(color("dim", "Then: export CIPHERWAKE_API_KEY=qpk_<32-hex>"));
-    process.exit(3);
-  }
 
   const baseline = parseFlag(args, "--baseline") || "last-week";
   const failOn = parseFlag(args, "--fail-on") || "high";
   const format = parseFlag(args, "--format") || "pretty";
 
+  // Build headers conditionally — Authorization is set ONLY if the user has
+  // an API key. Without it, the server's applyRepoQuota falls through to the
+  // anonymous per-IP rate limit path (just like /api/scan).
+  const headers = {
+    "Content-Type": "application/json",
+    "User-Agent": `pqcheck-cli/${VERSION}`,
+  };
+  if (QP_API_KEY) {
+    headers["Authorization"] = `Bearer ${QP_API_KEY}`;
+  }
+
   let resp;
   try {
     resp = await fetch(`${API_BASE}/api/trust-diff`, {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${QP_API_KEY}`,
-        "User-Agent": `pqcheck-cli/${VERSION}`,
-      },
+      headers,
       body: JSON.stringify({ domain, baseline, fail_on: failOn }),
     });
   } catch (err) {
@@ -2068,14 +2403,26 @@ async function runTrustDiffCommand(args) {
   }
   if (resp.status === 429) {
     const body = await safeJSON(resp);
-    console.error(color("red", "error: Trust Diff API quota exceeded for this month"));
+    console.error(color("red", "error: Trust Diff API quota exceeded"));
     if (body?.message) console.error(color("dim", body.message));
+    console.error(color("dim", "Higher quota via free API key (no card): https://cipherwake.io/account#api-keys"));
     process.exit(3);
   }
+  // R74-confirm friction fix #2 (GPT 2026-05-22): 404 on first-deploy is
+  // expected — the domain has never been scanned, so there's no baseline to
+  // diff against. Instead of asking the user to run `pqcheck <domain>` first
+  // (a friction step that breaks the AI-coder funnel), automatically fall
+  // through to /api/scan, populate the cache, and emit ship_decision based
+  // on the scan's current absolute state. Subsequent deploy-checks will
+  // have a baseline and produce a real drift verdict.
+  if (resp.status === 404 && parseAiMode(args)) {
+    return await runScanBasedDeployCheck(domain, args);
+  }
   if (!resp.ok) {
     const body = await safeJSON(resp);
     console.error(color("red", `error: /api/trust-diff returned ${resp.status}`));
     if (body?.message) console.error(color("dim", body.message));
+    if (body?.hint) console.error(color("dim", body.hint));
     process.exit(3);
   }
 
@@ -2083,6 +2430,72 @@ async function runTrustDiffCommand(args) {
   const verdict = result.verdict || "pass";
   const deltas = Array.isArray(result.deltas) ? result.deltas : [];
 
+  // AI Coder Mode — three-layer output (banner / body / structured block).
+  if (parseAiMode(args)) {
+    const maxSev = highestSeverity(deltas);
+    const hasUnexpectedDiff = deltas.length > 0;
+    const shipDecision = computeShipDecision({ maxSeverity: maxSev, hasUnexpectedDiff });
+    const topDelta = [...deltas].sort((a, b) => severityRank(b.severity) - severityRank(a.severity))[0];
+
+    const topIssue = topDelta
+      ? `[${String(topDelta.severity || "").toUpperCase()}] ${topDelta.title || topDelta.type}${topDelta.what_changed ? ` — ${topDelta.what_changed}` : ""}`
+      : "No deltas observed since baseline.";
+    const whyMatters = topDelta
+      ? `This change happened between your baseline (${baseline}) and now. If it's an intentional change you shipped, accept it. If unexpected, your domain's posture drifted without an associated deploy — investigate before the diff compounds.`
+      : `Your public trust posture is stable since ${baseline}. No CSP / HSTS / cert / SPKI / DMARC / vendor-script regressions.`;
+    const nextActions = shipDecision === "pass"
+      ? [`Posture stable. Safe to announce deploy.`]
+      : [
+          `Review each delta and decide if it was intentional.`,
+          `If intentional: accept (no action needed in CI; quota tick recorded).`,
+          `If not intentional: revert the deploy or investigate the drift source.`,
+        ];
+
+    console.log("");
+    console.log(formatAiBanner({
+      domain,
+      kind: "trust-diff",
+      dbr: result.current_score,
+      grade: result.current_grade,
+      maxSeverity: maxSev,
+      shipDecision,
+    }));
+    console.log(formatAiBody({ topIssue, whyMatters, nextActions }));
+    console.log(formatAiFooterBlock({
+      status: shipDecision,
+      domain,
+      kind: "trust-diff",
+      baseline,
+      verdict,
+      delta_count: deltas.length,
+      max_severity: maxSev,
+      ship_decision: shipDecision,
+      top_issue: topDelta?.id || topDelta?.type || "none",
+      top_issue_title: topDelta?.title || "",
+      dbr: typeof result.current_score === "number" ? result.current_score.toFixed(1) : "",
+      grade: result.current_grade || "",
+      quota_used: result.quota?.used_this_month ?? "",
+      quota_limit: result.quota?.monthly_limit ?? "",
+      scanned_at: new Date().toISOString(),
+      advisory_only: "true",
+    }));
+    console.log("");
+
+    await writeLastScanFile({
+      domain,
+      kind: "trust-diff",
+      score: typeof result.current_score === "number" ? result.current_score : null,
+      grade: result.current_grade || null,
+      max_severity: maxSev,
+      ship_decision: shipDecision,
+      baseline,
+      delta_count: deltas.length,
+      top_issue: topDelta?.id || topDelta?.title || null,
+    });
+
+    process.exit(shipDecisionExitCode(shipDecision));
+  }
+
   // Format output
   if (format === "json") {
     console.log(JSON.stringify(result, null, 2));
@@ -2146,8 +2559,14 @@ async function runTrustDiffCommand(args) {
  *
  * Exit codes match trust-diff: 0 pass · 1 warn · 2 fail · 3 error.
  *
- * Requires CIPHERWAKE_API_KEY env var (Free tier: 100 calls/repo/mo at
- * /account#api-keys, or use the GitHub Action which fetches OIDC automatically).
+ * Authentication paths (server's applyRepoQuota supports all three):
+ *   • CIPHERWAKE_API_KEY=qpk_... (paid quota, higher cap)
+ *   • GITHUB_ACTIONS=true + id-token (OIDC, keyless, Free 100 calls/repo/mo)
+ *   • No auth (anonymous per-IP rate limit — frictionless first-use)
+ *
+ * R74-confirm friction fix (GPT 2026-05-22): the hard-gate on API key has
+ * been removed; server applyRepoQuota handles all 3 auth paths, including
+ * anonymous per-IP rate limit for frictionless first use.
  */
 async function runPreviewDiffCommand(args) {
   const previewUrl = parseFlag(args, "--preview");
@@ -2157,13 +2576,6 @@ async function runPreviewDiffCommand(args) {
     console.error(color("dim", "Usage: npx pqcheck preview-diff --preview https://preview-xyz.vercel.app --production https://example.com [--compare-transport] [--fail-on high] [--format pretty|json]"));
     process.exit(3);
   }
-  if (!QP_API_KEY) {
-    console.error(color("red", "error: pqcheck preview-diff requires CIPHERWAKE_API_KEY"));
-    console.error(color("dim", "Generate a free key (100 calls/repo/mo) at https://cipherwake.io/account#api-keys"));
-    console.error(color("dim", "Then: export CIPHERWAKE_API_KEY=qpk_<32-hex>"));
-    console.error(color("dim", "Or use the GitHub Action with 'permissions: id-token: write' — no key needed."));
-    process.exit(3);
-  }
 
   const compareTransport = args.includes("--compare-transport");
   const failOn = parseFlag(args, "--fail-on") || "high";
@@ -2177,15 +2589,19 @@ async function runPreviewDiffCommand(args) {
     ? "report"
     : "fail";
 
+  const headers = {
+    "Content-Type": "application/json",
+    "User-Agent": `pqcheck-cli/${VERSION}`,
+  };
+  if (QP_API_KEY) {
+    headers["Authorization"] = `Bearer ${QP_API_KEY}`;
+  }
+
   let resp;
   try {
     resp = await fetch(`${API_BASE}/api/preview-diff`, {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${QP_API_KEY}`,
-        "User-Agent": `pqcheck-cli/${VERSION}`,
-      },
+      headers,
       body: JSON.stringify({
         preview_url: previewUrl,
         production_url: productionUrl,
@@ -2213,6 +2629,10 @@ async function runPreviewDiffCommand(args) {
     const body = await safeJSON(resp);
     console.error(color("red", `error: /api/preview-diff returned ${resp.status}`));
     if (body?.message) console.error(color("dim", body.message));
+    // Server-side may return a `hint` field on rejected inputs (e.g. localhost
+    // / private-IP URLs surface the tunnel-options hint). Print it so the
+    // user knows what to do next instead of just seeing the rejection.
+    if (body?.hint) console.error(color("dim", body.hint));
     process.exit(3);
   }
 
@@ -2220,6 +2640,73 @@ async function runPreviewDiffCommand(args) {
   const verdict = result?.result?.verdict || "pass";
   const summaryLines = result?.result?.summary_lines || [];
 
+  // AI Coder Mode — three-layer output (banner / body / structured block).
+  if (parseAiMode(args)) {
+    const maxSev = result?.result?.max_severity || "none";
+    const hasUnexpectedDiff = summaryLines.some((l) => !/no meaningful/i.test(l));
+    const prevScore = result?.preview?.score;
+    const prodScore = result?.production?.score;
+    const scoreDelta = (typeof prevScore === "number" && typeof prodScore === "number")
+      ? Number((prevScore - prodScore).toFixed(2))
+      : null;
+    const shipDecision = computeShipDecision({ maxSeverity: maxSev, hasUnexpectedDiff, scoreDelta });
+
+    const firstDelta = summaryLines.find((l) => !/no meaningful/i.test(l));
+    const topIssue = firstDelta || "No meaningful application-surface changes between preview and production.";
+    const whyMatters = hasUnexpectedDiff
+      ? `Preview URL introduces application-surface changes vs production. If you intentionally added (e.g.) a new third-party script or relaxed a CSP, accept and merge. If unexpected, the change is hidden in this PR's bundle — investigate before merge.`
+      : `Your preview is application-equivalent to production. No new vendors, no header regressions, no DBR score drop.`;
+    const nextActions = shipDecision === "pass"
+      ? [`Preview matches production. Safe to merge.`]
+      : [
+          `Review the changes above in this PR before merging.`,
+          `Each "+ New third-party script" is a real new third-party request your users will make on this deploy.`,
+          `Each "- CSP weakened" or "~ HSTS weakened" reduces production safety.`,
+        ];
+
+    console.log("");
+    console.log(formatAiBanner({
+      domain: result?.production?.domain || productionUrl,
+      kind: "preview-diff",
+      dbr: prevScore,
+      grade: result?.preview?.grade,
+      maxSeverity: maxSev,
+      shipDecision,
+    }));
+    console.log(formatAiBody({ topIssue, whyMatters, nextActions }));
+    console.log(formatAiFooterBlock({
+      status: shipDecision,
+      domain: result?.production?.domain || productionUrl,
+      kind: "preview-diff",
+      preview_url: previewUrl,
+      production_url: productionUrl,
+      verdict,
+      max_severity: maxSev,
+      delta_count: summaryLines.filter((l) => !/no meaningful/i.test(l)).length,
+      ship_decision: shipDecision,
+      preview_dbr: typeof prevScore === "number" ? prevScore.toFixed(1) : "",
+      production_dbr: typeof prodScore === "number" ? prodScore.toFixed(1) : "",
+      score_delta: scoreDelta !== null ? scoreDelta.toString() : "",
+      top_issue: firstDelta || "none",
+      scanned_at: new Date().toISOString(),
+      advisory_only: "true",
+    }));
+    console.log("");
+
+    await writeLastScanFile({
+      domain: result?.production?.domain || productionUrl,
+      kind: "preview-diff",
+      preview_url: previewUrl,
+      production_url: productionUrl,
+      score: typeof prevScore === "number" ? prevScore : null,
+      max_severity: maxSev,
+      ship_decision: shipDecision,
+      delta_count: summaryLines.filter((l) => !/no meaningful/i.test(l)).length,
+    });
+
+    process.exit(shipDecisionExitCode(shipDecision));
+  }
+
   if (format === "json") {
     console.log(JSON.stringify(result, null, 2));
   } else {
@@ -2409,7 +2896,7 @@ function computeLockDiff(oldLock, newLock) {
 
 // `pqcheck watch <domain>` — adds the given domain to the user's watched-
 // domain list via the authenticated /api/watched-domains POST. Requires
-// QUANTAPACT_API_KEY env var. Closes the CLI ↔ account loop: developers
+// CIPHERWAKE_API_KEY env var. Closes the CLI ↔ account loop: developers
 // who use the CLI can now opt into persistent monitoring from the same
 // surface without leaving the terminal.
 async function runWatchCommand(args) {
@@ -2921,9 +3408,10 @@ async function runDeployCheckCommand(args) {
   if (!args.includes("--fail-on")) forwarded.push("--fail-on", "high");
 
   // Pre-print a deploy-context header (only in text mode — JSON/SARIF users
-  // are scripting and don't want our preamble polluting their pipe).
+  // are scripting and don't want our preamble polluting their pipe; AI mode
+  // emits its own banner so don't double-up).
   const format = parseFormat(forwarded);
-  if (format === "text") {
+  if (format === "text" && !parseAiMode(forwarded)) {
     console.log("");
     console.log(`  ${color("bold", "🚀 Deploy gate")} ${color("dim", "— checking public trust posture vs last scan")}`);
     console.log("");
@@ -3541,6 +4029,1093 @@ async function tryOpenBrowser(url) {
   });
 }
 
+// =============================================================================
+// `pqcheck guard --domain X -- <deploy command>` — wrapper command
+// =============================================================================
+// The strongest single artifact for terminal-first AI-coder workflows.
+// Runs deploy-check first, conditionally executes the wrapped deploy command
+// based on ship_decision. AI coders type ONE command; Cipherwake controls
+// whether the deploy actually runs.
+//
+// Usage:
+//   npx pqcheck guard --domain example.com -- vercel deploy --prod
+//   npx pqcheck guard --domain example.com --gate-mode strict -- bash deploy.sh
+//   npx pqcheck guard --domain example.com --bypass "shipping despite review" -- ...
+//
+// Exit codes:
+//   0 = deploy ran and succeeded (pre-check passed or user confirmed review)
+//   1 = pre-check returned review and user chose not to proceed
+//   2 = pre-check returned block and deploy was refused (use --bypass to override)
+//   3 = wrapper / deploy command itself errored
+// =============================================================================
+async function runGuardCommand(args) {
+  // Parse flags and the `--` separator.
+  const sepIdx = args.indexOf("--");
+  const ourArgs = sepIdx >= 0 ? args.slice(0, sepIdx) : args;
+  const deployCmd = sepIdx >= 0 ? args.slice(sepIdx + 1) : [];
+
+  const domain = parseFlag(ourArgs, "--domain");
+  const gateMode = parseFlag(ourArgs, "--gate-mode") || "balanced";
+  const bypassReason = parseFlag(ourArgs, "--bypass");
+  const noPostCheck = ourArgs.includes("--no-post-check");
+
+  if (!domain) {
+    console.error(color("red", "error: pqcheck guard requires --domain"));
+    console.error(color("dim", "Usage: npx pqcheck guard --domain example.com -- <deploy command>"));
+    console.error(color("dim", "Example: npx pqcheck guard --domain example.com -- vercel deploy --prod"));
+    process.exit(3);
+  }
+  if (deployCmd.length === 0) {
+    console.error(color("red", "error: pqcheck guard requires a deploy command after `--`"));
+    console.error(color("dim", "Usage: npx pqcheck guard --domain example.com -- vercel deploy --prod"));
+    process.exit(3);
+  }
+  if (!["balanced", "advisory", "strict"].includes(gateMode)) {
+    console.error(color("red", `error: --gate-mode must be one of: balanced, advisory, strict (got "${gateMode}")`));
+    process.exit(3);
+  }
+
+  const labelByMode = {
+    balanced: "Balanced (default — review on HIGH, block on CRITICAL)",
+    advisory: "Advisory (warnings only, deploy never blocked)",
+    strict: "Strict (block on any finding ≥ medium)",
+  };
+
+  console.log("");
+  console.log(`  ${color("bold", "◆ Cipherwake Deploy Guard")} ${color("dim", `· ${labelByMode[gateMode]}`)}`);
+  console.log(`  ${color("dim", `domain: ${domain}`)}`);
+  console.log(`  ${color("dim", `deploy: ${deployCmd.join(" ")}`)}`);
+  console.log("");
+
+  if (bypassReason) {
+    console.log(color("yellow", `  ⚠ --bypass set with reason: "${bypassReason}"`));
+    console.log(color("dim", "  The pre-deploy check will still run, but a review or block won't stop the deploy."));
+    console.log("");
+  }
+
+  // Run the pre-deploy check. We invoke ourselves (the CLI) as a subprocess
+  // rather than calling internal functions because the deploy-check exit
+  // code + ship_decision semantics are the contract; recreating that logic
+  // inline would risk drift.
+  const { spawn } = await import("node:child_process");
+
+  // Detect the right binary to invoke: if we're running via `npx pqcheck`
+  // we want to re-invoke pqcheck (process.argv[1]); if we're installed
+  // globally, same path.
+  const selfPath = process.argv[1];
+
+  console.log(color("dim", "  Running pre-deploy check ..."));
+  const checkArgs = ["deploy-check", domain, "--ai"];
+  // In advisory mode the deploy NEVER blocks — pass --fail-on none so the
+  // server returns findings but the verdict downgrades to report.
+  if (gateMode === "advisory") checkArgs.push("--fail-on", "none");
+  // In strict mode block on any finding ≥ medium.
+  if (gateMode === "strict") checkArgs.push("--fail-on", "medium");
+
+  let checkOutput = "";
+  const checkExitCode = await new Promise((resolve) => {
+    const child = spawn(process.execPath, [selfPath, ...checkArgs], {
+      stdio: ["ignore", "pipe", "inherit"],
+    });
+    child.stdout.on("data", (chunk) => {
+      const s = chunk.toString();
+      checkOutput += s;
+      process.stdout.write(s);
+    });
+    child.on("close", (code) => resolve(code ?? 3));
+    child.on("error", () => resolve(3));
+  });
+
+  // Parse the structured CIPHERWAKE_AI_GUARD_RESULT block to extract
+  // ship_decision (the contract field). If we can't find it, fail safe.
+  let shipDecision = "review";
+  const blockMatch = checkOutput.match(/CIPHERWAKE_AI_GUARD_RESULT\n([\s\S]*?)\nEND_CIPHERWAKE_AI_GUARD_RESULT/);
+  if (blockMatch) {
+    const sdLine = blockMatch[1].split("\n").find((l) => l.startsWith("ship_decision="));
+    if (sdLine) shipDecision = sdLine.split("=")[1].trim();
+  }
+
+  console.log("");
+  console.log(color("bold", `  Pre-deploy check returned: ship_decision=${shipDecision}`));
+
+  // Decide what to do.
+  if (shipDecision === "pass") {
+    console.log(color("green", "  ✓ Posture stable — running deploy command."));
+    console.log("");
+  } else if (shipDecision === "review") {
+    if (bypassReason) {
+      console.log(color("yellow", "  ⚠ Review-level finding(s) detected, but --bypass is set — proceeding."));
+    } else if (process.stdin.isTTY) {
+      const readline = await import("node:readline");
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await new Promise((resolve) => {
+        rl.question(color("yellow", "\n  ⚠ Cipherwake flagged a review-level finding. Continue with deploy? [y/N]: "), (a) => {
+          rl.close();
+          resolve((a || "").trim().toLowerCase());
+        });
+      });
+      if (answer !== "y" && answer !== "yes") {
+        console.log(color("dim", "  Deploy cancelled by user."));
+        process.exit(1);
+      }
+    } else {
+      console.error(color("red", "  ✗ Review-level finding(s) and no interactive terminal — failing closed."));
+      console.error(color("dim", "  Re-run interactively, or pass --bypass \"<reason>\" to acknowledge."));
+      process.exit(1);
+    }
+  } else if (shipDecision === "block") {
+    if (bypassReason) {
+      console.log(color("red", "  ⚠ BLOCK-level finding, but --bypass is set with explicit reason — proceeding."));
+      console.log(color("dim", `  Logged bypass reason: "${bypassReason}"`));
+    } else {
+      console.error(color("red", "  ✗ Cipherwake returned BLOCK — refusing to run deploy command."));
+      console.error(color("dim", "  Investigate the finding above. To override, re-run with --bypass \"<your reason>\"."));
+      process.exit(2);
+    }
+  }
+
+  // Execute the wrapped deploy command.
+  console.log(color("dim", `  Executing: ${deployCmd.join(" ")}`));
+  console.log("");
+  const deployExitCode = await new Promise((resolve) => {
+    const child = spawn(deployCmd[0], deployCmd.slice(1), { stdio: "inherit" });
+    child.on("close", (code) => resolve(code ?? 3));
+    child.on("error", (err) => {
+      console.error(color("red", `  ✗ Deploy command failed to spawn: ${err.message}`));
+      resolve(3);
+    });
+  });
+
+  if (deployExitCode !== 0) {
+    console.error(color("red", `\n  ✗ Deploy command exited with code ${deployExitCode}.`));
+    process.exit(deployExitCode);
+  }
+
+  // Post-deploy check — useful for verifying the live URL after deploy.
+  if (!noPostCheck) {
+    console.log("");
+    console.log(color("dim", "  Running post-deploy check ..."));
+    const postExitCode = await new Promise((resolve) => {
+      const child = spawn(process.execPath, [selfPath, domain, "--ai", "--fresh"], { stdio: "inherit" });
+      child.on("close", (code) => resolve(code ?? 0));
+      child.on("error", () => resolve(0));
+    });
+    if (postExitCode !== 0) {
+      console.error(color("yellow", `\n  ⚠ Post-deploy check returned non-zero (${postExitCode}) — investigate before announcing.`));
+    }
+  }
+
+  console.log("");
+  console.log(color("green", "  ◆ Deploy guard complete."));
+  process.exit(0);
+}
+
+// =============================================================================
+// `pqcheck protocol install` — Rule 17 consent-flow installer for the AI Coder
+// Protocol.
+// =============================================================================
+// Detects ~/.claude/CLAUDE.md and ./.cursorrules, then asks ONE upfront question
+// (auto / manual / no) per Rule 17. Never silently writes user config.
+// =============================================================================
+const AI_CODER_PROTOCOL_TEXT = `
+## Pre-deploy verification with Cipherwake
+
+Before announcing any deploy of a public-facing site, you MUST run a
+Cipherwake deploy check and route on the result.
+
+1. Run:
+
+   npx pqcheck deploy-check <your-domain> --ai
+
+   (Or wrap your deploy command with: npx pqcheck guard --domain <your-domain> -- <deploy-cmd>)
+
+2. Parse the CIPHERWAKE_AI_GUARD_RESULT block at the end of stdout.
+   Extract the \`ship_decision\` field.
+
+3. Route on ship_decision:
+
+   • pass    — Public trust surface is stable. Safe to announce.
+
+   • review  — STOP. Surface the change to the user:
+
+               "Cipherwake flagged a change: <top_issue>. The public
+                trust surface drifted between baseline and now. Want me to:
+                  1) Ship anyway (you accept the change as intentional)
+                  2) Revert the deploy
+                  3) Investigate before deciding"
+
+               Wait for explicit user choice. Do NOT announce the deploy
+               until they confirm.
+
+   • block   — STOP. Surface to the user:
+
+               "Cipherwake flagged a CRITICAL change: <top_issue>.
+                I recommend not announcing this deploy until we investigate.
+                Want to revert and look, or override?"
+
+               Wait for explicit user override before announcing.
+
+4. Never claim a deploy is "done" or "shipped" until either:
+   • ship_decision was pass, OR
+   • the user explicitly confirmed they want to ship despite review/block.
+
+Reference: https://cipherwake.io/methodology/ai-coder-protocol
+`;
+
+async function runProtocolCommand(args) {
+  const sub = args[0];
+  if (sub !== "install") {
+    console.error(color("red", `error: unknown protocol subcommand "${sub || ""}"`));
+    console.error(color("dim", "Usage:"));
+    console.error(color("dim", "  Interactive:       npx pqcheck protocol install"));
+    console.error(color("dim", "  Auto (incl AI):    npx pqcheck protocol install --auto"));
+    console.error(color("dim", "  Print only:        npx pqcheck protocol install --manual"));
+    console.error(color("dim", "  Add audit metadata: --invoked-by=\"<name>\" --consent-phrase=\"<user words>\""));
+    process.exit(3);
+  }
+
+  const os = await import("node:os");
+  const path = await import("node:path");
+  const fs = await import("node:fs/promises");
+  const readline = await import("node:readline");
+
+  // -------------------------------------------------------------------------
+  // Flag-driven setup mode (per CLAUDE.md Rule 17 — agent-invocation path).
+  //   --auto   → install to all detected files, no prompts. AI-agent-friendly.
+  //   --manual → print only, no install. Same as choosing [m] interactively.
+  //   (no flag, with TTY)  → interactive [a/m/n] prompt
+  //   (no flag, no TTY)    → bail with helpful error pointing at --auto/--manual
+  //
+  // Optional audit metadata (richer trail in install-prefs.json):
+  //   --invoked-by="<name>"      — who initiated the install (AI name+version, "human", etc.)
+  //   --consent-phrase="<words>" — the literal words that authorized this (free-form)
+  //
+  // The flag's presence IS the consent signal — Cipherwake doesn't second-guess
+  // a flag that's explicitly typed. The audit trail file captures who, when,
+  // and what for customer recourse if needed.
+  //
+  // Rule 17's spirit is "no surprises." A flag that was explicitly passed
+  // (by a human or by an AI on the human's behalf) is the opposite of a
+  // surprise — it's a recorded, intentional action.
+  // -------------------------------------------------------------------------
+  const autoFlag = args.includes("--auto");
+  const manualFlag = args.includes("--manual");
+  const invokedBy = parseFlag(args, "--invoked-by") || (autoFlag ? "unknown-agent-or-script" : null);
+  const consentPhrase = parseFlag(args, "--consent-phrase") || null;
+
+  if (autoFlag && manualFlag) {
+    console.error(color("red", "error: --auto and --manual are mutually exclusive"));
+    process.exit(3);
+  }
+
+  // Detect candidate files across major AI coders that:
+  //   (a) read an instructions file at session start, AND
+  //   (b) can run shell commands (so they can actually invoke pqcheck).
+  //
+  // Surfaces that ONLY do autocomplete (Copilot ghost text, basic Codeium,
+  // tab-only IDEs) are intentionally not here — the protocol can't apply to
+  // them; they need the GitHub Action PR-comment surface instead.
+  const candidates = [
+    { label: "Claude Code (global)", path: path.join(os.homedir(), ".claude", "CLAUDE.md") },
+    { label: "Claude Code (project)", path: path.join(process.cwd(), "CLAUDE.md") },
+    { label: "Cursor (project)", path: path.join(process.cwd(), ".cursorrules") },
+    { label: "Aider conf (project)", path: path.join(process.cwd(), ".aider.conf.yml") },
+    { label: "Aider conventions (project)", path: path.join(process.cwd(), "CONVENTIONS.md") },
+    { label: "GitHub Copilot Chat / Workspace (project)", path: path.join(process.cwd(), ".github", "copilot-instructions.md") },
+    { label: "Windsurf / Codeium (project)", path: path.join(process.cwd(), ".windsurfrules") },
+    { label: "Continue.dev (project)", path: path.join(process.cwd(), ".continuerules") },
+    { label: "Cline / Roo Cline (project)", path: path.join(process.cwd(), ".clinerules") },
+    { label: "AGENTS.md (cross-tool standard)", path: path.join(process.cwd(), "AGENTS.md") },
+  ];
+
+  const detected = [];
+  for (const c of candidates) {
+    try {
+      await fs.access(c.path);
+      detected.push(c);
+    } catch { /* file doesn't exist; that's OK */ }
+  }
+
+  console.log("");
+  console.log(color("bold", "◆ Cipherwake AI Coder Protocol — install"));
+  console.log("");
+  if (autoFlag || manualFlag) {
+    console.log(color("dim", `Mode: ${autoFlag ? "auto (--auto flag set)" : "print-only (--manual flag set)"}`));
+    if (invokedBy) console.log(color("dim", `Invoked by: ${invokedBy}`));
+    if (consentPhrase) console.log(color("dim", `Consent phrase: "${consentPhrase}"`));
+    console.log("");
+  }
+  console.log("Here's what would be added:");
+  console.log("");
+  if (detected.length === 0) {
+    console.log(color("dim", "  No existing CLAUDE.md / .cursorrules / .aider.conf.yml found."));
+    console.log(color("dim", "  Creating ~/.claude/CLAUDE.md with the protocol."));
+    detected.push({ label: "Claude Code (will create)", path: path.join(os.homedir(), ".claude", "CLAUDE.md") });
+  }
+  for (const d of detected) {
+    console.log(`  • Append a ~30-line "## Pre-deploy verification with Cipherwake" section to ${color("bold", d.path)}`);
+    console.log(`    ${color("dim", `(${d.label} — existing content preserved)`)}`);
+  }
+  console.log("");
+
+  // --manual → print only, no install
+  if (manualFlag) {
+    console.log(color("bold", "── Cipherwake AI Coder Protocol — paste this into your AI coder's instructions ──"));
+    console.log(AI_CODER_PROTOCOL_TEXT);
+    console.log(color("bold", "── End of protocol ──"));
+    console.log("");
+    console.log(color("dim", `For target files, see: ${detected.map(d => d.path).join(", ")}`));
+    process.exit(0);
+  }
+
+  // --auto → install to all detected files
+  if (autoFlag) {
+    console.log(color("dim", "Auto-install (--auto flag set). Writing audit trail to ~/.config/cipherwake/install-prefs.json."));
+    console.log("");
+    return await performAutoInstall(detected, {
+      mode: "auto-flag",
+      consent_phrase: consentPhrase,
+      invoked_by: invokedBy,
+      fs, path, os,
+    });
+  }
+
+  // Interactive (human-at-terminal) path.
+  console.log("Per CLAUDE.md Rule 17, Cipherwake never modifies your config without asking.");
+  console.log("");
+  console.log("  [a]uto    — I add the protocol to all detected files + show you a diff afterward");
+  console.log("  [m]anual  — Print the protocol so you can paste it yourself");
+  console.log("  [n]o      — Skip; you can re-run anytime with `npx pqcheck protocol install`");
+  console.log("");
+
+  if (!process.stdin.isTTY) {
+    console.error(color("red", "error: pqcheck protocol install requires an interactive terminal — OR an explicit --auto / --manual flag."));
+    console.error(color("dim", "Re-run in an interactive shell, OR pass one of:"));
+    console.error(color("dim", "  --auto    (install to all detected files; AI-friendly)"));
+    console.error(color("dim", "  --manual  (print protocol so you can paste it yourself; no install)"));
+    console.error(color("dim", "Optional audit metadata: --invoked-by=\"<name>\" --consent-phrase=\"<words>\""));
+    process.exit(3);
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const choice = await new Promise((resolve) => {
+    rl.question("Choose [a/m/n]: ", (a) => {
+      rl.close();
+      resolve((a || "").trim().toLowerCase());
+    });
+  });
+
+  if (choice === "n" || choice === "no") {
+    console.log("");
+    console.log(color("dim", "Skipped. Re-run anytime: npx pqcheck protocol install"));
+    process.exit(0);
+  }
+
+  if (choice === "m" || choice === "manual") {
+    console.log("");
+    console.log(color("bold", "── Cipherwake AI Coder Protocol — paste this into your AI coder's instructions ──"));
+    console.log(AI_CODER_PROTOCOL_TEXT);
+    console.log(color("bold", "── End of protocol ──"));
+    console.log("");
+    console.log(color("dim", `For target files, see: ${detected.map(d => d.path).join(", ")}`));
+    process.exit(0);
+  }
+
+  if (choice === "a" || choice === "auto") {
+    return await performAutoInstall(detected, {
+      mode: "interactive",
+      consent_phrase: "user typed [a] at the install prompt",
+      invoked_by: "human-at-terminal",
+      fs, path, os,
+    });
+  }
+
+  console.error(color("red", `Unknown choice "${choice}". Expected a / m / n.`));
+  process.exit(3);
+}
+
+// Shared install routine — used by both interactive and agent-invoked paths.
+// Writes the protocol to each detected file and records the audit trail.
+async function performAutoInstall(detected, opts) {
+  const { fs, path, os } = opts;
+  const results = [];
+  for (const d of detected) {
+    try {
+      await fs.mkdir(path.dirname(d.path), { recursive: true });
+      let existing = "";
+      try { existing = await fs.readFile(d.path, "utf8"); } catch { /* file may not exist yet */ }
+      if (existing.includes("## Pre-deploy verification with Cipherwake")) {
+        console.log(color("dim", `  ⊝ ${d.path} — already contains the protocol, skipping.`));
+        results.push({ path: d.path, label: d.label, status: "skipped-already-present" });
+        continue;
+      }
+      const newContent = existing + "\n" + AI_CODER_PROTOCOL_TEXT + "\n";
+      await fs.writeFile(d.path, newContent, "utf8");
+      console.log(color("green", `  ✓ ${d.path} — protocol appended (${AI_CODER_PROTOCOL_TEXT.split("\n").length} lines)`));
+      results.push({ path: d.path, label: d.label, status: "installed" });
+    } catch (err) {
+      console.log(color("red", `  ✗ ${d.path} — failed: ${err.message}`));
+      results.push({ path: d.path, label: d.label, status: "failed", error: String(err?.message || err) });
+    }
+  }
+
+  // Persist the audit trail to ~/.config/cipherwake/install-prefs.json.
+  // This is the customer's recourse if they ever dispute the install — the
+  // file shows who invoked it, when, and the exact consent phrase used.
+  try {
+    const prefsDir = path.join(os.homedir(), ".config", "cipherwake");
+    await fs.mkdir(prefsDir, { recursive: true });
+    const prefsPath = path.join(prefsDir, "install-prefs.json");
+    let prefs = { history: [] };
+    try {
+      const existing = await fs.readFile(prefsPath, "utf8");
+      prefs = JSON.parse(existing);
+      if (!Array.isArray(prefs.history)) prefs.history = [];
+    } catch { /* first run, file doesn't exist or is malformed */ }
+    prefs.history.push({
+      timestamp: new Date().toISOString(),
+      command: "protocol-install",
+      mode: opts.mode,
+      consent_phrase: opts.consent_phrase,
+      invoked_by: opts.invoked_by,
+      cwd: process.cwd(),
+      hostname: os.hostname(),
+      pqcheck_version: VERSION,
+      results,
+    });
+    await fs.writeFile(prefsPath, JSON.stringify(prefs, null, 2), "utf8");
+    console.log(color("dim", `  Audit trail: ${prefsPath}`));
+  } catch (err) {
+    console.log(color("dim", `  (audit trail write failed: ${err.message} — non-fatal)`));
+  }
+
+  console.log("");
+  console.log(color("green", "Done. Your AI coder will follow the protocol on its next deploy."));
+  console.log(color("dim", "Reference: https://cipherwake.io/methodology/ai-coder-protocol"));
+  process.exit(0);
+}
+
+// =============================================================================
+// `pqcheck setup --auto --domain <D>` — consolidated installer
+// =============================================================================
+// One command installs everything an AI-coder workflow needs:
+//   1. GitHub Action workflow file (CI hard gate)
+//   2. AI Coder Protocol across all detected rules files (CLAUDE.md /
+//      .cursorrules / .github/copilot-instructions.md / .aider.conf.yml /
+//      AGENTS.md / etc.) — multi-platform, defense-in-depth
+//   3. Git pre-push hook (catches manual git push origin main bypasses)
+//   4. Claude Code statusLine config in ~/.claude/settings.json (per-flag
+//      consent counts as Rule 17 consent; recorded in audit trail)
+//   5. VS Code extension via `code --install-extension` if `code` CLI on PATH
+//      (skipped silently if not available)
+//
+// The pinnedai-equivalent for Cipherwake. Launch story: "One command, every
+// AI coder ready."
+//
+// Usage:
+//   npx pqcheck setup --auto --domain cipherwake.io
+//   npx pqcheck setup --auto --domain cipherwake.io \\
+//     --invoked-by "Claude Code" --consent-phrase "the user said yes do B"
+// =============================================================================
+
+const GIT_PREPUSH_HOOK_SCRIPT = `#!/usr/bin/env bash
+# Cipherwake pre-push hook — installed by \`pqcheck setup --auto\`
+#
+# Runs deploy-check before pushes to deploy-triggering branches. Catches the
+# case where a human (or an AI that forgot the protocol) pushes directly to
+# main without running deploy-check first. Defense-in-depth alongside the
+# GitHub Action + the AI Coder Protocol.
+#
+# To bypass for a single push: CIPHERWAKE_HOOK_SKIP=1 git push
+# To uninstall: rm .git/hooks/pre-push (or pqcheck setup --uninstall — TBD)
+
+CIPHERWAKE_DOMAIN="\${CIPHERWAKE_DOMAIN:-DOMAIN_PLACEHOLDER}"
+DEPLOY_BRANCHES_REGEX="\${CIPHERWAKE_DEPLOY_BRANCHES:-^refs/heads/(main|master|production|deploy)$}"
+
+if [ "\$CIPHERWAKE_HOOK_SKIP" = "1" ]; then
+  echo "▶ Cipherwake hook: CIPHERWAKE_HOOK_SKIP=1 — bypassing"
+  exit 0
+fi
+
+# Read which refs are being pushed. We only act on pushes to deploy branches.
+SHOULD_RUN=0
+while read local_ref local_sha remote_ref remote_sha; do
+  if [[ "\$remote_ref" =~ \$DEPLOY_BRANCHES_REGEX ]]; then
+    SHOULD_RUN=1
+    break
+  fi
+done
+
+if [ "\$SHOULD_RUN" = "0" ]; then
+  exit 0
+fi
+
+echo "▶ Cipherwake pre-push: running deploy-check on \$CIPHERWAKE_DOMAIN..."
+
+# npx pqcheck deploy-check exits: 0=pass, 1=warn/review, 2=fail/block, 3=error
+npx --yes pqcheck deploy-check "\$CIPHERWAKE_DOMAIN" --ai
+RC=\$?
+
+case "\$RC" in
+  0)
+    echo "▶ Cipherwake: ship_decision=pass — proceeding with push"
+    exit 0
+    ;;
+  1)
+    echo ""
+    echo "▶ Cipherwake flagged a REVIEW-level finding (see output above)."
+    echo "▶ Push allowed — but please review the change before announcing the deploy."
+    echo "▶ To suppress this notice for one push: CIPHERWAKE_HOOK_SKIP=1 git push"
+    exit 0
+    ;;
+  2)
+    echo ""
+    echo "✗ Cipherwake returned BLOCK — refusing push."
+    echo "✗ Investigate the finding above before deploying."
+    echo "✗ To override (with explicit acknowledgement): CIPHERWAKE_HOOK_SKIP=1 git push"
+    exit 1
+    ;;
+  *)
+    echo "▶ Cipherwake pre-check errored (exit \$RC) — allowing push (fail-open)."
+    echo "▶ Set CIPHERWAKE_API_KEY if deploy-check is failing on auth."
+    exit 0
+    ;;
+esac
+`;
+
+const CLAUDE_STATUSLINE_CONFIG_SNIPPET = `
+  "statusLine": {
+    "type": "command",
+    "command": "npx cipherwake-statusline"
+  }`;
+
+// R74-confirm SHIP #14-15 (GPT 2026-05-22): network connectivity diagnostic.
+// Customer runs this when "scan hung" or "command not found" to surface the
+// actual broken hop instead of guessing. Tests: DNS resolution → TCP → TLS
+// → HTTP for each upstream.
+async function runDebugNetworkCommand() {
+  console.log("");
+  console.log(color("bold", "◆ Cipherwake — network diagnostic"));
+  console.log(color("dim", "Probes every upstream the CLI depends on. Run this when scans hang or fail."));
+  console.log("");
+
+  const probes = [
+    { name: "cipherwake.io (API)", url: "https://cipherwake.io/api/scan?domain=cipherwake.io" },
+    { name: "cipherwake.io (homepage)", url: "https://cipherwake.io/" },
+    { name: "crt.sh (CT log upstream)", url: "https://crt.sh/?q=%25.cipherwake.io&output=json" },
+    { name: "Vercel direct (bypass Cloudflare)", url: "https://quantapact.vercel.app/" },
+  ];
+
+  let anyFailed = false;
+  for (const p of probes) {
+    const t0 = Date.now();
+    try {
+      const ctrl = new AbortController();
+      const tmr = setTimeout(() => ctrl.abort(), 10000);
+      const resp = await fetch(p.url, { method: "HEAD", signal: ctrl.signal });
+      clearTimeout(tmr);
+      const elapsed = Date.now() - t0;
+      const statusOk = resp.status >= 200 && resp.status < 500;
+      const marker = statusOk ? color("green", "✓") : color("yellow", "⚠");
+      console.log(`  ${marker} ${p.name.padEnd(38)} HTTP ${resp.status}  ${elapsed}ms`);
+      if (!statusOk) anyFailed = true;
+    } catch (err) {
+      anyFailed = true;
+      const elapsed = Date.now() - t0;
+      const msg = (err && err.message) || String(err);
+      const kind = err?.name === "AbortError" ? "timeout" : "error";
+      console.log(`  ${color("red", "✗")} ${p.name.padEnd(38)} ${kind.toUpperCase()}  ${elapsed}ms  ${msg.slice(0, 60)}`);
+    }
+  }
+
+  console.log("");
+  if (anyFailed) {
+    console.log(color("bold", "Possible causes (in order of likelihood):"));
+    console.log("  1. Corporate proxy / VPN blocking outbound HTTPS to public scanners.");
+    console.log("     → Try setting HTTPS_PROXY env var, or run from a non-corporate network.");
+    console.log("  2. Cloudflare WAF rate-limited your IP. Wait 5-15min and retry.");
+    console.log("     → Or switch networks (mobile hotspot bypasses your home IP).");
+    console.log("  3. DNS resolver doesn't resolve cipherwake.io.");
+    console.log("     → Test with: `dig cipherwake.io`. If it fails, your resolver is offline.");
+    console.log("  4. crt.sh is intermittently slow — that's the upstream we use for CT logs.");
+    console.log("     → Cipherwake degrades to a 14-day stale-cache fallback when crt.sh fails, so this");
+    console.log("       only matters on first scan of brand-new domains.");
+    console.log("");
+    console.log(color("dim", "If you're still blocked, file a bug at https://cipherwake.io/feedback"));
+    process.exit(1);
+  } else {
+    console.log(color("green", "  ✓ All upstreams reachable — Cipherwake should work for you."));
+    console.log("");
+  }
+}
+
+async function runSetupCommand(args) {
+  const autoFlag = args.includes("--auto");
+  const planFlag = args.includes("--plan");                              // R74-confirm BLOCKING #19 (GPT 2026-05-22)
+  const domain = parseFlag(args, "--domain");
+  const failOn = parseFlag(args, "--fail-on") || "high";
+  const baseline = parseFlag(args, "--baseline") || "last-scan";
+  const invokedBy = parseFlag(args, "--invoked-by") || (autoFlag ? "unknown-agent-or-script" : null);
+  const consentPhrase = parseFlag(args, "--consent-phrase") || null;
+  const skipWorkflow = args.includes("--skip-workflow");
+  const skipProtocol = args.includes("--skip-protocol");
+  const skipHook = args.includes("--skip-hook");
+  const skipStatusline = args.includes("--skip-statusline");
+  const skipVscode = args.includes("--skip-vscode");
+
+  if (!domain) {
+    console.error(color("red", "error: pqcheck setup requires --domain"));
+    console.error(color("dim", "Usage: npx pqcheck setup --auto --domain example.com"));
+    console.error(color("dim", "  --plan         Print the install plan without writing any files"));
+    console.error(color("dim", "  --invoked-by=\"<name>\" --consent-phrase=\"<words>\"   (audit trail)"));
+    console.error(color("dim", "Skip flags: --skip-workflow --skip-protocol --skip-hook --skip-statusline --skip-vscode"));
+    process.exit(3);
+  }
+  if (!autoFlag && !planFlag && !process.stdin.isTTY) {
+    console.error(color("red", "error: pqcheck setup requires --auto or --plan when stdin is not a TTY"));
+    console.error(color("dim", "Pass --auto explicitly (the flag IS the consent signal per CLAUDE.md Rule 17),"));
+    console.error(color("dim", "or --plan to see what would be installed without writing anything."));
+    process.exit(3);
+  }
+
+  // R74-confirm BLOCKING #19 (GPT 2026-05-22): --plan mode prints the
+  // intended changes without writing. Addresses GPT's "init modifies too
+  // much without a clear dry run" concern. Customer can run --plan first
+  // to inspect, then run --auto when they're comfortable. AI agents are
+  // encouraged (per the protocol page) to run --plan first when no recent
+  // user consent for --auto exists in the conversation.
+  if (planFlag) {
+    const os = await import("node:os");
+    const path = await import("node:path");
+    const fs = await import("node:fs/promises");
+    console.log("");
+    console.log(color("bold", `◆ Cipherwake Setup — PLAN (dry run, no files will be written)`));
+    console.log(color("dim", `Domain target: ${domain}`));
+    console.log("");
+    console.log(color("bold", "Files this install would touch:"));
+    const planEntries = [];
+    if (!skipWorkflow) planEntries.push({ what: "GitHub Action workflow", to: path.join(process.cwd(), ".github", "workflows", "cipherwake.yml"), op: "create" });
+    if (!skipProtocol) {
+      const candidates = [
+        { label: "Claude Code (global)", path: path.join(os.homedir(), ".claude", "CLAUDE.md") },
+        { label: "Claude Code (project)", path: path.join(process.cwd(), "CLAUDE.md") },
+        { label: "Cursor", path: path.join(process.cwd(), ".cursorrules") },
+        { label: "GitHub Copilot", path: path.join(process.cwd(), ".github", "copilot-instructions.md") },
+        { label: "Aider", path: path.join(process.cwd(), ".aider.conf.yml") },
+        { label: "AGENTS.md", path: path.join(process.cwd(), "AGENTS.md") },
+      ];
+      for (const c of candidates) {
+        let exists = false;
+        try { await fs.access(c.path); exists = true; } catch { /* */ }
+        planEntries.push({ what: `AI Coder Protocol — ${c.label}`, to: c.path, op: exists ? "append-markered" : "skip (file not present)" });
+      }
+    }
+    if (!skipHook) planEntries.push({ what: "git pre-push hook", to: path.join(process.cwd(), ".git", "hooks", "pre-push"), op: "create (if git repo)" });
+    if (!skipStatusline) {
+      const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+      let exists = false;
+      try { await fs.access(settingsPath); exists = true; } catch { /* */ }
+      planEntries.push({ what: "Claude Code statusLine", to: settingsPath, op: exists ? "deep-merge (backup first)" : "create" });
+      planEntries.push({ what: "Claude Code chat-hook (PostToolUse Bash)", to: settingsPath, op: exists ? "deep-merge into hooks.PostToolUse" : "create" });
+    }
+    if (!skipVscode) planEntries.push({ what: "VS Code / Cursor extension", to: "via `code --install-extension cipherwakelabs.cipherwake-statusbar`", op: "attempt (soft-fail if Marketplace listing missing)" });
+    for (const e of planEntries) {
+      console.log(`  ${color("dim", e.op.padEnd(28))} ${color("bold", e.what)}`);
+      console.log(`    ${color("dim", "→")} ${e.to}`);
+    }
+    console.log("");
+    console.log(color("bold", "To proceed:"));
+    console.log(`  npx pqcheck setup --auto --domain ${domain}${invokedBy ? ` --invoked-by "${invokedBy}"` : ""}${consentPhrase ? ` --consent-phrase "${consentPhrase}"` : ""}`);
+    console.log("");
+    console.log(color("dim", "Per Cipherwake Rule 17, --auto is the consent signal. Backups are taken before each settings.json write."));
+    console.log("");
+    return;
+  }
+
+  const os = await import("node:os");
+  const path = await import("node:path");
+  const fs = await import("node:fs/promises");
+  const { spawn } = await import("node:child_process");
+
+  console.log("");
+  console.log(color("bold", `◆ Cipherwake Setup — ${domain}`));
+  console.log("");
+  if (autoFlag) {
+    console.log(color("dim", "Auto mode (--auto flag set). Per CLAUDE.md Rule 17, the flag is the consent signal."));
+    if (invokedBy) console.log(color("dim", `Invoked by: ${invokedBy}`));
+    if (consentPhrase) console.log(color("dim", `Consent phrase: "${consentPhrase}"`));
+    console.log("");
+  }
+
+  const installSummary = [];
+
+  // -------------------------------------------------------------------------
+  // Component 1: GitHub Action workflow (.github/workflows/cipherwake.yml)
+  // -------------------------------------------------------------------------
+  if (!skipWorkflow) {
+    const workflowPath = path.join(process.cwd(), ".github", "workflows", "cipherwake.yml");
+    try {
+      try {
+        await fs.access(workflowPath);
+        console.log(color("dim", `  ⊝ workflow at .github/workflows/cipherwake.yml already exists — skipping`));
+        installSummary.push({ component: "GitHub Action workflow", path: workflowPath, status: "skipped-already-present" });
+      } catch {
+        const workflowYaml = renderTrustDiffWorkflow({ domain, failOn, baseline });
+        await fs.mkdir(path.dirname(workflowPath), { recursive: true });
+        await fs.writeFile(workflowPath, workflowYaml, "utf8");
+        console.log(color("green", `  ✓ wrote .github/workflows/cipherwake.yml (CI hard-gate layer)`));
+        installSummary.push({ component: "GitHub Action workflow", path: workflowPath, status: "installed" });
+      }
+    } catch (err) {
+      console.log(color("red", `  ✗ workflow install failed: ${err.message}`));
+      installSummary.push({ component: "GitHub Action workflow", status: "failed", error: String(err?.message || err) });
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Component 2: AI Coder Protocol across detected rules files
+  // -------------------------------------------------------------------------
+  if (!skipProtocol) {
+    const candidates = [
+      { label: "Claude Code (global)", path: path.join(os.homedir(), ".claude", "CLAUDE.md") },
+      { label: "Claude Code (project)", path: path.join(process.cwd(), "CLAUDE.md") },
+      { label: "Cursor (project)", path: path.join(process.cwd(), ".cursorrules") },
+      { label: "Aider conf (project)", path: path.join(process.cwd(), ".aider.conf.yml") },
+      { label: "Aider conventions (project)", path: path.join(process.cwd(), "CONVENTIONS.md") },
+      { label: "GitHub Copilot Chat / Workspace (project)", path: path.join(process.cwd(), ".github", "copilot-instructions.md") },
+      { label: "Windsurf / Codeium (project)", path: path.join(process.cwd(), ".windsurfrules") },
+      { label: "Continue.dev (project)", path: path.join(process.cwd(), ".continuerules") },
+      { label: "Cline / Roo Cline (project)", path: path.join(process.cwd(), ".clinerules") },
+      { label: "AGENTS.md (cross-tool standard)", path: path.join(process.cwd(), "AGENTS.md") },
+    ];
+    // Detect any existing files; auto-create the global Claude Code file so
+    // every install yields at least one rules-file landing site.
+    const protocolTargets = [];
+    for (const c of candidates) {
+      try {
+        await fs.access(c.path);
+        protocolTargets.push(c);
+      } catch { /* skip */ }
+    }
+    if (protocolTargets.length === 0) {
+      protocolTargets.push({ label: "Claude Code (created)", path: path.join(os.homedir(), ".claude", "CLAUDE.md") });
+    }
+    // R74-confirm BLOCKING #6 (GPT 2026-05-22): wrap the protocol section in
+    // fenced markers so future installs / updates / removals can locate and
+    // replace exactly this block without scanning for the heading. Idempotent:
+    // if markers exist, the block between them is replaced; if neither markers
+    // nor heading exist, the block is appended. Always preserves whatever the
+    // user has written outside the markers.
+    const START_MARKER = "<!-- CIPHERWAKE_AI_CODER_PROTOCOL_START — managed by pqcheck setup; safe to delete this section between markers but do not edit by hand -->";
+    const END_MARKER = "<!-- CIPHERWAKE_AI_CODER_PROTOCOL_END -->";
+    for (const t of protocolTargets) {
+      try {
+        await fs.mkdir(path.dirname(t.path), { recursive: true });
+        let existing = "";
+        try { existing = await fs.readFile(t.path, "utf8"); } catch { /* file may not exist */ }
+
+        const hasMarkers = existing.includes(START_MARKER) && existing.includes(END_MARKER);
+        const hasLegacyHeading = existing.includes("## Pre-deploy verification with Cipherwake");
+
+        if (hasMarkers) {
+          // Replace just the bounded section — leaves all other user content untouched.
+          const startIdx = existing.indexOf(START_MARKER);
+          const endIdx = existing.indexOf(END_MARKER) + END_MARKER.length;
+          const before = existing.slice(0, startIdx);
+          const after = existing.slice(endIdx);
+          const next = `${before.replace(/\n+$/, "")}\n\n${START_MARKER}\n${AI_CODER_PROTOCOL_TEXT}\n${END_MARKER}\n${after.replace(/^\n+/, "")}`;
+          if (next === existing) {
+            console.log(color("dim", `  ⊝ ${path.basename(t.path)} (${t.label}) — protocol already current`));
+            installSummary.push({ component: "AI Coder Protocol", path: t.path, label: t.label, status: "skipped-already-present" });
+            continue;
+          }
+          await fs.writeFile(t.path, next, "utf8");
+          console.log(color("green", `  ✓ refreshed protocol section → ${path.basename(t.path)} (${t.label})`));
+          installSummary.push({ component: "AI Coder Protocol", path: t.path, label: t.label, status: "installed-updated" });
+        } else if (hasLegacyHeading) {
+          // Old install lacks markers. Don't double-append; treat as already present.
+          // Note: customers can re-run `pqcheck protocol install --auto` to upgrade to the markered form.
+          console.log(color("dim", `  ⊝ ${path.basename(t.path)} (${t.label}) — legacy unmarkered protocol present (run \`pqcheck protocol install --auto\` to upgrade to markered form)`));
+          installSummary.push({ component: "AI Coder Protocol", path: t.path, label: t.label, status: "skipped-legacy-present" });
+        } else {
+          // Fresh install — append with fenced markers.
+          const sep = existing.length > 0 ? "\n\n" : "";
+          await fs.writeFile(t.path, `${existing}${sep}${START_MARKER}\n${AI_CODER_PROTOCOL_TEXT}\n${END_MARKER}\n`, "utf8");
+          console.log(color("green", `  ✓ appended protocol (markered) → ${path.basename(t.path)} (${t.label})`));
+          installSummary.push({ component: "AI Coder Protocol", path: t.path, label: t.label, status: "installed" });
+        }
+      } catch (err) {
+        console.log(color("red", `  ✗ ${t.path} — failed: ${err.message}`));
+        installSummary.push({ component: "AI Coder Protocol", path: t.path, status: "failed", error: String(err?.message || err) });
+      }
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Component 3: Git pre-push hook
+  // -------------------------------------------------------------------------
+  if (!skipHook) {
+    const gitDir = path.join(process.cwd(), ".git");
+    let isGitRepo = true;
+    try { await fs.access(gitDir); } catch { isGitRepo = false; }
+    if (!isGitRepo) {
+      console.log(color("dim", `  ⊝ git pre-push hook — skipped (not a git repo: no .git dir in ${process.cwd()})`));
+      installSummary.push({ component: "git pre-push hook", status: "skipped-not-git-repo" });
+    } else {
+      const hookPath = path.join(gitDir, "hooks", "pre-push");
+      try {
+        let existing = "";
+        try { existing = await fs.readFile(hookPath, "utf8"); } catch { /* file may not exist */ }
+        if (existing.includes("Cipherwake pre-push hook")) {
+          console.log(color("dim", `  ⊝ .git/hooks/pre-push already contains the Cipherwake hook — skipping`));
+          installSummary.push({ component: "git pre-push hook", path: hookPath, status: "skipped-already-present" });
+        } else if (existing.trim() && !existing.startsWith("#!/")) {
+          console.log(color("yellow", `  ⊝ .git/hooks/pre-push exists but doesn't look like our hook — skipped to avoid overwriting your script`));
+          installSummary.push({ component: "git pre-push hook", path: hookPath, status: "skipped-conflicts" });
+        } else {
+          const hookScript = GIT_PREPUSH_HOOK_SCRIPT.replace("DOMAIN_PLACEHOLDER", domain);
+          await fs.mkdir(path.dirname(hookPath), { recursive: true });
+          await fs.writeFile(hookPath, hookScript, { mode: 0o755 });
+          // Ensure executable bit set (writeFile mode is platform-dependent)
+          try { await fs.chmod(hookPath, 0o755); } catch { /* best effort */ }
+          console.log(color("green", `  ✓ installed .git/hooks/pre-push (catches manual \`git push origin main\` bypasses)`));
+          installSummary.push({ component: "git pre-push hook", path: hookPath, status: "installed" });
+        }
+      } catch (err) {
+        console.log(color("red", `  ✗ pre-push hook install failed: ${err.message}`));
+        installSummary.push({ component: "git pre-push hook", path: hookPath, status: "failed", error: String(err?.message || err) });
+      }
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Component 4: Claude Code statusLine config
+  // -------------------------------------------------------------------------
+  // R74-confirm BLOCKING #10 (GPT 2026-05-22): backup before any settings.json
+  // write. The user's ~/.claude/settings.json is theirs; we deep-merge our
+  // entries but if the merge is ever wrong (existing key shape we didn't
+  // anticipate), the backup gives them a one-second rollback path. The backup
+  // is also surfaced in the install summary so the audit trail captures it.
+  async function backupSettingsJson(settingsPath) {
+    try {
+      let raw;
+      try { raw = await fs.readFile(settingsPath, "utf8"); } catch { return null; }
+      const ts = new Date().toISOString().replace(/[:.]/g, "-");
+      const backupPath = `${settingsPath}.bak.${ts}`;
+      await fs.writeFile(backupPath, raw, "utf8");
+      return backupPath;
+    } catch (e) {
+      console.log(color("yellow", `  ⚠ settings.json backup failed (${(e && e.message || e)}); proceeding anyway`));
+      return null;
+    }
+  }
+
+  if (!skipStatusline) {
+    const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+    try {
+      let settings = {};
+      let existed = false;
+      try {
+        const raw = await fs.readFile(settingsPath, "utf8");
+        settings = JSON.parse(raw);
+        existed = true;
+      } catch { /* will create */ }
+      if (existed && settings.statusLine && typeof settings.statusLine === "object") {
+        // Already has a statusLine config — don't overwrite.
+        console.log(color("dim", `  ⊝ ~/.claude/settings.json already has a statusLine entry — leaving alone`));
+        console.log(color("dim", `    To use the Cipherwake statusline instead, set: "command": "npx cipherwake-statusline"`));
+        installSummary.push({ component: "Claude Code statusLine", path: settingsPath, status: "skipped-existing-config" });
+      } else {
+        const backupPath = existed ? await backupSettingsJson(settingsPath) : null;
+        if (backupPath) console.log(color("dim", `    backup: ${backupPath}`));
+        settings.statusLine = { type: "command", command: "npx cipherwake-statusline" };
+        await fs.mkdir(path.dirname(settingsPath), { recursive: true });
+        await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+        console.log(color("green", `  ✓ added statusLine config → ~/.claude/settings.json`));
+        installSummary.push({ component: "Claude Code statusLine", path: settingsPath, status: existed ? "installed-updated" : "installed-created", backup: backupPath });
+      }
+    } catch (err) {
+      console.log(color("red", `  ✗ statusLine config install failed: ${err.message}`));
+      installSummary.push({ component: "Claude Code statusLine", path: settingsPath, status: "failed", error: String(err?.message || err) });
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Component 4b: Claude Code chat-hook (PostToolUse on Bash → cipherwake-chat-hook)
+  // Pushes a live "◆ Cipherwake just caught X" message into the chat scrollback
+  // every time a pqcheck command runs. Merges with existing hook configs;
+  // doesn't clobber other hooks per CLAUDE.md Rule 17.
+  // -------------------------------------------------------------------------
+  if (!skipStatusline) {
+    const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+    try {
+      let settings = {};
+      let existed = false;
+      try {
+        const raw = await fs.readFile(settingsPath, "utf8");
+        settings = JSON.parse(raw);
+        existed = true;
+      } catch { /* will create */ }
+      settings.hooks = settings.hooks || {};
+      settings.hooks.PostToolUse = settings.hooks.PostToolUse || [];
+
+      // Look for an existing matcher entry for Bash
+      let bashEntry = settings.hooks.PostToolUse.find((e) => e?.matcher === "Bash");
+      if (!bashEntry) {
+        bashEntry = { matcher: "Bash", hooks: [] };
+        settings.hooks.PostToolUse.push(bashEntry);
+      }
+      bashEntry.hooks = bashEntry.hooks || [];
+
+      const cipherwakeHookCmd = "npx cipherwake-chat-hook";
+      const alreadyInstalled = bashEntry.hooks.some(
+        (h) => h?.type === "command" && typeof h?.command === "string" && h.command.includes("cipherwake-chat-hook"),
+      );
+
+      if (alreadyInstalled) {
+        console.log(color("dim", `  ⊝ chat-hook already configured in ~/.claude/settings.json PostToolUse — skipping`));
+        installSummary.push({ component: "Claude Code chat-hook", path: settingsPath, status: "skipped-already-present" });
+      } else {
+        const backupPath = existed ? await backupSettingsJson(settingsPath) : null;
+        if (backupPath) console.log(color("dim", `    backup: ${backupPath}`));
+        bashEntry.hooks.push({ type: "command", command: cipherwakeHookCmd });
+        await fs.mkdir(path.dirname(settingsPath), { recursive: true });
+        await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+        console.log(color("green", `  ✓ added chat-hook (PostToolUse Bash) → ~/.claude/settings.json`));
+        console.log(color("dim", `    Every \`pqcheck\` run will now push a live status message into Claude Code chat`));
+        installSummary.push({ component: "Claude Code chat-hook", path: settingsPath, status: existed ? "installed-updated" : "installed-created", backup: backupPath });
+      }
+    } catch (err) {
+      console.log(color("red", `  ✗ chat-hook install failed: ${err.message}`));
+      installSummary.push({ component: "Claude Code chat-hook", status: "failed", error: String(err?.message || err) });
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Component 5: VS Code / Cursor extension (via `code` CLI if available)
+  // -------------------------------------------------------------------------
+  if (!skipVscode) {
+    // Check if `code` CLI is on PATH
+    const codeAvailable = await new Promise((resolve) => {
+      const child = spawn("code", ["--version"], { stdio: ["ignore", "ignore", "ignore"] });
+      child.on("error", () => resolve(false));
+      child.on("close", (rc) => resolve(rc === 0));
+    });
+    if (!codeAvailable) {
+      console.log(color("dim", `  ⊝ VS Code extension — \`code\` CLI not on PATH. Install from Marketplace: search "Cipherwake Trust Status Bar"`));
+      installSummary.push({ component: "VS Code / Cursor extension", status: "skipped-code-cli-not-available" });
+    } else {
+      // Note: until the extension is published to Marketplace, `code --install-extension cipherwakelabs.cipherwake-statusbar`
+      // won't resolve. We attempt the install and treat failure as a soft skip.
+      const installResult = await new Promise((resolve) => {
+        const child = spawn("code", ["--install-extension", "cipherwakelabs.cipherwake-statusbar"], { stdio: ["ignore", "pipe", "pipe"] });
+        let out = "";
+        child.stdout?.on("data", (d) => out += d.toString());
+        child.stderr?.on("data", (d) => out += d.toString());
+        child.on("close", (rc) => resolve({ rc, out }));
+        child.on("error", (err) => resolve({ rc: -1, out: err.message }));
+      });
+      if (installResult.rc === 0) {
+        console.log(color("green", `  ✓ installed VS Code extension: cipherwakelabs.cipherwake-statusbar`));
+        installSummary.push({ component: "VS Code / Cursor extension", status: "installed" });
+      } else {
+        console.log(color("dim", `  ⊝ VS Code extension install attempted but not on Marketplace yet. Awaiting publish.`));
+        installSummary.push({ component: "VS Code / Cursor extension", status: "skipped-not-on-marketplace-yet", attempted: true });
+      }
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Audit trail
+  // -------------------------------------------------------------------------
+  try {
+    const prefsDir = path.join(os.homedir(), ".config", "cipherwake");
+    await fs.mkdir(prefsDir, { recursive: true });
+    const prefsPath = path.join(prefsDir, "install-prefs.json");
+    let prefs = { history: [] };
+    try {
+      const existing = await fs.readFile(prefsPath, "utf8");
+      prefs = JSON.parse(existing);
+      if (!Array.isArray(prefs.history)) prefs.history = [];
+    } catch { /* first run */ }
+    prefs.history.push({
+      timestamp: new Date().toISOString(),
+      command: "setup",
+      mode: autoFlag ? "auto-flag" : "interactive",
+      domain,
+      consent_phrase: consentPhrase,
+      invoked_by: invokedBy,
+      cwd: process.cwd(),
+      hostname: os.hostname(),
+      pqcheck_version: VERSION,
+      summary: installSummary,
+    });
+    await fs.writeFile(prefsPath, JSON.stringify(prefs, null, 2), "utf8");
+    console.log("");
+    console.log(color("dim", `  Audit trail: ${prefsPath}`));
+  } catch (err) {
+    console.log(color("dim", `  (audit trail write failed: ${err.message} — non-fatal)`));
+  }
+
+  // R74-confirm BLOCKING #16 (GPT 2026-05-22): write an install manifest so
+  // a Ctrl-C'd or partially-failed install can be diagnosed + resumed. The
+  // manifest is the "what got done" record, separate from install-prefs.json
+  // (which is the "who/why" audit trail). A future `pqcheck doctor --repair`
+  // command will use this to skip already-completed steps. For now the file
+  // is the artifact you can `cat` to see exactly what got written.
+  try {
+    const manifestPath = path.join(os.homedir(), ".config", "cipherwake", "install-manifest.json");
+    let manifestList = [];
+    try {
+      manifestList = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+      if (!Array.isArray(manifestList)) manifestList = [];
+    } catch { /* new file */ }
+    manifestList.unshift({
+      run_at: new Date().toISOString(),
+      domain,
+      auto_flag: autoFlag,
+      invoked_by: invokedBy || null,
+      consent_phrase: consentPhrase || null,
+      cwd: process.cwd(),
+      cli_version: VERSION,
+      install_summary: installSummary,
+      // Surface the backup paths separately so `pqcheck doctor --repair --rollback` can find them
+      backups: installSummary.filter((s) => s.backup).map((s) => ({ component: s.component, backup: s.backup })),
+    });
+    // Keep last 20 install runs for forensics
+    manifestList = manifestList.slice(0, 20);
+    await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+    await fs.writeFile(manifestPath, JSON.stringify(manifestList, null, 2), "utf8");
+    console.log(color("dim", `  Install manifest: ${manifestPath}`));
+  } catch (err) {
+    console.log(color("dim", `  (manifest write failed: ${err.message} — non-fatal)`));
+  }
+
+  // -------------------------------------------------------------------------
+  // Summary table
+  // -------------------------------------------------------------------------
+  console.log("");
+  console.log(color("bold", "◆ Setup complete — summary:"));
+  console.log("");
+  for (const s of installSummary) {
+    const icon = s.status === "installed" || s.status === "installed-created" || s.status === "installed-updated"
+      ? color("green", "✓")
+      : s.status?.startsWith("skipped")
+        ? color("dim", "⊝")
+        : color("red", "✗");
+    const label = s.component;
+    const detail = s.status === "installed" || s.status === "installed-created" || s.status === "installed-updated"
+      ? color("dim", `installed${s.path ? " → " + s.path.replace(os.homedir(), "~") : ""}`)
+      : color("dim", s.status?.replace(/-/g, " "));
+    console.log(`  ${icon} ${label.padEnd(34, " ")} ${detail}`);
+  }
+  console.log("");
+  console.log(color("dim", `Reference: https://cipherwake.io/methodology/ai-coder-protocol`));
+  console.log("");
+
+  process.exit(0);
+}
+
 main().catch((err) => {
   console.error(color("red", `fatal: ${err.message}`));
   process.exit(2);