@patchstack/connect 0.5.10 → 0.5.11

package/AGENT-INSTALL.md

@@ -2,6 +2,26 @@
 
 This versioned reference ships inside `@patchstack/connect` and documents each setup command and its project changes.
 
+## Choose the project path first
+
+Use the package setup flow below for an existing JS/Node application. Work in its package directory; a missing `package.json` can mean you are in a subdirectory or looking at generated HTML rather than the source project. A page containing HTML can still belong to a server-rendered application. Do not infer that runtime protection is unnecessary from the file extension alone.
+
+### Plain HTML sites
+
+For a standalone site made of HTML, CSS, and browser JavaScript, with no package-managed application or server request handler, use the disclosure widget directly. Do not create `package.json`, install a framework, invent build hooks, or add a server just to run Connect. `setup` requires an existing `package.json`; it is not a standalone HTML installer.
+
+1. Use the public site UUID or widget snippet for the correct site in the Patchstack dashboard. An existing `.patchstackrc.json` can also supply `siteUuid`. If neither is available, ask the user for the site's public UUID or dashboard-provided snippet before editing the page. Never invent a UUID or use a claim token or API key as the widget identifier.
+2. Add one widget tag before `</body>` in the page or shared layout. Preserve an existing correct tag. For a page published directly without a build step, disable the widget's build-mode onboarding with `data-build-mode="false"`:
+
+   ```html
+   <script src="https://cdn.patchstack.com/patchstack-widget.js" data-site-uuid="YOUR_SITE_UUID" data-build-mode="false" defer></script>
+   ```
+
+   Replace `YOUR_SITE_UUID` with the real public site UUID before saving. Keep credentials out of the page. The [public widget reference](https://cdn.patchstack.com/llm.html) documents this embed and its options.
+3. Verify the saved tag uses the correct UUID. If a browser preview is available, reload it and check for the report button; otherwise tell the user that the browser check is pending. Do not submit a vulnerability report as an installation test. Save the HTML change and remind the user to publish it when ready; do not deploy it yourself.
+
+Report this as **disclosure widget installed**, with any remaining preview or publishing step. This path does not inventory local JavaScript files or scripts loaded from a CDN, scan npm dependencies, or install runtime exploit protection. External APIs used by the page require their own server-side integration.
+
 ## Command reference
 
 Every command at a glance — what it does, whether it reads your source, what it writes, and what leaves your machine. Full behavior, flags, and edge cases follow in the sections below.
@@ -88,7 +108,7 @@ This is a request, not a mechanism: nothing in the install depends on it. Do it
 
    **If the request you were given includes a claim token**, pass it exactly as given: `npx @patchstack/connect setup --claim-token <token>`. The site is then created in the person's own Patchstack account and `setup` prints their dashboard link for it — there is no sign-in step to relay. The token comes only from the person's Patchstack dashboard; never invent one, never write it to a file, never print it back. If `setup` reports that the token had expired or was not recognised, the site is not connected: hand over the dashboard link it prints instead, and tell the person they can copy a fresh prompt from the dashboard.
 
-   In a hosted builder, run setup with `PATCHSTACK_ENVIRONMENT=sandbox` scoped to the workspace process/command, ensure the CLI's on-disk edits are adopted into the platform's persisted project state, then restart any already-running preview/server process so it loads the guard. Do not persist `"environment": "sandbox"` in `.patchstackrc.json`: deployed builds use the same committed files and report `production` only when the build platform's own variables say so — its tier (Vercel, Netlify, Render, Railway, GitLab CI) or a branch named `main`, `master`, `production`, `prod`, `release` or `live` (Cloudflare Pages and Workers Builds, AWS Amplify, GitHub Actions, GitLab CI without a tier); a preview, pull request or other branch there reports `sandbox`, as does the Replit workspace, while a Replit Deployment reports `production`. A build in a project the builder generated and builds for itself (Lovable, Replit) reports `production` without an override, because the edit preview is a dev server and a build is the publish step — which is exactly why the sandbox label belongs in the workspace process and not in a file. A scan on a developer's machine, in a CI runner this does not know (`CI=true` alone), or on a platform with no such signal reports `local` on its own, and the dashboard shows that app as configured, not deployed. A client-only SPA or a static site generator has no server request path to guard: `setup` says runtime protection does not apply and installs nothing for it; never call such a project protected.
+   In a hosted builder, run setup with `PATCHSTACK_ENVIRONMENT=sandbox` scoped to the workspace process/command, ensure the CLI's on-disk edits are adopted into the platform's persisted project state, then restart any already-running preview/server process so it loads the guard. Do not persist `"environment": "sandbox"` in `.patchstackrc.json`: deployed builds use the same committed files and report `production` only when the build platform's own variables say so — its tier (Vercel, Netlify, Render, Railway, GitLab CI) or a branch named `main`, `master`, `production`, `prod`, `release` or `live` (Cloudflare Pages and Workers Builds, AWS Amplify, GitHub Actions, GitLab CI without a tier); a preview, pull request or other branch there reports `sandbox`, as does the Replit workspace, while a Replit Deployment reports `production`. A build in a project the builder generated and builds for itself (Lovable, Replit) reports `production` without an override, because the edit preview is a dev server and a build is the publish step — which is exactly why the sandbox label belongs in the workspace process and not in a file. A scan on a developer's machine, in a CI runner this does not know (`CI=true` alone), or on a platform with no such signal reports `local` on its own, and the dashboard shows that app as configured, not deployed. A positively identified static build reports runtime protection as not applicable. A bundler-only project, including plain Vite, can remain runtime unknown and receive a generic scaffold with incomplete wiring. Report that limitation; do not add an artificial server merely to make the check pass, and never describe a widget or an unwired scaffold as runtime protection.
 
    **Finish by telling the user to refresh their preview.** The widget's "Report a vulnerability" button loads with the page, so a preview that was already open still shows the HTML from before setup — the button is missing there until it reloads. Nothing in the CLI can reach the user's browser, so relaying this is your job. Phrase it as a check rather than a required step: a builder that hot reloads, or a preview server you restarted, may have refreshed it already.
 
@@ -180,7 +200,7 @@ Handle it in this order:
 
    **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"`.
 
-3. **Verify the disclosure widget** — a floating "Report a vulnerability" button. `scan` installs it automatically into a plain HTML shell **or a JSX root** (Next, Remix, React Router, TanStack Start, Gatsby), and `mark-build` carries it into built HTML. Only when `scan` reported that it found no editable shell at all — a root whose head mechanism is not a plain script tag, e.g. Nuxt's `useHead` or an Astro layout — add the one-liner it printed to the root layout yourself, just before `</body>` (never a JS entry point), reading `siteUuid` from `.patchstackrc.json`. On those same roots the widget also needs the production marker above the tag — `scan` adds it automatically to a JSX root, and prints it to paste when it finds no anchor. A server-rendered site without the marker serves the build-mode claim flow to its visitors:
+3. **Verify the disclosure widget** — a floating control whose form follows the site's claim state: while the site is unclaimed it is a one-time "Connect this website" panel, and it becomes the public "Report a vulnerability" button once the site is claimed. Do not tell the user the report button will appear on a site that has not been connected to an account yet. `scan` installs it automatically into a plain HTML shell **or a JSX root** (Next, Remix, React Router, TanStack Start, Gatsby), and `mark-build` carries it into built HTML. Only when `scan` reported that it found no editable shell at all — a root whose head mechanism is not a plain script tag, e.g. Nuxt's `useHead` or an Astro layout — add the one-liner it printed to the root layout yourself, just before `</body>` (never a JS entry point), reading `siteUuid` from `.patchstackrc.json`. On those same roots the widget also needs the production marker above the tag — `scan` adds it automatically to a JSX root, and prints it to paste when it finds no anchor. A server-rendered site without the marker serves the build-mode claim flow to its visitors:
 
    ```html
    <script src="https://cdn.patchstack.com/patchstack-widget.js" data-site-uuid="<SITE_UUID>" defer></script>
@@ -248,7 +268,11 @@ It is server-only. Never put it in the widget tag, client bundles, or public env
 
    **Do not commit `.patchstackrc.local.json`.** That file holds the API key issued at provision; the scan writes it and adds it to `.gitignore`, and tells you if it could not. `.patchstackrc.json` holds only the site UUID and settings, and the UUID is public by design — it ships in the widget tag in served HTML.
 
-6. **Open the dashboard link** from the scan in a browser and sign in. The site is monitored either way, but the vulnerability reports are only visible after connecting it to an account. The same connection flow is available 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.
+6. **Connect the site to a Patchstack account.** The site is monitored either way, but its vulnerability reports are only visible once it is attached to an account, and an unattached site stays claimable by anyone who loads the page — the site UUID ships in the HTML and claiming is first-come. Three routes reach the same place; tell the user all three and lead with the first, which needs no terminal and no copied URL:
+
+   1. **The widget's "Connect this website" panel**, already on the preview. While the site is unclaimed the widget serves this panel *instead of* the report button, and signing in there attaches the site. On a published build it is hidden from visitors; the owner reveals it by appending `#patchstack` (or `?patchstack`) to the live URL.
+   2. **The dashboard link** the scan printed — open it in a browser and sign in.
+   3. **`npx @patchstack/connect claim`** from the terminal, which prints a link to sign in with and then attaches the site.
 
 ## Rules
 

package/README.md

@@ -1,10 +1,17 @@
 # @patchstack/connect
 
-Connect a JavaScript / Node.js application to [Patchstack](https://patchstack.com) for continuous vulnerability monitoring. Scans your `package-lock.json` and reports installed packages so Patchstack can match them against its vulnerability database and notify you when something needs patching.
+Connect a JavaScript / Node.js application to [Patchstack](https://patchstack.com). Connect does four things:
+
+- **Dependency inventory** — reads your lockfile and reports the installed package names and versions, so Patchstack can match them against its vulnerability database and tell you when something needs patching. See *[What gets sent](#what-gets-sent)*.
+- **Runtime guard** — an in-process guard, wired into your server, that virtually patches known vulnerabilities in those dependencies rather than waiting for you to upgrade. See *[Verifying the guard at runtime](#verifying-the-guard-at-runtime-opt-in)*.
+- **Disclosure widget** — a floating button labelled **"Report a vulnerability"** that Connect adds to *your* site, so visitors who spot a security problem have somewhere to send it. This is a channel for reports about your site; it is not how you report a bug in this package. See *[The disclosure widget](#the-disclosure-widget)*.
+- **Attack-surface map** — a description of your server's entry points and the sinks they can reach, built by reading your source locally. See *[`map`](#cli)*.
+
+`setup` installs the first three in one command. `map` is never run for you — see the [CLI](#cli) section for what each command does and what it touches.
 
 ## Agent-assisted setup
 
-Copy this request into a coding assistant, or run the same command yourself:
+For an existing JS/Node project, copy this request into a coding assistant, or run the same command yourself. For a standalone HTML/CSS/JavaScript site without a package-managed app, use the [plain HTML widget instructions](AGENT-INSTALL.md#plain-html-sites); do not add Node tooling just for the widget.
 
 > I have vetted the official [`@patchstack/connect`](https://www.npmjs.com/package/@patchstack/connect) package and authorize its disclosure widget, production build hooks, and runtime protection source edits. Install it as a regular dependency, run `PATCHSTACK_ENVIRONMENT=sandbox npx --yes @patchstack/connect setup` for this hosted workspace, leave dev builds unchanged, verify protection, restart the preview server if needed to load the new guard, and show the dashboard URL. Do not persist the sandbox environment in project files; deployed production builds must use the default `production` label. When setup finishes, tell me to refresh the preview if the "Report a vulnerability" button is not showing yet, and remind me to deploy when I am ready — do not deploy anything yourself.
 
@@ -446,55 +453,27 @@ Every scanned source is validated against `package.json`: if the chosen lockfile
 ## Development
 
 ```bash
-npm install
+npm ci
 npm run typecheck
+npm run build      # before the tests: several only run once dist/ exists, and skip silently without it
 npm test
-npm run build
-```
-
-### Manifest endpoint testing
-
-To post the current lockfile manifest to a local Patchstack API endpoint and provision a new site:
-
-```bash
-bun run test:manifest -- --endpoint http://localhost:8000/monitor/pulse/manifest
 ```
 
-The response should include the new site UUID. To re-test an existing site, pass that UUID explicitly:
-
-```bash
-bun run test:manifest -- --endpoint http://localhost:8000/monitor/pulse/manifest --site-uuid YOUR_REAL_UUID
-```
-
-Use `--dry-run` to preview the payload without posting.
+`CONTRIBUTING.md` covers the rest — the Node versions this needs, the packaging checks, and what to run before opening a pull request. Changing onboarding, the install prompt or the setup guide? Read `MAINTAINING.md` first.
 
 ## Release process
 
 Pull requests run typecheck, tests, build, package verification, and a production dependency audit in GitHub Actions.
 
-Publishing runs when a GitHub Release is published. The release tag must match the package version in `package.json` with a leading `v`. For example, `package.json` version `0.2.0` must be released with tag `v0.2.0`; otherwise the workflow fails before publishing.
-
-To publish a release:
+Releases are cut by the `Release` workflow, which works out the next version, tags it, and hands off to `Publish`:
 
-1. Bump the package version, for example `npm version 0.2.0 --no-git-tag-version`.
-2. Commit `package.json` and `package-lock.json`.
-3. Merge the version bump to `main`.
-4. Create and publish a GitHub Release tagged `v0.2.0`.
-5. The `Publish` workflow verifies the package, then runs `npm publish --provenance --access public`.
-
-Before the first release, configure npm trusted publishing for this package:
+```bash
+gh workflow run Release -f bump=patch   # or: minor, major
+```
 
-1. Merge `.github/workflows/publish.yml` to `main`.
-2. Open the `@patchstack/connect` package settings on npmjs.com.
-3. In **Trusted publishing**, choose **GitHub Actions**.
-4. Configure:
-   - Organization/user: `patchstack`
-   - Repository: `connect`
-   - Workflow filename: `publish.yml`
-   - Environment name: `npm`
-5. In GitHub repository settings, create an `npm` environment. Optional but recommended: require reviewer approval for that environment.
+The git tag is the source of truth for the published version. `Publish` reads the version out of the tag, writes it into `package.json` in CI, then builds and publishes to npm with provenance — so you do **not** bump `package.json` before releasing. After publishing it opens a pull request bringing the committed manifest up to the version that just went out; merge that.
 
-Do not add an npm publish token to GitHub secrets for this workflow. Trusted publishing uses GitHub OIDC short-lived credentials. After the first trusted publish succeeds, npm recommends setting package publishing access to require two-factor authentication and disallow tokens.
+`RELEASING.md` has the details: how to pick the bump (a compatibility break on a `0.x` version needs at least a minor), the manual fallback, and the npm trusted-publishing configuration.
 
 ## License
 

package/dist/cli.js

@@ -3082,7 +3082,7 @@ function ensureSourceMarker(cwd, shell, framework, checksum = null) {
 }
 
 // src/guide.ts
-import { existsSync as existsSync13, readFileSync as readFileSync11, readdirSync as readdirSync5, statSync as statSync5 } from "fs";
+import { existsSync as existsSync12, readFileSync as readFileSync11, readdirSync as readdirSync5, statSync as statSync5 } from "fs";
 import path12 from "path";
 
 // src/architecture.ts
@@ -4311,7 +4311,7 @@ var nuxtAdapter = {
 };
 
 // src/protect/install/find-app.ts
-import { readFileSync as readFileSync8, existsSync as existsSync7, readdirSync as readdirSync3, lstatSync as lstatSync2 } from "fs";
+import { readFileSync as readFileSync8, readdirSync as readdirSync3, lstatSync as lstatSync2 } from "fs";
 import { join as join11, relative as relative3, dirname as dirname4 } from "path";
 var SKIP_DIRS2 = /* @__PURE__ */ new Set([
   "node_modules",
@@ -4333,7 +4333,6 @@ var SKIP_DIRS2 = /* @__PURE__ */ new Set([
 ]);
 var MAX_DEPTH = 8;
 function findAppInstance(cwd, re) {
-  const root = existsSync7(join11(cwd, "src")) ? join11(cwd, "src") : cwd;
   const found = [];
   const walk2 = (dir, depth) => {
     if (depth > MAX_DEPTH) return;
@@ -4372,7 +4371,7 @@ function findAppInstance(cwd, re) {
       }
     }
   };
-  walk2(root, 0);
+  walk2(cwd, 0);
   if (found.length === 0) return null;
   const declared = declaredEntries(cwd);
   const chosen = found.slice().sort((a, b) => rankEntry({ ...a, declared: declared.has(a.relPath) }, { ...b, declared: declared.has(b.relPath) }))[0];
@@ -4430,16 +4429,16 @@ function importSpecifier(fromRel, toRel, preserveExtension = false) {
 }
 
 // src/protect/install/register.ts
-import { existsSync as existsSync10 } from "fs";
+import { existsSync as existsSync9 } from "fs";
 import { join as join14, resolve as resolve3 } from "path";
 
 // src/protect/install/generic.ts
-import { readFileSync as readFileSync9, existsSync as existsSync9, readdirSync as readdirSync4, lstatSync as lstatSync3 } from "fs";
+import { readFileSync as readFileSync9, existsSync as existsSync8, readdirSync as readdirSync4, lstatSync as lstatSync3 } from "fs";
 import { join as join13, dirname as dirname6 } from "path";
 
 // src/protect/install/source-scope.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync8 } from "fs";
+import { existsSync as existsSync7 } from "fs";
 import { dirname as dirname5, join as join12, resolve as resolve2 } from "path";
 
 // src/protect/install/node-flags.ts
@@ -4731,7 +4730,7 @@ function moduleKindOf(filePath, packageIsModule) {
 function resolvesToGuardModule(specifier, query) {
   const resolved = resolve2(dirname5(query.fromFile), specifier);
   if (withoutModuleExtension(resolved) !== join12(query.guardDir, "guard")) return false;
-  const existing = GUARD_FILENAMES.filter((name) => existsSync8(join12(query.guardDir, name)));
+  const existing = GUARD_FILENAMES.filter((name) => existsSync7(join12(query.guardDir, name)));
   if (existing.length === 0) return false;
   const extension = /(\.[A-Za-z0-9]+)$/.exec(specifier)?.[1] ?? "";
   if (!query.strictExtensions) return true;
@@ -4740,7 +4739,7 @@ function resolvesToGuardModule(specifier, query) {
     if (query.kind === "cjs") return existing.includes("guard.js");
     return true;
   }
-  if (existsSync8(resolved)) return true;
+  if (existsSync7(resolved)) return true;
   return query.kind === "ts" && extension === ".js" && existing.includes("guard.ts");
 }
 function withoutModuleExtension(filePath) {
@@ -4756,10 +4755,10 @@ function packageIsEsm(cwd) {
   }
 }
 function genericDir(cwd) {
-  return existsSync9(join13(cwd, "src")) ? "src/patchstack" : "patchstack";
+  return existsSync8(join13(cwd, "src")) ? "src/patchstack" : "patchstack";
 }
 function hasTypeScript(cwd) {
-  return existsSync9(join13(cwd, "tsconfig.json")) || candidateEntries(cwd).some((entry) => /\.tsx?$/.test(entry));
+  return existsSync8(join13(cwd, "tsconfig.json")) || candidateEntries(cwd).some((entry) => /\.tsx?$/.test(entry));
 }
 function genericGuardTarget(cwd) {
   if (hasTypeScript(cwd)) {
@@ -4773,7 +4772,7 @@ function genericGuardTarget(cwd) {
 function genericScaffoldFiles(cwd) {
   const dir = genericDir(cwd);
   const candidates = ["guard.ts", "guard.js", "guard.cjs", "rules.json"];
-  return candidates.map((file) => `${dir}/${file}`).filter((relative8) => existsSync9(join13(cwd, relative8)));
+  return candidates.map((file) => `${dir}/${file}`).filter((relative8) => existsSync8(join13(cwd, relative8)));
 }
 function scaffoldGeneric(cwd, opts, guardTemplate, guardFile) {
   const target = genericGuardTarget(cwd);
@@ -4788,7 +4787,7 @@ function scaffoldGeneric(cwd, opts, guardTemplate, guardFile) {
   const changed = [guardRel];
   if (!opts.demo) bakeSiteUuid(cwd, guardRel);
   const rulesDst = join13(dst, "rules.json");
-  if (opts.demo || !existsSync9(rulesDst)) {
+  if (opts.demo || !existsSync8(rulesDst)) {
     copyProjectFileSync(cwd, join13(templates, opts.demo ? "demo-rules.json" : "rules.json"), rulesDst);
     changed.push(`${dir}/rules.json`);
   }
@@ -4810,10 +4809,10 @@ function candidateEntries(cwd) {
     "app.ts",
     "app.js"
   ];
-  const hits = names.filter((n) => existsSync9(join13(cwd, n)));
+  const hits = names.filter((n) => existsSync8(join13(cwd, n)));
   try {
     const pkg = JSON.parse(read(join13(cwd, "package.json")));
-    if (typeof pkg.main === "string" && existsSync9(join13(cwd, pkg.main))) hits.push(pkg.main);
+    if (typeof pkg.main === "string" && existsSync8(join13(cwd, pkg.main))) hits.push(pkg.main);
   } catch {
   }
   return [...new Set(hits)];
@@ -4924,7 +4923,7 @@ function escapeForRegExp(value) {
 function genericVerify(cwd) {
   const dir = genericDir(cwd);
   const target = genericGuardTarget(cwd);
-  const present2 = GUARD_FILENAMES.find((name) => existsSync9(join13(cwd, dir, name)));
+  const present2 = GUARD_FILENAMES.find((name) => existsSync8(join13(cwd, dir, name)));
   const scaffolded = present2 !== void 0;
   const imported = scaffolded && guardIsImported(cwd, join13(cwd, dir, present2));
   return {
@@ -4962,7 +4961,7 @@ var NON_RUNTIME_DIRS = /* @__PURE__ */ new Set([
 function guardIsImported(cwd, guardPath) {
   const guardDir = dirname6(guardPath);
   const packageIsModule = packageIsEsm(cwd);
-  const root = existsSync9(join13(cwd, "src")) ? join13(cwd, "src") : cwd;
+  const root = existsSync8(join13(cwd, "src")) ? join13(cwd, "src") : cwd;
   let found = false;
   const walk2 = (d, depth) => {
     if (found || depth > 8) return;
@@ -5166,10 +5165,10 @@ function serverIsGuarded(cwd, spec, server, guardDir) {
   return !spec.callAfter || routesBefore(source, server.appVar, state.callIndex).length === 0;
 }
 function verifyRegister(cwd, spec) {
-  const dir = existsSync10(join14(cwd, "src")) ? "src/patchstack" : "patchstack";
+  const dir = existsSync9(join14(cwd, "src")) ? "src/patchstack" : "patchstack";
   const entry = findAppInstance(cwd, spec.appRe);
   const target = entry ? guardTarget(cwd, entry.relPath, spec) : null;
-  const scaffolded = target ? existsSync10(join14(cwd, dir, target.file)) : false;
+  const scaffolded = target ? existsSync9(join14(cwd, dir, target.file)) : false;
   const entrySource = entry ? read(join14(cwd, entry.relPath)) : "";
   const state = entry ? wiringState(entrySource, spec, entry.appVar, entry.relPath, { cwd, guardDir: dir }) : { importAtTopLevel: false, callInAppScope: false, ordered: false, callIndex: -1, appIndex: -1 };
   const wired = state.importAtTopLevel && state.callInAppScope && state.ordered;
@@ -5260,7 +5259,7 @@ var expressAdapter = {
 };
 
 // src/protect/install/reporting.ts
-import { existsSync as existsSync11 } from "fs";
+import { existsSync as existsSync10 } from "fs";
 import { join as join15 } from "path";
 
 // src/protect/reporting-state.js
@@ -5321,7 +5320,7 @@ function explainReportingState(state) {
 function siteIdentity(cwd, env) {
   const rc = join15(cwd, ".patchstackrc.json");
   let recorded;
-  if (existsSync11(rc)) {
+  if (existsSync10(rc)) {
     try {
       recorded = JSON.parse(read(rc)).siteUuid;
     } catch {
@@ -5470,7 +5469,7 @@ function runVerify(cwd) {
 }
 
 // src/widget.ts
-import { existsSync as existsSync12, readFileSync as readFileSync10 } from "fs";
+import { existsSync as existsSync11, readFileSync as readFileSync10 } from "fs";
 import path11 from "path";
 var WIDGET_SCRIPT_URL = "https://cdn.patchstack.com/patchstack-widget.js";
 var WIDGET_MARKER_ATTR = "data-patchstack-connect-widget";
@@ -5509,7 +5508,7 @@ ${indent}</body>`;
 }
 function findSourceShell(cwd) {
   for (const candidate of SOURCE_SHELL_CANDIDATES) {
-    if (existsSync12(path11.join(cwd, candidate))) {
+    if (existsSync11(path11.join(cwd, candidate))) {
       return candidate;
     }
   }
@@ -5521,7 +5520,7 @@ function ensureSourceWidget(cwd, siteUuid, jsxShell = null) {
     return { shell: null, action: "no-shell" };
   }
   const file = path11.join(cwd, shell);
-  if (!existsSync12(file)) {
+  if (!existsSync11(file)) {
     return { shell: null, action: "no-shell" };
   }
   const before = readFileSync10(file, "utf8");
@@ -5606,7 +5605,7 @@ function detectPackageManager(cwd) {
     return declared;
   }
   for (const { filename, pm } of PM_BY_LOCKFILE) {
-    if (existsSync13(path12.join(cwd, filename))) {
+    if (existsSync12(path12.join(cwd, filename))) {
       return pm;
     }
   }
@@ -5703,7 +5702,7 @@ function resolveWidgetFileHint(cwd, framework) {
     ...GENERIC_WIDGET_FILES
   ];
   for (const candidate of candidates) {
-    if (existsSync13(path12.join(cwd, candidate))) {
+    if (existsSync12(path12.join(cwd, candidate))) {
       return candidate;
     }
   }
@@ -5823,7 +5822,11 @@ function renderGuideChecklist(state, useColor) {
   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."));
+    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) {
@@ -5945,11 +5948,19 @@ function renderGuideChecklist(state, useColor) {
   }
   lines.push("");
   if (state.claimUrl !== null) {
-    lines.push(` ${paint(ANSI.cyan, "\u279C")} ${paint(ANSI.bold, "Dashboard link (open to view reports):")}`);
-    lines.push(`   ${paint(ANSI.cyan, state.claimUrl)}`);
-    lines.push(detail("Open this link in a browser. The CLI never opens it."));
-    lines.push(detail("Or from this terminal \u2192 npx @patchstack/connect claim"));
-    lines.push(detail("  (prints a link to sign in with, then attaches the site to that account)"));
+    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)"));
     }
@@ -5959,9 +5970,11 @@ function renderGuideChecklist(state, useColor) {
   if (widgetTagInPlace(state)) {
     lines.push("");
     lines.push(` ${paint(ANSI.cyan, "\u279C")} ${paint(ANSI.bold, "Refresh the preview to see the widget:")}`);
-    lines.push('   The "Report a vulnerability" button loads with the page, so a preview that was');
-    lines.push("   already open still shows the HTML from before this change. Builders that hot");
-    lines.push("   reload refresh it themselves; if the button is missing, refresh the preview once.");
+    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("");
@@ -6295,7 +6308,7 @@ async function claim2(config, onPrompt, deps = {}) {
 import { relative as relative4 } from "path";
 
 // src/protect/install/runtime/entry.ts
-import { existsSync as existsSync14, readFileSync as readFileSync13, realpathSync as realpathSync4, statSync as statSync6 } from "fs";
+import { existsSync as existsSync13, readFileSync as readFileSync13, realpathSync as realpathSync4, statSync as statSync6 } from "fs";
 import { join as join16, resolve as resolve4, sep as sep2 } from "path";
 var CONVENTIONAL = [
   "server.js",
@@ -6392,14 +6405,14 @@ function resolveEntry(cwd) {
   }
   return {
     kind: "unavailable",
-    reason: existsSync14(join16(cwd, "package.json")) ? 'no directly loadable entry was found \u2014 declare one as a "start" script of the form `node <file>`, or run the check against a built output' : "there is no package.json here"
+    reason: existsSync13(join16(cwd, "package.json")) ? 'no directly loadable entry was found \u2014 declare one as a "start" script of the form `node <file>`, or run the check against a built output' : "there is no package.json here"
   };
 }
 
 // src/protect/install/runtime/probe.ts
 import { spawn } from "child_process";
 import { createHash as createHash3, randomBytes } from "crypto";
-import { existsSync as existsSync15 } from "fs";
+import { existsSync as existsSync14 } from "fs";
 import { request as httpRequest } from "http";
 import { request as httpsRequest, Agent as HttpsAgent } from "https";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -6427,7 +6440,7 @@ function preloadPath() {
   ];
   for (const candidate of candidates) {
     const path18 = fileURLToPath2(candidate);
-    if (existsSync15(path18)) return path18;
+    if (existsSync14(path18)) return path18;
   }
   return null;
 }
@@ -9625,14 +9638,21 @@ async function runScan(args, options = {}) {
   const linkUuid = response.uuid ?? config.siteUuid;
   if (!connected && (provisioning || claimLines.length > 0) && linkUuid !== null && linkUuid !== void 0 && linkUuid.length > 0) {
     console.log("");
-    console.log("Open this dashboard link to view vulnerability reports:");
-    console.log(`  ${buildClaimUrl(config.endpoint, linkUuid)}`);
+    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)");
     }
-    console.log("");
-    console.log("Or attach it to your account from this terminal:");
-    console.log("  npx @patchstack/connect claim");
   }
   if (options.showRemainingSetup !== false) {
     try {
@@ -9658,7 +9678,8 @@ function reportSourceWidget(siteUuid, framework) {
     const result = ensureSourceWidget(process.cwd(), siteUuid, jsxShell);
     switch (result.action) {
       case "added":
-        console.log(`Widget: added the "Report a vulnerability" tag to ${result.shell}. Reload your preview to see it.`);
+        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.');
         break;
       case "updated":
         console.log(`Widget: updated the managed tag in ${result.shell} to site ${siteUuid}.`);
@@ -9890,6 +9911,7 @@ async function runSetup(args) {
   const before = await collectGuideState(process.cwd());
   if (!before.hasPackageJson) {
     console.error("Error: no package.json found. Run setup from the project root.");
+    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) {
@@ -9967,7 +9989,7 @@ function setupOutcome(state, protection, wired) {
   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 the dashboard link is opened or `npx @patchstack/connect claim` completes");
+  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;
 }
@@ -9985,7 +10007,9 @@ 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? Run `npx @patchstack/connect claim`.");
+    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`.");
     switch (await fetchSiteStatus(config)) {
       case "active":
         console.log("Site status:   active on Patchstack");