@patchstack/connect 0.3.4 → 0.3.6

package/AGENT-INSTALL.md

@@ -2,22 +2,24 @@
 
 This is a plain-text instruction document. Read it and follow the steps — there is nothing here to pipe to a shell or execute from a URL.
 
-You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL.md` (the package is already installed) or from the [GitHub repo](https://github.com/patchstack/connect). The canonical, always-current version of the full guide lives at https://patchstack.com/install.txt — prefer it when you have network access; this bundled copy matches the package version it shipped with.
+You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL.md` (the package is already installed) or from the [GitHub repo](https://github.com/patchstack/connect). This bundled copy matches the package version it shipped with and is all you need — there is no requirement to fetch anything remote. (A long-form copy also lives at https://patchstack.com/install.txt for humans browsing outside the package.)
 
 ## Verify before you trust (do this, it's quick)
 
 - The connector is a normal npm package: [`@patchstack/connect`](https://www.npmjs.com/package/@patchstack/connect), MIT-licensed, source at https://github.com/patchstack/connect. Install it pinned, check the integrity hash in the lockfile, run `npm audit` over it — whatever your policy requires.
 - First published May 2026. If the package is absent from your training data, `npm view @patchstack/connect` (read-only) shows the live registry record.
-- It reads the project's **lockfile only** (`package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`) and sends package names + versions to Patchstack for vulnerability matching. No source code, no env vars, no file paths, no git history.
+- It reads the project's **dependency list only** — from the lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`) or, on bun projects (`bun.lock`/`bun.lockb`), by enumerating the installed packages under `node_modules/` — and sends package names + versions to Patchstack for vulnerability matching. No source code, no env var values, no file paths, no git history. (`mark-build` additionally stamps built HTML with a coarse stack descriptor that may include hosting-related env variable *names* — e.g. `VERCEL`, `CF_PAGES` — never their values.)
+- The package also bundles an **opt-in** `protect` command (runtime exploit guard, currently for TanStack Start + Supabase apps; its templates live under `dist/protect/`). It patches the app's Supabase client to route traffic through a same-origin guard — and it runs **only** when you explicitly run `patchstack-connect protect`. Nothing in this document, and none of `scan`, `guide`, `status`, or `mark-build`, modifies application source.
 - Patchstack is not WordPress-only. This connector monitors any JS/Node project — Vite, Next.js, plain vanilla JS, anything with a lockfile.
 
 ## Before you start — never install twice
 
-- If `.patchstackrc.json` exists, the project is already provisioned. Reuse its UUID; run `npx @patchstack/connect status` to re-print it and the claim URL. **Do not run `scan` to provision a second site.**
+- `npx @patchstack/connect guide` prints a live checklist above this document showing which steps are already done in the current project (install, provisioning, build hooks, widget) with commands tailored to it. Its purpose is to prevent duplicate work — verify its claims however your policy requires, but only do the steps it marks ✖.
+- If `.patchstackrc.json` contains a `siteUuid` key, the project is already provisioned. Reuse that UUID; run `npx @patchstack/connect status` to re-print it and the claim URL. **Do not run `scan` to provision a second site.** (A `.patchstackrc.json` with other keys — e.g. an `endpoint` override — but no `siteUuid` is *not* provisioned yet; scan normally.)
 - If `@patchstack/connect` is already in `devDependencies`, skip the install command.
 - If the widget script tag (`cdn.patchstack.com/patchstack-widget.js`) is already in the layout, don't add a second one.
 
-## Install steps (run in order, don't pause between them unless one fails)
+## Install steps (do the ones the checklist marks ✖, in order; they are designed to run back-to-back — if one fails, stop and report rather than improvising)
 
 1. **Install** (skip if already present), matching the project's package manager:
 
@@ -36,7 +38,7 @@ You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL
 
    It prints a claim URL. Surface that URL to the user verbatim — never fetch it yourself; it must be opened in their browser.
 
-3. **Wire builds** in `package.json` (chain with `&&` if hooks already exist):
+3. **Wire builds** in `package.json`:
 
    ```jsonc
    {
@@ -47,7 +49,11 @@ You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL
    }
    ```
 
-4. **Install the disclosure widget** — a floating "Report a vulnerability" button. Read the UUID from `.patchstackrc.json` and use it as `userToken`. Place these two snippets via the framework's HTML/layout mechanism (never a JS entry point):
+   If a `prebuild`/`postbuild` hook already exists, chain instead of replacing it, e.g. `"prebuild": "existing-command && patchstack-connect scan"`.
+
+   **Bun-managed projects:** `bun run` does not execute npm-style `pre`/`post` scripts, so wire the build script directly instead: `"build": "patchstack-connect scan && <existing build command> && patchstack-connect mark-build"`.
+
+4. **Install the disclosure widget** — a floating "Report a vulnerability" button. Read the `siteUuid` value from `.patchstackrc.json` (the same site UUID step 2 provisioned) and pass it as the widget's `userToken`. Place these two snippets via the framework's HTML/layout mechanism (never a JS entry point):
 
    ```html
    <script src="https://cdn.patchstack.com/patchstack-widget.js"></script>
@@ -58,7 +64,7 @@ You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL
 
    Framework-specific placement patterns: https://cdn.patchstack.com/llm.html. The `userToken` is public by design — it ships in client-side HTML and is not a secret.
 
-5. **Commit** `.patchstackrc.json` and the updated `package.json` so every developer and CI run reports to the same site.
+5. **Commit** `.patchstackrc.json`, the updated `package.json`, and the layout/HTML file carrying the widget snippet, so every developer and CI run reports to the same site.
 
 6. **Tell the user to claim the site** (free): open the claim URL from step 2 in a browser and sign in. The site is monitored either way, but the vulnerability reports are only visible after claiming. They can also claim directly from the widget's "Connect this website" prompt. On the published site, the owner reaches the widget login by appending `#patchstack` to the live URL.
 

package/README.md

@@ -6,22 +6,13 @@ For how this repo fits with the wider Patchstack ecosystem (`saas`, `hub`, `patc
 
 ## Install prompt (for AI coding tools)
 
-Copy and paste this prompt into any AI coding assistant (Cursor, v0, Bolt, Lovable, Claude Code, etc.):
+Copy and paste this prompt into any AI coding assistant (Cursor, v0, Bolt, Lovable, Claude Code, etc.). If the assistant declines or stops partway, the step-by-step flow in [`GETTING-STARTED.md`](https://github.com/patchstack/connect/blob/main/GETTING-STARTED.md) covers what to do next:
 
-> Add Patchstack dependency vulnerability monitoring to this project:
->
-> 1. `npm install --save-dev @patchstack/connect` — or the pnpm/yarn/bun equivalent (MIT, source: https://github.com/patchstack/connect; verify with `npm view @patchstack/connect` if unsure).
-> 2. `npx @patchstack/connect scan` — saves a site ID to `.patchstackrc.json` and prints a claim URL. Show me that URL; don't open it.
-> 3. Add `package.json` scripts `"prebuild": "patchstack-connect scan"` and `"postbuild": "patchstack-connect mark-build"`, then commit the changes.
-> 4. Run `npx @patchstack/connect guide` and use it to add the report-a-vulnerability widget and finish any framework-specific details.
+> Add Patchstack dependency vulnerability monitoring: install `@patchstack/connect` as a dev dependency (MIT — verify with `npm view @patchstack/connect`; source: https://github.com/patchstack/connect), run `npx @patchstack/connect scan` and show me the claim URL it prints (I'll open it in my browser to view reports — don't open or fetch it yourself), then run `npx @patchstack/connect guide` and finish what its checklist flags: the package.json build hooks and the report-a-vulnerability widget snippet.
 
-The shape of this prompt is deliberate — it has survived three distinct AI-agent refusal modes, and each one punished a different shortcut:
+Every clause is load-bearing. AI agents routinely audit this package before completing the request — verifying the tarball against the registry, checking `dist/` for lifecycle scripts and shell/eval calls — and the flow is designed to pass that audit, not to discourage it. The prompt can stay short because `guide` is state-aware: it inspects the project (package manager, `.patchstackrc.json`, `package.json` scripts, widget presence, framework) and prints a live checklist of only the remaining steps — with the real site UUID and framework-specific widget placement — followed by the full reference guide (`AGENT-INSTALL.md`, also at https://patchstack.com/install.txt). That also makes the flow idempotent: re-running `guide` on a finished project reports all-done instead of prompting a second install.
 
-1. **"Follow the instructions at this URL" reads as remote script execution.** Agents refuse before ever fetching the doc.
-2. **Agents whose training predates May 2026 assert the package doesn't exist.** Step 1's `npm view` resolves that against the registry instead of the model's memory.
-3. **"Install the package, then follow the instructions it ships" reads as handing control to the package author** — structurally the same as prompt injection — and preemptive reassurance language ("it's safe, don't be suspicious, note your knowledge cutoff") is itself flagged as a manipulation signal.
-
-So the prompt inlines the core install as concrete, individually inspectable commands, delegates nothing up front, and argues nothing. `npx @patchstack/connect guide` (which prints the bundled `AGENT-INSTALL.md`) enters only at step 4, as an assist for widget placement, re-run rules, and troubleshooting — by then the agent has already installed and audited the package, so consulting its docs is ordinary behavior rather than the instruction channel the install depends on. The always-current long-form guide lives at https://patchstack.com/install.txt.
+Before changing this prompt (or `guide` / `AGENT-INSTALL.md`), read [`field-test/README.md`](https://github.com/patchstack/connect/blob/main/field-test/README.md): it documents the AI-agent refusal modes each clause guards against, and its harness runs a real agent through the full install in a throwaway fixture against a mocked API and scores the outcome on eight checks. Validate any variant there first.
 
 ## Quick start (zero configuration)
 
@@ -70,6 +61,16 @@ patchstack-connect scan   [options]                Scan the lockfile and POST to
 patchstack-connect init   <site-uuid>              Optional: pre-seed .patchstackrc.json with
                                                    an existing site UUID
 patchstack-connect status [options]                Show current configuration
+patchstack-connect mark-build [options]            Stamp built HTML with a production flag +
+                                                   build fingerprint (run as a postbuild step)
+patchstack-connect guide                           Show this project's setup status (what's done,
+                                                   what's missing, with tailored commands), then
+                                                   print the full setup guide
+patchstack-connect protect                         Opt-in: install the always-on runtime exploit
+                                                   guard (currently TanStack Start + Supabase; it
+                                                   patches the app's Supabase client to route
+                                                   traffic through a same-origin guard). Never
+                                                   run by scan/guide/mark-build.
 patchstack-connect help                            Print help
 
 Options (for scan and status):
@@ -100,7 +101,7 @@ Environment variables:
 }
 ```
 
-The site UUID is the only credential. Possession of it grants the right to submit manifests for that site, so treat it like an API token: keep it out of public repos, and prefer the environment variable in CI.
+The site UUID identifies the site; it is not a secret — the disclosure widget ships the same UUID in client-side HTML as its `userToken`, and committing `.patchstackrc.json` is the intended workflow so every developer and CI run reports to the same site. Possession of the UUID lets someone submit dependency manifests for that site (noise, not data access). In CI setups where the file isn't committed, set `PATCHSTACK_SITE_UUID` instead.
 
 ## Programmatic API
 
@@ -126,7 +127,7 @@ Lower-level pieces are also exported: `scanLockfile`, `buildWirePayload`, `postM
 }
 ```
 
-That's the entire payload. No source code, no environment variables, no file paths — just the package names and versions from your lockfile. Duplicate names with different versions are preserved so transitive vulnerabilities aren't missed.
+That's the entire payload. No source code, no environment variable values, no file paths — just the package names and versions from your lockfile. Duplicate names with different versions are preserved so transitive vulnerabilities aren't missed. (`mark-build` separately stamps built HTML with a stack descriptor that may include hosting-related env variable *names* — e.g. `VERCEL` — never their values.)
 
 ## Supported lockfiles
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
 
 // src/parsers/index.ts
 import { access } from "fs/promises";
@@ -1250,14 +1250,351 @@ function injectMarker(html, snippet) {
   return stripped + snippet;
 }
 
+// src/guide.ts
+import { existsSync as existsSync2, readFileSync, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import path8 from "path";
+var WIDGET_SCRIPT_URL = "https://cdn.patchstack.com/patchstack-widget.js";
+var WIDGET_NEEDLE = "patchstack-widget";
+var INSTALL_COMMANDS = {
+  npm: "npm install --save-dev @patchstack/connect",
+  pnpm: "pnpm add -D @patchstack/connect",
+  yarn: "yarn add -D @patchstack/connect",
+  bun: "bun add -d @patchstack/connect"
+};
+var PM_BY_LOCKFILE = [
+  { filename: "package-lock.json", pm: "npm" },
+  { filename: "bun.lock", pm: "bun" },
+  { filename: "bun.lockb", pm: "bun" },
+  { filename: "pnpm-lock.yaml", pm: "pnpm" },
+  { filename: "yarn.lock", pm: "yarn" }
+];
+var WIDGET_FILE_CANDIDATES = {
+  next: [
+    "app/layout.tsx",
+    "app/layout.jsx",
+    "src/app/layout.tsx",
+    "src/app/layout.jsx",
+    "pages/_document.tsx",
+    "pages/_document.jsx",
+    "src/pages/_document.tsx"
+  ],
+  nuxt: ["app.vue", "src/app.vue", "app/app.vue"],
+  remix: ["app/root.tsx", "app/root.jsx"],
+  "react-router": ["app/root.tsx", "src/root.tsx"],
+  "tanstack-start": ["src/routes/__root.tsx", "app/routes/__root.tsx"],
+  sveltekit: ["src/app.html"],
+  astro: ["src/layouts/Layout.astro"],
+  gatsby: ["src/html.js"]
+};
+var GENERIC_WIDGET_FILES = ["index.html", "public/index.html"];
+var SKIPPED_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  ".output",
+  ".next",
+  ".nuxt",
+  ".svelte-kit",
+  ".vercel",
+  ".netlify",
+  "coverage",
+  "vendor"
+]);
+var WIDGET_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".html",
+  ".htm",
+  ".tsx",
+  ".jsx",
+  ".ts",
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".vue",
+  ".svelte",
+  ".astro",
+  ".ejs",
+  ".hbs"
+]);
+var WIDGET_SCAN_MAX_FILES = 4e3;
+var WIDGET_SCAN_MAX_DEPTH = 6;
+var WIDGET_SCAN_MAX_BYTES = 512 * 1024;
+function detectPackageManager(cwd) {
+  for (const { filename, pm } of PM_BY_LOCKFILE) {
+    if (existsSync2(path8.join(cwd, filename))) {
+      return pm;
+    }
+  }
+  return "npm";
+}
+function installCommand(pm) {
+  return INSTALL_COMMANDS[pm];
+}
+function readPackageJson(cwd) {
+  try {
+    return JSON.parse(readFileSync(path8.join(cwd, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function installedVersion(cwd, declaredRange) {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(path8.join(cwd, "node_modules", "@patchstack", "connect", "package.json"), "utf8")
+    );
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+  }
+  return declaredRange;
+}
+function findWidgetMarker(cwd, siteUuid) {
+  let budget = WIDGET_SCAN_MAX_FILES;
+  let sawWidget = false;
+  let sawTokenMatch = false;
+  const settled = () => sawTokenMatch || sawWidget && siteUuid == null;
+  const walk2 = (dir, depth) => {
+    if (depth > WIDGET_SCAN_MAX_DEPTH || budget <= 0) {
+      return;
+    }
+    let entries;
+    try {
+      entries = readdirSync2(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (budget <= 0 || settled()) {
+        return;
+      }
+      const full = path8.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIPPED_DIRS.has(entry.name) || entry.name.startsWith(".")) {
+          continue;
+        }
+        walk2(full, depth + 1);
+        continue;
+      }
+      if (!entry.isFile() || !WIDGET_EXTENSIONS.has(path8.extname(entry.name).toLowerCase())) {
+        continue;
+      }
+      budget -= 1;
+      try {
+        if (statSync2(full).size > WIDGET_SCAN_MAX_BYTES) {
+          continue;
+        }
+        const content = readFileSync(full, "utf8");
+        if (!content.includes(WIDGET_NEEDLE)) {
+          continue;
+        }
+        sawWidget = true;
+        if (siteUuid != null && content.includes(siteUuid)) {
+          sawTokenMatch = true;
+        }
+      } catch {
+      }
+    }
+  };
+  walk2(cwd, 0);
+  return {
+    found: sawWidget,
+    uuidMatches: sawWidget && siteUuid != null ? sawTokenMatch : null
+  };
+}
+function resolveWidgetFileHint(cwd, framework) {
+  const candidates = [
+    ...framework !== null ? WIDGET_FILE_CANDIDATES[framework] ?? [] : [],
+    ...GENERIC_WIDGET_FILES
+  ];
+  for (const candidate of candidates) {
+    if (existsSync2(path8.join(cwd, candidate))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+async function collectGuideState(cwd) {
+  const pkg = readPackageJson(cwd);
+  const packageManager = detectPackageManager(cwd);
+  let installed = null;
+  if (pkg?.devDependencies?.["@patchstack/connect"] !== void 0) {
+    installed = {
+      version: installedVersion(cwd, pkg.devDependencies["@patchstack/connect"]),
+      section: "devDependencies"
+    };
+  } else if (pkg?.dependencies?.["@patchstack/connect"] !== void 0) {
+    installed = {
+      version: installedVersion(cwd, pkg.dependencies["@patchstack/connect"]),
+      section: "dependencies"
+    };
+  }
+  let siteUuid = null;
+  let claimUrl = null;
+  let endpointOverride = null;
+  try {
+    const config = await resolveConfig({ cwd });
+    siteUuid = config.siteUuid;
+    if (siteUuid !== null) {
+      claimUrl = buildClaimUrl(config.endpoint, siteUuid);
+    }
+    if (config.endpoint !== DEFAULT_ENDPOINT) {
+      endpointOverride = config.endpoint;
+    }
+  } catch {
+  }
+  const declaredNames = Object.keys({ ...pkg?.dependencies, ...pkg?.devDependencies });
+  const stack = detectStack(
+    declaredNames.map((name) => ({ name, version: "" })),
+    {}
+  );
+  const widget = findWidgetMarker(cwd, siteUuid);
+  return {
+    projectName: pkg?.name ?? null,
+    hasPackageJson: pkg !== null,
+    packageManager,
+    installed,
+    siteUuid,
+    claimUrl,
+    endpointOverride,
+    // bun run doesn't execute npm-style pre/post scripts, so chaining inside
+    // the build script itself also counts as wired (and is what we suggest on bun).
+    prebuildWired: (pkg?.scripts?.prebuild ?? "").includes("patchstack-connect scan") || (pkg?.scripts?.build ?? "").includes("patchstack-connect scan"),
+    postbuildWired: (pkg?.scripts?.postbuild ?? "").includes("patchstack-connect mark-build") || (pkg?.scripts?.build ?? "").includes("patchstack-connect mark-build"),
+    widgetInstalled: widget.found,
+    widgetTokenMatches: widget.uuidMatches,
+    framework: stack.framework,
+    widgetFileHint: resolveWidgetFileHint(cwd, stack.framework)
+  };
+}
+var ANSI = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  cyan: "\x1B[36m"
+};
+function countRemainingSteps(state) {
+  return [
+    state.installed !== null,
+    state.siteUuid !== null,
+    state.prebuildWired && state.postbuildWired,
+    state.widgetInstalled && state.widgetTokenMatches !== false
+  ].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)}`;
+  const lines = [];
+  const headerParts = [state.framework, state.packageManager].filter(
+    (part) => part !== null
+  );
+  const name = state.projectName ?? path8.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("Run the guide from the project root."));
+    return lines.join("\n");
+  }
+  if (state.installed !== null) {
+    lines.push(done(`@patchstack/connect installed (${state.installed.version}, ${state.installed.section})`));
+  } else {
+    lines.push(todo("Install @patchstack/connect as a dev dependency"));
+    lines.push(detail(`\u2192 ${installCommand(state.packageManager)}`));
+    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("\u2192 npx @patchstack/connect scan"));
+    lines.push(detail("Reads the lockfile, registers the project, writes .patchstackrc.json,"));
+    lines.push(detail("and prints a claim URL \u2014 show that URL to the user; never open it yourself."));
+  }
+  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 builds \u2014 chain into the package.json build script (bun skips pre/post hooks)"));
+    lines.push(detail('\u2192 "build": "patchstack-connect scan && <existing build command> && patchstack-connect mark-build"'));
+  } else {
+    lines.push(todo("Wire builds \u2014 add to package.json scripts (chain with && if a hook exists)"));
+    if (!state.prebuildWired) {
+      lines.push(detail('\u2192 "prebuild": "patchstack-connect scan"'));
+    }
+    if (!state.postbuildWired) {
+      lines.push(detail('\u2192 "postbuild": "patchstack-connect mark-build"'));
+    }
+  }
+  const widgetOk = state.widgetInstalled && state.widgetTokenMatches !== false;
+  if (widgetOk) {
+    lines.push(done("Disclosure widget installed"));
+  } else if (state.widgetInstalled) {
+    lines.push(todo("Disclosure widget found, but its userToken doesn't match this project's site UUID"));
+    lines.push(detail(`\u2192 a wrong userToken makes the widget silently no-op; set it to '${state.siteUuid}'`));
+  } else {
+    lines.push(todo('Add the "Report a vulnerability" widget'));
+    const placement = state.widgetFileHint !== null ? `\u2192 add to ${state.widgetFileHint}, just before </body> (via the framework's HTML/layout mechanism):` : "\u2192 add just before </body> via the framework's HTML/layout mechanism (never a JS entry point):";
+    lines.push(detail(placement));
+    lines.push(detail(`  <script src="${WIDGET_SCRIPT_URL}"></script>`));
+    const token = state.siteUuid ?? "<SITE_UUID from .patchstackrc.json \u2014 run scan first>";
+    lines.push(detail(`  <script>PatchstackWidget.init({ userToken: '${token}' });</script>`));
+    lines.push(detail("The userToken is public by design \u2014 it ships in client-side HTML."));
+  }
+  lines.push("");
+  if (state.claimUrl !== null) {
+    lines.push(` ${paint(ANSI.cyan, "\u279C")} ${paint(ANSI.bold, "Claim the site (free, opens the dashboard):")}`);
+    lines.push(`   ${paint(ANSI.cyan, state.claimUrl)}`);
+    lines.push(detail("Open in a browser. AI agents: show this URL to the user verbatim."));
+    if (state.endpointOverride !== null) {
+      lines.push(detail("(this URL inherits the endpoint override above)"));
+    }
+  } else {
+    lines.push(detail("The claim URL appears after the first scan (re-print any time with `status`)."));
+  }
+  const remaining = countRemainingSteps(state);
+  lines.push("");
+  if (remaining === 0) {
+    lines.push(
+      done(
+        paint(
+          ANSI.bold,
+          "All setup steps complete. Commit .patchstackrc.json, package.json, and the file carrying the widget snippet."
+        )
+      )
+    );
+    if (state.claimUrl !== null) {
+      lines.push(detail("The only manual action left is claiming the site via the URL above (if not already claimed)."));
+    }
+  } else {
+    lines.push(
+      ` ${paint(ANSI.yellow, String(remaining))} step(s) remaining \u2014 details in the reference guide below.`
+    );
+  }
+  return lines.join("\n");
+}
+
 // src/protect/install.ts
-import { readFileSync, writeFileSync, existsSync as existsSync2, mkdirSync, copyFileSync } from "fs";
+import { readFileSync as readFileSync2, writeFileSync, existsSync as existsSync3, mkdirSync, copyFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 var TEMPLATES = join(dirname(fileURLToPath(import.meta.url)), "protect", "templates");
 var APP = process.cwd();
 var PS_DIR = join(APP, "src/integrations/patchstack");
-var read = (p) => readFileSync(p, "utf8");
+var read = (p) => readFileSync2(p, "utf8");
 var log = (msg) => console.log(`patchstack protect: ${msg}`);
 var CLIENT_TUNNEL = [
   "",
@@ -1302,10 +1639,10 @@ var FUNCTION_MIDDLEWARE_DEF = [
 ].join("\n");
 function detectSupportedStack(cwd) {
   const pkgPath = join(cwd, "package.json");
-  if (!existsSync2(pkgPath)) return false;
+  if (!existsSync3(pkgPath)) return false;
   const pkg = JSON.parse(read(pkgPath));
   const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-  return Boolean(deps["@tanstack/react-start"]) && existsSync2(join(cwd, "src/start.ts")) && existsSync2(join(cwd, "src/integrations/supabase/client.ts"));
+  return Boolean(deps["@tanstack/react-start"]) && existsSync3(join(cwd, "src/start.ts")) && existsSync3(join(cwd, "src/integrations/supabase/client.ts"));
 }
 function scaffold(cwd) {
   const dst = join(cwd, "src/integrations/patchstack");
@@ -1388,8 +1725,11 @@ Usage:
   patchstack-connect protect                         Install always-on runtime protection (the
                                                      guard) into a TanStack Start + Supabase app.
                                                      Covers the browser + server-function paths.
-  patchstack-connect guide                           Print the full setup guide for AI coding
-                                                     agents (also at https://patchstack.com/install.txt)
+  patchstack-connect guide [--full]                  Show this project's setup status (what's done,
+                                                     what's missing, with tailored commands), then
+                                                     print the full setup guide. --full prints the
+                                                     guide even when setup is complete
+                                                     (also at https://patchstack.com/install.txt)
   patchstack-connect help                            Print this message
 
 Options (for scan and status):
@@ -1480,14 +1820,22 @@ async function runScan(args) {
   }
   const { payload, stats } = buildWirePayload(manifest);
   console.log(
-    `Found ${payload.packages.length} unique package versions across ${stats.uniqueNames} package names in ${manifest.ecosystem} lockfile.`
+    `Found ${payload.packages.length} unique package versions across ${stats.uniqueNames} package names (${manifest.ecosystem} ecosystem).`
+  );
+  console.log(
+    `Reporting under the ${config.environment} environment (override with PATCHSTACK_ENVIRONMENT).`
   );
-  console.log(`Reporting under the ${config.environment} environment.`);
+  if (config.endpoint !== DEFAULT_ENDPOINT) {
+    console.log(
+      `Using endpoint override: ${config.endpoint} (set via --endpoint, PATCHSTACK_ENDPOINT, or .patchstackrc.json).`
+    );
+  }
   if (stats.duplicateNames.length > 0) {
-    console.log(`${stats.duplicateNames.length} package(s) appear at multiple versions:`);
-    if (stats.duplicateNames.length <= 10) {
-      console.log(`  ${stats.duplicateNames.join(", ")}`);
-    }
+    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}`
+    );
   }
   if (dryRun) {
     console.log("");
@@ -1524,6 +1872,9 @@ async function runScan(args) {
     console.log("");
     console.log("Claim this site to view vulnerability reports in your Patchstack dashboard:");
     console.log(`  ${buildClaimUrl(config.endpoint, response.uuid)}`);
+    if (config.endpoint !== DEFAULT_ENDPOINT) {
+      console.log("  (this URL inherits the endpoint override above)");
+    }
   }
   return 0;
 }
@@ -1535,9 +1886,27 @@ async function runProtectCommand(_args) {
   }
   return 0;
 }
-async function runGuide() {
+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));
+    allDone = countRemainingSteps(state) === 0;
+  } catch {
+  }
+  if (allDone && args.flags.get("full") !== true) {
+    console.log("");
+    console.log(
+      "Full reference guide: `npx @patchstack/connect guide --full` (or read node_modules/@patchstack/connect/AGENT-INSTALL.md)."
+    );
+    return 0;
+  }
+  console.log("");
+  console.log("\u2014\u2014\u2014\u2014 Full reference guide (ships as AGENT-INSTALL.md) \u2014\u2014\u2014\u2014");
+  console.log("");
   const guidePath = new URL("../AGENT-INSTALL.md", import.meta.url);
-  console.log(readFileSync2(guidePath, "utf8"));
+  console.log(readFileSync3(guidePath, "utf8"));
   return 0;
 }
 async function runStatus(args) {
@@ -1547,7 +1916,9 @@ async function runStatus(args) {
     cliEndpoint: getStringFlag(args.flags, "endpoint")
   });
   console.log(`Site UUID:   ${config.siteUuid ?? "(none yet \u2014 the next `scan` will provision one)"}`);
-  console.log(`Endpoint:    ${config.endpoint}`);
+  console.log(
+    `Endpoint:    ${config.endpoint}${config.endpoint === DEFAULT_ENDPOINT ? "" : " (override)"}`
+  );
   console.log(`Timeout:     ${config.timeoutMs}ms`);
   console.log(`Environment: ${config.environment}`);
   if (config.siteUuid !== null) {
@@ -1596,7 +1967,7 @@ async function runMarkBuild(args) {
   const snippet = buildInjectionSnippet(checksum, stack);
   let marked = 0;
   for (const file of files) {
-    const before = readFileSync2(file, "utf8");
+    const before = readFileSync3(file, "utf8");
     const after = injectMarker(before, snippet);
     if (after !== before) {
       writeFileSync2(file, after);
@@ -1627,7 +1998,7 @@ async function main() {
     case "protect":
       return runProtectCommand(args);
     case "guide":
-      return runGuide();
+      return runGuide(args);
     default:
       console.error(`Unknown command: ${args.command}
 `);