@patchstack/connect 0.5.12 → 0.5.15

package/dist/cli.js

@@ -221,7 +221,7 @@ function unreadableWarning(filename, report) {
   if (report.unreadable === 0) return null;
   const shown = report.samples.join(", ");
   const one = report.unreadable === 1;
-  return `${filename}: ${report.unreadable} entr${one ? "y was" : "ies were"} not in a form this scanner reads (${shown}${report.unreadable > report.samples.length ? ", \u2026" : ""}), so ${one ? "it is" : "they are"} absent from this manifest. Anything installed only through ${one ? "that entry" : "those entries"} is not being checked.`;
+  return `${filename}: ${report.unreadable} entr${one ? "y" : "ies"} could not be read (${shown}${report.unreadable > report.samples.length ? ", \u2026" : ""}), so ${one ? "that package is" : "those packages are"} not being checked.`;
 }
 
 // src/parsers/bun.ts
@@ -1123,7 +1123,7 @@ async function scanLockfile(cwd) {
       warnings.push(staleWarning("node_modules/", missing));
     }
     warnings.push(
-      walkWasCandidate ? "Reporting node_modules/, which is what the build loads." : "Scanned node_modules/ instead. Delete the stale lockfile to silence this warning."
+      walkWasCandidate ? "Checked the installed packages in node_modules/, which is what the build loads." : "Checked the installed packages in node_modules/ instead. Delete the out-of-date package list file to stop this warning."
     );
     return manifestWith(walked, warnings);
   }
@@ -1135,7 +1135,7 @@ async function scanLockfile(cwd) {
     );
   }
   warnings.push(
-    `No fully-consistent source found; reporting ${firstParsed.filename}. The manifest may understate the real dependency set.`
+    `No package list matches package.json; checked ${firstParsed.filename}, so some packages may be missing. Reinstall your packages to fix this.`
   );
   return manifestWith(firstParsed.packages, warnings);
 }
