mcprigor 1.4.0 → 1.5.1

package/docs/GETTING-STARTED.md

@@ -126,7 +126,7 @@ mcp-acceptance-tests/
 
 ## Next steps
 
-- [Plain-language cookbook](PLAIN-LANGUAGE-COOKBOOK.md)
+- [Natural-language cookbook](NATURAL-LANGUAGE-COOKBOOK.md)
 - [QA workspace](QA-WORKSPACE.md)
 - [Engineer setup and CI](ENGINEER-SETUP.md)
 - [Troubleshooting](TROUBLESHOOTING.md)

package/docs/GITHUB-ACTION.md

@@ -0,0 +1,82 @@
+# GitHub Action and pull-request reports
+
+> Available since `v1.5.0`; pin `@v1` for the latest 1.x or `@v1.5.0` for full reproducibility.
+
+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,59 @@ Server options:
     Authorization: "Bearer ${env.QA_TOKEN}"
 ```
 
+An HTTP target may fetch a bearer token at run time with `Token from` (a command whose single-line stdout becomes the `Authorization` header), or drive an interactive browser login with `OAuth`:
+
+```text
+Server options:
+  OAuth: oauth
+```
+
+`OAuth: oauth` performs an authorization-code + PKCE browser login once at the start of the run and carries the in-memory session (with automatic refresh) into every test. The block form takes optional `clientId`, `clientSecret` (use `${env.NAME}`), and `scope`. Tokens are never written to disk and are always redacted. See the [Authentication guide](AUTHENTICATION.md).
+
+### Environment variables and secrets
+
+Any string value in a target block — a header, a URL, a `cwd`, an `env` entry, a `Server options` field — may contain `${env.NAME}` placeholders. Before the suite connects, each placeholder is replaced with the value of the operating-system environment variable `NAME`:
+
+```text
+MCP URL: ${env.MCP_URL}
+
+Server options:
+  headers:
+    Authorization: "Bearer ${env.MCP_TOKEN}"
+    X-Api-Key: "${env.API_KEY}"
+```
+
+```bash
+MCP_URL=https://qa.example.com/mcp MCP_TOKEN=... API_KEY=... mcprigor test suite.mcpr
+```
+
+Rules:
+
+- The syntax is exactly `${env.NAME}`. `NAME` is a literal environment-variable name; there is no shell, no command substitution, and no default-value syntax.
+- A placeholder may be embedded in a larger string (`"Bearer ${env.MCP_TOKEN}"`) or be the whole value (`"${env.API_KEY}"`), and a value may contain several placeholders.
+- If `NAME` is not set, the run stops immediately with `Environment variable not found: NAME` — it never sends an empty header or a half-substituted URL.
+- Never write a literal secret into a suite. Keep tokens and keys in the environment (locally) or in CI secrets, and reference them with `${env.NAME}` so the committed `.mcpr` file carries no credentials.
+- Header values are registered with the redactor automatically, so a resolved token never appears in reports, evidence bundles, or published URLs.
+
+The same `${env.NAME}` placeholders work in every target surface: single-server `Server options`, per-server `Server options for "name"` in compositions, and `Target options for "name"` in parity comparisons.
+
+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 +132,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 +151,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 +159,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 +239,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/MCP-SERVER.md

@@ -16,7 +16,7 @@ Or with an explicit root:
 mcprigor serve path/to/project
 ```
 
-The server speaks MCP over stdio. Typical client configuration:
+The server speaks MCP over stdio (`mcp` is an alias for `serve`). Typical client configuration:
 
 ```json
 {

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/{PLAIN-LANGUAGE-COOKBOOK.md → NATURAL-LANGUAGE-COOKBOOK.md}

@@ -1,4 +1,4 @@
-# Plain-language cookbook
+# Natural-language cookbook
 
 Copy a pattern, replace the names and values, then run `mcprigor check FILE`.
 
@@ -187,7 +187,7 @@ Run with `mcprigor parity FILE`.
 
 ## Test a server that needs a bearer token
 
-Point the suite at the deployed endpoint and pass the token through an environment variable. Never paste a real token into a test file.
+Point the suite at the deployed endpoint and pass the token through an environment variable. The `${env.NAME}` placeholder is replaced with the value of the `NAME` environment variable before the suite connects, so no real token ever lives in the test file.
 
 ```text
 MCP Test 1
