[ENG-3784] Close the install on a refresh and a deploy, not a blank page

[mariojgt]

Closes ENG-3784

What changed

A finished install now ends by naming the two things the user still has to do, in the CLI output and in the install prompt:

• Refresh the preview. The page they are looking at loaded before the widget tag existed, so it renders no "Report a vulnerability" button.
• Deploy. Everything setup writes is a source change, so the live site keeps serving its previous build.

guide's checklist grows a block for each, and setup closes with the same two lines addressed to the assistant, so it relays them instead of reporting success against a page that shows nothing.

Why the blank page happens

setup edits index.html (or, on a code root, the layout). A preview tab that was already open holds the HTML from before that edit, and the widget script only runs on a page load — so the button is absent until the page reloads. Nothing in the process can change that: the CLI's only outputs are file writes and an HTTPS POST, and it has no channel to the browser or iframe showing the preview.

On the auto-refresh half of the ticket

Connect cannot force it, on any platform. This is not a per-builder gap to work around — no builder exposes a "reload the preview" call to a process running inside the workspace, so there is nothing to call.

What happens today is incidental and works most of the time: Vite-based builders watch index.html and issue a full reload when it changes, and framework fast-refresh does the same for a code root. It fails when the dev server was not running during setup, when the preview is a built preview rather than an HMR one, when the platform never adopted the CLI's on-disk edits, or when the preview socket had dropped.

"Usually reloads, sometimes not" is why the wording is conditional — "Builders that hot reload refresh it themselves; if the button is missing, refresh the preview once" — rather than "refresh now". That satisfies the ticket's requirement not to tell someone to refresh a page that just refreshed itself.

A genuinely forced refresh would have to come from the dashboard's install-guide page polling for the site to connect, which is not this repo.

Fix

• widgetTagInPlace() in src/guide.ts, and two closing blocks in the checklist.
• The refresh block appears only when the tag is really in the source carrying this project's UUID — 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. The build hooks, guard and production marker still need a deploy even when someone set "widget": false.
• runSetup ends with Tell the user: and the two lines, so the relay is explicit rather than hoped for.
• The install prompt gains both asks, bounded: "remind me to deploy when I am ready — do not deploy anything yourself." Without that clause an assistant can read "remind me to deploy" as authorization and ship the app.
• Matching notes in AGENT-INSTALL.md, README.md and GETTING-STARTED.md.

Also in here: the install prompt had drifted

The prompt is meant to be byte-identical in README.md, GETTING-STARTED.md and field-test/prompt.txt. It has not been since the sandbox/protection wording landed in README alone — the other two kept the older short version. That meant the field-test gate was measuring a prompt nobody pastes, so this change could not be validated without fixing it first.

All three are now aligned on the README wording, and tests/install-prompt.test.ts compares them and fails on drift. Happy to split this into its own PR if you would rather review it separately.

Verified

npm test (2465 passing, 7 skipped) and npm run typecheck are green. Nine new tests cover both notices and their gates, plus the three-way prompt identity.

The field-test gate has not passed yet. node field-test/run.mjs --persona hostile --rounds 3 is required for a change to the prompt, src/guide.ts or AGENT-INSTALL.md. Two attempts were killed mid-round-1 by session teardown, so there is no scorecard — not a red run, no run. This needs a completed gate before merge. Worth noting the fixture installs the published package, so it can only validate the prompt shape here; the checklist changes want a re-run after publication.

Out of scope, worth a follow-up

The ticket asks to verify behaviour across feature-flag states. Connect's output has no flag dependence — it renders from local project state and reads no flag — so that verification belongs with whoever owns the widget and dashboard UIs.

Also worth confirming how much of the original non-render ENG-3684 already explains, since the dogfooding sessions may predate that fix.

Docs: updated in this PR (AGENT-INSTALL.md, README.md, GETTING-STARTED.md, MAINTAINING.md).

🤖 Generated with Claude Code

[mariojgt]

/review

[coderbuds]

Adds clear refresh and deploy reminders consistently across docs, CLI, and tests.

🎯 Quality: 100% Elite · 📦 Size: Medium

📈 This month: Your 71st PR — above team average · Averaging Excellent

_{See how your team is trending →}