@@ -1149,12 +1149,19 @@ function otherCompleteSources(all, current, declared) {
 }
 function conflictWarning(filename, conflicts) {
   const shown = conflicts.slice(0, 3).map(({ other, conflict }) => `${conflict.name} ${conflict.version} vs ${conflict.otherVersion} in ${other}`).join("; ");
-  return `${filename} and another lockfile disagree about installed versions (${shown}${conflicts.length > 3 ? `, +${conflicts.length - 3} more` : ""}). Scanned node_modules/ instead. Remove whichever lockfile your package manager does not maintain.`;
-}
+  return `${filename} and another package list file give different versions (${shown}${conflicts.length > 3 ? `, +${conflicts.length - 3} more` : ""}). Checked node_modules/ instead. Delete the file your package manager does not use.`;
+}
+var INSTALL_BY_SOURCE = {
+  "package-lock.json": "npm install",
+  "bun.lock": "bun install",
+  "bun.lockb": "bun install",
+  "pnpm-lock.yaml": "pnpm install",
+  "yarn.lock": "yarn install"
+};
 function staleWarning(source, missing) {
   const sample = missing.slice(0, 3).join(", ");
   const suffix = missing.length > 3 ? `, +${missing.length - 3} more` : "";
-  return `${source} looks stale: package.json declares ${missing.length} dependenc${missing.length === 1 ? "y" : "ies"} it does not contain (${sample}${suffix}).`;
+  return `${source} is out of date: it is missing ${missing.length} package${missing.length === 1 ? "" : "s"} listed in package.json (${sample}${suffix}). Run ${INSTALL_BY_SOURCE[source] ?? "your install command"} to update it.`;
 }
 async function presentLockfiles(cwd) {
   const probed = await Promise.all(
@@ -1622,21 +1629,28 @@ var CLAIM_TOKEN_HEADER = "X-Patchstack-Claim-Token";
 function claimTokenHeader(config) {
   return config.endpointTrusted !== false && isHeaderValue(config.claimToken) ? { [CLAIM_TOKEN_HEADER]: config.claimToken } : {};
 }
-function claimOutcomeLines(claim3, config) {
-  if (typeof config.claimToken !== "string" || config.claimToken === "") return [];
+function claimOutcome(claim3, config) {
+  if (typeof config.claimToken !== "string" || config.claimToken === "") return null;
   if (claim3?.state === "claimed" || claim3?.state === "owned-by-you") {
-    const dashboardUrl = safeRemoteUrl(claim3.dashboard_url);
-    const dashboard = dashboardUrl === null ? [] : [`Dashboard: ${dashboardUrl}`];
-    return [
-      claim3.state === "claimed" ? "Connected to your Patchstack account." : "This site is already connected to your Patchstack account.",
-      ...dashboard
-    ];
+    return {
+      connected: true,
+      summary: claim3.state === "claimed" ? "Connected to your Patchstack account" : "This project is already connected to your Patchstack account",
+      dashboardUrl: safeRemoteUrl(claim3.dashboard_url),
+      hint: []
+    };
   }
-  const why = claim3 === void 0 ? "Patchstack did not act on the claim token" : claim3.state === "owned-by-other" ? "this site belongs to a different Patchstack account" : claim3.reason === "expired" ? "the claim token has expired" : "Patchstack did not recognise the claim token";
-  return [
-    `Not connected to your account: ${why}.`,
-    "Open the dashboard link below to connect it, or copy a fresh prompt from the dashboard."
-  ];
+  const why = claimFailureReason(claim3);
+  return {
+    connected: false,
+    summary: `Not connected to your account: ${why}`,
+    dashboardUrl: null,
+    hint: ["Open the dashboard link below to connect it, or copy a fresh prompt from the dashboard."]
+  };
+}
+function claimFailureReason(claim3) {
+  if (claim3 === void 0) return "Patchstack did not act on the claim token";
+  if (claim3.state === "owned-by-other") return "this project belongs to a different Patchstack account";
+  return claim3.reason === "expired" ? "the claim token has expired" : "Patchstack did not recognise the claim token";
 }
 function buildEndpointUrl(base, siteUuid) {
   const trimmed = base.replace(/\/$/, "");
@@ -1645,13 +1659,13 @@ function buildEndpointUrl(base, siteUuid) {
 function authFailureMessage(status, config) {
   const hasCredential = typeof config.pulseAuth === "string" && config.pulseAuth.length > 0;
   if (status === 401 && !hasCredential) {
-    return "Patchstack requires an API credential for this site and none is configured. Run `npx patchstack-connect login`, or set PATCHSTACK_API_KEY.";
+    return "Patchstack needs this project's API key, and none is set here. Run npx @patchstack/connect login, or set PATCHSTACK_API_KEY.";
   }
   if (status === 401) {
-    return "Patchstack rejected this API credential. It may have expired, been revoked, or the site may no longer exist. Run `npx patchstack-connect login` to issue a new one.";
+    return "Patchstack did not accept this project's API key: it may have expired or been revoked, or the project may no longer exist. Run npx @patchstack/connect login to get a new one.";
   }
   if (status === 403) {
-    return "This API credential is not permitted to act on this site. Check that siteUuid in .patchstackrc.json matches the credential (a credential is issued for one site).";
+    return "This API key belongs to a different project. Check that siteUuid in .patchstackrc.json is the project the key was made for.";
   }
   return null;
 }
@@ -2064,7 +2078,7 @@ function renderDemoGuide(state) {
     `Patchstack demo guide \u2014 ${scenario.name}`,
     "",
     "Goal: prove that a live Patchstack virtual patch blocks the vulnerable payload while normal traffic still succeeds.",
-    "Deployment required: no. Keep the app running locally; the connector and generated guard contact Patchstack\u2019s production API.",
+    "Deployment required: no. Keep the app running locally; Connect and the generated guard contact Patchstack\u2019s production API.",
     "",
     `1. ${siteReady ? "\u2713" : "\u25CB"} Connect this project from Bolt\u2019s Host account dropdown`,
     siteReady ? `   Ready \u2014 .patchstackrc.json contains site ${state.siteUuid}.` : "   Click \u201CConnect Patchstack\u201D in Bolt. This creates .patchstackrc.json; no separate CLI login is needed.",
@@ -3825,7 +3839,7 @@ function classifyArchitecture(cwd) {
     return {
       requestPath: "none",
       evidence: statics.map((label) => `static build: ${label}`),
-      note: `This project builds a static site (${statics.join(", ")}) and nothing in it receives a request, so there is no request path for a runtime guard to attach to. Dependency monitoring and the disclosure widget still apply; runtime protection does not.`
+      note: `This project builds a static site (${statics.join(", ")}) and nothing in it receives a request, so there is no request path for a runtime guard to attach to. Dependency monitoring and the Patchstack Connector still apply; runtime protection does not.`
     };
   }
   return {
@@ -3840,7 +3854,21 @@ import { readFileSync as readFileSync7, existsSync as existsSync3 } from "fs";
 import { join as join5, dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 var read = (p) => readFileSync7(p, "utf8");
-var log = (msg) => console.log(`patchstack protect: ${msg}`);
+var logSink = null;
+var log = (msg) => {
+  if (logSink !== null) logSink(msg);
+  else console.log(`patchstack protect: ${msg}`);
+};
+function collectProtectLog(fn) {
+  const lines = [];
+  const previous = logSink;
+  logSink = (msg) => lines.push(...msg.split("\n"));
+  try {
+    return { result: fn(), lines };
+  } finally {
+    logSink = previous;
+  }
+}
 function hasDependency(cwd, name) {
   try {
     const pkg = JSON.parse(read(join5(cwd, "package.json")));
@@ -5502,6 +5530,147 @@ function ensureSourceWidget(cwd, siteUuid, jsxShell = null) {
   return { shell, action };
 }
 
+// src/progress.ts
+var PROGRESS_STEPS = [
+  { step: "installed", label: "Install the Patchstack connector" },
+  { step: "connected", label: "Connect project to Patchstack account" },
+  { step: "synced", label: "Sync and monitor your project" },
+  { step: "deployed", label: "Deploy project to protect live app" }
+];
+function stepLabel(step, environment) {
+  if (step === "synced" && environment) return `Sync and monitor in ${environment} environment`;
+  return PROGRESS_STEPS.find((entry) => entry.step === step).label;
+}
+function deployNote(context) {
+  if (context.environment !== "production") return null;
+  return context.environmentSource === "builder" ? "Reported as a publish. Patchstack ticks this once it sees the live site." : "Built for production. Patchstack ticks this once it sees the live site.";
+}
+var ANSI = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  cyan: "\x1B[36m"
+};
+function nextProgressStep(progress) {
+  return PROGRESS_STEPS.find(({ step }) => !progress[step])?.step ?? null;
+}
+function nextStepTitle(step, context) {
+  switch (step) {
+    case "installed":
+      return "install the Patchstack connector";
+    case "connected":
+      return "connect this project to your Patchstack account";
+    case "synced":
+      return "sync this project with Patchstack";
+    case "deployed":
+      return context.environment === "production" ? "open your live app so Patchstack can see it" : "deploy your project to protect the live app";
+  }
+}
+function nextStepLines(step, context) {
+  switch (step) {
+    case "installed":
+      return [`Run: ${context.installCommand}`, "Then run: npx @patchstack/connect setup"];
+    case "connected":
+      if (context.siteUuid === null) {
+        return [
+          "Run: npx @patchstack/connect setup",
+          "It adds this project to Patchstack and prints the link to connect it.",
+          'Cannot run commands here? See "When your tool will not run this CLI" in AGENT-INSTALL.md.'
+        ];
+      }
+      return [
+        context.claimUrl !== null ? `Open ${context.claimUrl}` : "Run: npx @patchstack/connect claim",
+        // A production run is the deploy itself, so there is nothing further to point at.
+        ...context.environment === "production" ? [] : ["Already connected? Then commit, set PATCHSTACK_API_KEY on your host, and deploy."]
+      ];
+    case "synced":
+      return ["Run: npx @patchstack/connect scan"];
+    case "deployed":
+      if (context.environment === "production") {
+        return ["Open the live site once so Patchstack can see it.", "Not published yet? Publish or deploy it now."];
+      }
+      return [
+        "Commit your changes. Never commit .patchstackrc.local.json.",
+        "Set PATCHSTACK_API_KEY (from .patchstackrc.local.json) on your hosting platform.",
+        "Deploy or publish. The live site keeps its old version until you do."
+      ];
+  }
+}
+function renderProgress(progress, context, options) {
+  const paint = (code, text) => options.useColor ? `${code}${text}${ANSI.reset}` : text;
+  const lines = [];
+  for (const { step } of PROGRESS_STEPS) {
+    const label = stepLabel(step, context.environment);
+    lines.push(progress[step] ? ` ${paint(ANSI.green, "\u2714")} ${label}` : ` ${paint(ANSI.yellow, "\u2718")} ${label}`);
+    const note = step === "deployed" && !progress.deployed ? deployNote(context) : null;
+    if (note !== null) lines.push(`     ${paint(ANSI.dim, note)}`);
+  }
+  const next = nextProgressStep(progress);
+  lines.push("");
+  if (next === null) {
+    lines.push(paint(ANSI.bold, "All done."));
+    return lines;
+  }
+  lines.push(`${paint(ANSI.cyan, "\u279C")} ${paint(ANSI.bold, `Next: ${nextStepTitle(next, context)}`)}`);
+  for (const line of nextStepLines(next, context)) {
+    lines.push(`  ${line}`);
+  }
+  return lines;
+}
+
+// src/report.ts
+function emptyReport() {
+  return { done: [], missing: [] };
+}
+var ANSI2 = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m"
+};
+function renderStatus(title, report, progress, context, options) {
+  const paint = (code, text) => options.useColor ? `${code}${text}${ANSI2.reset}` : text;
+  const lines = [paint(ANSI2.bold, title), ""];
+  if (report.done.length > 0) {
+    lines.push(paint(ANSI2.bold, "Done"));
+    for (const item of report.done) lines.push(` ${paint(ANSI2.green, "\u2714")} ${item}`);
+    lines.push("");
+  }
+  if (report.missing.length > 0) {
+    lines.push(paint(ANSI2.bold, "Missing"));
+    for (const item of report.missing) {
+      lines.push(` ${paint(ANSI2.yellow, "\u2718")} ${item.text}`);
+      for (const hint of item.hint ?? []) lines.push(`   ${hint}`);
+      if (options.verbose === true) {
+        for (const detail2 of item.detail ?? []) lines.push(`   ${paint(ANSI2.dim, detail2)}`);
+      }
+    }
+    lines.push("");
+  }
+  if (options.withoutProgress === true) {
+    if (lines[lines.length - 1] === "") lines.pop();
+    return lines;
+  }
+  lines.push(...renderProgress(progress, context, { useColor: options.useColor }));
+  return lines;
+}
+function renderHookSummary(report, progress, context) {
+  const lowerFirst = (text) => text.charAt(0).toLowerCase() + text.slice(1);
+  const lines = [];
+  if (report.done.length > 0) {
+    lines.push(`Patchstack: ${report.done.map(lowerFirst).join("; ")}.`);
+  }
+  const next = nextProgressStep(progress);
+  if (next !== null) {
+    const first = next === "deployed" && context.environment === "production" ? void 0 : nextStepLines(next, context)[0];
+    lines.push(`Patchstack next step: ${nextStepTitle(next, context)}.${first !== void 0 ? ` ${first}` : ""}`);
+  }
+  return lines;
+}
+
 // src/guide.ts
 var PROD_MARKER_NEEDLE = "__PATCHSTACK_PROD__";
 var WIDGET_NEEDLE2 = "patchstack-widget";
@@ -5698,8 +5867,12 @@ async function collectGuideState(cwd) {
   let claimUrl = null;
   let endpointOverride = null;
   let widgetOptOut = false;
+  let environment = null;
+  let environmentSource = null;
   try {
     const config = await resolveConfig({ cwd });
+    environment = config.environment;
+    environmentSource = config.environmentSource ?? null;
     siteUuid = config.siteUuid;
     if (siteUuid !== null && config.endpointTrusted !== false) {
       claimUrl = buildClaimUrl(config.endpoint, siteUuid);
@@ -5726,6 +5899,8 @@ async function collectGuideState(cwd) {
     siteUuid,
     claimUrl,
     endpointOverride,
+    environment,
+    environmentSource,
     hasBuildScript: Boolean(pkg?.scripts?.build?.trim()),
     installScanWired: (pkg?.scripts?.postinstall ?? "").includes("patchstack-connect scan"),
     // The scan has to run first: a later prebuild command may upload and stamp the map that the bundle
@@ -5744,7 +5919,7 @@ async function collectGuideState(cwd) {
     protectionApplicable: protection.applicable
   };
 }
-var ANSI = {
+var ANSI3 = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
   dim: "\x1B[2m",
@@ -5758,9 +5933,6 @@ function needsSourceProductionMarker(state) {
   }
   return !state.widgetFileHint.toLowerCase().endsWith(".html");
 }
-function widgetTagInPlace(state) {
-  return state.siteUuid !== null && !state.widgetOptOut && state.widgetInstalled && state.widgetTokenMatches !== false;
-}
 function countRemainingSteps(state) {
   return [
     state.installed?.section === "dependencies",
@@ -5772,217 +5944,143 @@ function countRemainingSteps(state) {
     !state.protectionApplicable || state.protectionWired
   ].filter((step) => !step).length;
 }
-function renderGuideChecklist(state, useColor) {
-  const paint = (code, text) => useColor ? `${code}${text}${ANSI.reset}` : text;
-  const done = (text) => ` ${paint(ANSI.green, "\u2714")} ${text}`;
-  const todo = (text) => ` ${paint(ANSI.yellow, "\u2716")} ${paint(ANSI.bold, text)}`;
-  const detail = (text) => `     ${paint(ANSI.dim, text)}`;
+function guideProgress(state, known = {}) {
+  return {
+    installed: state.installed !== null,
+    // Claim state lives on the server and nothing on disk records it, so only a caller that has just
+    // heard from the server (a scan's claim outcome) can mark it done.
+    connected: false,
+    // `.patchstackrc.json` only gains a site UUID from a manifest the server stored.
+    synced: state.siteUuid !== null,
+    // Only the dashboard can see the live site, so nothing the CLI runs marks this done.
+    deployed: false,
+    ...known
+  };
+}
+function guideNextStepContext(state) {
+  return {
+    installCommand: installCommand(state.packageManager),
+    siteUuid: state.siteUuid,
+    claimUrl: state.claimUrl,
+    environment: state.environment,
+    environmentSource: state.environmentSource
+  };
+}
+function notConnectedItem(why = []) {
+  return {
+    text: "Not connected to your Patchstack account",
+    hint: [...why, "Until it is, anyone who opens your app can connect it to their own account."]
+  };
+}
+function buildScriptLines(state) {
   const lines = [];
-  const headerParts = [state.framework, state.packageManager].filter(
-    (part) => part !== null
-  );
-  const name = state.projectName ?? path12.basename(process.cwd());
-  lines.push(paint(ANSI.bold, `Patchstack setup status \u2014 ${name} (${headerParts.join(" \xB7 ")})`));
-  if (state.endpointOverride !== null) {
-    lines.push(
-      detail(
-        `endpoint override in effect: ${state.endpointOverride} (set via .patchstackrc.json, PATCHSTACK_ENDPOINT, or --endpoint)`
-      )
-    );
-  }
-  lines.push("");
-  if (!state.hasPackageJson) {
-    lines.push(todo("No package.json found in this directory."));
-    lines.push(detail("For a JS/Node app, run the guide from its package directory; check that package.json is readable and valid."));
-    lines.push(detail("For a standalone HTML/CSS/browser-JavaScript site, use the disclosure widget directly."));
-    lines.push(detail("Do not create a Node project, build hooks, or a server just to install the widget."));
-    lines.push(detail("Use the correct site UUID or widget snippet from the Patchstack dashboard; never invent one."));
-    lines.push(detail('See "Plain HTML sites" in AGENT-INSTALL.md. Widget-only setup provides no dependency scan or runtime protection.'));
-    return lines.join("\n");
-  }
-  if (countRemainingSteps(state) > 0) {
-    lines.push(` ${paint(ANSI.cyan, "\u279C")} ${paint(ANSI.bold, "Tell the user what you are doing as you go.")}`);
-    lines.push("   Installs here take minutes and they are watching output they cannot read.");
-    lines.push("   Say it in plain words: their site is built out of hundreds of ready-made");
-    lines.push("   pieces of code, Patchstack keeps track of which ones it uses and warns them");
-    lines.push("   when one turns out to be unsafe, and nothing their visitors see changes.");
-    lines.push("   Avoid lockfile / dependency / manifest / npm / UUID when speaking to them.");
-    lines.push("");
-  }
-  if (state.siteUuid === null) {
-    lines.push(` ${paint(ANSI.cyan, "\u279C")} ${paint(ANSI.bold, "Nothing is set up yet \u2014 two commands cover the steps below:")}`);
-    if (state.installed?.section !== "dependencies") {
-      lines.push(`   ${installCommand(state.packageManager)}`);
-    }
-    lines.push("   npx @patchstack/connect setup");
-    lines.push("   setup provisions the site, adds the widget, installs and verifies runtime protection,");
-    lines.push("   and wires the install and build scans, then prints this checklist again. Anything");
-    lines.push("   still listed there is a step setup could not apply safely, and is yours to finish.");
-    lines.push("");
-  }
-  if (state.installed?.section === "dependencies") {
-    lines.push(done(`@patchstack/connect installed (${state.installed.version}, ${state.installed.section})`));
-  } else if (state.installed !== null) {
-    lines.push(todo(`Move @patchstack/connect to runtime dependencies (currently ${state.installed.section})`));
-    lines.push(detail(`Run \u2192 ${installCommand(state.packageManager)}`));
-    lines.push(detail("The generated guard imports @patchstack/connect/protect at runtime."));
-  } else {
-    lines.push(todo("Install @patchstack/connect as a runtime dependency"));
-    lines.push(detail(`Run \u2192 ${installCommand(state.packageManager)}`));
+  if (!state.installScanWired) lines.push('"postinstall": "patchstack-connect scan"');
+  if (state.hasBuildScript && !(state.prebuildWired && state.postbuildWired)) {
     if (state.packageManager === "bun") {
-      lines.push(detail(`(if bun isn't available here, ${INSTALL_COMMANDS.npm} works too)`));
-    }
-  }
-  if (state.siteUuid !== null) {
-    lines.push(done(`Site provisioned (${state.siteUuid})`));
-  } else {
-    lines.push(todo("Provision the site \u2014 run the first scan"));
-    lines.push(detail("Run \u2192 npx @patchstack/connect scan"));
-    lines.push(detail("Reads the lockfile, registers the project, writes .patchstackrc.json,"));
-    lines.push(detail("and prints a dashboard link. The CLI prints the link but never opens it."));
-    lines.push(detail("If your tool refuses to run this command, hand it to the person instead of working"));
-    lines.push(detail('around it \u2014 see "When your tool will not run this CLI" in the reference guide.'));
-  }
-  if (state.installScanWired) {
-    lines.push(done("Dependency-install scan wired (postinstall)"));
-  } else {
-    lines.push(todo("Scan again whenever dependencies are installed"));
-    lines.push(detail('Edit package.json \u2192 "postinstall": "patchstack-connect scan"'));
-  }
-  if (!state.hasBuildScript) {
-    lines.push(done("No build script to integrate (postinstall covers dependency changes)"));
-  } else if (state.prebuildWired && state.postbuildWired) {
-    lines.push(done("Build hooks wired (scan before builds, mark-build after)"));
-  } else if (state.packageManager === "bun") {
-    lines.push(todo('Wire the build hooks yourself \u2014 edit package.json (bun skips pre/post hooks, so chain inside "build")'));
-    lines.push(detail('Edit package.json \u2192 "build": "patchstack-connect scan && <existing build command> && patchstack-connect mark-build"'));
-  } else {
-    lines.push(todo('Wire the build hooks yourself \u2014 edit package.json "scripts" (chain with && if a hook already exists)'));
-    if (!state.prebuildWired) {
-      lines.push(detail('Edit package.json \u2192 "prebuild": "patchstack-connect scan"'));
-    }
-    if (!state.postbuildWired) {
-      lines.push(detail('Edit package.json \u2192 "postbuild": "patchstack-connect mark-build"'));
-    }
-  }
-  const widgetOk = state.widgetInstalled && state.widgetTokenMatches !== false;
-  if (state.widgetOptOut && !widgetOk) {
-    lines.push(done('Disclosure widget disabled by config ("widget": false in .patchstackrc.json)'));
-  } else if (widgetOk) {
-    lines.push(done("Disclosure widget installed"));
-  } else if (state.widgetInstalled) {
-    lines.push(todo("Fix the disclosure widget yourself \u2014 its site UUID doesn't match this project's"));
-    lines.push(detail(`Edit the widget tag \u2192 set data-site-uuid (or userToken) to '${state.siteUuid}' (a wrong UUID makes the widget silently no-op)`));
-  } else if (state.siteUuid === null) {
-    lines.push(todo('Add the "Report a vulnerability" widget \u2014 the first scan does this for you'));
-    lines.push(detail("Run \u2192 npx @patchstack/connect scan  (provisions the site and adds the widget tag"));
-    lines.push(detail("  to the root HTML shell: index.html / public/index.html / src/app.html)"));
-  } else {
-    lines.push(todo('Add the "Report a vulnerability" widget yourself \u2014 this root is code, not a plain HTML shell'));
-    lines.push(detail("Note \u2192 a normal `scan` adds this tag to a plain HTML shell automatically; add it by hand here:"));
-    const placement = state.widgetFileHint !== null ? `Edit ${state.widgetFileHint} \u2192 put it just before </body>:` : "Edit your root layout \u2192 put it just before </body> (the framework's HTML/layout mechanism, never a JS entry point):";
-    lines.push(detail(placement));
-    lines.push(detail(`  ${buildWidgetTag(state.siteUuid)}`));
-    lines.push(detail("The site UUID is public by design \u2014 it ships in client-side HTML."));
-  }
-  if (needsSourceProductionMarker(state)) {
-    if (state.productionMarkerWired) {
-      lines.push(done("Production marker wired (widget switches to report mode on the published site)"));
+      lines.push('"build": "patchstack-connect scan && <existing build command> && patchstack-connect mark-build"');
     } else {
-      lines.push(todo("Add the production marker \u2014 this root is server-rendered, so mark-build cannot stamp it"));
-      lines.push(
-        detail(
-          "Without it the widget treats the published site as build mode and shows the claim flow to visitors."
-        )
-      );
-      const gate = productionGate(state.framework);
-      if (hasJsxShell(state.framework)) {
-        lines.push(detail(`Run \u2192 npx @patchstack/connect scan  (adds it to ${state.widgetFileHint} automatically)`));
-        lines.push(detail("Or add it by hand, in <head> above the widget tag:"));
-        for (const snippetLine of buildSourceMarkerSnippet(state.framework).split("\n")) {
-          lines.push(detail(`  ${snippetLine}`));
-        }
-      } else {
-        lines.push(
-          detail(
-            `Edit ${state.widgetFileHint} \u2192 using the framework's head mechanism, emit an inline`
-          )
-        );
-        lines.push(detail(`  <script>window.__PATCHSTACK_PROD__=true;</script> only when ${gate}.`));
-      }
-      lines.push(detail(`The ${gate} guard is required \u2014 an ungated marker also hides the claim flow in preview.`));
+      if (!state.prebuildWired) lines.push('"prebuild": "patchstack-connect scan"');
+      if (!state.postbuildWired) lines.push('"postbuild": "patchstack-connect mark-build"');
     }
   }
-  if (!state.protectionApplicable) {
-    lines.push(done("Runtime protection: not applicable \u2014 this project has no request path"));
-    for (const check of state.protectionChecks.filter((item) => item.hint !== void 0 && item.group !== "reporting")) {
-      lines.push(detail(check.hint ?? ""));
-    }
-  } else if (state.protectionWired) {
-    lines.push(done(`Runtime protection wired (${state.protectionStack})`));
-  } else {
-    lines.push(todo(`Finish runtime protection (${state.protectionStack})`));
-    for (const check of state.protectionChecks.filter((item) => !item.ok)) {
-      lines.push(detail(`${check.label}${check.hint ? ` \u2014 ${check.hint}` : ""}`));
-    }
-    lines.push(detail("Verify \u2192 npx @patchstack/connect protect --check"));
-    lines.push(detail("Prove a request reaches the guard (starts your app) \u2192 npx @patchstack/connect protect --check --runtime"));
+  return lines;
+}
+function guideMissing(state, known = {}) {
+  const missing = [];
+  if (state.installed?.section === "devDependencies") {
+    missing.push({
+      text: "Patchstack is installed as a development tool only, so your live app cannot load it",
+      hint: [`Run: ${installCommand(state.packageManager)}`]
+    });
   }
-  lines.push("");
-  if (state.claimUrl !== null) {
-    lines.push(` ${paint(ANSI.cyan, "\u279C")} ${paint(ANSI.bold, "Connect this site to your Patchstack account:")}`);
-    let route = 1;
-    if (widgetTagInPlace(state)) {
-      lines.push(`   ${route++}. In the preview \u2014 while the site is unclaimed the widget shows a`);
-      lines.push('      "Connect this website" panel. Signing in there attaches the site.');
-    }
-    lines.push(`   ${route++}. In a browser \u2014 open the dashboard link (the CLI never opens it):`);
-    lines.push(`      ${paint(ANSI.cyan, state.claimUrl)}`);
-    lines.push(`   ${route}. From this terminal \u2192 npx @patchstack/connect claim`);
-    lines.push("      (prints a link to sign in with, then attaches the site to that account)");
-    lines.push(detail("Reports have no owner to reach until one of these completes. The site UUID ships"));
-    lines.push(detail("in the page and claiming is first-come, so an unclaimed site stays claimable by"));
-    lines.push(detail("anyone who loads it."));
-    if (state.endpointOverride !== null) {
-      lines.push(detail("(this URL inherits the endpoint override above)"));
-    }
-  } else {
-    lines.push(detail("The dashboard link appears after the first scan (re-print any time with `status`)."));
+  if (state.siteUuid === null) return missing;
+  if (!state.widgetOptOut && state.widgetInstalled && state.widgetTokenMatches === false) {
+    missing.push({
+      text: "The Patchstack widget on your page belongs to a different project",
+      hint: [`Set data-site-uuid to '${state.siteUuid}' on the widget tag.`]
+    });
+  } else if (!state.widgetOptOut && !state.widgetInstalled) {
+    missing.push({
+      text: "The Patchstack widget is not on your page yet",
+      hint: [
+        state.widgetFileHint !== null ? `Add this to ${state.widgetFileHint}, just before </body>:` : "Add this to your main page layout, just before </body>:",
+        `  ${buildWidgetTag(state.siteUuid)}`
+      ]
+    });
   }
-  if (widgetTagInPlace(state)) {
-    lines.push("");
-    lines.push(` ${paint(ANSI.cyan, "\u279C")} ${paint(ANSI.bold, "Refresh the preview to see the widget:")}`);
-    lines.push("   The widget loads with the page, so a preview that was already open still shows");
-    lines.push("   the HTML from before this change. Builders that hot reload refresh it themselves;");
-    lines.push("   if nothing appears, refresh the preview once.");
-    lines.push('   Unclaimed, the widget shows the "Connect this website" panel; the public');
-    lines.push('   "Report a vulnerability" button takes its place once the site is claimed.');
-  }
-  if (state.siteUuid !== null) {
-    lines.push("");
-    lines.push(` ${paint(ANSI.cyan, "\u279C")} ${paint(ANSI.bold, "Deploy to put this on your live site:")}`);
-    lines.push("   These are source changes. Your deployed site keeps serving its previous build,");
-    lines.push("   so visitors only get the widget after you deploy (or hit Publish) again.");
+  if (state.protectionApplicable && !state.protectionWired) {
+    const failing = state.protectionChecks.filter((item) => !item.ok && item.group !== "reporting");
+    const generic = state.protectionStack === "generic";
+    missing.push({
+      key: "runtime-protection",
+      text: generic ? "Runtime protection: not added to your server yet" : `Runtime protection: not finished for ${state.protectionStack}`,
+      hint: generic ? ["Add Patchstack where requests enter your app. Run npx @patchstack/connect protect for the steps."] : ["Run: npx @patchstack/connect protect, then npx @patchstack/connect protect --check"],
+      detail: failing.map((check) => `${check.label}${check.hint ? ` \u2014 ${check.hint}` : ""}`)
+    });
   }
-  const remaining = countRemainingSteps(state);
-  lines.push("");
-  if (remaining === 0) {
-    lines.push(
-      done(
-        paint(
-          ANSI.bold,
-          "Ready to deploy. Everything above is in the working tree only: commit .patchstackrc.json, package.json, the runtime guard changes, and the file carrying the widget snippet; add PATCHSTACK_API_KEY to the hosting platform; then deploy. Never commit .patchstackrc.local.json \u2014 it holds the API key, and setup has already added it to .gitignore."
-        )
-      )
-    );
-    if (state.claimUrl !== null) {
-      lines.push(detail("Until the site is attached to an account (dashboard link above, or `claim`), nobody can see its reports."));
-    }
-  } else {
-    lines.push(
-      ` ${paint(ANSI.yellow, String(remaining))} step(s) remaining \u2014 details in the reference guide below.`
+  const scripts = buildScriptLines(state);
+  if (scripts.length > 0) {
+    missing.push({
+      text: "Patchstack does not check your packages on install and build yet",
+      hint: ["Run: npx @patchstack/connect setup (it adds the build steps to package.json)"],
+      detail: [
+        state.packageManager === "bun" ? "Add to package.json scripts:" : "Add to package.json scripts (chain with && if one exists):",
+        ...scripts.map((line) => `  ${line}`)
+      ]
+    });
+  }
+  if (needsSourceProductionMarker(state) && !state.productionMarkerWired) {
+    const gate = productionGate(state.framework);
+    missing.push(
+      hasJsxShell(state.framework) ? {
+        text: "Your live app does not tell Patchstack it is live yet",
+        hint: [`Run: npx @patchstack/connect scan (it edits ${state.widgetFileHint})`],
+        detail: [`Or add inside <head>:`, ...buildSourceMarkerSnippet(state.framework).split("\n").map((line) => `  ${line}`)]
+      } : {
+        text: "Your live app does not tell Patchstack it is live yet",
+        hint: [
+          `Add this inside <head> in ${state.widgetFileHint}, only when ${gate}:`,
+          "  <script>window.__PATCHSTACK_PROD__=true;</script>"
+        ]
+      }
     );
   }
+  if (known.connected !== true) missing.push(notConnectedItem());
+  return missing;
+}
+function renderGuideChecklist(state, useColor2, known = {}, options = {}) {
+  const paint = (code, text) => useColor2 ? `${code}${text}${ANSI3.reset}` : text;
+  const name = state.projectName ?? path12.basename(process.cwd());
+  const title = `Patchstack status for ${name}`;
+  if (!state.hasPackageJson) {
+    return [
+      paint(ANSI3.bold, title),
+      "",
+      paint(ANSI3.bold, "Missing"),
+      ` ${paint(ANSI3.yellow, "\u2718")} No package.json here.`,
+      "   For a JS/Node app, run this from its package directory.",
+      '   For a plain HTML site, follow "Plain HTML sites" in AGENT-INSTALL.md. It gets the widget only: no dependency scan or runtime protection.',
+      "   Do not create a Node project just to add the widget.",
+      "   Use the site UUID or widget snippet from the Patchstack dashboard. Never invent one."
+    ].join("\n");
+  }
+  const lines = renderStatus(
+    title,
+    { done: [], missing: guideMissing(state, known) },
+    guideProgress(state, known),
+    guideNextStepContext(state),
+    { useColor: useColor2, verbose: options.verbose }
+  );
+  if (options.verbose === true) {
+    const verbose2 = [
+      `Project: ${[state.framework, state.packageManager].filter((part) => part !== null).join(" \xB7 ")}`,
+      ...state.siteUuid !== null ? [`Site UUID: ${state.siteUuid}`] : [],
+      ...state.environment !== null ? [`Environment: ${state.environment}${state.environmentSource !== null ? ` (${state.environmentSource})` : ""}`] : [],
+      ...state.endpointOverride !== null ? [`Endpoint override: ${state.endpointOverride}`] : [],
+      ...state.widgetOptOut ? ['Widget is off ("widget": false in .patchstackrc.json).'] : []
+    ];
+    lines.splice(1, 0, ...verbose2.map((line) => paint(ANSI3.dim, line)));
+  }
   return lines.join("\n");
 }
 
@@ -7494,14 +7592,16 @@ function requestMemberAccesses(params, body, ts, opts = {}) {
     const inner = unwrap(e);
     return Boolean(inner && ts.isCallExpression(inner) && ts.isPropertyAccessExpression(inner.expression) && ["json", "formData"].includes(inner.expression.name.text) && ts.isIdentifier(inner.expression.expression) && inner.expression.expression.text === reqName);
   };
+  const isCallee = (n) => Boolean(n.parent && (ts.isCallExpression(n.parent) || ts.isNewExpression(n.parent)) && n.parent.expression === n);
+  const ACCESSOR_SOURCES = /* @__PURE__ */ new Set(["header", "cookie", "form-body"]);
   const visit = (n) => {
-    if (ts.isPropertyAccessExpression(n) && isReqSourceExpr(n.expression)) {
+    if (ts.isPropertyAccessExpression(n) && isReqSourceExpr(n.expression) && !isCallee(n)) {
       record(n.name.text, sourceOfExpr(n.expression));
     }
     if (ts.isElementAccessExpression(n) && isReqSourceExpr(n.expression) && n.argumentExpression && ts.isStringLiteral(n.argumentExpression)) {
       record(n.argumentExpression.text, sourceOfExpr(n.expression));
     }
-    if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression) && n.expression.name.text === "get" && isReqSourceExpr(n.expression.expression) && n.arguments.length === 1 && n.arguments[0] && ts.isStringLiteral(n.arguments[0])) {
+    if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression) && n.expression.name.text === "get" && isReqSourceExpr(n.expression.expression) && n.arguments.length === 1 && n.arguments[0] && ts.isStringLiteral(n.arguments[0]) && ACCESSOR_SOURCES.has(sourceOfExpr(n.expression.expression))) {
       record(n.arguments[0].text, sourceOfExpr(n.expression.expression));
     }
     if (ts.isVariableDeclaration(n) && n.initializer) {
@@ -7553,6 +7653,7 @@ function requestMemberAccesses(params, body, ts, opts = {}) {
 
 // src/map/flows.ts
 var MAX_DEPENDENCY_INPUT_FLOWS_PER_ENDPOINT = 100;
+var ACCESSOR_NAMESPACES = /* @__PURE__ */ new Set(["headers", "cookies"]);
 function spaceOfKey(key) {
   if (key === "query") return "get";
   if (key === "params") return "route-param";
@@ -7578,18 +7679,18 @@ function linkFlows(bodyNode, params, inputs, sinks, ts, invocations) {
   }
   const CONTAINER_KEYS = /* @__PURE__ */ new Set([...REQ_SOURCES, "data", "input", "payload"]);
   const rootPath = /* @__PURE__ */ new Map();
-  const addRoot = (name, path17, space) => {
-    if (!rootPath.has(name)) rootPath.set(name, { path: path17, space });
+  const addRoot = (name, path17, space, accessor = false, request = false) => {
+    if (!rootPath.has(name)) rootPath.set(name, { path: path17, space, ...accessor ? { accessor } : {}, ...request ? { request } : {} });
   };
-  for (const p of params ?? []) {
+  for (const [index, p] of (params ?? []).entries()) {
     if (!p?.name) continue;
-    if (ts.isIdentifier(p.name)) addRoot(p.name.text, "");
+    if (ts.isIdentifier(p.name)) addRoot(p.name.text, "", void 0, false, index === 0);
     else if (ts.isObjectBindingPattern(p.name)) {
       for (const el of p.name.elements) {
         if (!ts.isBindingElement(el) || !ts.isIdentifier(el.name)) continue;
         const key = bindingKey(el, ts);
         const container = key !== void 0 && CONTAINER_KEYS.has(key);
-        addRoot(el.name.text, container ? "" : key ?? el.name.text, container ? spaceOfKey(key) : void 0);
+        addRoot(el.name.text, container ? "" : key ?? el.name.text, container ? spaceOfKey(key) : void 0, container && ACCESSOR_NAMESPACES.has(key));
       }
     }
   }
@@ -7601,7 +7702,8 @@ function linkFlows(bodyNode, params, inputs, sinks, ts, invocations) {
       const m = cur.expression.name.text;
       if (["json", "formData", "text"].includes(m)) {
         const root = rootIdentifier(cur.expression.expression, ts);
-        return root && rootPath.has(root) ? { path: "", space: "post" } : void 0;
+        if (!root || !rootPath.has(root)) return void 0;
+        return m === "formData" ? { path: "", space: "post", accessor: true } : { path: "", space: "post" };
       }
       if (["parse", "safeParse", "validate", "cast"].includes(m)) {
         for (const a of cur.arguments) {
@@ -7611,21 +7713,21 @@ function linkFlows(bodyNode, params, inputs, sinks, ts, invocations) {
         return void 0;
       }
     }
-    const p = pathFromTainted(cur, ts, rootPath);
-    return p;
+    return pathFromTainted(cur, ts, rootPath) ?? accessorRead(cur, ts, rootPath);
   };
   const aliasVisit = (n) => {
     if (ts.isVariableDeclaration(n) && n.initializer) {
       const base = requestReadPath(n.initializer);
       if (base !== void 0) {
-        if (ts.isIdentifier(n.name)) addRoot(n.name.text, base.path, base.space);
+        if (ts.isIdentifier(n.name)) addRoot(n.name.text, base.path, base.space, base.accessor === true);
         else if (ts.isObjectBindingPattern(n.name)) {
           for (const el of n.name.elements) {
             if (!ts.isBindingElement(el) || !ts.isIdentifier(el.name)) continue;
             const key = bindingKey(el, ts);
-            const space = base.space ?? (base.path === "" ? spaceOfKey(key) : void 0);
-            const container = base.path === "" && key !== void 0 && CONTAINER_KEYS.has(key);
-            addRoot(el.name.text, container ? "" : join22(base.path, key ?? el.name.text), space);
+            const namespace = base.request === true && key !== void 0 && REQ_SOURCES.includes(key);
+            const container = base.path === "" && key !== void 0 && CONTAINER_KEYS.has(key) && (namespace || !REQ_SOURCES.includes(key));
+            const space = base.space ?? (namespace ? spaceOfKey(key) : void 0);
+            addRoot(el.name.text, container ? "" : join22(base.path, key ?? el.name.text), space, namespace && ACCESSOR_NAMESPACES.has(key));
           }
         }
       }
@@ -7657,7 +7759,7 @@ function linkFlows(bodyNode, params, inputs, sinks, ts, invocations) {
         for (const a of args) for (const l of sinkArgumentLimitations(a, ts, rootPath)) sinkLimits.push(l);
         for (let i = 0; i < args.length; i++) {
           const role = argumentRoleOf(sink.kind, method, i, args.length);
-          const whole = pathFromTainted(args[i], ts, rootPath);
+          const whole = pathFromTainted(args[i], ts, rootPath) ?? accessorRead(args[i], ts, rootPath);
           for (const read2 of taintedReadPaths(args[i], ts, rootPath)) {
             const key = `${read2.space ?? "*"}:${read2.path}`;
             const exact = whole !== void 0 && whole.path === read2.path && whole.space === read2.space;
@@ -7819,6 +7921,18 @@ function taintedReadPaths(node, ts, rootPath, includeDeferredBodies = true) {
   const visit = (n) => {
     if (!n) return;
     if (!includeDeferredBodies && (ts.isArrowFunction(n) || ts.isFunctionExpression(n) || ts.isFunctionDeclaration(n))) return;
+    if (ts.isCallExpression(n)) {
+      const accessed = accessorRead(n, ts, rootPath);
+      if (accessed !== void 0) {
+        add(accessed);
+        return;
+      }
+      if (ts.isPropertyAccessExpression(n.expression)) {
+        visit(n.expression.expression);
+        for (const arg of n.arguments ?? []) visit(arg);
+        return;
+      }
+    }
     if (ts.isPropertyAccessExpression(n) || ts.isElementAccessExpression(n)) {
       const read2 = pathFromTainted(n, ts, rootPath);
       if (read2 !== void 0) {
@@ -7838,11 +7952,11 @@ function taintedReadPaths(node, ts, rootPath, includeDeferredBodies = true) {
 function sinkArgumentLimitations(node, ts, rootPath) {
   const out = [];
   const seen = /* @__PURE__ */ new Set();
-  const add = (kind, detail, n) => {
-    const key = `${kind}:${detail}`;
+  const add = (kind, detail2, n) => {
+    const key = `${kind}:${detail2}`;
     if (seen.has(key)) return;
     seen.add(key);
-    out.push({ kind, detail, line: lineOf(n) });
+    out.push({ kind, detail: detail2, line: lineOf(n) });
   };
   const text = (n) => {
     try {
@@ -7869,7 +7983,25 @@ function sinkArgumentLimitations(node, ts, rootPath) {
   visit(node);
   return out;
 }
-function pathFromTainted(node, ts, rootPath) {
+function accessorRead(node, ts, rootPath) {
+  let cur = node;
+  while (cur && (ts.isAwaitExpression(cur) || ts.isParenthesizedExpression(cur) || ts.isNonNullExpression(cur))) cur = cur.expression;
+  if (!cur || !ts.isCallExpression(cur) || !ts.isPropertyAccessExpression(cur.expression)) return void 0;
+  const [name] = cur.arguments;
+  if (cur.expression.name.text !== "get" || cur.arguments.length !== 1 || !name || !ts.isStringLiteralLike(name)) return void 0;
+  if (!isAccessor(cur.expression.expression, ts, rootPath)) return void 0;
+  return pathFromTainted(cur.expression.expression, ts, rootPath, [name.text]);
+}
+function isAccessor(node, ts, rootPath) {
+  let cur = node;
+  while (cur && (ts.isParenthesizedExpression(cur) || ts.isNonNullExpression(cur))) cur = cur.expression;
+  if (ts.isIdentifier(cur)) return rootPath.get(cur.text)?.accessor === true;
+  if (ts.isPropertyAccessExpression(cur) && ACCESSOR_NAMESPACES.has(cur.name.text) && ts.isIdentifier(cur.expression)) {
+    return rootPath.get(cur.expression.text)?.request === true;
+  }
+  return false;
+}
+function pathFromTainted(node, ts, rootPath, trailing = []) {
   const segs = [];
   let cur = node;
   for (; ; ) {
@@ -7893,12 +8025,14 @@ function pathFromTainted(node, ts, rootPath) {
   if (!cur || !ts.isIdentifier(cur)) return void 0;
   const base = rootPath.get(cur.text);
   if (base === void 0) return void 0;
+  segs.push(...trailing);
   let space = base.space;
-  if (base.path === "" && segs.length > 1 && REQ_SOURCES.includes(segs[0])) {
+  if (base.request === true && base.path === "" && segs.length > 1 && REQ_SOURCES.includes(segs[0])) {
     space = spaceOfKey(segs[0]) ?? space;
     segs.shift();
   }
-  return { path: normalizePath([base.path, ...segs].filter(Boolean).join(".")), space };
+  const request = base.request === true && segs.length === 0 ? { request: true } : {};
+  return { path: normalizePath([base.path, ...segs].filter(Boolean).join(".")), space, ...request };
 }
 
 // src/map/invocations.ts
@@ -8798,7 +8932,7 @@ function isPreBundleBuildHook(env = process.env) {
   return /^\s*patchstack-connect\s+scan(?:\s*(?:&&|;)|\s*$)/.test(env.npm_lifecycle_script ?? "");
 }
 function undeliveredReportLines(err, config, cwd) {
-  const lines = [`patchstack: manifest not reported \u2014 ${err.message}`];
+  const lines = [`patchstack: could not send the package list to Patchstack \u2014 ${err.message}`];
   if (err.code === "UNAUTHORIZED") {
     const hasCredential = typeof config.pulseAuth === "string" && config.pulseAuth.length > 0;
     if (hasCredential) {
@@ -8813,7 +8947,7 @@ function undeliveredReportLines(err, config, cwd) {
     }
   }
   lines.push(
-    "patchstack: continuing the build. Patchstack keeps the last manifest it accepted for this site until a scan that can report."
+    "patchstack: continuing the build. Patchstack keeps the last package list it received until a check gets through."
   );
   return lines;
 }
@@ -8964,9 +9098,9 @@ import path15 from "path";
 var SCAN_COMMAND = "patchstack-connect scan";
 var MARK_BUILD_COMMAND = "patchstack-connect mark-build";
 function setupProtection(cwd) {
-  const install = runProtect(cwd);
+  const { result: install, lines: log2 } = collectProtectLog(() => runProtect(cwd));
   const verification = runVerify(cwd);
-  return { install, verification };
+  return { install, verification, log: log2 };
 }
 function appendHook(existing, command) {
   if (existing === void 0 || existing.trim().length === 0) {
@@ -9059,7 +9193,7 @@ Usage:
                                                      If no UUID is configured, the server
                                                      provisions one and we persist it. After a
                                                      successful post it also adds/updates the
-                                                     disclosure-widget <script> tag in the root
+                                                     Patchstack Connector <script> tag in the root
                                                      HTML shell (index.html, public/index.html,
                                                      or src/app.html) \u2014 opt out with
                                                      "widget": false in .patchstackrc.json.
@@ -9168,6 +9302,8 @@ Usage:
 Global:
   --version               Print the installed version of this package and exit
   --help                  Print this help and exit
+  --verbose               Also print the technical detail: site ID, endpoint, checksum,
+                          environment and why, files written, installer steps
 
 Options (for scan, setup, status, and uninstall):
   --site-uuid <uuid>      Override the configured site UUID
@@ -9223,6 +9359,13 @@ Examples:
   npx @patchstack/connect demo-guide node-serialize
 `;
 var VALUE_FLAGS = /* @__PURE__ */ new Set(["site-uuid", "endpoint", "dir", "url", "out", "claim-token"]);
+var verbose = false;
+function detail(line) {
+  if (verbose) console.log(line);
+}
+function useColor() {
+  return process.stdout.isTTY === true && process.env.NO_COLOR === void 0;
+}
 function parseArgs(argv) {
   const args = argv.slice(2);
   const positional = [];
@@ -9281,7 +9424,7 @@ async function runInit(args) {
   const target = await writeConfigFile(process.cwd(), { siteUuid: uuid });
   console.log(`Wrote ${target}`);
   console.log("");
-  console.log("Next: run `npx @patchstack/connect scan` to send your first manifest.");
+  console.log("Next: run `npx @patchstack/connect scan`.");
   return 0;
 }
 async function runClaim(args) {
@@ -9303,7 +9446,7 @@ async function runClaim(args) {
     console.log(`    ${result2.dashboardUrl ?? buildClaimUrl(config.endpoint, siteUuid)}`);
     if (result2.credentialSaved === true) {
       const ignore = await secretFileIgnored(process.cwd());
-      console.log(`    A credential for this site was issued and saved to ${SECRET_CONFIG_FILENAME}.`);
+      console.log(`    Saved a new credential to ${SECRET_CONFIG_FILENAME}.`);
       console.log(gitignoreOutcomeLine(ignore));
     }
     console.log("");
@@ -9314,8 +9457,7 @@ async function runClaim(args) {
   Your code:  ${userCode}`);
     console.log(`  Claim at:   ${verificationUri}
 `);
-    console.log("  Open that link and sign in to Patchstack \u2014 or create an account \u2014 to attach");
-    console.log("  this site to it. Whoever approves becomes the site's owner.\n");
+    console.log("  Open the link and sign in (or sign up) to connect this site. Whoever approves owns it.\n");
   };
   if (args.flags.has("wait")) {
     const pending = readPendingClaim(siteUuid);
@@ -9359,8 +9501,7 @@ async function runClaim(args) {
       return 1;
     }
     prompt(started.pending.userCode, started.pending.verificationUri);
-    console.log("  Give that link to the user. When they confirm they have claimed the site, run");
-    console.log("  this same command again (or `claim --wait` to block until they do).\n");
+    console.log("  Give the link to the user. Once they approve, run this command again (or `claim --wait`).\n");
     return 0;
   }
   const result = await claim2(config, (userCode, verificationUri) => {
@@ -9390,8 +9531,7 @@ async function runLogin(args) {
     console.log(`
   \u2713 Credential restored and saved to ${SECRET_CONFIG_FILENAME}.`);
     console.log(gitignoreOutcomeLine(ignore));
-    console.log("    The previous credential no longer works. Update it anywhere else it was set:");
-    console.log("    CI secrets, hosting env vars, preview environments, other checkouts.\n");
+    console.log("    The old credential no longer works. Update it in CI, hosting and other checkouts.\n");
     return 0;
   };
   if (args.flags.has("wait")) {
@@ -9412,9 +9552,8 @@ async function runLogin(args) {
   Your code:  ${userCode}`);
     console.log(`  Approve at: ${verificationUri}
 `);
-    console.log("  Open that link and approve it as the site's owner. Approving issues a new");
-    console.log("  credential and stops the current one working \u2014 CI, deploys and any other");
-    console.log("  machine using it will need the new value.\n");
+    console.log("  Open the link and approve as the site's owner. This replaces the current credential,");
+    console.log("  so CI, deploys and other machines will need the new one.\n");
   };
   if (process.stdout.isTTY !== true) {
     const existing = config.siteUuid === null ? null : readPendingLogin(config.siteUuid);
@@ -9439,8 +9578,7 @@ async function runLogin(args) {
       return 1;
     }
     prompt(started.pending.userCode, started.pending.verificationUri);
-    console.log("  Give that link to the user. When they confirm they have approved it, run");
-    console.log("  this same command again (or `login --wait` to block until they do).\n");
+    console.log("  Give the link to the user. Once they approve, run this command again (or `login --wait`).\n");
     return 0;
   }
   const result = await login(config, (userCode, verificationUri) => {
@@ -9458,8 +9596,8 @@ var MAX_RETRY_TIMEOUT_MS = 18e4;
 async function postManifestAccepted(config, payload) {
   const { response, environmentUsed } = await postManifestWithEnvironmentFallback(config, payload);
   if (environmentUsed !== config.environment) {
-    console.warn(
-      `patchstack: this Patchstack API does not know the ${config.environment} label yet; the report was accepted as ${environmentUsed}, which also keeps it apart from production.`
+    detail(
+      `This Patchstack API does not know the ${config.environment} label yet; the report was accepted as ${environmentUsed}, which also keeps it apart from production.`
     );
   }
   return response;
@@ -9475,23 +9613,27 @@ async function postManifestWithPatience(config, payload) {
     if (!(err instanceof PatchstackError) || err.code !== "NETWORK_TIMEOUT") throw err;
     const timeoutMs = Math.min(config.timeoutMs * RETRY_TIMEOUT_FACTOR, MAX_RETRY_TIMEOUT_MS);
     if (timeoutMs <= config.timeoutMs) throw err;
-    console.warn(
-      `patchstack: the report timed out after ${config.timeoutMs}ms; trying once more with ${timeoutMs}ms.`
-    );
+    console.warn("Patchstack is slow to answer. Trying once more\u2026");
+    detail(`The report timed out after ${config.timeoutMs}ms; trying once more with ${timeoutMs}ms.`);
     const response = await postManifestAccepted({ ...config, timeoutMs }, payload);
     try {
       const target = await persistTimeout(process.cwd(), timeoutMs);
-      console.log(`Saved a ${timeoutMs}ms request timeout to ${target}, so builds inherit it.`);
+      detail(`Saved a ${timeoutMs}ms request timeout to ${target}, so builds inherit it.`);
     } catch {
-      console.warn(
-        `patchstack: could not save the timeout; set PATCHSTACK_TIMEOUT_MS=${timeoutMs} where builds run.`
-      );
+      console.warn(`Could not save the longer wait. Set PATCHSTACK_TIMEOUT_MS=${timeoutMs} where your builds run.`);
     }
     return response;
   }
 }
+function plural(count, one, many) {
+  return `${count} ${count === 1 ? one : many}`;
+}
 async function runScan(args, options = {}) {
   const dryRun = args.flags.get("dry-run") === true;
+  const say = (line) => {
+    if (verbose || dryRun) console.log(line);
+  };
+  const report = options.report ?? emptyReport();
   const config = await resolveCliConfig(args, {
     cliClaimToken: getStringFlag(args.flags, "claim-token"),
     // The one command that reports them, so the one command that resolves them.
@@ -9499,48 +9641,41 @@ async function runScan(args, options = {}) {
   });
   const manifest = await scanLockfile(process.cwd());
   for (const warning of manifest.warnings ?? []) {
-    console.warn(`patchstack: ${warning}`);
+    if (dryRun) console.warn(`patchstack: ${warning}`);
+    else report.missing.push({ text: warning });
   }
   const installPaths = args.flags.get("install-paths") === true;
   const { payload, stats } = buildWirePayload(manifest, { installPaths });
-  console.log(
-    `Found ${payload.packages.length} unique package versions across ${stats.uniqueNames} package names (${manifest.ecosystem} ecosystem).`
-  );
+  say(`Found ${payload.packages.length} package versions across ${stats.uniqueNames} packages (${manifest.ecosystem}).`);
   if (installPaths) {
     const located = payload.packages.filter((pkg) => pkg.paths !== void 0).length;
     console.log(
-      payload.installPathsComplete ? `Including each package's install location in the dependency tree (--install-paths), for all ${located}.` : `Including install locations (--install-paths), for ${located} of ${payload.packages.length} \u2014 this lockfile format does not record them for the rest, which will be reported as "not recorded" rather than "not installed there".`
+      payload.installPathsComplete ? `Including install locations (--install-paths) for all ${located}.` : `Including install locations (--install-paths) for ${located} of ${payload.packages.length}. This lockfile does not record the rest; they are sent as "not recorded".`
     );
   }
   if (config.environment === "local") {
-    console.log(
-      "Reporting from this machine as the local environment: the dashboard will show the app as configured, not deployed. A build on a platform this recognises reports production or sandbox on its own; on a platform it does not know, set PATCHSTACK_ENVIRONMENT=production for the build that goes live."
-    );
+    say("Environment: local (this machine). Set PATCHSTACK_ENVIRONMENT=production on a live build your host does not identify.");
   } else {
     const because = (config.environmentEvidence ?? []).length > 0 ? ` (${config.environmentEvidence.join("; ")})` : "";
-    console.log(`Reporting under the ${config.environment} environment${because}. Override with PATCHSTACK_ENVIRONMENT.`);
+    say(`Environment: ${config.environment}${because}.`);
   }
   if (config.endpoint !== DEFAULT_ENDPOINT) {
-    console.log(
-      `Using endpoint override: ${config.endpoint} (set via --endpoint, PATCHSTACK_ENDPOINT, or .patchstackrc.json).`
-    );
+    say(`Endpoint override: ${config.endpoint}`);
   }
   if (stats.duplicateNames.length > 0) {
     const sample = stats.duplicateNames.slice(0, 10).join(", ");
     const more = stats.duplicateNames.length > 10 ? `, +${stats.duplicateNames.length - 10} more` : "";
-    console.log(
-      `${stats.duplicateNames.length} package(s) appear at multiple versions: ${sample}${more}`
-    );
+    say(`${stats.duplicateNames.length} package(s) at more than one version: ${sample}${more}`);
   }
   const body = buildManifestBody(config, payload);
   if (typeof body.url === "string") {
-    console.log(`Reporting this app's address as ${body.url}.`);
+    say(`Reporting app address: ${body.url}`);
   }
   if (typeof body.name === "string") {
-    console.log(`Reporting this app's name as "${body.name}".`);
+    say(`Reporting app name: "${body.name}"`);
   }
   if (typeof config.claimToken === "string" && config.claimToken !== "") {
-    console.log("A claim token is set: the site will be connected to the Patchstack account that issued it.");
+    say("Claim token set. The site will join the Patchstack account that issued it.");
   }
   if (dryRun) {
     console.log("");
@@ -9559,15 +9694,15 @@ async function runScan(args, options = {}) {
   }
   if (isPreBundleBuildHook()) {
     const cleared = applyBuildStamp(process.cwd(), null);
-    if (cleared.kind === "cleared") console.log(`Removed the previous map binding from ${cleared.file}.`);
+    if (cleared.kind === "cleared") say(`Removed the previous map binding from ${cleared.file}.`);
   }
   const shellFramework = detectStack(payload.packages).framework;
   if (config.widget) {
-    reportSourceMarker(shellFramework, computeManifestChecksum(payload.packages));
+    reportSourceMarker(shellFramework, computeManifestChecksum(payload.packages), report);
   }
   const provisioning = config.siteUuid === null;
   if (provisioning) {
-    console.log("No site UUID configured \u2014 provisioning a new Patchstack site from this manifest\u2026");
+    say("No site yet. Creating one on Patchstack\u2026");
   }
   let response;
   try {
@@ -9577,113 +9712,147 @@ async function runScan(args, options = {}) {
     for (const line of undeliveredReportLines(err, config, process.cwd())) console.error(line);
     return 0;
   }
+  const checked = `Checked ${plural(stats.uniqueNames, "package", "packages")}`;
+  if (response.stored) {
+    report.done.unshift(checked);
+    say(`Stored manifest #${response.manifest_id} (checksum ${response.checksum}).`);
+  } else if (response.reason === "duplicate") {
+    report.done.unshift(checked, "No changes since the last check");
+  } else {
+    report.missing.push({
+      text: "Patchstack did not save this check",
+      hint: [response.message ?? "Run this again in a few minutes."],
+      detail: [`Server response: ${JSON.stringify(response)}`]
+    });
+  }
   if (provisioning && response.uuid !== void 0 && response.uuid.length > 0) {
     const target = await persistSiteUuid(process.cwd(), response.uuid);
-    console.log(`Provisioned site ${response.uuid}. Saved UUID to ${target}.`);
+    report.done.push("Added this project to Patchstack");
+    say(`Created site ${response.uuid}. Saved to ${target}.`);
   }
   if (typeof response.api_key === "string" && response.api_key.length > 0) {
     const hadCredentialInConfig = await credentialInCommittedConfig(process.cwd());
     const saved = await persistApiKey(process.cwd(), response.api_key);
-    console.log(`Saved API key to ${saved.path}. Do not commit it.`);
-    console.log(
-      saved.ignored ? "  Added to .gitignore." : `  NOT ignored by git \u2014 ${saved.reason ?? "unknown reason"}. Add \`${SECRET_CONFIG_FILENAME}\` to .gitignore yourself before committing.`
-    );
+    if (saved.ignored) {
+      report.done.push(`Saved the project's API key in ${SECRET_CONFIG_FILENAME}. Never commit this file`);
+      say(`Saved API key to ${saved.path} (git-ignored).`);
+    } else {
+      report.missing.push({
+        text: `${SECRET_CONFIG_FILENAME} holds your API key, and git does not ignore it`,
+        hint: [`Add ${SECRET_CONFIG_FILENAME} to .gitignore before you commit. Never commit this file.`],
+        detail: [`Saved to ${saved.path}. Not ignored: ${saved.reason ?? "unknown reason"}.`]
+      });
+    }
     if (hadCredentialInConfig) {
-      console.log(
-        "A credential was also present in .patchstackrc.json and has been removed from it. If that file was ever committed, rotate the credential from the dashboard."
-      );
+      report.missing.push({
+        text: "Your API key was in .patchstackrc.json",
+        hint: [
+          `It is now in ${SECRET_CONFIG_FILENAME}. If .patchstackrc.json was ever committed, replace the key in the Patchstack dashboard.`
+        ]
+      });
     }
   }
-  if (response.stored) {
-    console.log(`Stored manifest #${response.manifest_id} (checksum ${response.checksum}).`);
-  } else if (response.reason === "duplicate") {
-    console.log("Manifest unchanged since last scan \u2014 nothing to store.");
-  } else {
-    console.log(`Server response: ${response.message ?? JSON.stringify(response)}`);
-  }
-  const claimLines = claimOutcomeLines(response.claim, config);
-  if (claimLines.length > 0) {
-    console.log("");
-    for (const line of claimLines) console.log(line);
+  const claim3 = claimOutcome(response.claim, config);
+  if (claim3 !== null && claim3.connected) {
+    report.done.push(claim3.dashboardUrl !== null ? `${claim3.summary}: ${claim3.dashboardUrl}` : claim3.summary);
+  } else if (claim3 !== null) {
+    report.missing.push(notConnectedItem([`${claim3.summary}.`, ...claim3.hint]));
   }
   const connected = response.claim?.state === "claimed" || response.claim?.state === "owned-by-you";
   const effectiveUuid = config.siteUuid ?? response.uuid ?? null;
   if (config.widget && effectiveUuid !== null && effectiveUuid.length > 0) {
-    reportSourceWidget(effectiveUuid, shellFramework);
-  }
-  const linkUuid = response.uuid ?? config.siteUuid;
-  if (!connected && (provisioning || claimLines.length > 0) && linkUuid !== null && linkUuid !== void 0 && linkUuid.length > 0) {
-    console.log("");
-    console.log("Connect this site to your Patchstack account \u2014 any one of these:");
-    if (config.widget) {
-      console.log('  1. In the preview \u2014 the widget shows a "Connect this website" panel while the');
-      console.log("     site is unclaimed. Signing in there attaches it.");
-      console.log("  2. Open this dashboard link in a browser:");
-      console.log(`     ${buildClaimUrl(config.endpoint, linkUuid)}`);
-      console.log("  3. From this terminal: npx @patchstack/connect claim");
-    } else {
-      console.log("  1. Open this dashboard link in a browser:");
-      console.log(`     ${buildClaimUrl(config.endpoint, linkUuid)}`);
-      console.log("  2. From this terminal: npx @patchstack/connect claim");
-    }
-    if (config.endpoint !== DEFAULT_ENDPOINT) {
-      console.log("  (this URL inherits the endpoint override above)");
-    }
-  }
-  if (options.showRemainingSetup !== false) {
+    reportSourceWidget(effectiveUuid, shellFramework, report);
+  }
+  const synced = effectiveUuid !== null && effectiveUuid.length > 0 && (response.stored || response.reason === "duplicate");
+  const outcome = {
+    connected,
+    synced,
+    // Only the dashboard can see the live site; a production scan is reported, not confirmed.
+    deployed: false
+  };
+  options.onReported?.(outcome);
+  if (options.report === void 0) {
     try {
-      const state = await collectGuideState(process.cwd());
-      const remaining = countRemainingSteps(state);
-      if (remaining > 0) {
-        const hooksMissing = !(state.prebuildWired && state.postbuildWired);
-        console.log("");
-        console.log(
-          `Setup not complete \u2014 ${remaining} step(s) remaining${hooksMissing ? ", including the package.json build hooks (which scan can't wire)" : ""}.`
-        );
-        console.log("Run `npx @patchstack/connect guide` for the exact steps to finish for this project.");
-      }
+      await printScanReport(config, effectiveUuid, outcome, report, options.showRemainingSetup !== false);
     } catch {
     }
   }
   return 0;
 }
-function reportSourceWidget(siteUuid, framework) {
+function mergeMissing(...lists) {
+  const merged = [];
+  for (const item of lists.flat()) {
+    const key = item.key ?? item.text;
+    if (!merged.some((existing) => (existing.key ?? existing.text) === key)) merged.push(item);
+  }
+  return merged;
+}
+function scanNextStepContext(config, state, siteUuid) {
+  const uuid = siteUuid !== null && siteUuid.length > 0 ? siteUuid : state.siteUuid;
+  return {
+    ...guideNextStepContext(state),
+    environment: config.environment,
+    environmentSource: config.environmentSource,
+    siteUuid: uuid,
+    claimUrl: uuid !== null && config.endpointTrusted !== false ? buildClaimUrl(config.endpoint, uuid) : null
+  };
+}
+async function printScanReport(config, siteUuid, outcome, report, withProgress) {
+  const state = await collectGuideState(process.cwd());
+  const context = scanNextStepContext(config, state, siteUuid);
+  const progress = guideProgress(state, outcome);
+  if ((isInstallOrBuildHook() || runningInCi()) && !verbose) {
+    for (const item of report.missing) console.warn(`Patchstack: ${[item.text + ".", ...item.hint ?? []].join(" ")}`);
+    for (const line of renderHookSummary(report, progress, context)) console.log(line);
+    return;
+  }
+  if (verbose) console.log("");
+  const missing = mergeMissing(report.missing, withProgress ? guideMissing(state, outcome) : []);
+  for (const line of renderStatus("Patchstack scan", { done: report.done, missing }, progress, context, {
+    useColor: useColor(),
+    verbose,
+    withoutProgress: !withProgress
+  })) {
+    console.log(line);
+  }
+}
+function reportSourceWidget(siteUuid, framework, report) {
+  const handAdd = (why) => {
+    report.missing.push({
+      text: "The Patchstack widget is not on your page yet",
+      hint: [why, `  ${buildWidgetTag(siteUuid)}`]
+    });
+  };
   try {
     const hint = hasJsxShell(framework) ? resolveWidgetFileHint(process.cwd(), framework) : null;
     const jsxShell = hint !== null && !hint.toLowerCase().endsWith(".html") ? hint : null;
     const result = ensureSourceWidget(process.cwd(), siteUuid, jsxShell);
     switch (result.action) {
       case "added":
-        console.log(`Widget: added the disclosure widget tag to ${result.shell}. Reload your preview to see it.`);
-        console.log('  Unclaimed, it shows a "Connect this website" panel; the "Report a vulnerability" button replaces it once the site is claimed.');
+        report.done.push(`Added the Patchstack widget to ${result.shell}`);
         break;
       case "updated":
-        console.log(`Widget: updated the managed tag in ${result.shell} to site ${siteUuid}.`);
+        report.done.push(`Updated the Patchstack widget in ${result.shell}`);
         break;
       case "unchanged":
-        console.log(`Widget: already installed in ${result.shell}.`);
+        report.done.push(`The Patchstack widget is already in ${result.shell}`);
         break;
       case "manual":
-        console.log(`Widget: found an existing (manual) install in ${result.shell} \u2014 left untouched.`);
+        report.done.push(`Left your own Patchstack widget in ${result.shell} as it is`);
         break;
       case "no-body":
-        console.log(`Widget: ${result.shell} has no </body> tag to anchor on. Add this tag to your root layout manually:`);
-        console.log(`  ${buildWidgetTag(siteUuid)}`);
+        handAdd(`${result.shell} has no </body>. Add this to your main page layout, just before </body>:`);
         break;
       case "no-shell":
-        console.log("Widget: no root shell found to edit (index.html / public/index.html / src/app.html, or a JSX root).");
-        console.log("Add this tag to your root layout before </body> (run `guide` for framework-specific placement):");
-        console.log(`  ${buildWidgetTag(siteUuid)}`);
+        handAdd("Add this to your main page layout, just before </body>:");
         break;
     }
-    if (result.action === "added" || result.action === "updated") {
-      console.log('  (opt out any time with "widget": false in .patchstackrc.json)');
-    }
   } catch (err) {
-    console.warn(`Widget: skipped (${err.message}).`);
+    handAdd("Add this to your main page layout, just before </body>:");
+    detail(`Widget: skipped (${err.message}).`);
   }
 }
-function reportSourceMarker(framework, checksum = null) {
+function reportSourceMarker(framework, checksum, report) {
   try {
     const shell = resolveWidgetFileHint(process.cwd(), framework);
     if (shell === null || shell.toLowerCase().endsWith(".html")) {
@@ -9692,30 +9861,25 @@ function reportSourceMarker(framework, checksum = null) {
     const result = ensureSourceMarker(process.cwd(), shell, framework, checksum);
     switch (result.action) {
       case "added":
-        console.log(`Production marker: added to ${shell} (guarded by ${productionGate(framework)}).`);
-        console.log("  This root is server-rendered, so the marker ships in source rather than built HTML.");
+        report.done.push(`Set up ${shell} to tell Patchstack when it runs as your live app`);
+        detail(`Production marker: added to ${shell} (only set when ${productionGate(framework)}).`);
         break;
       case "manual":
-        console.log(`Production marker: already set in ${shell} \u2014 left untouched.`);
+        detail(`Production marker: already in ${shell}.`);
         break;
       case "no-anchor":
       case "unsupported":
-        console.log(
-          `Production marker: ${shell} needs it by hand \u2014 without it the widget reads the published site as build mode.`
-        );
-        if (hasJsxShell(framework)) {
-          for (const line of buildSourceMarkerSnippet(framework).split("\n")) {
-            console.log(`  ${line}`);
-          }
-        } else {
-          console.log(
-            `  Emit <script>window.__PATCHSTACK_PROD__=true;</script> only when ${productionGate(framework)}.`
-          );
-        }
+        report.missing.push({
+          text: "Your live app does not tell Patchstack it is live yet",
+          hint: hasJsxShell(framework) ? [`Add this inside <head> in ${shell}:`, ...buildSourceMarkerSnippet(framework).split("\n").map((line) => `  ${line}`)] : [
+            `Add this inside <head> in ${shell}, only when ${productionGate(framework)}:`,
+            "  <script>window.__PATCHSTACK_PROD__=true;</script>"
+          ]
+        });
         break;
     }
   } catch (err) {
-    console.warn(`Production marker: skipped (${err.message}).`);
+    detail(`Production marker: skipped (${err.message}).`);
   }
 }
 async function runProtectCommand(args) {
@@ -9855,8 +10019,7 @@ async function runGuide(args) {
   let allDone = false;
   try {
     const state = await collectGuideState(process.cwd());
-    const useColor = process.stdout.isTTY === true && process.env.NO_COLOR === void 0;
-    console.log(renderGuideChecklist(state, useColor));
+    console.log(renderGuideChecklist(state, useColor(), {}, { verbose }));
     allDone = countRemainingSteps(state) === 0;
   } catch {
   }
@@ -9874,96 +10037,85 @@ async function runGuide(args) {
   console.log(readFileSync19(guidePath, "utf8"));
   return 0;
 }
+function reportProtection(protection, report) {
+  for (const line of protection.log) detail(`patchstack protect: ${line}`);
+  if (protection.install.status === "not-applicable") {
+    report.done.push("Runtime protection is not needed: this project has no server");
+    if (protection.install.leftovers.length > 0) {
+      report.missing.push({
+        text: "Files from an earlier Patchstack protection setup are not used here",
+        hint: [`You can delete: ${protection.install.leftovers.join(", ")}`]
+      });
+    }
+    return;
+  }
+  if (protection.verification.wired) {
+    const changed = protection.install.status === "wired" && protection.install.changed.length > 0;
+    report.done.push(
+      changed ? `Added runtime protection (${protection.verification.stack})` : `Runtime protection is already set up (${protection.verification.stack})`
+    );
+    return;
+  }
+  if (protection.install.status === "scaffolded" && protection.install.plan.includes("Could not locate a server entry")) {
+    report.missing.push({
+      key: "runtime-protection",
+      text: "Runtime protection: no server file found",
+      hint: ["Add Patchstack where requests enter your app. Run npx @patchstack/connect protect for the steps."]
+    });
+  }
+}
+function buildStepsLine(wired) {
+  if (wired.strategy === "postinstall-only") {
+    return wired.changed ? "Added a package check after each install to package.json" : "The package check after each install is already in package.json";
+  }
+  return wired.changed ? "Added the build steps to package.json" : "The build steps are already in package.json";
+}
 async function runSetup(args) {
   if (args.flags.get("dry-run") === true) {
-    console.error("Error: setup does not support --dry-run. Use `scan --dry-run` to preview the manifest.");
+    console.error("Setup cannot run as a preview. To see what would be sent, run: npx @patchstack/connect scan --dry-run");
     return 1;
   }
   const before = await collectGuideState(process.cwd());
   if (!before.hasPackageJson) {
-    console.error("Error: no package.json found. Run setup from the project root.");
+    console.error("No package.json here. Run setup from the folder that has your package.json.");
     console.error("For a standalone HTML site, use the widget-only instructions in AGENT-INSTALL.md; do not create a Node project just to run setup.");
     return 1;
   }
   if (before.installed === null) {
     console.error(
-      `Error: @patchstack/connect is not declared in package.json.
+      `The Patchstack connector is not installed in this project yet.
 Run: ${installCommand(before.packageManager)}`
     );
     return 1;
   }
-  console.log("Patchstack setup \u2014 applying bounded project changes");
-  console.log("  1. Scan dependencies, provision/reuse the site, and manage the source widget");
-  const scanCode = await runScan(args, { showRemainingSetup: false });
+  const report = emptyReport();
+  let reported = {};
+  const scanCode = await runScan(args, {
+    report,
+    onReported: (outcome) => {
+      reported = outcome;
+    }
+  });
   if (scanCode !== 0) {
     return scanCode;
   }
-  console.log("");
-  console.log("  2. Install and verify runtime protection");
-  const protection = setupProtection(process.cwd());
-  if (protection.install.status === "not-applicable") {
-    console.log("Runtime protection: not applicable to this project \u2014 nothing installed.");
-    console.log(`  ${protection.install.reason}`);
-    if (protection.install.leftovers.length > 0) {
-      console.log("  An earlier run scaffolded a guard here before that was established. These files do");
-      console.log("  nothing on this project and can be deleted:");
-      for (const file of protection.install.leftovers) console.log(`    ${file}`);
-    }
-  } else if (protection.verification.wired) {
-    console.log(`Runtime protection: wired (${protection.verification.stack}).`);
-  } else {
-    console.log(`Runtime protection: manual wiring remains (${protection.verification.stack}):`);
-    for (const check of protection.verification.checks) {
-      console.log(`  ${check.ok ? "\u2713" : "\u2717"} ${check.label}${!check.ok && check.hint ? ` \u2014 ${check.hint}` : ""}`);
-    }
-    console.log("Run `npx @patchstack/connect protect --check` after completing the failed checks.");
-  }
-  console.log("");
-  console.log("  3. Wire dependency-install and production-build scans into package.json");
+  reportProtection(setupProtection(process.cwd()), report);
   const wired = wireBuildScripts(process.cwd(), before.packageManager);
-  console.log(`Build integration: ${wired.detail}`);
-  console.log("");
-  console.log("  4. Verify setup status");
+  report.done.push(buildStepsLine(wired));
+  detail(`Build hooks: ${wired.detail}`);
+  const config = await resolveCliConfig(args);
   const after = await collectGuideState(process.cwd());
-  const useColor = process.stdout.isTTY === true && process.env.NO_COLOR === void 0;
-  console.log(renderGuideChecklist(after, useColor));
-  const remaining = countRemainingSteps(after);
-  if (remaining > 0) {
-    console.log("");
-    console.log(`Setup applied its bounded changes; ${remaining} manual step(s) remain above.`);
+  const missing = mergeMissing(report.missing, guideMissing(after, reported));
+  const context = scanNextStepContext(config, after, after.siteUuid);
+  if (verbose) console.log("");
+  for (const line of renderStatus("Patchstack setup", { done: report.done, missing }, guideProgress(after, reported), context, {
+    useColor: useColor(),
+    verbose
+  })) {
+    console.log(line);
   }
-  const outcome = setupOutcome(after, protection, wired);
-  console.log("");
-  console.log("Outcome \u2014 relay this to the user as it is:");
-  for (const [label, value] of outcome) console.log(`  ${label}: ${value}`);
   return 0;
 }
-function setupOutcome(state, protection, wired) {
-  const remaining = countRemainingSteps(state);
-  const lines = [];
-  lines.push(["Status", remaining === 0 ? "Ready to deploy (configured locally; nothing is live yet)" : `Configured locally; ${remaining} step(s) still to finish (see the checklist above)`]);
-  lines.push(["Monitoring", "starts with the first build that runs on your hosting platform"]);
-  if (protection.install.status === "not-applicable") {
-    lines.push(["Runtime protection", "not applicable \u2014 this project has no request path (static build)"]);
-  } else if (protection.verification.wired) {
-    lines.push(["Runtime protection", `wired (${protection.verification.stack}) \u2014 local wiring verified; verify against the live site after deploy with \`protect --check --runtime\``]);
-  } else {
-    lines.push(["Runtime protection", `not wired yet (${protection.verification.stack}) \u2014 finish the checks above, then \`npx @patchstack/connect protect --check\``]);
-  }
-  lines.push(["Next steps", [
-    "add PATCHSTACK_API_KEY (from .patchstackrc.local.json) to your hosting platform's environment variables",
-    "commit .patchstackrc.json, package.json and the widget change (never .patchstackrc.local.json)",
-    'deploy, then check the site in the Patchstack dashboard \u2014 it reads "Deployed" once the live site is seen'
-  ].join("; ")]);
-  const warnings = [];
-  if (!wired.changed && wired.strategy === "postinstall-only") warnings.push("no build script, so only dependency installs are scanned");
-  if (protection.install.status === "not-applicable" && protection.install.leftovers.length > 0) {
-    warnings.push(`earlier guard scaffold does nothing here and can be deleted: ${protection.install.leftovers.join(", ")}`);
-  }
-  if (state.claimUrl !== null) warnings.push('the site is not attached to an account until someone signs in through the widget\'s "Connect this website" panel, the dashboard link is opened, or `npx @patchstack/connect claim` completes');
-  if (warnings.length > 0) lines.push(["Warnings", warnings.join("; ")]);
-  return lines;
-}
 async function runStatus(args) {
   const config = await resolveCliConfig(args);
   console.log(`Site UUID:   ${config.siteUuid ?? "(none yet \u2014 the next `scan` will provision one)"}`);
@@ -9974,24 +10126,14 @@ async function runStatus(args) {
   console.log(`Environment: ${config.environment}`);
   if (config.siteUuid !== null) {
     console.log(`Dashboard URL: ${buildClaimUrl(config.endpoint, config.siteUuid)}`);
-    console.log(`  Not attached to an account yet? Sign in through the widget's "Connect this`);
-    console.log('  website" panel on the preview, open the link above, or run');
-    console.log("  `npx @patchstack/connect claim`.");
+    console.log("  Not connected yet? Open the link above or run `npx @patchstack/connect claim`.");
     switch (await fetchSiteStatus(config)) {
       case "active":
         console.log("Site status:   active on Patchstack");
         break;
       case "removed":
         console.log("Site status:   removed from Patchstack");
-        console.log(
-          "  The site record no longer exists (deleted from the dashboard or via the"
-        );
-        console.log(
-          "  widget uninstall flow). The local integration files are still in this"
-        );
-        console.log(
-          '  project \u2014 see "Uninstalling" in AGENT-INSTALL.md to remove them.'
-        );
+        console.log('  The local files are still here. See "Uninstalling" in AGENT-INSTALL.md to remove them.');
         break;
       case "unknown":
         console.log("Site status:   could not be verified (Patchstack unreachable)");
@@ -10026,8 +10168,7 @@ async function runUninstall(args) {
       break;
   }
   console.log("");
-  console.log("This command only signals Patchstack. The local integration files must still be");
-  console.log('removed \u2014 follow the "Uninstalling" steps in AGENT-INSTALL.md.');
+  console.log('Local files are not touched. Remove them with the "Uninstalling" steps in AGENT-INSTALL.md.');
   return 0;
 }
 function describeStack(stack) {
@@ -10060,7 +10201,7 @@ async function reportBuildStamp(config, payload, marker) {
     await postManifestWithEnvironmentFallback(bounded, payload, marker);
   } catch (err) {
     console.warn(
-      `mark-build: this build was not reported to Patchstack (${err.message}). The pages were still marked as described above.`
+      `mark-build: could not tell Patchstack about this build (${err.message}). The pages were still marked.`
     );
   }
 }
@@ -10122,22 +10263,14 @@ async function runMarkBuild(args) {
   const files = findHtmlFiles(dir);
   if (files.length === 0) {
     console.warn(`mark-build: found ${dir} but no HTML files in it.`);
-    console.warn(
-      "mark-build: this build looks server-rendered, so the production flag has nothing to stamp."
-    );
-    console.warn(
-      "mark-build: add the marker to your root shell instead \u2014 run `patchstack-connect guide` for the snippet."
-    );
+    console.warn("mark-build: this looks like a server-rendered app. Run `npx @patchstack/connect guide` to see what your main layout needs.");
     await reportBuildStamp(reported, wirePayload, "no-pages");
     return 0;
   }
   const staleBy = staleBuildAge(files, startedAt);
   if (staleBy !== null) {
     console.warn(
-      `mark-build: nothing in ${dir} has been written in the last ${Math.round(staleBy / 6e4)} minute(s), so this looks like output from an earlier build.`
-    );
-    console.warn(
-      "mark-build: run it as a postbuild hook (or straight after the build) so what is stamped is what was just produced."
+      `mark-build: nothing in ${dir} changed in the last ${Math.round(staleBy / 6e4)} minute(s). Run it right after the build (as postbuild).`
     );
   }
   const snippet = published ? buildInjectionSnippet(checksum, stack) : "";
@@ -10160,7 +10293,8 @@ async function runMarkBuild(args) {
   }
   const stackSummary = stack !== null ? describeStack(stack) : null;
   if (published) {
-    console.log(
+    console.log(`Patchstack: marked ${plural(files.length, "page", "pages")} as your live app.`);
+    detail(
       `mark-build: marked ${marked} HTML file(s) in ${dir}${checksum !== null ? ` (build ${checksum})` : ""}${widgetTouched > 0 ? `, widget tag ensured in ${widgetTouched}` : ""}${stackSummary !== null ? ` [${stackSummary}]` : ""}.`
     );
     await reportBuildStamp(reported, wirePayload, "stamped");
@@ -10168,13 +10302,10 @@ async function runMarkBuild(args) {
   }
   const because = environmentEvidence.length > 0 ? ` (${environmentEvidence.join("; ")})` : "";
   console.log(
-    `mark-build: ${environment} build${because} \u2014 production marker withheld from ${files.length} HTML file(s) in ${dir}${widgetTouched > 0 ? `, widget tag ensured in ${widgetTouched}` : ""}${stackSummary !== null ? ` [${stackSummary}]` : ""}.`
-  );
-  console.log(
-    "mark-build: the marker tells Patchstack a page is the live site, so only the build that deploys carries it. Your hosting platform's build stamps it automatically."
+    `Patchstack: ${environment} build, so ${plural(files.length, "page is", "pages are")} not marked as your live app. Publishing this folder by hand? Run again with --production.`
   );
-  console.log(
-    "mark-build: publishing this directory by hand? Re-run with --production (or set PATCHSTACK_ENVIRONMENT=production) so the deployed pages carry it."
+  detail(
+    `mark-build: ${environment} build${because}, so no production marker in ${files.length} HTML file(s) in ${dir}${widgetTouched > 0 ? `, widget tag ensured in ${widgetTouched}` : ""}${stackSummary !== null ? ` [${stackSummary}]` : ""}.`
   );
   await reportBuildStamp(reported, wirePayload, "withheld");
   return 0;
@@ -10188,8 +10319,28 @@ function packageVersion() {
     return "unknown";
   }
 }
+function plainErrorMessage(err) {
+  switch (err.code) {
+    case "NETWORK_ERROR":
+      return "Could not reach Patchstack. Check your internet connection and try again.";
+    case "NETWORK_TIMEOUT":
+      return "Patchstack took too long to answer. Try again in a minute.";
+    case "SERVER_ERROR":
+      return "Patchstack could not handle the request right now. Try again in a few minutes.";
+    case "LOCKFILE_NOT_FOUND":
+      return "Could not find the list of installed packages. Install your packages first (for example npm install), then try again.";
+    case "LOCKFILE_PARSE_ERROR":
+    case "LOCKFILE_UNSUPPORTED":
+      return "Could not read the list of installed packages. Reinstall your packages (for example npm install), then try again.";
+    case "CONFIG_MISSING":
+      return "This project is not set up with Patchstack yet. Run npx @patchstack/connect setup first.";
+    default:
+      return null;
+  }
+}
 async function main() {
   const args = parseArgs(process.argv);
+  verbose = args.flags.get("verbose") === true;
   if (args.flags.has("version") || args.command === "version") {
     console.log(packageVersion());
     return 0;
@@ -10234,7 +10385,9 @@ async function main() {
 }
 main().then((code) => process.exit(code)).catch((err) => {
   if (err instanceof PatchstackError) {
-    console.error(`Error (${err.code}): ${err.message}`);
+    const plain = plainErrorMessage(err);
+    console.error(`${plain ?? err.message} (${err.code})`);
+    if (plain !== null && verbose) console.error(`Detail: ${err.message}`);
     process.exit(1);
   }
   console.error("Unexpected error:", err);