@@ -210,6 +210,15 @@ Run it with the token in the environment:
 QA_TOKEN=... mcprigor test orders.mcpr
 ```
 
+The placeholder can sit inside a larger string (`"Bearer ${env.QA_TOKEN}"`) or be the whole value, and any header works the same way — API keys, custom tenant headers, and so on:
+
+```text
+Server options:
+  headers:
+    X-Api-Key: "${env.API_KEY}"
+    X-Tenant: "acme"
+```
+
 Three guarantees come with this pattern:
 
 - if `QA_TOKEN` is not set, the run stops with `Environment variable not found: QA_TOKEN` instead of sending an empty header;
@@ -238,7 +247,7 @@ Test: "Search behaves the same"
 
 ## When the token must be fetched first
 
-MCP Rigor does not perform OAuth login flows or token exchanges itself; tests stay deterministic and secrets stay outside test files. When a short-lived token must be acquired (client-credentials exchange, cloud CLI, vault), fetch it in the step before the run:
+When a short-lived token must be acquired non-interactively (client-credentials exchange, cloud CLI, vault), fetch it in the step before the run:
 
 ```bash
 QA_TOKEN=$(curl -s -X POST https://auth.example.com/oauth/token \
@@ -256,7 +265,29 @@ In CI, do the same in the workflow:
   run: npx mcprigor test tests/*.mcpr
 ```
 
-Interactive browser-redirect OAuth is out of scope by design: an acceptance run must be repeatable without a human in the loop.
+For CI and other unattended runs, obtain the token non-interactively as above. When a real user must sign in through a browser, use interactive OAuth instead (next recipe).
+
+## Sign in through the browser (interactive OAuth)
+
+When a server requires a real user login, let MCP Rigor run the browser authorization-code flow once and carry the authorized session — with automatic refresh — into every test in the run:
+
+```text
+MCP URL: https://app.example.com/mcp
+
+Server options:
+  OAuth: oauth
+
+Test: "an authenticated call succeeds"
+  Call tool "find_order" with:
+    orderId: "A-1001"
+  Expect "structuredContent.status" equals "shipped"
+```
+
+```bash
+mcprigor test orders.mcpr
+```
+
+Your browser opens to the identity provider; after you sign in, the tokens are held in memory (never written to disk, always redacted) and reused for the whole suite. For pre-registered clients or specific scopes, use the block form with `clientId`, `clientSecret: "${env.…}"`, and `scope`. Because it needs a human, keep interactive OAuth for local runs and use a non-interactive credential in CI. See the [Authentication guide](AUTHENTICATION.md) for the full flow.
 
 ## Fetch an OAuth token before connecting
 
@@ -302,6 +333,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

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/PUBLISHING.md

@@ -0,0 +1,53 @@
+# Shareable hosted reports
+
+> Available since `1.5.0`.
+
+Turn a test run into a URL anyone can open — no repository access, no CI login:
+
+```bash
+export NETLIFY_AUTH_TOKEN=...   # personal or CI token
+mcprigor publish tests/catalog.mcpr --site your-netlify-site
+```
+
+`publish` runs the suite, builds the readable HTML report **with the clickable request/response session timeline**, deploys it to your Netlify site with the dependency-free digest API, waits until the deploy is live, and prints the shareable URL:
+
+```
+Published report: https://68b1c2--your-site.netlify.app
+```
+
+Each publish is a normal Netlify deploy of your own site, so access control, custom domains, deploy previews, and retention follow your existing hosting configuration. Unchanged files are skipped automatically via content digests.
+
+## Options
+
+```bash
+mcprigor publish suite.mcpr --site SITE [--include-json] [--test NAME] [--env qa]
+mcprigor publish suite.mcpr --out reports/latest
+```
+
+- `--site` — Netlify site ID or name. The token comes only from `NETLIFY_AUTH_TOKEN` (or `MCPRIGOR_PUBLISH_TOKEN`); tokens are never accepted as command-line flags.
+- `--out DIR` — write the same bundle to a local directory instead of (or in addition to) hosting it. Serve it from any static host: S3, GitHub Pages, nginx, an artifact store.
+- `--include-json` — also publish `result.json` for dashboards and programmatic consumers.
+- `--test`, `--env`, `--command`, `--url` — the same run-selection options as `mcprigor test`.
+
+The exit code still reflects the run (`0` passed, `1` failed), so `publish` can replace `test` in a pipeline step that both gates and shares.
+
+## Publishing from the QA workspace UI
+
+The visual workspace (`mcprigor workspace`) exposes the same features without the command line:
+
+- **HTML report** — every finished test run has an `HTML report` button that opens the full report, including the clickable session timeline, in a new tab.
+- **Publish** — start the workspace with hosting configured and a `Publish` button appears next to the export buttons:
+
+  ```bash
+  export MCPRIGOR_PUBLISH_SITE=your-netlify-site
+  export NETLIFY_AUTH_TOKEN=...
+  mcprigor workspace
+  ```
+
+  Clicking it deploys the selected run's report and opens the shareable URL; a `View published ↗` link stays on the run for re-opening or copying. Without both variables the button is hidden and the API answers with a clear configuration message — the token itself never reaches the browser.
+
+## Security
+
+- The report is produced by the same pipeline as `--html`: secrets and configured redaction patterns are removed **before** the report exists.
+- Publishing makes the report as public as the target site. Use a password-protected or team-restricted Netlify site for internal results.
+- The hosting token is read from the environment at the last moment and is never echoed, logged, or stored.

package/docs/QA-GUIDE.md

@@ -1,6 +1,6 @@
 # QA guide
 
-Use this page as a short everyday checklist. For examples, open the [plain-language cookbook](PLAIN-LANGUAGE-COOKBOOK.md).
+Use this page as a short everyday checklist. For examples, open the [natural-language cookbook](NATURAL-LANGUAGE-COOKBOOK.md).
 
 ## Everyday workflow
 
@@ -121,7 +121,7 @@ Use values as `${row.input}` and `${row.expected}`.
 ## Where to go next
 
 - [Getting started](GETTING-STARTED.md)
-- [Plain-language cookbook](PLAIN-LANGUAGE-COOKBOOK.md)
+- [Natural-language cookbook](NATURAL-LANGUAGE-COOKBOOK.md)
 - [Guided authoring](GUIDED-AUTHORING.md)
 - [Data and reusable flows](DATA-AND-REUSE.md)
 - [Troubleshooting](TROUBLESHOOTING.md)

package/docs/QA-WORKSPACE.md

@@ -30,7 +30,7 @@ An empty folder shows a three-step welcome screen. Choose **＋ New test file**
 2. Edit the plain-language scenario. The editor provides syntax highlighting, line numbers, and autocomplete: top-level declarations at the start of a line, actions and assertions when indented, and comparison phrases after `Expect "field"`. Accept with `Tab` or `Enter`; force the list open with `Ctrl+Space`.
 3. Choose **Validate** (`Ctrl/⌘+S` saves, `Ctrl/⌘+Enter` runs). A wording problem highlights the offending line and moves the cursor to it.
 4. Choose **▶ Run tests** or **Parity**.
-5. Review the results panel: per-file pass/fail with durations; select a file for its full report.
+5. Review the results panel: per-file pass/fail with durations; select a file for its full report. Drag either panel divider to resize the file list, editor, and results areas; widths persist across reloads, arrow keys resize a focused divider, and double-click resets the layout.
 
 The editor marks unsaved changes; running or validating saves them first. If the file changed elsewhere after you opened it, the workspace refuses to overwrite it and asks you to reload.
 
@@ -52,6 +52,10 @@ Test runs are recorded in `.mcprigor/workspace-history.jsonl` (most recent 2000
 
 One search box filters all three tabs. It matches suite names, test names, and error text, and highlights matches, so you can answer questions like "when did `delivered` start failing?" without leaving the browser.
 
+Completed runs expose **PDF**, **CSV**, and **JUnit XML** downloads. The Trends tab exports a rich trends PDF, aggregate CSV, or raw history CSV. PDF reports include summary cards, pass-rate visuals, per-test detail, failures, durations, and evidence identifiers.
+
+An **HTML report** button opens the full report — including the clickable request/response session timeline — in a new tab. When the workspace is started with `MCPRIGOR_PUBLISH_SITE` and `NETLIFY_AUTH_TOKEN` set, a **Publish** button also appears: one click hosts the report at a shareable static URL and keeps a `View published ↗` link on the run. See [Shareable hosted reports](PUBLISHING.md).
+
 ## What is available
 
 - Creating, renaming, and editing `.mcpr` suites (YAML and JSON suites are listed and editable too)