[NO-TICKET] Tell the agent to report what the setup actually covered

[mariojgt]

[NO-TICKET]

What changed

AGENT-INSTALL.md now tells the installing agent two things it did not say before: a step still on the checklist is work to finish, and a ✔ can mean "nothing owed here" rather than "this part is on". Docs only — no CLI or behaviour change.

Why a finished-looking install can be a partial one

The checklist (guide, and the copy setup prints) marks the steps a project still owes. A part the project cannot carry, or one that is switched off, is therefore green with nothing outstanding:

• No build script to integrate (postinstall covers dependency changes)
• Disclosure widget disabled by config ("widget": false in .patchstackrc.json)
• Runtime protection: not applicable — this project has no request path

All three are ticks. A project reaches "0 step(s) remaining" and "Ready to deploy" with the widget switched off and no runtime guard — tests/guide.test.ts already pins that case. An agent summarising the checklist for someone who did not write the project reports "Patchstack is set up", which is true of the work owed and false of the coverage. Nothing in the shipped docs told it to read the ticks any other way.

Fix

• "A step the checklist still lists is yours to finish, not a result to report." Names the steps setup can leave behind — moving the package out of devDependencies, the widget tag in a root layout it could not edit, the production marker on a server-rendered root, wiring a generic guard into the server entry — and points at Manual setup steps 3 and 4, rather than delegating to whatever the CLI prints.
• "A tick is 'nothing owed here', not 'this part is on'." Quotes the three checklist lines verbatim so they are recognisable in the output, and asks for the result to be reported part by part — dependency scans, the disclosure widget, the build hooks, runtime protection — with the inactive ones named and explained.
• Calls out "widget": false as the one part that is off by a setting rather than by the shape of the project, so the agent raises it with the person instead of silently shipping without the widget.

Verified

npm test (3252 passed, 7 skipped) and npm run capabilities:check are green. The three quoted checklist strings were copied from a real guide run against a fixture, not from reading the renderer, so they match what an agent actually sees.

The field test is outstanding, and this ships without it. AGENT-INSTALL.md is unpacked from the registry by the harness fixture, so a run against the current tarball would audit the previous text and say nothing about this change. It needs a run immediately after the release that carries it — standard or lovable, which install more reliably than hostile when the question is document accuracy. Until then the local deterministic checks above are what stand behind it.

Out of scope, worth a follow-up

The checklist still renders a reduced install as fully green. This change teaches the reader to interpret the output; it does not change the output. A helper in src/guide.ts could name the inactive parts directly, both in the checklist and in the outcome block that setup asks the agent to relay as it is — which is the surface that survives summarising. That is a CLI change and deserves its own ticket.

While looking: the outcome block's one related warning — no build script, so only dependency installs are scanned — is gated on the build hook not having changed, so it fires only on a re-run and stays silent on the first one, which is the run whose output the agent relays. Worth folding into the same follow-up.

Docs: this is the docs change.

🤖 Generated with Claude Code

[mariojgt]

/review

[coderbuds]

Documentation now clearly reports what setup actually covered.

🎯 Quality: 97% Elite · 📦 Size: Tiny

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

_{See how your team is trending →}