[NO-TICKET] Point agents at setup first and describe the widget by claim state

[mariojgt]

What changed

• guide checklist: on a project that is not set up yet, the checklist now opens with the two commands that cover every step: install the package, then npx @patchstack/connect setup. The individual steps are still listed below it, unchanged, and the new lines go away once the site is provisioned.
• Widget wording: AGENT-INSTALL.md, README.md and GETTING-STARTED.md no longer promise the "Report a vulnerability" button right after setup. They now say a site shows the "Connect this website" panel until it is claimed, and the button after.
• AGENT-INSTALL.md readability: a five-step "usual path" list near the top, and the long hosted-builder paragraph split into short steps plus a list of how each environment is labelled.

Why agents were led off course

• AGENT-INSTALL.md tells agents to run guide first. On a fresh project guide listed six separate steps (run scan, hand-edit package.json three times, wire protection) and never mentioned setup, which does all of them in one bounded command. An agent following the checklist assembled the install by hand.
• A freshly set up site is unclaimed, and an unclaimed site shows the connect panel, not the report button. The checklist already said this; the three docs did not. An agent repeating the docs sent the person looking for a button that is not there.
• The "what to do" section of AGENT-INSTALL.md started around line 90, and the hosted-builder instruction was one 1,700-character paragraph mixed with platform detection details.

Fix

• src/guide.ts: add a lead block when siteUuid is null. It names the install command only when the package is not yet a runtime dependency. No existing checklist line changes.
• Docs: reword the seven widget lines to follow claim state.
• AGENT-INSTALL.md: add the usual-path list and split the paragraph. No content removed, so every capability is still disclosed.
• No command behaves differently. The install prompt is not touched and stays identical in README.md, GETTING-STARTED.md and field-test/prompt.txt.

Verified

• npm test: 3255 passed, including 3 new tests for the checklist lead (shown when unprovisioned, install command omitted when already a dependency, gone once provisioned).
• npm run typecheck, npm run build, npm run capabilities:check: pass.
• Ran guide from the built CLI on a fresh project and checked the new lead appears above the unchanged steps.

Outstanding: these are AGENT-INSTALL.md and guide output changes, which the field test can only see once published. Run node field-test/run.mjs --persona hostile --rounds 3, plus --persona standard for doc accuracy, immediately after the release that carries this PR.

Out of scope, worth a follow-up

The install prompt still says to refresh if the "Report a vulnerability" button is not showing, which is not what an unclaimed site shows. The docs now explain it, but fixing the prompt itself is a prompt change that needs a hostile field-test run before shipping, so it belongs in its own PR.

Docs: this PR is the docs change. MAINTAINING.md needs no update.

🤖 Generated with Claude Code

[coderbuds]

Docs and CLI now clearly describe the widget state and prioritize setup first.

🎯 Quality: 100% Elite · 📦 Size: Small

📈 This month: Your 156th PR — above team average · Averaging Excellent

_{See how your team is trending →}

[mariojgt]

/review