Disclose detection reporting, and stop claiming it does not exist

AGENT-INSTALL.md

@@ -12,7 +12,7 @@ This versioned reference ships inside `@patchstack/connect` and documents each s
 - The package also exposes **`protect`** directly (runtime exploit guard; its templates live under `dist/protect/`). `setup` invokes it automatically; `scan`, `guide`, `status`, and `mark-build` do not. It writes only local files and auto-wires known stacks — **TanStack Start + Supabase** (patches the Supabase client + `src/start.ts`), **Next.js** (scaffolds `middleware.ts`), **SvelteKit** (`src/hooks.server.ts`), **Astro** (`src/middleware.ts`), **Nuxt** (`server/middleware/`), **NestJS** (`app.use(patchstackMiddleware)` in the bootstrap), **Fastify** (`app.register(patchstackFastify)`), and **Express** (`app.use(patchstackMiddleware)`). On **any other stack** it scaffolds a framework-agnostic guard under `src/patchstack/` and prints a wiring plan — then you finish the install by importing that guard into your server entry (`protectFetch(handler)` for a Web-Fetch server, or `app.use(patchstackMiddleware)` for Node/Express) and running `patchstack-connect protect --check` to confirm it is wired (exit 1 until it is). Passing `--demo` seeds a broad sample rule set (for demonstrations, not production).
 - **`demo node-serialize` is an explicit production-backed walkthrough.** It requires `node-serialize@0.0.4` to already be present in the lockfile; it does not install the vulnerable dependency. It runs the same production `scan`, polls the configured site's public Pulse rules endpoint until rule `18843` is served, runs `protect`, verifies the generated guard, and prints exploit/benign test requests. It writes the same manifest/widget and guard files as those underlying commands. It does not start/restart the app and does not send the printed requests.
 - **`map` is a local, read-only analysis command.** It walks the project's server source (skipping `node_modules`, build output and dot-directories; it does not follow symlinks out of the project unless you pass `--follow-symlinks`), parses it with the project's **own** `typescript`, and prints JSON describing the attack surface: entry points, the inputs each reads, the sinks they can reach (database / file system / process / outbound HTTP) with the npm package behind each, and evidence-backed input→sink flows, each labelled with how the link was established — from an exact read at the sink's own call site, through a transformed or cross-module link, down to the two being present together with no proven link. Static analysis is best-effort, so the output reports the *detected* surface with coverage counters — not a completeness guarantee. It writes nothing (except the file you name with `--out`) and is never invoked by `scan`, `setup`, `guide`, `protect`, or `mark-build`.
-- **`map --upload` is the one opt-in that sends anything derived from your source.** It POSTs the same JSON document to `monitor/pulse/input-map/<your site uuid>` so Patchstack can pin protection rules to your app's own parameter names instead of guessing them. What is sent is exactly what `map` prints — a structural description: route paths, parameter/field names, the dependency behind each sink, and file paths with line numbers. **No source code, no file contents, no environment variable values.** It never runs without the flag, it is skipped when no entry points are detected, and a failure to reach Patchstack is reported and ignored rather than failing your build. Omit the flag and the command stays entirely local.
+- **`map --upload` is the only command that sends a description of your source.** (The runtime guard can also report rule detections, which carry route paths and parameter names — see "Runtime guard reporting" below.) It POSTs the same JSON document to `monitor/pulse/input-map/<your site uuid>` so Patchstack can pin protection rules to your app's own parameter names instead of guessing them. What is sent is exactly what `map` prints — a structural description: route paths, parameter/field names, the dependency behind each sink, and file paths with line numbers. **No source code, no file contents, no environment variable values.** It never runs without the flag, it is skipped when no entry points are detected, and a failure to reach Patchstack is reported and ignored rather than failing your build. Omit the flag and the command stays entirely local.
 - **`demo-guide node-serialize` is the read-only companion.** It checks the Host-created site configuration and vulnerable lockfile entry, explains the complete local prepare/run/restart/prove/cleanup sequence, and prints the next exact command. It does not require a deployment and does not change files or contact Patchstack.
 - Patchstack is not WordPress-only. This connector monitors any JS/Node project — Vite, Next.js, plain vanilla JS, anything with a lockfile.
 
@@ -78,7 +78,7 @@ This versioned reference ships inside `@patchstack/connect` and documents each s
 
    Framework-specific placement patterns: https://cdn.patchstack.com/llm.html. The site UUID is public by design — it ships in client-side HTML and is not a secret. The credential is the opposite, and `scan` writes it for you — **there is no manual step, and you should never invent or ask the user for this value**:
 
-- `apiKey` (also `PATCHSTACK_API_KEY`, WP format `{secret}-{oauth.id}`) — one credential for both paths. It authenticates **Pulse ingest** (manifest, attack-surface map, package removal), where it is exchanged for a short-lived token rather than sent directly, and **block-log reporting** through the connector `POST /api/logs/log`, so "Threats blocked" fills in the dashboard.
+- `apiKey` (also `PATCHSTACK_API_KEY`, WP format `{secret}-{oauth.id}`) — one credential for both paths. It authenticates **Pulse ingest** (manifest, attack-surface map, package removal, rule detections), where it is exchanged for a short-lived token rather than sent directly, and **block-log reporting** through the connector `POST /api/logs/log`, so "Threats blocked" fills in the dashboard.
 
 It is server-only. Never put it in the widget tag, client bundles, or public env vars (`NEXT_PUBLIC_*`, etc.). Prefer `PATCHSTACK_API_KEY` in production; `.patchstackrc.json` is fine for local DX. If it is lost, `npx @patchstack/connect login` recovers it via dashboard approval — do not delete the file and re-provision, which would create a second site. Opt out of reporting with `PATCHSTACK_TELEMETRY=off`. If the project must not carry the widget, persist `"widget": false` in `.patchstackrc.json`; otherwise the next scan re-adds it.
 
@@ -105,6 +105,48 @@ It is server-only. Never put it in the widget tag, client bundles, or public env
 - If a step fails, stop and report it. Don't proceed with placeholders.
 - In CI where `.patchstackrc.json` can't be committed, set `PATCHSTACK_SITE_UUID` and `PATCHSTACK_API_KEY` as env vars instead. Precedence: CLI flag → env var → `.patchstackrc.json`. `login` is interactive and refuses to run in CI, so CI always takes its credential from the environment.
 
+## Runtime guard reporting
+
+The runtime guard (`protect`) can report the rules that matched, so the dashboard can show what a rule
+would have stopped while it is still in dry-run. Two separate paths, with different triggers:
+
+- **Blocked requests** go to the connector `POST /api/logs/log`, the same path the WordPress plugin uses,
+  and fill in "Threats blocked". This runs when the guard is holding an `apiKey` and a rule blocked a
+  request. The credential is first exchanged at `POST /oauth/token` (client credentials) for a bearer
+  token; the `apiKey` itself is not sent to the log endpoint. Disable with `PATCHSTACK_TELEMETRY=off`, or
+  `reportFirewallLog: false` in `createProtection`.
+- **Every rule that matched** goes to `monitor/pulse/detections/<your site uuid>` — including matches that
+  blocked, which are reported on both paths. This is **off unless you pass `reportDetections: true`** to
+  `createProtection`; the scaffolded guard does not pass it. It also requires a provisioned site UUID and
+  is disabled by `PATCHSTACK_TELEMETRY=off`. It exists because a rule carrying `dry-run` blocks nothing,
+  so without it nothing distinguishes a rule that is protecting from one that is quietly wrong.
+
+What a detection report contains, per matched rule: the rule id, the request path **with any query string
+removed**, the parameter names that rule reads (from the rule's own definition), which phase matched,
+whether it was enforced, the identifier of the rule bundle in use, and a timestamp. Each batch also
+carries a count of reports dropped when traffic outran the flush, so a partial sample is not read as a
+complete one.
+
+The parameter names are **identifiers, and they name the request region they refer to** — `post.title`,
+`get.redirect_to`, `cookie.session`, `server.HTTP_AUTHORIZATION`. So a rule that inspects a cookie or an
+`Authorization` header sends that cookie's or header's **name**. They are read from the rule's own
+definition, not from your traffic, so they describe what is being screened rather than what any request
+contained.
+
+What it does not contain: **no values of any kind.** Not the value that matched, not the request body,
+and not the value of any header, cookie or query-string parameter — including those of the parameters
+named above. Reports are batched, capped in memory, and dropped rather than retried if Patchstack cannot
+be reached — a reporting failure never delays or fails a request.
+
+Two more endpoints the package can call, for completeness:
+
+- `GET monitor/widget/settings/<your site uuid>` — how `status` tells "this site was deleted on
+  Patchstack" apart from "still active". It sends no credential and nothing about your project; the site
+  UUID in the path is the whole request.
+- `GET api/get-rules/3` — the older rules path, used only when the guard is configured with a `token`
+  instead of a site UUID. The zero-configuration flow provisions a site UUID and uses
+  `monitor/pulse/rules/<uuid>` instead, so this is unreachable unless you pass `token` yourself.
+
 ## Verifying the install
 
 - `npx @patchstack/connect status` re-prints the site UUID and dashboard URL, and checks whether the site still exists on Patchstack (`Site status: active / removed / could not be verified`).