[ENG-3984] Define the "Report a vulnerability" button at first use, and correct three stale README sections

[mariojgt]

Closes ENG-3984

What changed

The README named a "Report a vulnerability" button in the install prompt and the quick start, then did not say what it was until The disclosure widget, roughly 300 lines later. It is now defined at first use. Three other sections were out of date and are corrected alongside it: the opening summary, the release process, and the development loop.

Why it misled readers

Four separate causes, one per fix.

The button had no antecedent. Read top-down — which is how an assistant reads a README — the phrase lands beside a package about vulnerability monitoring, so it reads as either "report a vulnerable dependency to Patchstack" or "this is where you report a security bug in @patchstack/connect". It is neither: it is a button Connect renders on the reader's own site, for their visitors. Nothing corrected the second reading, because there is no SECURITY.md in the repository and CONTRIBUTING.md points at one "if present".

The opening described a narrower package than the one that installs. It covered dependency scanning only, and named package-lock.json when five lockfile formats are supported. The runtime guard, the disclosure widget and the attack-surface map all ship in dist/ and were documented further down, so the impression a reader formed from the first paragraph was wrong by omission.

The release section described the inverse of the real pipeline. It said to bump package.json, commit it, merge it, and that a tag not matching it fails the workflow. The tag is the source of truth: Publish reads the version out of the tag and writes it into package.json in CI (.github/workflows/publish.yml:113), and Release computes the bump. Anyone following the README would have done work the pipeline then undoes.

The development loop listed npm test before npm run build. CONTRIBUTING.md:53 is explicit that several tests only run once dist/ exists and skip without it — "reads exactly like passing". The documented order tested less than it appeared to.

Fix

• Replace the opening paragraph with four bullets — dependency inventory, runtime guard, disclosure widget, attack-surface map — each linking to its section. The widget bullet says the button is on the reader's own site and is not how to report a bug in this package.
• Add a line stating that setup installs the first three and that map is never run for you.
• Rewrite the release section to match RELEASING.md and publish.yml, and point at the former for the rest.
• Move the one-time npm trusted-publishing setup to RELEASING.md, where a maintainer would look for it.
• Reorder the development loop to build before testing, with the reason inline, and switch npm install to npm ci.
• Move the local-endpoint manifest recipe to CONTRIBUTING.md. It is contributor-only and was shipping to every consumer inside the tarball.

The install prompt is byte-untouched, so README.md, GETTING-STARTED.md and field-test/prompt.txt still agree and no prompt re-gate is triggered.

Verified

npm run typecheck, npm run build, npm test — 3194 passed, 7 skipped, across 193 files. That includes the README assertions in tests/execution-disclosure.test.ts (the protect --check --runtime disclosures, the traversal-only claim, the worker-thread and discovery-window caveats) and the three-way prompt comparison in tests/install-prompt.test.ts.

npm run capabilities:check and npm run rule-contract:check clean. npm pack --dry-run shows tarball contents unchanged apart from the README itself. All four new anchor links resolve to real headings. The CLI block still lists all 13 commands the binary dispatches, so no capability in dist/ is left undisclosed.

Not verified, and not verifiable before release: the hostile field test. README.md ships inside the tarball, so it is in the same bucket as AGENT-INSTALL.md — the fixture installs the published package, so a run today would audit 0.5.8's README and say nothing about this diff. Per CLAUDE.md and MAINTAINING.md that run belongs immediately after the release carrying this change, with standard or lovable added for document accuracy. The deterministic gates above are what stand behind it until then. There is already an outstanding post-release run from #271; if both land in the same release, one hostile --rounds 3 covers the prompt-survival question for both.

Out of scope, worth a follow-up

There is no SECURITY.md. CONTRIBUTING.md tells a reporter to see it "if present", and it is not. That absence is half of why "Report a vulnerability" was ambiguous in the first place — defining the button removes the confusion, but there is still no documented channel for a vulnerability in the package itself. Someone should decide whether that file should exist.

package.json's description omits the disclosure widget. It names dependency inventory, attack-surface mapping and the guard. That is the same under-description the old README opening had, and it is the text npm renders above the README — so it reaches more readers than the paragraph fixed here. Left alone because it is package metadata rather than documentation, and worth deciding deliberately.

The CLI section is an 85-line preformatted block. A table would scan better for both readers and assistants, but that block carries the load-bearing disclosures (map READS YOUR SOURCE FILES, protect --check --runtime STARTS THE APP) and reformatting it risks weakening them. Its own change, with its own review.

Docs: this is the docs change. GETTING-STARTED.md and AGENT-INSTALL.md need nothing — they describe the same button, and the prompt they share with the README did not move.

🤖 Generated with Claude Code

[coderbuds]

Reorganized README and docs to improve clarity of setup and release processes.

🎯 Quality: 99% Elite · 📦 Size: Small

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

_{See how your team is trending →}

[mariojgt]

/review