qa-engineer 0.10.0 → 0.12.0

package/skills/qa-api/scripts/qa-tool.mjs

@@ -29,6 +29,7 @@
 // `node qa-tool.mjs …`, which needs none.
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -38,7 +39,7 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 const USAGE = `usage: node qa-tool.mjs <tool> <subcommand> [args]
 
   analysis     parse artifacts, classify errors, validate contracts, diff-guard,
-               read .qa/context.md, render an HTML report, print the footer
+              read .qa/context.md, render an HTML report, print the footer
   diagnostics  root cause, timeline, priority, repair plans, release readiness
   playwright   normalize a Playwright report or summarize a trace
 
@@ -53,15 +54,26 @@ examples:
 /**
  * Where the engine is, and how we found it.
  *
- * Ordered by cost: a bundled copy needs no resolution and no network, a
- * node_modules copy needs no network, and npx needs both on first use. Reporting
- * *which* one answered matters when a skill degrades — "the engine is missing" and
- * "the engine is being fetched" are different problems.
+ * Ordered by cost: a bundled copy needs no resolution and no network, a shared copy
+ * needs one stat per ancestor, a node_modules copy needs no network, and npx needs both
+ * on first use. Reporting *which* one answered matters when a skill degrades — "the
+ * engine is missing" and "the engine is being fetched" are different problems.
+ *
+ * The shared lookup is what lets one skill directory serve a project, a workspace, and a
+ * machine-wide install without knowing which installed it. Walking up for
+ * `.qa-engineer/engine` finds a workspace install from a skill inside the repository,
+ * and finds a global install from a skill linked into an agent's user-level directory —
+ * `~/.claude/skills/qa-explore` walks up to `~`, where `~/.qa-engineer/engine` is.
  */
 function resolveEngine() {
   const bundled = path.join(here, 'lib', 'bin', 'qa-engine.mjs');
   if (fs.existsSync(bundled)) return { kind: 'bundled', command: [process.execPath, bundled] };
 
+  for (const root of candidateSharedRoots()) {
+    const shared = path.join(root, 'bin', 'qa-engine.mjs');
+    if (fs.existsSync(shared)) return { kind: 'shared', command: [process.execPath, shared] };
+  }
+
   for (const base of candidateModuleRoots()) {
     const installed = path.join(base, 'qa-engineer', 'packages', 'engine', 'bin', 'qa-engine.mjs');
     if (fs.existsSync(installed)) {
@@ -75,6 +87,30 @@ function resolveEngine() {
   };
 }
 
+/** Shared engine directories worth checking, most specific first. */
+function candidateSharedRoots() {
+  const roots = [];
+
+  // An explicit home wins over anything discovered, so a user who moved the install can
+  // rely on it rather than on whatever the walk happens to find first.
+  const override = process.env.QA_ENGINEER_HOME;
+  if (override && override.trim()) roots.push(path.join(path.resolve(override.trim()), 'engine'));
+
+  let dir = here;
+  for (let depth = 0; depth < 12; depth += 1) {
+    roots.push(path.join(dir, '.qa-engineer', 'engine'));
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // The default machine home, for the case where the skill lives outside it entirely.
+  const home = os.homedir();
+  if (home) roots.push(path.join(home, '.qa-engineer', 'engine'));
+
+  return roots;
+}
+
 /** node_modules directories worth checking, nearest first. */
 function candidateModuleRoots() {
   const roots = [];

package/skills/qa-audit/scripts/qa-tool.mjs

@@ -29,6 +29,7 @@
 // `node qa-tool.mjs …`, which needs none.
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -38,7 +39,7 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 const USAGE = `usage: node qa-tool.mjs <tool> <subcommand> [args]
 
   analysis     parse artifacts, classify errors, validate contracts, diff-guard,
-               read .qa/context.md, render an HTML report, print the footer
+              read .qa/context.md, render an HTML report, print the footer
   diagnostics  root cause, timeline, priority, repair plans, release readiness
   playwright   normalize a Playwright report or summarize a trace
 
@@ -53,15 +54,26 @@ examples:
 /**
  * Where the engine is, and how we found it.
  *
- * Ordered by cost: a bundled copy needs no resolution and no network, a
- * node_modules copy needs no network, and npx needs both on first use. Reporting
- * *which* one answered matters when a skill degrades — "the engine is missing" and
- * "the engine is being fetched" are different problems.
+ * Ordered by cost: a bundled copy needs no resolution and no network, a shared copy
+ * needs one stat per ancestor, a node_modules copy needs no network, and npx needs both
+ * on first use. Reporting *which* one answered matters when a skill degrades — "the
+ * engine is missing" and "the engine is being fetched" are different problems.
+ *
+ * The shared lookup is what lets one skill directory serve a project, a workspace, and a
+ * machine-wide install without knowing which installed it. Walking up for
+ * `.qa-engineer/engine` finds a workspace install from a skill inside the repository,
+ * and finds a global install from a skill linked into an agent's user-level directory —
+ * `~/.claude/skills/qa-explore` walks up to `~`, where `~/.qa-engineer/engine` is.
  */
 function resolveEngine() {
   const bundled = path.join(here, 'lib', 'bin', 'qa-engine.mjs');
   if (fs.existsSync(bundled)) return { kind: 'bundled', command: [process.execPath, bundled] };
 
+  for (const root of candidateSharedRoots()) {
+    const shared = path.join(root, 'bin', 'qa-engine.mjs');
+    if (fs.existsSync(shared)) return { kind: 'shared', command: [process.execPath, shared] };
+  }
+
   for (const base of candidateModuleRoots()) {
     const installed = path.join(base, 'qa-engineer', 'packages', 'engine', 'bin', 'qa-engine.mjs');
     if (fs.existsSync(installed)) {
@@ -75,6 +87,30 @@ function resolveEngine() {
   };
 }
 
+/** Shared engine directories worth checking, most specific first. */
+function candidateSharedRoots() {
+  const roots = [];
+
+  // An explicit home wins over anything discovered, so a user who moved the install can
+  // rely on it rather than on whatever the walk happens to find first.
+  const override = process.env.QA_ENGINEER_HOME;
+  if (override && override.trim()) roots.push(path.join(path.resolve(override.trim()), 'engine'));
+
+  let dir = here;
+  for (let depth = 0; depth < 12; depth += 1) {
+    roots.push(path.join(dir, '.qa-engineer', 'engine'));
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // The default machine home, for the case where the skill lives outside it entirely.
+  const home = os.homedir();
+  if (home) roots.push(path.join(home, '.qa-engineer', 'engine'));
+
+  return roots;
+}
+
 /** node_modules directories worth checking, nearest first. */
 function candidateModuleRoots() {
   const roots = [];

package/skills/qa-debug/SKILL.md

@@ -21,6 +21,8 @@ Investigate a failure the way an experienced QA engineer would: gather the evide
 
 Do not propose or make code changes here — that is `/qa-fix`, which consumes this skill's output. Do not run tests (`/qa-run`) or generate them (`/qa-generate`). This skill explains a failure; it does not repair it.
 
+This skill is often entered **automatically**: a red `/qa-run` hands its validated execution result straight here rather than asking the user to type the next command. That changes nothing about the investigation — the input is the same artifact a human would have passed — but it does bind this skill to the far end of the handoff: the chain stops here. Do not dispatch onward, and do not re-run the suite to gather more evidence; when the evidence is insufficient, say what is missing and name the command that would capture it.
+
 ## Inputs
 
 - The user's request, which follows in the conversation: the failing test, run, or artifact.
@@ -35,6 +37,7 @@ Do not propose or make code changes here — that is `/qa-fix`, which consumes t
 | When | Load |
 | --- | --- |
 | Following the investigation end to end | [references/investigation-workflow.md](references/investigation-workflow.md) |
+| Being entered automatically from a red run, and where the chain stops | [references/failure-handoff.md](references/failure-handoff.md) |
 | Classifying the root cause | [references/root-cause-analysis.md](references/root-cause-analysis.md), [references/failure-taxonomy.md](references/failure-taxonomy.md) |
 | Reconstructing the sequence of events | [references/timeline-builder.md](references/timeline-builder.md) |
 | Assigning severity, priority, and owner | [references/finding-prioritization.md](references/finding-prioritization.md) |

package/skills/qa-debug/references/failure-handoff.md

@@ -0,0 +1,44 @@
+<!-- synced-from: shared/execution/failure-handoff.md — do not edit; edit the source and run: node scripts/sync-shared.mjs --write -->
+# Failure Handoff
+
+What an execution skill does the moment a run goes red: it hands the completed result to the diagnostic skill **automatically**, by command name, and shows the diagnosis alongside the run. A red run whose only output is "1 failed — try `/qa-debug`" makes the reader do the one step they were always going to do, and it makes them do it without the run's own knowledge of what was captured and where.
+
+This is the pack's single, deliberately narrow exception to composition-by-recommendation: everywhere else a skill ends by *naming* the next command. The exception exists because a failure is the one outcome where the next step is not a choice.
+
+## When it fires
+
+| Run status | Handoff |
+| --- | --- |
+| `failed` | Automatic: dispatch the diagnostic command with the execution result |
+| `errored` | Automatic: the run itself broke, and *why* is the whole question |
+| `passed` with flaky tests | No dispatch. The run is green and nobody is blocked; recommend the flakiness command instead |
+| `passed`, `no-tests-run` | No dispatch. There is nothing to diagnose |
+| `blocked` | No dispatch. No run was attempted, so there is no failure — the block itself is the finding |
+
+## The rules that keep it bounded
+
+1. **One hop, forward only.** The diagnostic skill may not dispatch onward and may not re-enter execution. A run that diagnoses that re-runs that diagnoses is a loop no user asked for; the chain is exactly two links and then it stops with a recommendation.
+2. **The successor must not mutate.** Diagnosis reads artifacts and explains. Anything that edits a file, a test, or a config stays a recommendation the user approves — automation is for *learning* why the run failed, never for acting on the answer.
+3. **Dispatch by name, never by path.** The handoff invokes the diagnostic command; it does not load the sibling skill's files, which are not guaranteed to exist at runtime.
+4. **The artifact goes first.** The execution result is written and validated against its contract *before* the handoff, and the handoff passes its path. The successor consumes a contract-conformant artifact, exactly as it would from a human invocation — there is no privileged in-memory channel between the two, so the automatic path and the manual path produce the same diagnosis.
+5. **Announce it, and let the user decline.** The run says it is diagnosing before it does. An explicit "no debug", "just run it", or a request for the run only suppresses the handoff, and the suppression is recorded rather than silently obeyed.
+6. **Degrade honestly.** The diagnostic command may be unavailable — not installed, or its engine missing. The handoff is then recorded as unavailable with the reason, and the recommendation to run it stands. A failed handoff never changes the run's status: the run's own numbers are already final.
+7. **The run's verdict is never revised.** The diagnosis explains a failure; it cannot argue it away. Nothing the successor concludes edits the execution result — a "the test is just flaky" diagnosis leaves a `failed` run `failed`.
+
+## What is recorded
+
+The execution result carries the handoff as data, so the automatic step is auditable rather than something that happened in the transcript:
+
+| Field | Meaning |
+| --- | --- |
+| `skill` | The successor, by command name |
+| `command` | The exact command dispatched, with the artifact path |
+| `artifact` | The execution result handed over |
+| `status` | `dispatched`, `skipped` (the user declined), or `unavailable` (it could not run) |
+| `reason` | Required for `skipped` and `unavailable` — why the diagnosis is not there |
+
+A red result that records no handoff at all is incomplete: the reader cannot tell whether the diagnosis was declined, impossible, or forgotten.
+
+## Why the failure evidence floor comes first
+
+The handoff is only worth as much as what the run captured. The diagnostic layer reads screenshots, traces, and logs; a run that failed with none of them produces a diagnosis of "insufficient evidence, re-run with tracing" — the exact round trip the automatic handoff exists to remove. That is why the floor (in the command-builder module) is a floor and not a strategy preference: the two features are one feature, seen from each end.

package/skills/qa-debug/scripts/qa-tool.mjs

@@ -29,6 +29,7 @@
 // `node qa-tool.mjs …`, which needs none.
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -38,7 +39,7 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 const USAGE = `usage: node qa-tool.mjs <tool> <subcommand> [args]
 
   analysis     parse artifacts, classify errors, validate contracts, diff-guard,
-               read .qa/context.md, render an HTML report, print the footer
+              read .qa/context.md, render an HTML report, print the footer
   diagnostics  root cause, timeline, priority, repair plans, release readiness
   playwright   normalize a Playwright report or summarize a trace
 
@@ -53,15 +54,26 @@ examples:
 /**
  * Where the engine is, and how we found it.
  *
- * Ordered by cost: a bundled copy needs no resolution and no network, a
- * node_modules copy needs no network, and npx needs both on first use. Reporting
- * *which* one answered matters when a skill degrades — "the engine is missing" and
- * "the engine is being fetched" are different problems.
+ * Ordered by cost: a bundled copy needs no resolution and no network, a shared copy
+ * needs one stat per ancestor, a node_modules copy needs no network, and npx needs both
+ * on first use. Reporting *which* one answered matters when a skill degrades — "the
+ * engine is missing" and "the engine is being fetched" are different problems.
+ *
+ * The shared lookup is what lets one skill directory serve a project, a workspace, and a
+ * machine-wide install without knowing which installed it. Walking up for
+ * `.qa-engineer/engine` finds a workspace install from a skill inside the repository,
+ * and finds a global install from a skill linked into an agent's user-level directory —
+ * `~/.claude/skills/qa-explore` walks up to `~`, where `~/.qa-engineer/engine` is.
  */
 function resolveEngine() {
   const bundled = path.join(here, 'lib', 'bin', 'qa-engine.mjs');
   if (fs.existsSync(bundled)) return { kind: 'bundled', command: [process.execPath, bundled] };
 
+  for (const root of candidateSharedRoots()) {
+    const shared = path.join(root, 'bin', 'qa-engine.mjs');
+    if (fs.existsSync(shared)) return { kind: 'shared', command: [process.execPath, shared] };
+  }
+
   for (const base of candidateModuleRoots()) {
     const installed = path.join(base, 'qa-engineer', 'packages', 'engine', 'bin', 'qa-engine.mjs');
     if (fs.existsSync(installed)) {
@@ -75,6 +87,30 @@ function resolveEngine() {
   };
 }
 
+/** Shared engine directories worth checking, most specific first. */
+function candidateSharedRoots() {
+  const roots = [];
+
+  // An explicit home wins over anything discovered, so a user who moved the install can
+  // rely on it rather than on whatever the walk happens to find first.
+  const override = process.env.QA_ENGINEER_HOME;
+  if (override && override.trim()) roots.push(path.join(path.resolve(override.trim()), 'engine'));
+
+  let dir = here;
+  for (let depth = 0; depth < 12; depth += 1) {
+    roots.push(path.join(dir, '.qa-engineer', 'engine'));
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // The default machine home, for the case where the skill lives outside it entirely.
+  const home = os.homedir();
+  if (home) roots.push(path.join(home, '.qa-engineer', 'engine'));
+
+  return roots;
+}
+
 /** node_modules directories worth checking, nearest first. */
 function candidateModuleRoots() {
   const roots = [];

package/skills/qa-explore/SKILL.md

@@ -58,12 +58,18 @@ Load only what the situation requires:
 1. **Intake.** Confirm URL. Parse attached test cases into a numbered checklist ([test-case-intake.md](references/test-case-intake.md)). Note known bugs as hypotheses to validate. Create a run id and artifact directory `qa-artifacts/explore-<run-id>/`.
 2. **Session.** Select a browser adapter ([browser-adapters.md](references/browser-adapters.md)). Navigate to the URL. If a login wall appears, **stop** and ask the user to sign in; never type credentials or OTPs. Baseline console errors and resource entries.
 3. **Functional.** Execute attached cases first, then surface-by-surface exploration per [pipeline.md](references/pipeline.md). After every action: DOM-verify, then capture evidence on failure or notable finding ([evidence-capture.md](references/evidence-capture.md)).
-4. **API audit.** Collect resource entries; replay exact app URLs in-page; classify and record findings ([api-replay.md](references/api-replay.md)).
+4. **API audit.** Capture a HAR, then run `analysis network` on it — **never count requests, time them, or spot duplicates by eye.** Replay exact app URLs in-page where a call needs confirming. The parser says what happened; you decide which of its flags matter to this product and write those as findings ([api-replay.md](references/api-replay.md)).
 5. **Performance.** Measure payloads, cold vs warm, long tasks / vitals signals under controlled conditions ([performance.md](references/performance.md)).
 6. **Security (client).** Run the client-side pass only — token storage, PII in URLs/payloads, error leakage, headers, optional read-only IDOR probe when in scope ([security.md](references/security.md)). No destructive tests.
 7. **UI / UX.** Check empty/loading/error states, consistency, mobile viewport spot-check; optional persona lens if the user named a role.
 8. **Optional DB.** Only if the user provided access: capture UI values with timestamps; query; separate data vs presentation bugs. Skip entirely otherwise and note "DB validation not in scope".
-9. **Report.** Assign stable IDs and severities ([finding-taxonomy.md](references/finding-taxonomy.md)). Every finding must include proof. Write `explore-result.json` **first** — including `scope` (what you set out to check, what you touched, and every boundary of the run with its reason) and findings written for a reader who has never seen the product — then validate it against the contract and **render** the HTML from it with the report renderer (see Tooling); never type the HTML. Write the Markdown from the same result ([report-pipeline.md](references/report-pipeline.md)). Include "what works well" and a prioritized fix order.
+9. **Report.** Assign stable IDs and severities ([finding-taxonomy.md](references/finding-taxonomy.md)). Every finding must include proof. Then, in this order ([report-pipeline.md](references/report-pipeline.md)):
+   1. Write `explore-result.json` — `artifacts[]` for every captured file, `scope` (what you set out to check, what you touched, and every boundary of the run with its reason), `executive` when a non-engineer will read it, and findings written for a reader who has never seen the product.
+   2. **Validate** it against the contract.
+   3. **Verify the artifacts** — `artifacts verify` must pass before anything is rendered. A missing or zero-byte file is reported, never quietly dropped.
+   4. **Build the bundle** with `report-bundle` — a portable folder that opens offline, with every link verified. That folder is the deliverable; point the user at its `index.html`. Never type HTML.
+
+   Include "what works well" and a prioritized fix order. Only report a score for a dimension the run actually measured.
 10. **Iterate.** On user feedback: validate live, add evidence, bump report version, never renumber IDs. After three stuck browser attempts on the same blocker, stop and escalate with findings.
 
 ## Guardrails
@@ -84,21 +90,31 @@ Invoke the bundled engine through its launcher, as documented in [references/det
 | Tool | Invocation | Output | Fallback |
 | --- | --- | --- | --- |
 | Contract self-check | `node <SKILL_DIR>/scripts/qa-tool.mjs analysis validate <explore-result.json> <SKILL_DIR>/contracts/explore-result.schema.json` | `{valid, errors}` — run this before rendering | None: an invalid result is not a report |
-| HTML report renderer | `node <SKILL_DIR>/scripts/qa-tool.mjs analysis report-html <explore-result.json> --out explore-report.html` | The complete self-contained report: every finding's current vs expected behaviour, repro, fix direction, evidence, and the attribution footer | Write the HTML by hand from the contract fields, rendering all of them, and say the report was not machine-rendered |
+| Artifact check | `node <SKILL_DIR>/scripts/qa-tool.mjs artifacts verify <explore-result.json>` | `{ok, stats, missing}`; exit 1 when a file a finding points at is absent or empty. Run it **before** rendering | List the missing files in the report yourself; never delete the evidence entry to make it pass |
+| Portable report bundle | `node <SKILL_DIR>/scripts/qa-tool.mjs analysis report-bundle <explore-result.json> --out report --zip` | **The canonical output.** A folder — `index.html` + `assets/` — that opens offline in any browser, with every link verified to resolve inside it, plus a `.zip` to send. | **None.** Report that the engine is missing and stop |
+| Single-file HTML | `node <SKILL_DIR>/scripts/qa-tool.mjs analysis report-html <explore-result.json> --embed --out explore-report.html` | The complete self-contained report — nav, search, charts, timeline, expandable findings, evidence, attribution. `--embed` inlines images; `--mode full\|executive\|developer\|artifact` picks the audience | **None.** Report that the engine is missing and stop — a hand-written report is the failure this design removes |
+| Other renderings | `node <SKILL_DIR>/scripts/qa-tool.mjs analysis report-export <explore-result.json> --format <markdown\|sarif\|junit\|csv\|json\|bundle> --out <file>` | The same validated result in the format the destination reads | Write the Markdown by hand; skip the machine formats |
+| Canonical schema | `node <SKILL_DIR>/scripts/qa-tool.mjs analysis report-schema` · `… analysis report-versions` | The producer-neutral contract any agent writes to, and the schema/theme/renderer versions in force | Use the skill's own `contracts/explore-result.schema.json` |
+| Network analysis | `node <SKILL_DIR>/scripts/qa-tool.mjs analysis network <capture.har> [--slow-ms N]` | The report's `network` block, counted and flagged by the parser: totals, per-endpoint timing and size, and an `issue` on each — `failed`, `slow`, `polling`, `duplicate`, `n-plus-one`, `large-payload`, `uncached`. Drop it straight into the result | Read `performance.getEntriesByType('resource')` and say in the report that counts were observed rather than parsed |
 | Secret redaction | `node <SKILL_DIR>/scripts/qa-tool.mjs analysis redact <file>` | The file with credentials and tokens masked, for evidence excerpts | Redact by hand before the excerpt is written |
 | Failure classification | `node <SKILL_DIR>/scripts/qa-tool.mjs analysis classify "<error message>"` | `{classification, confidence, reason}` for a console or network error | Classify per [finding-taxonomy.md](references/finding-taxonomy.md) |
 
 A missing `qa-tool.mjs` means the engine is not installed; run `qa doctor`.
 
-**The HTML is rendered, not written.** The result JSON is the source of truth for the report, and `report-html` reads it. Hand-typing the page is how the first live run silently dropped `actual`, `expected`, and `fixDirection` from every finding while the JSON held all three.
+**You produce structured data; the pack produces every document.** The result JSON is the source of truth and every format is rendered from it. You never write HTML, CSS, or styling of any kind — the contract has no field to carry a presentation hint, which is what makes a report from this skill identical whichever agent ran it. Hand-typing the page is how the first live run silently dropped `actual`, `expected`, and `fixDirection` from every finding while the JSON held all three.
+
+**Register artifacts; do not inline paths.** Every captured file gets an `artifacts[]` entry, and evidence points at it by `artifactId`. Paths are relative to the result JSON. That is what makes `artifacts verify` meaningful and what stopped the second live run's screenshots from rendering as broken images.
 
 ## Output
 
-Write under `qa-artifacts/explore-<run-id>/`:
+Write under `qa-artifacts/explore-<run-id>/`, so the whole run folder moves as a unit:
+
+- `explore-result.json` — machine-readable result conforming to [contracts/explore-result.schema.json](contracts/explore-result.schema.json); written first, and the source of every rendering below
+- `report/` — **the deliverable.** A portable bundle written by `report-bundle`: `index.html`, `report.json`, `report.md`, `manifest.json`, and `assets/`. It opens offline in any browser and every link is verified to resolve inside it. `--zip` adds `report.zip` for sending.
+- `screenshots/`, `network/`, `console/`, `dom/` — proof, registered in `artifacts[]` and referenced by `artifactId`; the bundle copies these into its own `assets/` tree
+
+Point the user at `report/index.html`. A hosted preview — a Claude Artifact, a Cursor preview, any cloud viewer — is an optional convenience that expires; it must never be presented as the deliverable.
 
-- `screenshots/` — proof images referenced by findings
-- `explore-result.json` — machine-readable result conforming to [contracts/explore-result.schema.json](contracts/explore-result.schema.json); written first, and the source of the two renderings below
-- `explore-report.html` — the report a person reads, **rendered** from the JSON by `report-html`
-- `explore-report.md` — the same content as Markdown, with the rendered attribution footer appended
+On request, also `report-html --embed` for one self-contained file, or `report-export` to SARIF (code-scanning viewers), JUnit (CI), or CSV (a tracking sheet). There is no PDF writer: the HTML has a print stylesheet that forces findings open and prints link targets, so **Print → Save as PDF** is the supported path.
 
-Validate the JSON against the schema before rendering, and again before declaring completion. Present a short prose verdict (severity counts + top findings) in the conversation, and point to the artifact paths.
+Validate the JSON and run `artifacts verify` before rendering, and again before declaring completion. Present a short prose verdict (severity counts + top findings) in the conversation, and point to the artifact paths.