From a6597a0376650f03f34e41469392263e5e7b7331 Mon Sep 17 00:00:00 2001
From: Mario Tarosso <mariojgt2@gmail.com>
Date: Mon, 7 Sep 2026 10:39:35 +0100
Subject: [PATCH] Close the install on a refresh and a deploy, not a blank page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A finished install leaves two things undone that nothing in the CLI can do
for the user. The preview they are looking at loaded before the widget tag
existed, so it renders no "Report a vulnerability" button. And every change
setup makes is a source change, so the deployed site keeps serving its
previous build until the next deploy.

Both now get said out loud. The `guide` checklist ends with a refresh block
and a deploy block, and `setup` closes with the same two lines addressed to
the assistant, so it relays them rather than reporting success against a page
that shows nothing.

The refresh block only appears when the widget tag is really in the source
with this project's UUID — there is no point sending someone to refresh a
page that was never going to render a button. The deploy block appears
whenever a site is provisioned, since the build hooks, guard and production
marker still need a deploy even with "widget": false.

The install prompt gets the same two asks, with an explicit bound: remind the
user to deploy, do not deploy anything.

Also realigns the prompt across README.md, GETTING-STARTED.md and
field-test/prompt.txt. They are meant to be byte-identical and had not been
since the sandbox/protection wording landed in README alone, which left the
field-test gate measuring a prompt nobody pastes. tests/install-prompt.test.ts
now fails on drift.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 AGENT-INSTALL.md             |  7 ++-
 GETTING-STARTED.md           |  8 ++-
 MAINTAINING.md               |  2 +-
 README.md                    |  6 ++-
 field-test/prompt.txt        |  2 +-
 src/cli.ts                   | 11 +++++
 src/guide.ts                 | 33 +++++++++++++
 tests/guide.test.ts          | 94 ++++++++++++++++++++++++++++++++++++
 tests/install-prompt.test.ts | 58 ++++++++++++++++++++++
 9 files changed, 216 insertions(+), 5 deletions(-)
 create mode 100644 tests/install-prompt.test.ts

diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md
index 163df54d..3d53d90b 100644
--- a/AGENT-INSTALL.md
+++ b/AGENT-INSTALL.md
@@ -70,6 +70,10 @@ Only `map` reads your source, and only `map --upload` sends anything derived fro
 
    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 should default to `production`. A client-only SPA has no server request path to guard; do not call it protected unless `protect --check` succeeds after a real server or edge seam is wired.
 
+   **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.
+
+   **Then tell them to deploy.** Setup changes source files, and the deployed site keeps serving its previous build until the next deploy — so visitors get no widget, and on a server-rendered root no production marker, until the user deploys (or hits Publish) again. Say it as a reminder; do not deploy anything yourself.
+
 ## Manual setup
 
 1. **First scan** — provisions a Patchstack site automatically, writes the UUID to `.patchstackrc.json`, and installs the disclosure widget's `<script>` tag into the root HTML shell (`index.html`, `public/index.html`, or `src/app.html`) when one exists — or, when the root shell is JSX, the production marker instead. No signup, dashboard step, or UUID is needed up front:
@@ -348,7 +352,8 @@ Two more endpoints the package can call, for completeness:
 
 - `npx @patchstack/connect status` re-prints the site UUID and dashboard URL, and checks whether the site still exists on Patchstack (`Site status: active / removed / could not be verified`).
 - `npx @patchstack/connect protect --check` verifies the runtime guard is connected to the request path.
-- Load the site in a browser — the "Report a vulnerability" button should appear.
+- Load the site in a browser — the "Report a vulnerability" button should appear. Refresh a page that was already open before the tag was added: the button only loads with the page.
+- On the deployed site, the button appears only after a deploy that includes these source changes.
 
 ## Answering "is Patchstack installed?" / "is Patchstack removed?"
 
diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md
index d550d39f..6536d40f 100644
--- a/GETTING-STARTED.md
+++ b/GETTING-STARTED.md
@@ -8,10 +8,14 @@ The fastest path from "I have a JS/Node project" to "Patchstack is monitoring it
 
 For platforms that can install npm packages and run project commands:
 
