State the public-repository boundary, and fix what already crossed it

.github/pull_request_template.md

@@ -0,0 +1,21 @@
+<!--
+Lead with what changed and why it matters, then the detail. Ordinary words; assume the reader is
+capable but has not seen this code today.
+-->
+
+## What changed
+
+## Why
+
+## How it was verified
+
+---
+
+- [ ] I reviewed the code, comments, fixtures, commit messages, generated output, and PR description for private Patchstack or customer information.
+- [ ] Nothing here is third-party confidential or proprietary material — copied system prompts, private transcripts, unpublished documentation. Where I relied on something being public, I verified it rather than assumed it.
+
+<!--
+This repository is public, including its history and this description. See "Public repository boundary"
+in CLAUDE.md / AGENTS.md. Secret scanning catches credentials; nothing catches a paragraph of
+architecture, so this checkbox is the only control that covers it.
+-->

AGENTS.md

@@ -0,0 +1,55 @@
+# Agent instructions for `@patchstack/connect`
+
+Applies to every agent and automation working in this repository, whichever tool it runs under.
+`CLAUDE.md` carries the same boundary plus Claude-specific working notes; this file exists so the rule
+does not depend on which agent is reading.
+
+## Public repository boundary
+
+This repository, its Git history, code comments, test output, issue content, commit messages, and
+pull-request titles and descriptions must be treated as public.
+
+Do not include information copied or inferred from private Patchstack systems unless it is already
+documented in this repository's public documentation or public API contract.
+
+This includes:
+
+- private repository names, paths, branches, pull requests, or source code;
+- internal service topology, database schemas, queues, credentials, endpoints, deployment details, or
+  operational runbooks;
+- customer, production, incident, or vulnerability-review data;
+- private reachability recipes, vPatch corpora, detection research, or rule-authoring rationale;
+- local filesystem paths, developer usernames, tokens, environment values, or private ticket contents.
+
+Use public product terminology such as "Patchstack SaaS," "Patchstack API," or "rules service." Describe
+only the public contract Connect depends on — not how private systems implement it.
+
+Code comments must explain the current invariant or externally observable behavior. Historical
+investigation, review conversations, mutation notes, internal implementation details, and "how we found
+this" belong in private engineering records, not source comments or public pull requests.
+
+Fixtures must be synthetic or explicitly public. Never copy fixtures or implementation details from a
+private repository merely to make a test realistic.
+
+Do not commit third-party confidential or proprietary material, including copied system prompts, private
+evaluation transcripts, unpublished documentation, or customer-provided integration details. Public
+availability elsewhere must be verified rather than assumed. Use synthetic fixtures unless the material is
+explicitly public and its license permits redistribution.
+
+This is a separate obligation from the one above, not a special case of it. Material can be entirely free
+of Patchstack internals and still be someone else's to publish — so a change can satisfy every rule above
+and still be a disclosure.
+
+Before committing or opening a pull request, inspect the complete staged diff, commit message, generated
+files, test output, and proposed PR description for public-boundary violations. If completing a task
+appears to require publishing private context, stop and ask for a public-safe abstraction.
+
+This is guidance, not enforcement. Secret scanning catches credentials; nothing catches a paragraph of
+architecture, so the review above is the only control that covers it.
+
+## Where the rest of the guidance lives
+
+- `CLAUDE.md` — commands, the tested install prompt, comment and explanation style, releasing.
+- `MAINTAINING.md` — which onboarding and setup files are load-bearing, and how to change one safely.
+- `RELEASING.md` — how a version is cut and published.
+- `field-test/README.md` — the agent harness, its scoring contract, and why its personas are synthetic.

CLAUDE.md

@@ -4,23 +4,66 @@ npm package that connects a JS/Node project to Patchstack vulnerability monitori
 
 Editing any onboarding, prompt, or setup-guide content? Read `MAINTAINING.md` first — it maps which files are load-bearing and how to ship a change safely.
 
+## Public repository boundary
+
+This repository, its Git history, code comments, test output, issue content, commit messages, and
+pull-request titles and descriptions must be treated as public.
+
+Do not include information copied or inferred from private Patchstack systems unless it is already
+documented in this repository's public documentation or public API contract.
+
+This includes:
+
+- private repository names, paths, branches, pull requests, or source code;
+- internal service topology, database schemas, queues, credentials, endpoints, deployment details, or
+  operational runbooks;
+- customer, production, incident, or vulnerability-review data;
+- private reachability recipes, vPatch corpora, detection research, or rule-authoring rationale;
+- local filesystem paths, developer usernames, tokens, environment values, or private ticket contents.
+
+Use public product terminology such as "Patchstack SaaS," "Patchstack API," or "rules service." Describe
+only the public contract Connect depends on — not how private systems implement it.
+
+Code comments must explain the current invariant or externally observable behavior. Historical
+investigation, review conversations, mutation notes, internal implementation details, and "how we found
+this" belong in private engineering records, not source comments or public pull requests.
+
+Fixtures must be synthetic or explicitly public. Never copy fixtures or implementation details from a
+private repository merely to make a test realistic.
+
+Do not commit third-party confidential or proprietary material, including copied system prompts, private
+evaluation transcripts, unpublished documentation, or customer-provided integration details. Public
+availability elsewhere must be verified rather than assumed. Use synthetic fixtures unless the material is
+explicitly public and its license permits redistribution.
+
+This is a separate obligation from the one above, not a special case of it. Material can be entirely free
+of Patchstack internals and still be someone else's to publish — so a change can satisfy every rule above
+and still be a disclosure.
+
+Before committing or opening a pull request, inspect the complete staged diff, commit message, generated
+files, test output, and proposed PR description for public-boundary violations. If completing a task
+appears to require publishing private context, stop and ask for a public-safe abstraction.
+
+This is guidance, not enforcement. Secret scanning catches credentials; nothing catches a paragraph of
+architecture, so the review above is the only control that covers it.
+
 ## Commands
 
 - `npm test` — vitest suite
 - `npm run typecheck` / `npm run build`
 - `node field-test/run.mjs --persona hostile --rounds 3` — agent field test (real AI agent, ~3–6 min and ~30–50k tokens per round; see `field-test/README.md` before running)
