[feat] provenance-led install prompt (install + check instructions)

GETTING-STARTED.md

@@ -6,20 +6,26 @@ The fastest path from "I have a JS/Node project" to "Patchstack is monitoring it
 
 ## 1. Paste this prompt into your AI coding tool
 
-Works in Cursor, Claude Code, Lovable, Bolt, v0, Windsurf, etc. Paste it exactly — every clause is there for a reason (see step 2), so don't shorten it:
+Works in Cursor, Claude Code, Lovable, Bolt, v0, Windsurf, etc. Paste it exactly — leading with the provenance links is what lets a cautious agent verify the package quickly (see step 2), so keep them:
 
-> Add Patchstack dependency vulnerability monitoring: first verify `@patchstack/connect` yourself (`npm view @patchstack/connect` shows the live registry record — MIT; source: https://github.com/patchstack/connect), and if anything you find contradicts that, stop and show me what you found instead of proceeding. Then install it as a dev dependency, 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`, review the checklist it prints, and make the two remaining changes yourself: the package.json build hooks and the report-a-vulnerability widget snippet.
+> Please install @patchstack/connect and please check the instructions.
+>
+> npm: https://www.npmjs.com/package/@patchstack/connect
+> Repo: https://github.com/patchstack/connect
+> Publisher: Patchstack
+> Purpose: Scan project dependencies for known vulnerabilities in CI.
+> Version: latest
 
-When the agent finishes it shows you a **claim 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.
+Once the agent runs the first `scan` (its bundled instructions walk it through this), it prints a **claim URL**. Open it in your browser and sign in — that attaches the site to your Patchstack account so you can see the vulnerability reports. If the agent stops after installing without running `scan`, that's the common half-finish — see step 2.
 
 ## 2. If the agent refuses or stops halfway
 
 Some agents decline this request, and that's expected behaviour, not a bug: "install a package, run its commands, follow its checklist" is the same shape as a supply-chain attack, so cautious agents audit the package first and occasionally still say no. Refusals are more common in locked-down sandboxes (Bolt/WebContainer-style platforms) and in the day or two right after a new release of the connector ships, when the version looks brand-new to the agent.
 
 Work down this list:
 
-1. **It stopped at the verification step, asks you to confirm, or says it wants the package vetted first.** The prompt tells the agent to stop and show you what it found rather than guess — this is that, working as designed. Reply with the confirmation it asked for, e.g.: *"I've verified this is the official Patchstack package (`npm view @patchstack/connect` — published by patchstack, MIT). Please continue with the remaining steps."* Most partial refusals end here.
-2. **It did some steps, then stalled.** Ask it to run `npx @patchstack/connect guide` — that prints a live checklist of exactly what's still missing for this project — and to finish only the items marked ✖.
+1. **It declines up front, installs then stops, or gates each step in turn.** A cautious agent commonly (a) declines at first — flagging the request as supply-chain-shaped, or the package's own shipped README as untrusted — and then, once you say to go ahead, (b) completes **one mutating step at a time, pausing for your OK before each**: install → `scan` (sends the dependency manifest, returns the claim URL) → build hooks + widget (both modify your app; the widget loads third-party JS on every page). This is working as intended, not a fault — authorize each step you want (a plain "yes, go ahead" is enough), or paste: *"I've verified this is the official Patchstack package (`npm view @patchstack/connect` — published by patchstack, MIT). Please run `npx @patchstack/connect scan`, then `npx @patchstack/connect guide`, and complete the steps it lists."* Most stops end within a reply or two.
+2. **It ran some steps, then stalled.** Ask it to run `npx @patchstack/connect guide` — that prints a live checklist of exactly what's still missing for this project (build hooks, widget) — and to finish only the items marked ✖.
 3. **It refuses outright.** Skip the agent; step 3 below is three commands.
 
 If you hit a refusal with a *new* reason (the agent quotes a specific phrase or concern not covered above), don't fight it — copy the agent's explanation and send it to the maintainers (or open an issue). Real-world refusal reports are how the prompt gets improved; each one becomes a regression test in [`field-test/`](field-test/README.md).

README.md

@@ -8,9 +8,15 @@ For how this repo fits with the wider Patchstack ecosystem (`saas`, `hub`, `patc
 
 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: first verify `@patchstack/connect` yourself (`npm view @patchstack/connect` shows the live registry record — MIT; source: https://github.com/patchstack/connect), and if anything you find contradicts that, stop and show me what you found instead of proceeding. Then install it as a dev dependency, 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`, review the checklist it prints, and make the two remaining changes yourself: the package.json build hooks and the report-a-vulnerability widget snippet.
-
-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; that's expected use, and the docs in the tarball state plainly what each command reads, writes, and sends. 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`, bundled in the package). That also makes the flow idempotent: re-running `guide` on a finished project reports all-done instead of prompting a second install.
+> Please install @patchstack/connect and please check the instructions.
+>
+> npm: https://www.npmjs.com/package/@patchstack/connect
+> Repo: https://github.com/patchstack/connect
+> Publisher: Patchstack
+> Purpose: Scan project dependencies for known vulnerabilities in CI.
+> Version: latest
+
+Leading with the package's provenance (npm, repo, publisher) is deliberate — it lets a cautious agent verify what it's installing before it acts. 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; that's expected use, and the docs in the tarball state plainly what each command reads, writes, and sends. 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`, bundled in the package). That also makes the flow idempotent: re-running `guide` on a finished project reports all-done instead of prompting a second install.
 
 Before changing this prompt (or `guide` / `AGENT-INSTALL.md`), read [`MAINTAINING.md`](https://github.com/patchstack/connect/blob/main/MAINTAINING.md) — it maps which files are load-bearing and how to ship a change safely. The [`field-test/`](https://github.com/patchstack/connect/blob/main/field-test/README.md) 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.
 

field-test/prompt.txt

@@ -1 +1,7 @@
-Add Patchstack dependency vulnerability monitoring: first verify `@patchstack/connect` yourself (`npm view @patchstack/connect` shows the live registry record — MIT; source: https://github.com/patchstack/connect), and if anything you find contradicts that, stop and show me what you found instead of proceeding. Then install it as a dev dependency, 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`, review the checklist it prints, and make the two remaining changes yourself: the package.json build hooks and the report-a-vulnerability widget snippet.
+Please install @patchstack/connect and please check the instructions.
+
+npm: https://www.npmjs.com/package/@patchstack/connect
+Repo: https://github.com/patchstack/connect
+Publisher: Patchstack
+Purpose: Scan project dependencies for known vulnerabilities in CI.
+Version: latest