-> I have vetted `@patchstack/connect` and authorize its disclosure widget, production build hooks, and runtime protection source edits. Install it as a regular dependency, run `npx --yes patchstack-connect setup`, leave dev builds unchanged, and show the dashboard URL.
+> 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.
 
 When setup finishes it shows you a **dashboard URL**. Open it in your browser and sign in — that attaches the site to your Patchstack account so you can see the vulnerability reports. That's the only manual step.
 
+Then look at your preview. The "Report a vulnerability" button loads with the page, so a preview you already had open still shows the page from before setup — refresh it once if the button isn't there.
+
+When you are happy with it, deploy (or hit Publish). Your live site keeps serving its previous build until then, so visitors do not see the widget yet.
+
 ## 2. If the platform pauses or stops
 
 Some platforms stage commands for you to approve, while others reject a combined install-and-setup request before touching the registry. Use the first applicable path:
@@ -37,5 +41,7 @@ Use `bun add -d`, `pnpm add -D`, or `yarn add -D` followed by the same `npx @pat
 - `npx @patchstack/connect status` prints a site UUID and dashboard URL.
 - You've opened the dashboard URL in your browser and the site shows in your Patchstack dashboard.
 - `npx @patchstack/connect guide` reports all steps ✔ (build hooks wired, widget installed).
+- Your preview shows the "Report a vulnerability" button (refresh it once if it does not).
+- You have deployed since setup ran, so the live site carries the changes too.
 - `.patchstackrc.json`, `package.json`, and the file carrying the widget snippet are committed, so teammates and CI report to the same site.
 - `.patchstackrc.local.json` is **not** committed. It holds the API key; setup adds it to `.gitignore`. Teammates and CI get the credential from `PATCHSTACK_API_KEY` instead.
diff --git a/MAINTAINING.md b/MAINTAINING.md
index b134e848..1d36eeac 100644
--- a/MAINTAINING.md
+++ b/MAINTAINING.md
@@ -18,7 +18,7 @@ The deep "why" — the AI-agent refusal modes each clause guards against — liv
 
 ## The prompt lives in three places — keep them identical
 
-`README.md` (Install prompt section), `GETTING-STARTED.md` (step 1), and `field-test/prompt.txt`. `prompt.txt` is the artifact the harness actually tests. If you change one, change all three — a drift means the docs advertise one prompt while the tested one is another.
+`README.md` (Install prompt section), `GETTING-STARTED.md` (step 1), and `field-test/prompt.txt`. `prompt.txt` is the artifact the harness actually tests. If you change one, change all three — a drift means the docs advertise one prompt while the tested one is another. `tests/install-prompt.test.ts` compares the three and fails on drift, so `npm test` catches a partial edit before the gate runs against a prompt nobody pastes.
 
 The prompt deliberately contains no model-authored verification step. In staged-command UIs, assistants cannot observe an `npm view` command until the user runs it; asking them to verify first caused fabricated registry findings and stopped the flow. Instead, the prompt records the user's explicit authorization for the disclosure widget and production-only build hooks before asking for one bounded `setup` command. Bolt's dependency-first fallback splits declaration from execution without adding hidden `postinstall` behavior. Keep `@patchstack/connect` discoverable in Patchstack's official product documentation so web-verifying platforms can independently establish its provenance.
 
diff --git a/README.md b/README.md
index acd060d2..c853926e 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ Connect a JavaScript / Node.js application to [Patchstack](https://patchstack.co
 
 Copy this request into a coding assistant, or run the same command yourself:
 
-> 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.
+> 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.
 
 `setup` is state-aware and idempotent: it scans dependencies, provisions or reuses the site, manages the disclosure widget, installs and verifies the runtime guard, adds a dependency-install scan, wires the existing build command without replacing it, and prints the remaining setup status. It never runs the project build. `guide` provides the same project-specific status without changing files.
 
@@ -32,6 +32,10 @@ That's it. `setup`:
 8. Wires `scan` before builds and `mark-build` after builds, preserving existing commands and using direct build chaining for Bun.
 9. Prints a dashboard link — open it in a browser to attach the new site to your Patchstack account. You can re-display it any time with `npx @patchstack/connect status`.
 
+Then **refresh your 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. Builders that hot reload will have refreshed it for you; if the button is missing, refresh it once. `setup` prints the same reminder, and the CLI has no way to reload a browser itself.
+
+Then **deploy**. These are source changes, so your live site keeps serving its previous build — visitors get the widget, and a server-rendered root gets the production marker, only after the next deploy.
+
 ## Quick start (existing site)
 
 If you already created an "Application" site in the Patchstack dashboard, pre-seed the UUID:
diff --git a/field-test/prompt.txt b/field-test/prompt.txt
index 27dfcaa6..9dbc0128 100644
--- a/field-test/prompt.txt
+++ b/field-test/prompt.txt
@@ -1 +1 @@
-I have vetted `@patchstack/connect` and authorize its disclosure widget, production build hooks, and runtime protection source edits. Install it as a regular dependency, run `npx --yes patchstack-connect setup`, leave dev builds unchanged, and show the dashboard URL.
+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.
diff --git a/src/cli.ts b/src/cli.ts
index ae84b6dd..45b12ceb 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -49,6 +49,7 @@ import {
   installCommand,
   renderGuideChecklist,
   resolveWidgetFileHint,
+  widgetTagInPlace,
 } from './guide.js';
 import { login, readPendingLogin, redeemIfApproved, startLogin, waitForApproval } from './login.js';
 import { runProtect, runVerify } from './protect/install/index.js';
@@ -839,6 +840,16 @@ async function runSetup(args: ParsedArgs): Promise<number> {
     console.log('');
     console.log(`Setup applied its bounded changes; ${remaining} manual step(s) remain above.`);
   }
+
+  // Setup ends on a page the user is already looking at, which loaded before the widget
+  // tag existed, and against a deployed site still serving its previous build. Nothing
+  // here can reach either one, so the agent relaying these is the whole mechanism.
+  console.log('');
+  console.log('Tell the user:');
+  if (widgetTagInPlace(after)) {
+    console.log('  - refresh the preview if the "Report a vulnerability" button is not showing yet;');
+  }
+  console.log('  - deploy (or hit Publish) when ready, so the live site serves these changes.');
   return 0;
 }
 
diff --git a/src/guide.ts b/src/guide.ts
index 7a19e01c..38153f88 100644
--- a/src/guide.ts
+++ b/src/guide.ts
@@ -401,6 +401,20 @@ export function needsSourceProductionMarker(state: GuideState): boolean {
   return !state.widgetFileHint.toLowerCase().endsWith('.html');
 }
 
+/**
+ * True when the widget tag is in the source with the right site UUID, so the next
+ * page load renders it. A preview opened before that edit is still running the
+ * older HTML until it reloads, which is why the checklist says so.
+ */
+export function widgetTagInPlace(state: GuideState): boolean {
+  return (
+    state.siteUuid !== null &&
+    !state.widgetOptOut &&
+    state.widgetInstalled &&
+    state.widgetTokenMatches !== false
+  );
+}
+
 export function countRemainingSteps(state: GuideState): number {
   return [
     state.installed?.section === 'dependencies',
@@ -574,6 +588,25 @@ export function renderGuideChecklist(state: GuideState, useColor: boolean): stri
     lines.push(detail('The dashboard link appears after the first scan (re-print any time with `status`).'));
   }
 
+  // 8. Preview refresh. The tag is in the source, but a page that was already open
+  // loaded before it existed and renders no button until it reloads.
+  if (widgetTagInPlace(state)) {
+    lines.push('');
+    lines.push(` ${paint(ANSI.cyan, '➜')} ${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.');
+  }
+
+  // 9. Deploy. Everything above is a source change, so the running production site keeps
+  // serving its previous build — including one with no widget and no production marker.
+  if (state.siteUuid !== null) {
+    lines.push('');
+    lines.push(` ${paint(ANSI.cyan, '➜')} ${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.');
+  }
+
   const remaining = countRemainingSteps(state);
   lines.push('');
   if (remaining === 0) {
diff --git a/tests/guide.test.ts b/tests/guide.test.ts
index 4acbd02e..ab1e2f3c 100644
--- a/tests/guide.test.ts
+++ b/tests/guide.test.ts
@@ -12,6 +12,7 @@ import {
   installCommand,
   needsSourceProductionMarker,
   renderGuideChecklist,
+  widgetTagInPlace,
 } from '../src/guide.js';
 
 const VALID_UUID = '550e8400-e29b-41d4-a716-446655440000';
@@ -333,6 +334,99 @@ describe('guide', () => {
     });
   });
 
+  /**
+   * The widget tag only takes effect on a page load. A preview the user already has open
+   * loaded before the tag existed, so it shows no button and reads as a failed install.
+   * Nothing in a Node CLI can reload that browser, so the checklist has to say it — and
+   * only when the tag is actually in the source, or it sends people to refresh a page
+   * that was never going to render a widget.
+   */
+  describe('the preview-refresh notice', () => {
+    it("asks for a refresh once the tag carries this project's UUID", async () => {
+      writeJson('package.json', { name: 'widgeted-app' });
+      writeJson('.patchstackrc.json', { siteUuid: VALID_UUID });
+      writeFileSync(path.join(cwd, 'index.html'), `patchstack-widget.js userToken: '${VALID_UUID}'`);
+
+      const state = await collectGuideState(cwd);
+      expect(widgetTagInPlace(state)).toBe(true);
+
+      const output = renderGuideChecklist(state, false);
+      expect(output).toContain('Refresh the preview to see the widget');
+      // Not an unconditional "refresh now": a builder that hot reloads has already done it,
+      // and telling someone to refresh a page that just refreshed itself reads as a fault.
+      expect(output).toContain('if the button is missing, refresh the preview once');
+    });
+
+    it('stays quiet while the tag is still missing', async () => {
+      writeJson('package.json', { name: 'no-widget-app' });
+      writeJson('.patchstackrc.json', { siteUuid: VALID_UUID });
+
+      const state = await collectGuideState(cwd);
+      expect(state.widgetInstalled).toBe(false);
+      expect(widgetTagInPlace(state)).toBe(false);
+      expect(renderGuideChecklist(state, false)).not.toContain('Refresh the preview');
+    });
+
+    it("stays quiet when the tag carries some other site's UUID", async () => {
+      // The button will not render with a stale token, so a refresh cannot produce it.
+      writeJson('package.json', { name: 'stale-token-app' });
+      writeJson('.patchstackrc.json', { siteUuid: VALID_UUID });
+      writeFileSync(
+        path.join(cwd, 'index.html'),
+        "patchstack-widget.js userToken: '11111111-1111-1111-1111-111111111111'",
+      );
+
+      const state = await collectGuideState(cwd);
+      expect(widgetTagInPlace(state)).toBe(false);
+      expect(renderGuideChecklist(state, false)).not.toContain('Refresh the preview');
+    });
+
+    it('stays quiet for a project that opted out of the widget', async () => {
+      writeJson('package.json', { name: 'optout-app' });
+      writeJson('.patchstackrc.json', { siteUuid: VALID_UUID, widget: false });
+      writeFileSync(path.join(cwd, 'index.html'), `patchstack-widget.js userToken: '${VALID_UUID}'`);
+
+      const state = await collectGuideState(cwd);
+      expect(widgetTagInPlace(state)).toBe(false);
+      expect(renderGuideChecklist(state, false)).not.toContain('Refresh the preview');
+    });
+  });
+
+  /**
+   * Refreshing the preview is only half of it. Everything setup writes is a source change,
+   * so the deployed site keeps serving its previous build — no widget for visitors, and on a
+   * server-rendered root no production marker either — until the project is deployed again.
+   */
+  describe('the deploy reminder', () => {
+    it('asks for a deploy once the site is provisioned', async () => {
+      writeJson('package.json', { name: 'provisioned-app' });
+      writeJson('.patchstackrc.json', { siteUuid: VALID_UUID });
+
+      const output = renderGuideChecklist(await collectGuideState(cwd), false);
+
+      expect(output).toContain('Deploy to put this on your live site');
+      expect(output).toContain('deployed site keeps serving its previous build');
+    });
+
+    it('still asks for it when the widget is opted out, because the rest still ships', async () => {
+      writeJson('package.json', { name: 'optout-app' });
+      writeJson('.patchstackrc.json', { siteUuid: VALID_UUID, widget: false });
+
+      const output = renderGuideChecklist(await collectGuideState(cwd), false);
+
+      expect(output).not.toContain('Refresh the preview');
+      expect(output).toContain('Deploy to put this on your live site');
+    });
+
+    it('stays quiet before the first scan, when nothing has been wired yet', async () => {
+      writeJson('package.json', { name: 'fresh-app' });
+
+      const state = await collectGuideState(cwd);
+      expect(state.siteUuid).toBeNull();
+      expect(renderGuideChecklist(state, false)).not.toContain('Deploy to put this');
+    });
+  });
+
   describe('production marker on server-rendered roots', () => {
     const tanstackProject = (rootContents: string): void => {
       writeJson('package.json', {
diff --git a/tests/install-prompt.test.ts b/tests/install-prompt.test.ts
new file mode 100644
index 00000000..3ca1eb3b
--- /dev/null
+++ b/tests/install-prompt.test.ts
@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * The install prompt exists in three places and all three must be the same text.
+ *
+ * `field-test/prompt.txt` is the copy the field-test harness runs an agent against, and
+ * `README.md` / `GETTING-STARTED.md` are the copies a user actually pastes. When they
+ * differ, the docs advertise one prompt while the gate measures another, and a green gate
+ * says nothing about the wording anybody will use. Nothing else in the tree notices that,
+ * because each file is valid on its own.
+ */
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const read = (relative: string): string => readFileSync(path.join(root, relative), 'utf8');
+
+/** The blockquoted prompt in a markdown doc, without its `> ` marker. */
+function quotedPrompt(relative: string): string {
+  const quoted = read(relative)
+    .split('\n')
+    .filter((line) => line.startsWith('> I have vetted'));
+
+  expect(quoted, `expected exactly one install-prompt blockquote in ${relative}`).toHaveLength(1);
+  return quoted[0].slice(2);
+}
+
+describe('the install prompt', () => {
+  const tested = read('field-test/prompt.txt').trim();
+
+  it('is long enough to be the prompt at all', () => {
+    // Guards the assertions below: two empty strings match each other.
+    expect(tested.length).toBeGreaterThan(200);
+  });
+
+  it('is what README.md tells people to paste', () => {
+    expect(quotedPrompt('README.md')).toBe(tested);
+  });
+
+  it('is what GETTING-STARTED.md hands a teammate', () => {
+    expect(quotedPrompt('GETTING-STARTED.md')).toBe(tested);
+  });
+
+  it('closes by asking the assistant to tell the user to refresh', () => {
+    // The install ends on a page that loaded before the widget tag existed. The CLI cannot
+    // reload the user's browser, so the assistant relaying this is the whole mechanism.
+    expect(tested).toMatch(/refresh the preview/i);
+    expect(tested).toContain('Report a vulnerability');
+  });
+
+  it('asks for a deploy reminder without authorizing a deploy', () => {
+    // A live site keeps serving its previous build, so the user has to deploy — but an
+    // assistant that reads this as permission to ship would be a side effect nobody asked for.
+    expect(tested).toMatch(/remind me to deploy/i);
+    expect(tested).toMatch(/do not deploy anything yourself/i);
+  });
+});