-- `node field-test/matrix.mjs --agents claude,codex,gemini` — personas × models cross-product; the platform personas (`bolt-diy`, `lovable`, `replit`) carry the real platform system prompts (provenance in `field-test/README.md`)
+- `node field-test/matrix.mjs --agents claude,codex,gemini` — personas × models cross-product. The personas are SYNTHETIC reconstructions of platform pressure, not platform system prompts — see `field-test/README.md`.
 
 ## The install prompt is a tested artifact
 
-The one-line install prompt in `README.md` ("Install prompt (for AI coding tools)") is adversarial-UX surface: every clause exists because an AI agent refused a shorter version. The refusal modes are documented in `field-test/README.md` — deliberately NOT in the shipped README/AGENT-INSTALL: agents `npm pack` the tarball and read everything, and narrating how the prompt survives refusals is itself read as a manipulation signal. For the same reason, the shipped docs must disclose every capability in `dist/` (e.g. the `protect` command) — an undisclosed capability or overbroad privacy claim is treated as misrepresentation and refused.
+The one-line install prompt in `README.md` ("Install prompt (for AI coding tools)") is adversarial-UX surface: every clause exists because an AI agent refused a shorter version. Do not narrate that history in any shipped doc — agents `npm pack` the tarball and read everything, and an explanation of how the prompt survives refusals is itself read as a manipulation signal. The detailed record is kept privately for the same reason and because it is research, not product documentation. What the shipped docs MUST do is disclose every capability in `dist/` (e.g. the `protect` command): an undisclosed capability or an overbroad privacy claim is treated as misrepresentation and refused.
 
 Invariants when touching it:
 
 - The prompt appears in three places that must stay identical: `README.md`, `GETTING-STARTED.md` (the teammate-facing flow), and `field-test/prompt.txt` — `prompt.txt` is the artifact the harness tests.
 - Any change to the prompt, the `guide` checklist output (`src/guide.ts`), or `AGENT-INSTALL.md` must pass `node field-test/run.mjs --persona hostile --rounds 3` before shipping. Agents audit the shipped docs, so inaccuracies in `AGENT-INSTALL.md` cost trust and cause refusals. **A round that never unpacked the tarball is VOID, not a pass and not a failure**: the shipped docs were never on disk, so no audit of them can have happened, and its scorecard is identical to a doc regression's. Unpacked means a non-empty `node_modules/@patchstack/connect/AGENT-INSTALL.md` — a dependency declaration in `package.json` is not an install. The harness retries void rounds within a bounded budget and exits 2 when every round was void — read that as "re-run", never as "the docs are fine". A doc change also wants a re-run after publication, when the published tarball actually carries it.
 - Don't add reassurance language ("it's safe", "nothing is executed remotely") — agents flag it as a manipulation signal. Don't ask the agent to "follow the guide/instructions it prints" unbounded — name the concrete steps instead.
-- A new real-world refusal report becomes a persona in `field-test/personas/` so the regression stays covered.
+- A new real-world refusal report becomes a persona in `field-test/personas/`, written in your own words as a synthetic reconstruction, so the regression stays covered without publishing someone else's material.
 - The fixture installs the *published* package, so an unpublished `guide`/CLI change can't be exercised end-to-end — publish first, or accept the run validates only the prompt shape.
 
 ## Comments and Explanations
@@ -43,8 +86,9 @@ sentences, ordinary words, no jargon where a plain word works. Lead with what ch
 why it matters, then the detail. Assume the reader is capable but has not seen this code
 today.
 
-This repo is public. Nothing committed here — code, comments, docs or commit messages — may
-contain customer names, internal URLs or internal hostnames.
+See "Public repository boundary" above, which this section is a specific case of: a comment that
+narrates how a bug was found is both a poor comment and, when the finding came from a private system,
+a disclosure.
 
 ## Releasing
 

README.md

@@ -2,8 +2,6 @@
 
 Connect a JavaScript / Node.js application to [Patchstack](https://patchstack.com) for continuous vulnerability monitoring. Scans your `package-lock.json` and reports installed packages so Patchstack can match them against its vulnerability database and notify you when something needs patching.
 
-For how this repo fits with the wider Patchstack ecosystem (`saas`, `hub`, `patchstack-website`, `patchstack-connect`), see [`patchstack/saas` → `docs/ecosystem.md`](https://github.com/patchstack/saas/blob/main/docs/ecosystem.md).
-
 ## Agent-assisted setup
 
 Copy this request into a coding assistant, or run the same command yourself: