mcprigor 1.4.0 → 1.5.0

package/docs/CLI-REFERENCE.md

@@ -31,6 +31,15 @@ mcprigor check tests/acceptance.mcpr
 
 Validates language and configuration without connecting to the server. Alias: `validate`.
 
+### `convert`
+
+```bash
+mcprigor convert tests/acceptance.mcpr --out tests/acceptance.yaml
+mcprigor convert tests/acceptance.mcpr --format json   # prints to stdout without --out
+```
+
+Emits the equivalent YAML or JSON suite for any input format. The natural language and YAML are in strict parity — both compile to the same suite model — so the converted file validates against the suite schema and runs with identical results. Use it to hand suites to programmatic tooling or to see exactly what a `.mcpr` file means.
+
 ### `test`
 
 ```bash
@@ -50,7 +59,8 @@ Common options:
 --github-annotations       Emit ::error/::notice workflow commands
                            (automatic when GITHUB_ACTIONS=true;
                            disable with --no-github-annotations)
---html report.html         Write a readable HTML report
+--html report.html         Write a readable HTML report with a clickable
+                           request/response session timeline
 --json result.json         Write structured JSON
 --junit result.xml         Write JUnit XML
 --evidence DIRECTORY       Save a sanitized evidence bundle
@@ -139,6 +149,40 @@ mcprigor record --out draft.mcpr -- node dist/server.js
 
 Proxies a live MCP stdio session: your client (an agent, MCP Inspector's CLI mode, or any harness) talks to `mcprigor record` on stdin/stdout, and Rigor forwards everything to the real server while logging each `tools/call` exchange. When the session ends it writes a reviewable `.mcpr` draft — one test per call, with deterministic assertions picked from the actual responses (up to three scalar `structuredContent` leaves, falling back to short text content). No AI: the draft is a literal transcription. Review it, prune it, and run it.
 
+## Multi-server compositions
+
+Model the MCP fleet an agent mounts together without overloading parity environments:
+
+```text
+MCP Test 1
+Suite: "Checkout fleet"
+Named server "catalog": node services/catalog.js
+Named server "billing": https://qa.example.com/billing/mcp
+
+Test: "catalog lookup"
+  On server "catalog"
+  Call tool "search" with:
+    query: "widget"
+
+Test: "billing health"
+  On server "billing"
+  Send "ping"
+```
+
+The YAML/JSON equivalent uses a top-level `servers` mapping and `server` on each test. The legacy `target` remains the default and existing suites are unchanged.
+
+Composition governance:
+
+```bash
+mcprigor composition-check fleet.mcpr
+mcprigor composition-discover fleet.mcpr --out mcp.composition.lock.yaml
+mcprigor composition-drift fleet.mcpr --against mcp.composition.lock.yaml --fail-on breaking
+```
+
+The combined lock embeds each server's standard discovery contract, plus cross-server issues and a stable fleet fingerprint. Checks detect duplicate tool names, conflicting tool schemas, duplicate resource URIs/templates, duplicate prompts, server additions/removals, and per-server contract drift.
+
+`composition-drift --fail-on` supports `breaking` (default), `potentially-breaking`, `any`, and `none`, matching the single-server drift gate.
+
 ## Project environments
 
 Define shared targets once in `mcprigor.config.yaml` (found in the working directory or any parent):
@@ -165,6 +209,74 @@ mcprigor drift suite.mcpr --against mcp.lock.yaml --env prod
 
 The selected environment replaces the suite's declared target and is announced in the output. With a `default:` set, plain `mcprigor test suite.mcpr` uses it automatically. `--command`/`--url` overrides still win over the environment when both are given. An environment value can be a command string, a URL string, or a mapping with `server`/`cwd`/`env` (stdio) or `url`/`headers`/`token from` (HTTP).
 
+## Deterministic security audit
+
+Run the built-in security and permissions probe pack against a suite target:
+
+```bash
+mcprigor audit suite.mcpr --pdf security-audit.pdf --json security-audit.json
+mcprigor audit --url https://qa.example.com/mcp --fail-on high
+```
+
+The default, non-destructive pack probes malformed JSON-RPC parameters, unknown/tool-name spoofing, oversized payloads, and path-traversal resource URIs. It also inventories every advertised tool for prompt-injection and secret-canary testing.
+
+Tool calls are never guessed or executed by default. Explicitly allow only reviewed, non-destructive tools:
+
+```bash
+mcprigor audit suite.mcpr --allow-tool search --allow-tool summarize
+```
+
+Allowed tools receive a fixed prompt-injection string containing a deterministic canary. MCP Rigor checks whether the tool followed/reflected the payload or exposed the canary. The canary is redacted from report evidence.
+
+Outputs:
+
+- terminal or `--markdown`
+- `--json audit.json`
+- `--csv audit.csv`
+- `--pdf audit.pdf` — rich scorecard with grade, severity cards, and finding detail
+- `--fail-on critical|high|medium|low|none` (default: `high`)
+
+Scoring deducts 35 for critical, 20 for high, 10 for medium, and 4 for low findings. Skipped probes do not affect the score and are shown with the exact opt-in needed.
+
+## Coverage gate
+
+```bash
+mcprigor coverage suite.mcpr --fail-under 80 --json coverage.json
+```
+
+Discovers the live MCP contract and reports untested tools, resources, resource templates, prompts, input properties, and enum/`oneOf`/`anyOf` branches. `--fail-under` accepts 0–100; `--markdown` produces a pull-request-friendly report. See [Coverage](COVERAGE.md).
+
+## Scheduled monitoring
+
+```bash
+mcprigor monitor prod.mcpr --every 15m --notify https://hooks.example/rigor
+```
+
+Runs an HTTP suite immediately and on a fixed interval, appends every result to trend history, and posts transition webhooks. `--notify-on` accepts `change` (default), `failure`, `recovery`, or `always`; `--max-runs` bounds cron/CI checks. See [Scheduled monitoring](MONITORING.md).
+
+## GitHub Action
+
+Use `FusionOnePlatform/mcprigor@v1` to run suites, contract drift, flaky warnings, job summaries, and an update-in-place pull-request comment. See [GitHub Action](GITHUB-ACTION.md).
+
+## Shareable hosted reports
+
+```bash
+mcprigor publish suite.mcpr --site your-netlify-site
+mcprigor publish suite.mcpr --out reports/latest
+```
+
+Runs the suite and hosts the HTML report (with the session timeline) at a shareable static URL, or writes a local bundle for any static host. The hosting token comes only from `NETLIFY_AUTH_TOKEN`. See [Shareable hosted reports](PUBLISHING.md).
+
+## Latency budgets and regression gate
+
+```bash
+mcprigor test suite.mcpr --fail-on-regression
+```
+
+- `Expect the call to finish within 800ms` fails one step when the live call exceeds the limit (`MCP-PERF-001`).
+- `Budget: p95 500ms over 20 calls` (suite-wide) and `Budget for "test name": p50 300ms` are judged after every run against recorded history plus the current run; a blown budget fails the run.
+- `--fail-on-regression` compares each passed test against the median of its recent history and fails when a test runs slower than 1.5x baseline (50 ms floor, needs 5 recorded samples). No thresholds to maintain — the baseline is the trend.
+
 ## Export reports (PDF, CSV, JUnit)
 
 Every run can be exported in machine- and human-friendly formats:

package/docs/COVERAGE.md

@@ -0,0 +1,37 @@
+# MCP surface and schema coverage
+
+> Available since `1.5.0`.
+
+`mcprigor coverage` answers which parts of a live MCP contract have no test evidence.
+
+```bash
+mcprigor coverage tests/catalog.mcpr
+mcprigor coverage tests/catalog.mcpr --fail-under 80 --json reports/coverage.json
+```
+
+MCP Rigor discovers the suite target, compares the live contract with static test steps, and measures these deterministic coverage units:
+
+- every advertised tool called at least once;
+- every fixed resource URI read at least once;
+- every resource template matched by a resource read;
+- every prompt requested at least once;
+- input-schema properties supplied by at least one call;
+- each `enum`, `oneOf`, and `anyOf` branch exercised by at least one tool argument set.
+
+The score is covered units divided by all discovered units. Surfaces with no discovered items report 100% and do not penalize servers that do not expose that capability.
+
+## CI gate
+
+```bash
+mcprigor coverage tests/catalog.mcpr --fail-under 80
+```
+
+The command exits nonzero when the score is below the threshold. Valid thresholds range from 0 to 100.
+
+Use `--markdown` for a pull-request-friendly table and `--json` for dashboards or historical retention.
+
+## What coverage proves
+
+Coverage proves that a test suite references observed contract surfaces and supplies arguments that reach structural schema branches. It does not claim semantic correctness, authorization coverage, or execution-path coverage inside the server. Pair it with assertions, contract drift, the security audit, and performance budgets.
+
+Coverage is calculated against the live discovered contract so newly added tools or schema options immediately appear as uncovered—even before they break an existing test.

package/docs/ENGINEER-SETUP.md

@@ -13,7 +13,7 @@ npm install --save-dev mcprigor
 For reproducible CI runs, pin an exact version in `package.json` and update it deliberately:
 
 ```json
-{ "devDependencies": { "mcprigor": "1.4.0" } }
+{ "devDependencies": { "mcprigor": "1.5.0" } }
 ```
 
 Release notes and tarball checksums for each version are on the [GitHub releases page](https://github.com/FusionOnePlatform/mcprigor/releases).

package/docs/EVIDENCE.md

@@ -31,6 +31,17 @@ mcprigor evidence-compare .mcprigor/run-001 .mcprigor/run-002
 
 Comparison checks the result and normalized trace fingerprints. Matching fingerprints indicate semantically identical evidence under the current normalization policy.
 
+## Interactive session timeline
+
+`mcprigor test suite.mcpr --html report.html` embeds a HAR-style session timeline directly in the readable report. Every recorded event appears in order:
+
+- connect, close, and diagnostic markers;
+- one row per JSON-RPC call, pairing the request with its response;
+- per-call duration in milliseconds;
+- failed calls flagged in red with the server's error payload.
+
+Click any row to expand its captured request parameters and response body. The timeline is self-contained (no network, no external assets) and uses the same redaction as evidence bundles, so secrets never reach the report. `--html` records a trace even without `--evidence`; combine both to keep the raw and normalized JSONL alongside the visual timeline.
+
 ## Events
 
 - `session.connect.start`

package/docs/GITHUB-ACTION.md

@@ -0,0 +1,82 @@
+# GitHub Action and pull-request reports
+
+> Available on `main`; publish by pinning the next MCP Rigor release tag.
+
+The MCP Rigor Action runs deterministic suites, optionally gates contract drift, includes flaky-history warnings, writes a rich job summary, and creates or updates one pull-request comment.
+
+## Workflow
+
+```yaml
+name: MCP Rigor
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  rigor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: FusionOnePlatform/mcprigor@v1
+        with:
+          suites: |
+            tests/**/*.mcpr
+          lock: mcp.lock.yaml
+          fail-on: breaking
+```
+
+The comment contains a suite table with pass/fail/skipped totals and durations, the classified contract drift report, flaky-test warnings when history exists, and collapsed failure detail. A stable HTML marker makes subsequent runs update the same comment rather than spamming the PR.
+
+## Inputs
+
+| Input | Default | Meaning |
+|---|---|---|
+| `suites` | `tests/**/*.mcpr` | Newline-separated paths or glob patterns |
+| `lock` | empty | Optional contract lock checked against the first matched suite |
+| `fail-on` | `breaking` | `breaking`, `potentially-breaking`, `any`, or `none` |
+| `node-version` | `22` | Node.js version used by the Action |
+| `version` | `latest` | MCP Rigor npm version installed for the run |
+| `comment` | `true` | Post/update a pull-request comment |
+| `flaky` | `true` | Add warnings when `.mcprigor/workspace-history.jsonl` exists |
+| `artifact` | `true` | Upload the report, drift markdown, and per-suite JSON as a build artifact |
+| `artifact-name` | `mcprigor-report` | Name of the uploaded artifact |
+
+Outputs:
+
+- `status` — `passed` or `failed`;
+- `report` — path to the combined Markdown report;
+- `drift-report` — path to the standalone contract drift Markdown (empty without `lock`);
+- `artifact-dir` — directory containing the report, drift markdown, and per-suite JSON results.
+
+## Contract drift as a PR artifact
+
+When `lock` is set, the Action runs `mcprigor drift --markdown` and produces two things automatically:
+
+1. a **Contract drift** section inside the PR comment and job summary;
+2. a standalone `drift.md` artifact recording the suite, lock file, gate, gate result, and the full classified diff.
+
+The whole report directory is uploaded with `actions/upload-artifact` (disable with `artifact: false`), so reviewers can download the exact drift evidence for a merge decision, and compliance flows can retain it beyond comment history. Consume `drift-report` from a later step to post the drift anywhere else:
+
+```yaml
+- id: rigor
+  uses: FusionOnePlatform/mcprigor@v1
+  with:
+    suites: tests/**/*.mcpr
+    lock: mcp.lock.yaml
+- run: cat "${{ steps.rigor.outputs.drift-report }}"
+  if: steps.rigor.outputs.drift-report != ''
+```
+
+
+## Fork safety
+
+The Action does not run arbitrary PR comment content. Test targets still come from repository suites, so use normal GitHub approval controls for workflows from untrusted forks. Pull-request comments require `pull-requests: write`; when the token cannot write (common for forks), set `comment: false` and rely on the job summary.
+
+Pin a full release tag for the strongest supply-chain reproducibility:
+
+```yaml
+- uses: FusionOnePlatform/mcprigor@v1.5.0
+```

package/docs/LANGUAGE-SPEC.md

@@ -1,9 +1,11 @@
 # MCP Test Language 1
 
-Status: compatibility-stable frontend for MCP Rigor 0.12.
+Status: compatibility-stable frontend for MCP Rigor 1.x.
 
 The `.mcpr` language and YAML compile to the same `Suite` runtime model. Every user-authored YAML capability has a deterministic plain-language equivalent; YAML remains available for generated files and programmatic integrations rather than being a more powerful test format.
 
+Parity is enforced, not aspirational: every `.mcpr` construct compiles to a suite that also validates against the YAML/JSON schema, and `mcprigor convert my-tests.mcpr --out my-tests.yaml` (or `--format json`) emits that equivalent file. The converted suite reloads to the identical suite model and produces the same run results — the regression suite converts each shipped example, reloads it from YAML, and compares runs.
+
 ## Design goals
 
 - Readable by QA professionals without programming experience
@@ -62,6 +64,23 @@ Server options:
     Authorization: "Bearer ${env.QA_TOKEN}"
 ```
 
+Multi-server compositions use named server declarations and per-test routing:
+
+```text
+Named server "catalog": node services/catalog.js
+Named server "billing": https://qa.example.com/billing/mcp
+
+Server options for "billing":
+  headers:
+    X-Tenant: qa
+
+Test: "catalog lookup"
+  On server "catalog"
+  Call tool "search"
+```
+
+The YAML equivalent is a top-level `servers` mapping plus `server` on a test. A composition requires at least two named servers, and an unknown `On server` name is rejected during compilation.
+
 Parity targets use the same connection grammar:
 
 ```text
@@ -77,6 +96,8 @@ Suite-level YAML fields have direct equivalents:
 
 ```text
 Default timeout: 10 seconds
+Budget: p95 500ms over 20 calls
+Budget for "order lookup": p50 300ms over 20 calls
 Redact: "secret-value", "token-value"
 Snapshots: snapshots.json
 Ignore snapshot paths: "$.createdAt", "$.requestId"
@@ -94,11 +115,7 @@ Client behavior:
       approved: true
 ```
 
-## Imports
-
-```
-
-Per-test scripted responses (override `Client behavior:` for one test):
+Per-test scripted responses override `Client behavior:` for one test:
 
 ```text
 When the server asks for input, respond "accept" with:
@@ -106,7 +123,10 @@ When the server asks for input, respond "accept" with:
 When the server asks for input, respond "decline"
 When the server requests sampling, respond "scripted text"
 ```
-text
+
+## Imports
+
+```text
 Import flows from "./shared/customer-flows.mcpr"
 ```
 
@@ -183,6 +203,7 @@ Send "ping"
 ```text
 Expect it succeeds
 Expect an error
+Expect the call to finish within 800ms
 Expect "structuredContent.total" equals 2
 Expect "content[0].text" contains "complete"
 Expect "items" exists

package/docs/MONITORING.md

@@ -0,0 +1,62 @@
+# Scheduled production monitoring
+
+> Available since `1.5.0`.
+
+Turn an HTTP MCP suite into a continuous production check:
+
+```bash
+mcprigor monitor tests/prod.mcpr \
+  --every 15m \
+  --notify https://alerts.example.com/hooks/mcprigor
+```
+
+The monitor runs immediately, then at the fixed interval until stopped. Durations accept `ms`, `s`, `m`, or `h`, with a minimum interval of one second.
+
+For operational safety, monitoring requires a Streamable HTTP target. It refuses stdio suites so a long-running process cannot repeatedly spawn local commands by accident.
+
+## Notification policies
+
+```bash
+mcprigor monitor tests/prod.mcpr --every 5m --notify URL --notify-on change
+```
+
+`--notify-on` supports:
+
+- `change` (default): first failure, then failure/recovery transitions;
+- `failure`: every failed run;
+- `recovery`: transitions from failed to passed;
+- `always`: every run.
+
+Webhook requests are JSON POSTs with a 15-second timeout:
+
+```json
+{
+  "source": "mcprigor",
+  "event": "monitor.failure",
+  "suite": "tests/prod.mcpr",
+  "run": 12,
+  "status": "failed",
+  "startedAt": "2026-08-30T12:00:00.000Z",
+  "durationMs": 842,
+  "summary": { "passed": 7, "failed": 1, "skipped": 0, "blocked": 0 },
+  "failures": [{ "name": "order lookup", "error": "..." }]
+}
+```
+
+A non-2xx webhook response fails the monitor with `MCP-MONITOR-003`; notification loss is never silently ignored.
+
+## History and trends
+
+Every monitoring run appends to `.mcprigor/workspace-history.jsonl`, so existing `mcprigor trends`, PDF/CSV exports, flaky detection, latency budgets, and regression analysis include production monitoring evidence.
+
+## Bounded runs
+
+For smoke tests, cron jobs, and CI validation:
+
+```bash
+mcprigor monitor tests/prod.mcpr --every 1m --max-runs 1
+```
+
+`SIGINT` and `SIGTERM` stop the interval cleanly after active MCP sessions shut down.
+
+Use an authenticated suite target (`headers` or `Token from:`), retain history according to your evidence policy, and send webhooks only to reviewed HTTPS endpoints.

package/docs/MULTI-SERVER-COMPOSITIONS.md

@@ -0,0 +1,103 @@
+# Multi-server compositions
+
+> Available since `1.5.0`.
+
+Real MCP clients mount several servers together. MCP Rigor compositions test each named server and govern the combined tool, resource, and prompt namespace as one fleet.
+
+## Declare named servers
+
+```text
+MCP Test 1
+Suite: "Checkout fleet"
+
+Named server "catalog": node services/catalog.js
+Named server "billing": https://qa.example.com/billing/mcp
+
+Server options for "billing":
+  Token from: node scripts/get-qa-token.mjs
+
+Test: "catalog search works"
+  On server "catalog"
+  Call tool "search" with:
+    query: "widget"
+  Expect "structuredContent.total" is a number
+
+Test: "billing responds"
+  On server "billing"
+  Send "ping"
+  Expect it succeeds
+```
+
+`On server` routes every action in that test to the selected server. Tests without `On server` continue to use the legacy/default `Server:` or `MCP URL:` target. Cross-test dependencies and exported values continue to work across named servers.
+
+YAML parity:
+
+```yaml
+version: 1
+name: Checkout fleet
+target:
+  transport: stdio
+  command: node
+  args: [services/gateway.js]
+servers:
+  catalog:
+    transport: stdio
+    command: node
+    args: [services/catalog.js]
+  billing:
+    transport: streamable-http
+    url: https://qa.example.com/billing/mcp
+tests:
+  - name: catalog search works
+    server: catalog
+    steps:
+      - tool:
+          name: search
+          arguments: { query: widget }
+```
+
+Unknown server names fail validation before a test starts.
+
+## Check the live composition
+
+```bash
+mcprigor composition-check tests/fleet.mcpr
+```
+
+The check discovers all named servers and reports:
+
+- `MCP-COMP-001`: duplicate tool name;
+- `MCP-COMP-002`: conflicting input/output schemas for the same tool (breaking);
+- `MCP-COMP-003`: duplicate resource URI or URI template (breaking);
+- `MCP-COMP-004`: duplicate prompt name.
+
+MCP Rigor reports collisions; it never silently renames or chooses a winning server.
+
+## Create a combined fleet lock
+
+```bash
+mcprigor composition-discover tests/fleet.mcpr \
+  --out contracts/checkout.composition.lock.yaml
+```
+
+The lock embeds each named server's ordinary discovery contract, the cross-server issue set, and a stable fleet fingerprint. Volatile discovery timestamps and diagnostics do not change the combined fingerprint. Writes are atomic: all servers must be discovered successfully before the previous lock is replaced.
+
+## Gate fleet drift in CI
+
+```bash
+mcprigor composition-drift tests/fleet.mcpr \
+  --against contracts/checkout.composition.lock.yaml \
+  --fail-on breaking
+```
+
+The drift report combines:
+
+- server additions and removals;
+- each server's tool/resource/prompt contract changes;
+- newly introduced or resolved cross-server conflicts.
+
+`--fail-on` accepts `breaking` (default), `potentially-breaking`, `any`, or `none`, matching the single-server drift gate. Add `--json report.json` for machine-readable CI evidence.
+
+## Composition versus parity
+
+Use a **composition** when several servers are mounted together and their namespaces interact. Use **transport parity** when the same logical server is exposed through alternate targets such as local stdio and deployed HTTP. The `servers` and `targets` fields remain intentionally separate.

package/docs/PERFORMANCE-GOVERNANCE.md

@@ -0,0 +1,85 @@
+# Performance governance
+
+> Available since `1.5.0`.
+
+MCP Rigor turns MCP latency into a deterministic release gate. It supports immediate per-call limits, percentile budgets over recorded history, and automatic regression detection against each test's historical baseline.
+
+## Limit one call
+
+Add a latency assertion after an action:
+
+```text
+Test: "order lookup stays interactive"
+  Call tool "find_order" with:
+    orderId: "A-1001"
+  Expect the call to finish within 800ms
+```
+
+The measured duration covers the live MCP request and response. A call over the limit fails with `MCP-PERF-001` and reports the measured and allowed duration.
+
+YAML parity:
+
+```yaml
+- tool:
+    name: find_order
+    arguments:
+      orderId: A-1001
+  assert:
+    maxDurationMs: 800
+```
+
+## Set percentile budgets
+
+A percentile budget uses successful durations from recent recorded runs plus the current run:
+
+```text
+Budget: p95 500ms over 20 calls
+Budget for "order lookup stays interactive": p50 300ms over 20 calls
+```
+
+- A suite-wide budget applies independently to every test.
+- A named budget applies only to that test.
+- MCP Rigor uses the deterministic nearest-rank percentile.
+- Fewer than three usable samples reports the budget as pending instead of guessing.
+- A measured percentile over budget fails the CLI run.
+
+YAML parity:
+
+```yaml
+budgets:
+  - test: "*"
+    percentile: 95
+    maxMs: 500
+    window: 20
+  - test: order lookup stays interactive
+    percentile: 50
+    maxMs: 300
+    window: 20
+```
+
+## Fail on regression without maintaining thresholds
+
+```bash
+mcprigor test tests/orders.mcpr --fail-on-regression
+```
+
+For every successful test, MCP Rigor compares the current duration with the median of its latest successful history. The gate requires at least five samples and reports a regression when the current run exceeds both:
+
+- 1.5× the historical median; and
+- the historical median plus 50 ms.
+
+The absolute floor prevents very small tests from failing because of ordinary scheduler jitter.
+
+## CI example
+
+```yaml
+- run: npx mcprigor test tests/orders.mcpr --fail-on-regression --junit reports/orders.xml
+```
+
+Explicit budgets answer “is this fast enough?” The regression gate answers “did this release make it materially slower?” Teams commonly use both.
+
+## History source
+
+CLI, QA workspace, and MCP-server-driven test runs append to `.mcprigor/workspace-history.jsonl`. The same data powers `mcprigor trends`, CSV/PDF trend exports, flaky detection, percentile budgets, and regression baselines.
+
+Commit the test and its budget declarations. Treat history as a CI artifact or retained workspace file according to your evidence policy.

package/docs/PLAIN-LANGUAGE-COOKBOOK.md

@@ -302,6 +302,34 @@ Test: "summaries embed the sampled text"
 
 Suite-wide defaults live in a `Client behavior:` block; these per-test lines override them for one test.
 
+## Set latency budgets and catch slow releases
+
+Fail a single call that takes too long:
+
+```text
+Test: "order lookup is fast"
+  Call tool "find_order" with:
+    orderId: "A-1001"
+  Expect the call to finish within 800ms
+```
+
+Set suite-level budgets measured as percentiles over recorded run history (the same history behind `mcprigor trends`):
+
+```text
+Budget: p95 500ms over 20 calls
+Budget for "order lookup is fast": p50 300ms
+```
+
+Budgets are judged after each `mcprigor test` run and fail the run when a percentile exceeds its budget. Until enough history exists they report as pending instead of guessing.
+
+Gate CI on latency regressions against the trend baseline — no budget numbers needed:
+
+```bash
+mcprigor test suite.mcpr --fail-on-regression
+```
+
+A test regresses when it runs slower than 1.5x its historical median (with a 50 ms floor so micro-tests don't trip on jitter).
+
 ## Match a snapshot
 
 ```text