@post-print/agent-test 0.3.4 → 0.3.6

package/dist/html-report.js

@@ -1,8 +1,8 @@
 import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
-import { compareSuiteReports, } from "./compare.js";
-import { formatUsageStats, summarizeReportResults, summarizeReports } from "./suite-summary.js";
+import { describeCompareOutcome } from "./compare-scenario.js";
+import { summarizeReports } from "./suite-summary.js";
 function escapeHtml(value) {
     return value
         .replaceAll("&", "&")
@@ -11,11 +11,19 @@ function escapeHtml(value) {
         .replaceAll('"', """)
         .replaceAll("'", "'");
 }
+const INTEGER_FORMAT = new Intl.NumberFormat("en-US", { maximumFractionDigits: 0 });
+const DECIMAL_FORMAT = new Intl.NumberFormat("en-US", {
+    minimumFractionDigits: 1,
+    maximumFractionDigits: 1,
+});
+function formatInteger(value) {
+    return INTEGER_FORMAT.format(Math.round(value));
+}
 function formatDuration(ms) {
     if (ms < 1000) {
-        return `${Math.round(ms)}ms`;
+        return `${formatInteger(ms)}ms`;
     }
-    return `${(ms / 1000).toFixed(1)}s`;
+    return `${DECIMAL_FORMAT.format(ms / 1000)}s`;
 }
 function statusLabel(result) {
     if (result.skipped) {
@@ -29,62 +37,95 @@ function statusClass(result) {
     }
     return result.passed ? "status-passed" : "status-failed";
 }
+const MISSING_REQUIREMENT = {
+    label: "Missing requirement",
+    hint: "A required string did not appear in assistant text, commands, or tool results.",
+};
+const FORBIDDEN_BEHAVIOR = {
+    label: "Forbidden behavior",
+    hint: "The agent did something it was told not to do.",
+};
+const MISSING_COMMAND = {
+    label: "Missing command",
+    hint: "An expected command never ran.",
+};
+const MISSING_TOOL = {
+    label: "Missing tool call",
+    hint: "An expected tool was never invoked.",
+};
+const FORBIDDEN_TOOL = {
+    label: "Forbidden tool call",
+    hint: "A tool the scenario forbids was invoked.",
+};
+const MISSING_SKILL = {
+    label: "Missing skill",
+    hint: "The agent did not read a skill it was expected to use.",
+};
+const UNEXPECTED_SKILL = {
+    label: "Unexpected skill",
+    hint: "The agent read a skill it should have avoided.",
+};
+const MISSING_READ_PATH = {
+    label: "Missing read path",
+    hint: "Expected a Read tool call whose args mention this path fragment (registry-first / grounding).",
+};
+const FORBIDDEN_READ_PATH = {
+    label: "Forbidden read path",
+    hint: "A successful Read returned content from a path the scenario forbids (miss attempts do not fail).",
+};
+const ROUTING = {
+    label: "Routing",
+    hint: "The routing announcement did not match expectations.",
+};
 /** Human-readable label + one-line explanation for the matcher codes assertRubric/judge emit. */
 const MATCHER_LABELS = {
     runAgent: { label: "Agent run", hint: "The agent session itself failed or was cut short." },
-    must: {
-        label: "Missing requirement",
-        hint: "A required behavior did not show up in the transcript.",
-    },
-    mustNot: { label: "Forbidden behavior", hint: "The agent did something it was told not to do." },
-    mustRun: { label: "Missing command", hint: "An expected command never ran." },
-    mustCallTool: {
-        label: "Missing tool call",
-        hint: "An expected tool was never invoked.",
-    },
-    mustNotCallTool: {
-        label: "Forbidden tool call",
-        hint: "A tool the scenario forbids was invoked.",
-    },
-    toHaveCalledTool: {
-        label: "Missing tool call",
-        hint: "An expected tool was never invoked.",
-    },
-    toHaveNotCalledTool: {
-        label: "Forbidden tool call",
-        hint: "A tool the scenario forbids was invoked.",
-    },
-    mustInvokeSkill: {
-        label: "Missing skill",
-        hint: "The agent didn't read a skill it was expected to use.",
-    },
-    mustNotInvokeSkill: {
-        label: "Unexpected skill",
-        hint: "The agent read a skill it should have avoided.",
-    },
-    mustReadPath: {
-        label: "Missing read path",
-        hint: "Expected a Read tool call whose args mention this path fragment (registry-first / grounding).",
+    liveScenario: {
+        label: "Isolated scenario",
+        hint: "The scenario subprocess exited before it wrote a result.",
     },
-    mustNotReadPath: {
-        label: "Forbidden read path",
-        hint: "A successful Read returned content from a path the scenario forbids (miss attempts do not fail).",
+    must: MISSING_REQUIREMENT,
+    mustInclude: MISSING_REQUIREMENT,
+    mustNot: FORBIDDEN_BEHAVIOR,
+    mustNotInclude: FORBIDDEN_BEHAVIOR,
+    mustRun: MISSING_COMMAND,
+    toHaveRunCommand: MISSING_COMMAND,
+    mustCallTool: MISSING_TOOL,
+    toHaveCalledTool: MISSING_TOOL,
+    mustNotCallTool: FORBIDDEN_TOOL,
+    toHaveNotCalledTool: FORBIDDEN_TOOL,
+    mustInvokeSkill: MISSING_SKILL,
+    toHaveInvokedSkill: MISSING_SKILL,
+    mustNotInvokeSkill: UNEXPECTED_SKILL,
+    toHaveNotInvokedSkill: UNEXPECTED_SKILL,
+    mustReadPath: MISSING_READ_PATH,
+    toHaveReadPath: MISSING_READ_PATH,
+    mustNotReadPath: FORBIDDEN_READ_PATH,
+    toHaveNotReadPath: FORBIDDEN_READ_PATH,
+    routingBlock: ROUTING,
+    toIncludeRoutingBlock: ROUTING,
+    toHaveRoutingBlockBeforeTools: ROUTING,
+    toHaveTier: ROUTING,
+    toHaveHandsOnTier: ROUTING,
+    toHaveHandsOnTierBeforeTools: ROUTING,
+    toHaveReviewDepth: {
+        label: "Review depth",
+        hint: "The review depth announcement did not match the rubric.",
     },
-    toHaveReadPath: {
-        label: "Missing read path",
-        hint: "Expected a Read tool call whose args mention this path fragment (registry-first / grounding).",
-    },
-    toHaveNotReadPath: {
-        label: "Forbidden read path",
-        hint: "A successful Read returned content from a path the scenario forbids (miss attempts do not fail).",
-    },
-    routingBlock: { label: "Routing", hint: "The routing announcement didn't match expectations." },
     workingTreeLeak: {
         label: "Working tree leak",
-        hint: "The agent's edits leaked outside its isolated worktree.",
+        hint: "The agent used a path outside the sealed workspace, or edited the caller checkout.",
     },
     recordTrace: { label: "Recording failed", hint: "Saving the trace to disk failed." },
     judge: { label: "Judge", hint: "The LLM judge flagged this scenario." },
+    faster: {
+        label: "Faster arm",
+        hint: "The named arm must finish in less time.",
+    },
+    cheaper: {
+        label: "Cheaper arm",
+        hint: "The named arm must use fewer tokens.",
+    },
 };
 function humanizeMatcher(matcher) {
     const [base] = matcher.split(":");
@@ -153,23 +194,45 @@ function buildOrderedTimeline(trace) {
     }
     return items.sort((a, b) => a.seq - b.seq);
 }
-function renderChat(trace) {
+function promptAlreadyInTrace(trace, prompt) {
+    return (trace?.messages.some((message) => message.role === "user" && message.content.trim() === prompt) ?? false);
+}
+function renderPromptBubble(prompt, trace) {
+    const text = prompt?.trim();
+    if (!text || promptAlreadyInTrace(trace, text)) {
+        return "";
+    }
+    return renderMessageBubble({ role: "user", content: text });
+}
+function renderChat(trace, prompt) {
+    const promptBubble = renderPromptBubble(prompt, trace);
     if (!trace) {
+        if (promptBubble) {
+            return `<div class="chat">${promptBubble}</div>`;
+        }
         return `<p class="empty">No transcript recorded for this scenario.</p>`;
     }
     const parts = [];
     const timeline = buildOrderedTimeline(trace);
     if (timeline) {
         parts.push(`<div class="chat">`);
+        if (promptBubble) {
+            parts.push(promptBubble);
+        }
         for (const item of timeline) {
             parts.push(item.kind === "message" ? renderMessageBubble(item.message) : renderToolCallCard(item.call));
         }
         parts.push(`</div>`);
     }
-    else if (trace.messages.length > 0 || trace.toolCalls.length > 0) {
-        parts.push(`<p class="empty note">Emission order wasn't recorded for this trace — messages and tool calls are shown in separate groups below.</p>`);
-        if (trace.messages.length > 0) {
+    else if (trace.messages.length > 0 || trace.toolCalls.length > 0 || promptBubble) {
+        if (!timeline && (trace.messages.length > 0 || trace.toolCalls.length > 0)) {
+            parts.push(`<p class="empty note">Emission order wasn't recorded for this trace — messages and tool calls are shown in separate groups below.</p>`);
+        }
+        if (promptBubble || trace.messages.length > 0) {
             parts.push(`<div class="chat">`);
+            if (promptBubble) {
+                parts.push(promptBubble);
+            }
             for (const message of trace.messages) {
                 parts.push(renderMessageBubble(message));
             }
@@ -243,14 +306,14 @@ function formatTokensBadge(result) {
         return undefined;
     }
     if (typeof usage.totalTokens === "number") {
-        return `${usage.totalTokens} tok`;
+        return `${formatInteger(usage.totalTokens)} tokens`;
     }
     const parts = [];
     if (typeof usage.inputTokens === "number") {
-        parts.push(`in ${usage.inputTokens}`);
+        parts.push(`in ${formatInteger(usage.inputTokens)}`);
     }
     if (typeof usage.outputTokens === "number") {
-        parts.push(`out ${usage.outputTokens}`);
+        parts.push(`out ${formatInteger(usage.outputTokens)}`);
     }
     return parts.length > 0 ? parts.join(" · ") : undefined;
 }
@@ -271,7 +334,7 @@ function renderUsageDetail(usage) {
         return "";
     }
     const items = present
-        .map(([label, value]) => `<div class="meta-item"><span class="meta-key">${escapeHtml(label)}</span><span class="meta-val">${value}</span></div>`)
+        .map(([label, value]) => `<div class="meta-item"><span class="meta-key">${escapeHtml(label)}</span><span class="meta-val">${formatInteger(value ?? 0)}</span></div>`)
         .join("");
     return `<section class="scenario-meta"><h3>Token usage</h3><div class="meta-grid">${items}</div></section>`;
 }
@@ -282,62 +345,66 @@ function renderTraceMeta(result) {
     }
     const skills = trace.skillsInvoked?.length ? trace.skillsInvoked.join(", ") : "(none)";
     const items = [
-        ["Messages", String(trace.messages.length)],
-        ["Tool calls", String(trace.toolCalls.length)],
+        ["Messages", formatInteger(trace.messages.length)],
+        ["Tool calls", formatInteger(trace.toolCalls.length)],
         ["Skills invoked", skills],
         ["Routing tier", trace.routing?.tier ?? "(none)"],
     ];
     if (result.attempts !== undefined && result.attempts > 1) {
-        items.push(["Attempts", String(result.attempts)]);
+        items.push(["Attempts", formatInteger(result.attempts)]);
     }
     const html = items
         .map(([label, value]) => `<div class="meta-item"><span class="meta-key">${escapeHtml(label)}</span><span class="meta-val">${escapeHtml(value)}</span></div>`)
         .join("");
     return `<section class="scenario-meta"><h3>Trace stats</h3><div class="meta-grid">${html}</div></section>`;
 }
-function renderUsageStatsBlock(usage, title = "Token usage") {
-    if (!usage) {
+function costItem(label, detail, value) {
+    return `<div class="cost-item"><span class="cost-value">${escapeHtml(value)}</span><span class="cost-label">${escapeHtml(label)}</span><span class="cost-detail">${escapeHtml(detail)}</span></div>`;
+}
+function renderCostSection(usage) {
+    if (!usage || usage.sumTotalTokens === undefined) {
         return "";
     }
-    const rows = [
-        ["Scenarios with usage", String(usage.scenariosWithUsage)],
-    ];
-    if (usage.sumTotalTokens !== undefined) {
-        rows.push(["Sum totalTokens", String(usage.sumTotalTokens)]);
-    }
-    if (usage.p50TotalTokens !== undefined) {
-        rows.push(["p50 totalTokens", String(usage.p50TotalTokens)]);
-    }
-    if (usage.p95TotalTokens !== undefined) {
-        rows.push(["p95 totalTokens", String(usage.p95TotalTokens)]);
-    }
+    const items = [costItem("Total", "Cost of this run", formatInteger(usage.sumTotalTokens))];
     if (usage.sumInputTokens !== undefined) {
-        rows.push(["Sum input", String(usage.sumInputTokens)]);
+        items.push(costItem("In", "Prompt and context the host sent", formatInteger(usage.sumInputTokens)));
     }
     if (usage.sumOutputTokens !== undefined) {
-        rows.push(["Sum output", String(usage.sumOutputTokens)]);
+        items.push(costItem("Out", "Text the agent wrote", formatInteger(usage.sumOutputTokens)));
     }
-    const items = rows
-        .map(([label, value]) => `<div class="meta-item"><span class="meta-key">${escapeHtml(label)}</span><span class="meta-val">${escapeHtml(value)}</span></div>`)
-        .join("");
-    return `<section class="usage-summary"><h3>${escapeHtml(title)}</h3><div class="meta-grid">${items}</div><p class="usage-compact muted">${escapeHtml(formatUsageStats(usage))}</p></section>`;
+    if (usage.scenariosWithUsage > 1 && usage.p50TotalTokens !== undefined) {
+        items.push(costItem("Typical", "Middle scenario. Half cost less than this.", formatInteger(usage.p50TotalTokens)));
+    }
+    if (usage.scenariosWithUsage > 1 && usage.maxTotalTokens !== undefined) {
+        items.push(costItem("Largest", "Heaviest scenario", formatInteger(usage.maxTotalTokens)));
+    }
+    return `<section class="cost" aria-labelledby="cost-heading">
+  <h2 id="cost-heading">Token cost</h2>
+  <p class="cost-lede">Tokens are cost, not the verdict. Pass and fail sit on each scenario.</p>
+  <div class="cost-grid">${items.join("")}</div>
+</section>`;
 }
 function formatSigned(value) {
     if (value === undefined) {
         return "n/a";
     }
     if (value > 0) {
-        return `+${value}`;
+        return `+${formatInteger(value)}`;
+    }
+    if (value < 0) {
+        return `-${formatInteger(Math.abs(value))}`;
     }
-    return String(value);
+    return formatInteger(value);
 }
-function passCell(passed, skipped) {
-    if (skipped) {
-        return `<span class="badge status-skipped">skip</span>`;
+function formatSignedDuration(deltaMs) {
+    if (deltaMs === undefined) {
+        return "n/a";
+    }
+    if (deltaMs === 0) {
+        return formatDuration(0);
     }
-    return passed
-        ? `<span class="badge status-passed">pass</span>`
-        : `<span class="badge status-failed">fail</span>`;
+    const sign = deltaMs > 0 ? "+" : "-";
+    return `${sign}${formatDuration(Math.abs(deltaMs))}`;
 }
 function deltaClass(value) {
     if (value === undefined || value === 0) {
@@ -345,122 +412,181 @@ function deltaClass(value) {
     }
     return value > 0 ? "delta-up" : "delta-down";
 }
-function compareScenarioLabel(row) {
-    if (row.aScenario && row.bScenario && row.aScenario !== row.bScenario) {
-        return `${row.scenario}<br><span class="muted compare-aliases">A: ${escapeHtml(row.aScenario)}<br>B: ${escapeHtml(row.bScenario)}</span>`;
-    }
-    return escapeHtml(row.scenario);
-}
-/** Render an A/B compare table (fragment — no document chrome). */
-export function renderCompareHtmlSection(report) {
-    const rows = report.paired
-        .map((row) => {
-        const regression = row.a.passed && !row.b.passed;
-        const improvement = !row.a.passed && row.b.passed;
-        const rowClass = regression
-            ? "compare-regress"
-            : improvement
-                ? "compare-improve"
-                : row.deltas.passedChanged
-                    ? "compare-changed"
-                    : "";
-        return `
-<tr class="${rowClass}">
-  <td class="compare-name">${compareScenarioLabel(row)}</td>
-  <td>${passCell(row.a.passed, row.a.skipped)}</td>
-  <td>${passCell(row.b.passed, row.b.skipped)}</td>
-  <td class="${deltaClass(row.deltas.durationMs)}">${escapeHtml(formatSigned(row.deltas.durationMs))}</td>
-  <td class="${deltaClass(row.deltas.toolCallCount)}">${escapeHtml(formatSigned(row.deltas.toolCallCount))}</td>
-  <td class="${deltaClass(row.deltas.skillCount)}">${escapeHtml(formatSigned(row.deltas.skillCount))}</td>
-  <td class="${deltaClass(row.deltas.registryHopCount)}">${escapeHtml(formatSigned(row.deltas.registryHopCount))}</td>
-  <td class="${deltaClass(row.deltas.totalTokens)}">${escapeHtml(formatSigned(row.deltas.totalTokens))}</td>
+function armDurationMs(arm) {
+    return typeof arm.durationMs === "number" ? arm.durationMs : undefined;
+}
+function armToolCount(arm) {
+    return arm.trace ? arm.trace.toolCalls.length : undefined;
+}
+function formatArmDuration(arm) {
+    const ms = armDurationMs(arm);
+    return ms === undefined ? "n/a" : formatDuration(ms);
+}
+function formatArmTokens(arm, key) {
+    const usage = arm.trace?.usage;
+    const value = key === "total"
+        ? usage?.totalTokens
+        : key === "input"
+            ? usage?.inputTokens
+            : usage?.outputTokens;
+    return typeof value === "number" ? formatInteger(value) : "n/a";
+}
+function tokenDelta(a, b, key) {
+    const pick = (arm) => {
+        const usage = arm.trace?.usage;
+        return key === "total"
+            ? usage?.totalTokens
+            : key === "input"
+                ? usage?.inputTokens
+                : usage?.outputTokens;
+    };
+    const aValue = pick(a);
+    const bValue = pick(b);
+    if (typeof aValue !== "number" || typeof bValue !== "number") {
+        return undefined;
+    }
+    return bValue - aValue;
+}
+function winnerCellClass(delta, side) {
+    if (delta === undefined || delta === 0) {
+        return "";
+    }
+    if (side === "a") {
+        return delta > 0 ? "is-better" : "is-worse";
+    }
+    return delta < 0 ? "is-better" : "is-worse";
+}
+function renderCompareMetricRow(label, aText, bText, delta, deltaText) {
+    return `<tr>
+  <th scope="row">${escapeHtml(label)}</th>
+  <td class="${winnerCellClass(delta, "a")}">${escapeHtml(aText)}</td>
+  <td class="${winnerCellClass(delta, "b")}">${escapeHtml(bText)}</td>
+  <td class="${deltaClass(delta)}">${escapeHtml(deltaText)}</td>
 </tr>`;
-    })
-        .join("\n");
-    const onlyA = report.onlyInA.length > 0
-        ? `<p class="muted">Only in A (${escapeHtml(report.aLabel)}): ${report.onlyInA.map((n) => escapeHtml(n)).join(", ")}</p>`
-        : "";
-    const onlyB = report.onlyInB.length > 0
-        ? `<p class="muted">Only in B (${escapeHtml(report.bLabel)}): ${report.onlyInB.map((n) => escapeHtml(n)).join(", ")}</p>`
+}
+function renderCompareMetrics(result) {
+    const compare = result.compare;
+    if (!compare) {
+        return "";
+    }
+    const aMs = armDurationMs(compare.a);
+    const bMs = armDurationMs(compare.b);
+    const durationDelta = aMs !== undefined && bMs !== undefined ? bMs - aMs : undefined;
+    const aTools = armToolCount(compare.a);
+    const bTools = armToolCount(compare.b);
+    const toolDelta = aTools !== undefined && bTools !== undefined ? bTools - aTools : undefined;
+    const totalDelta = tokenDelta(compare.a, compare.b, "total");
+    const callouts = describeCompareOutcome(compare);
+    const calloutList = callouts.length > 0
+        ? `<ul class="compare-callouts">${callouts.map((line) => `<li>${escapeHtml(line)}</li>`).join("")}</ul>`
         : "";
     return `
 <section class="compare">
   <header class="compare-header">
-    <h2>A/B compare</h2>
-    <p class="muted">${escapeHtml(report.aLabel)} → ${escapeHtml(report.bLabel)} · ${report.summary.pairedCount} paired · regressions ${report.summary.passRegressions} · improvements ${report.summary.passImprovements}</p>
+    <h3>Comparison</h3>
+    <p class="muted">${escapeHtml(compare.a.label)} vs ${escapeHtml(compare.b.label)}. Δ is B minus A. A lower time and a lower token count is better.</p>
   </header>
-  <div class="compare-summary meta-grid">
-    <div class="meta-item"><span class="meta-key">Mean Δ durationMs</span><span class="meta-val">${escapeHtml(formatSigned(report.summary.meanDurationDeltaMs !== undefined ? Math.round(report.summary.meanDurationDeltaMs) : undefined))}</span></div>
-    <div class="meta-item"><span class="meta-key">Mean Δ tools</span><span class="meta-val">${escapeHtml(formatSigned(report.summary.meanToolCallDelta !== undefined ? Math.round(report.summary.meanToolCallDelta) : undefined))}</span></div>
-    <div class="meta-item"><span class="meta-key">Mean Δ totalTokens</span><span class="meta-val">${escapeHtml(formatSigned(report.summary.meanTotalTokensDelta !== undefined ? Math.round(report.summary.meanTotalTokensDelta) : undefined))}</span></div>
-  </div>
-  ${onlyA}
-  ${onlyB}
+  ${calloutList}
   <div class="compare-table-wrap">
     <table class="compare-table">
       <thead>
         <tr>
-          <th>Scenario</th>
-          <th>A</th>
-          <th>B</th>
-          <th>Δ duration</th>
-          <th>Δ tools</th>
-          <th>Δ skills</th>
-          <th>Δ registry</th>
-          <th>Δ tokens</th>
+          <th>Metric</th>
+          <th>${escapeHtml(compare.a.label)}</th>
+          <th>${escapeHtml(compare.b.label)}</th>
+          <th>Δ</th>
         </tr>
       </thead>
       <tbody>
-        ${rows}
+        ${renderCompareMetricRow("Duration", formatArmDuration(compare.a), formatArmDuration(compare.b), durationDelta, formatSignedDuration(durationDelta))}
+        ${renderCompareMetricRow("Tokens", formatArmTokens(compare.a, "total"), formatArmTokens(compare.b, "total"), totalDelta, formatSigned(totalDelta))}
+        ${renderCompareMetricRow("In", formatArmTokens(compare.a, "input"), formatArmTokens(compare.b, "input"), tokenDelta(compare.a, compare.b, "input"), formatSigned(tokenDelta(compare.a, compare.b, "input")))}
+        ${renderCompareMetricRow("Out", formatArmTokens(compare.a, "output"), formatArmTokens(compare.b, "output"), tokenDelta(compare.a, compare.b, "output"), formatSigned(tokenDelta(compare.a, compare.b, "output")))}
+        ${renderCompareMetricRow("Tools", aTools === undefined ? "n/a" : formatInteger(aTools), bTools === undefined ? "n/a" : formatInteger(bTools), toolDelta, formatSigned(toolDelta))}
       </tbody>
     </table>
   </div>
 </section>`;
 }
-/** Standalone compare HTML document (written next to compare-report.json / .md). */
-export function renderCompareHtmlReport(report, meta = {}) {
-    const generatedAt = meta.generatedAt ?? new Date();
-    return `<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8" />
-<meta name="viewport" content="width=device-width, initial-scale=1" />
-<title>agent-test compare — ${escapeHtml(report.aLabel)} vs ${escapeHtml(report.bLabel)}</title>
-<style>${sharedReportCss()}</style>
-</head>
-<body>
-<main>
-  <header class="report-header">
-    <h1>agent-test compare</h1>
-    <span class="report-kicker">${escapeHtml(report.aLabel)} vs ${escapeHtml(report.bLabel)}</span>
+function renderArmMetrics(arm) {
+    const parts = [];
+    const ms = armDurationMs(arm);
+    if (ms !== undefined) {
+        parts.push(formatDuration(ms));
+    }
+    const tokens = formatArmTokens(arm, "total");
+    if (tokens !== "n/a") {
+        parts.push(`${tokens} tokens`);
+    }
+    const tools = armToolCount(arm);
+    if (tools !== undefined) {
+        parts.push(tools === 1 ? "1 tool" : `${formatInteger(tools)} tools`);
+    }
+    if (parts.length === 0) {
+        return "";
+    }
+    return `<p class="compare-arm-metrics">${escapeHtml(parts.join(" · "))}</p>`;
+}
+function renderArmColumn(arm, side) {
+    const description = arm.description
+        ? `<p class="compare-arm-description">${escapeHtml(arm.description)}</p>`
+        : "";
+    return `
+<article class="compare-arm compare-arm-${side}">
+  <header class="compare-arm-header">
+    <p class="compare-arm-kicker">${side === "a" ? "Arm A" : "Arm B"}</p>
+    <h3>${escapeHtml(arm.label)}</h3>
+    ${description}
+    ${renderArmMetrics(arm)}
   </header>
-  <div class="summary">
-    <div class="stats">
-      <span class="stat"><strong>${report.summary.pairedCount}</strong> paired</span>
-      <span class="stat stat-fail"><strong>${report.summary.passRegressions}</strong> regressions</span>
-      <span class="stat stat-pass"><strong>${report.summary.passImprovements}</strong> improvements</span>
-    </div>
-    <dl>
-      <dt>Generated</dt><dd>${escapeHtml(generatedAt.toISOString())}</dd>
-      <dt>A</dt><dd>${escapeHtml(report.aSuite)}</dd>
-      <dt>B</dt><dd>${escapeHtml(report.bSuite)}</dd>
-    </dl>
+  ${renderChat(arm.trace, arm.prompt)}
+</article>`;
+}
+function renderCompareConversations(result) {
+    const compare = result.compare;
+    if (!compare) {
+        return `<section class="conversation">
+    <h3>Conversation</h3>
+    ${renderChat(result.trace, result.prompt)}
+  </section>`;
+    }
+    return `
+<div class="compare-layout">
+  <div class="compare-arms">
+    ${renderArmColumn(compare.a, "a")}
+    ${renderArmColumn(compare.b, "b")}
   </div>
-  ${renderCompareHtmlSection(report)}
-</main>
-</body>
-</html>
-`;
+  ${renderCompareMetrics(result)}
+</div>`;
+}
+function renderStoryList(title, lines) {
+    if (!lines || lines.length === 0) {
+        return "";
+    }
+    const items = lines.map((line) => `<li>${escapeHtml(line)}</li>`).join("");
+    return `<section class="story-block"><h3>${escapeHtml(title)}</h3><ul class="story-list">${items}</ul></section>`;
+}
+function renderStory(result) {
+    const story = result.story;
+    if (!story) {
+        return "";
+    }
+    return `<div class="story">
+    ${renderStoryList("Criteria", story.criteria)}
+    ${renderStoryList("Result", [...story.result, ...story.verdict])}
+  </div>`;
 }
 function renderScenario(result) {
-    const open = result.passed || result.skipped ? "" : " open";
-    const failures = renderFailures(result);
+    const open = result.skipped ? "" : !result.passed || result.compare ? " open" : "";
+    const failures = result.story ? "" : renderFailures(result);
     const judgeVerdicts = renderJudgeVerdicts(result);
     const tokens = formatTokensBadge(result);
-    const usageDetail = renderUsageDetail(usageOf(result));
-    const traceMeta = renderTraceMeta(result);
-    const diagnostics = failures || judgeVerdicts
+    const usageDetail = result.compare ? "" : renderUsageDetail(usageOf(result));
+    const traceMeta = result.compare ? "" : renderTraceMeta(result);
+    const story = renderStory(result);
+    const diagnostics = story || failures || judgeVerdicts
         ? `<div class="diagnostics">
+    ${story}
     ${failures ? `<section><h3>What went wrong</h3>${failures}</section>` : ""}
     ${judgeVerdicts ? `<section><h3>Judge verdict</h3>${judgeVerdicts}</section>` : ""}
   </div>`
@@ -468,133 +594,150 @@ function renderScenario(result) {
     const metaRow = usageDetail || traceMeta
         ? `<div class="diagnostics meta-row">${usageDetail}${traceMeta}</div>`
         : "";
+    const compareClass = result.compare ? " compare-scenario" : "";
+    const description = result.description
+        ? `<span class="scenario-lede">${escapeHtml(result.description)}</span>`
+        : "";
     return `
-<details class="scenario ${statusClass(result)}"${open}>
+<details class="scenario ${statusClass(result)}${compareClass}"${open}>
   <summary>
     <span class="badge ${statusClass(result)}">${statusLabel(result)}</span>
-    <span class="scenario-name">${escapeHtml(result.scenario)}</span>
+    <span class="scenario-heading">
+      <span class="scenario-name">${escapeHtml(result.scenario)}</span>
+      ${description}
+    </span>
     ${tokens ? `<span class="tokens">${escapeHtml(tokens)}</span>` : ""}
     <span class="duration">${escapeHtml(formatDuration(result.durationMs))}</span>
   </summary>
   <div class="scenario-body">
   ${diagnostics}
   ${metaRow}
-  <section class="conversation">
-    <h3>Conversation</h3>
-    ${renderChat(result.trace)}
-  </section>
+  ${renderCompareConversations(result)}
   </div>
 </details>`;
 }
 function renderSuite(report) {
     const scenarios = report.results.map(renderScenario).join("\n");
-    const usage = (report.summary ?? summarizeReportResults(report.results)).usage;
-    const usageLine = usage
-        ? `<p class="suite-usage">${escapeHtml(formatUsageStats(usage))}</p>`
-        : "";
     return `
 <section class="suite">
   <header class="suite-header">
-    <div><h2>${escapeHtml(report.suite)}</h2><span class="host">${escapeHtml(report.host)}</span></div>
-    <div class="suite-meta">
-      <p class="suite-counts">${report.passed} passed · ${report.failed} failed · ${report.skipped} skipped</p>
-      ${usageLine}
+    <div class="suite-title">
+      <h2>${escapeHtml(report.suite)}</h2>
+      <span class="host">${escapeHtml(report.host)}</span>
     </div>
+    <p class="suite-counts"><span>${formatInteger(report.passed)} passed</span><span>${formatInteger(report.failed)} failed</span><span>${formatInteger(report.skipped)} skipped</span></p>
   </header>
-  ${usage ? renderUsageStatsBlock(usage, "Suite token usage") : ""}
   ${scenarios}
 </section>`;
 }
 function sharedReportCss() {
     return `
+  @layer reset, base, layout, components;
   :root {
-    --bg: #0f1419;
-    --panel: #1a2332;
-    --panel-2: #141c28;
-    --text: #e7ecf3;
-    --muted: #8b9bb4;
-    --border: #2a3548;
-    --pass: #3dd68c;
-    --fail: #f07178;
-    --skip: #ffcc66;
-    --user-bubble: #24406b;
-    --assistant-bubble: #1f2f26;
-    --system-bubble: #241f38;
-    --tool: #e0af68;
-    --tool-bubble: #2a2214;
-    --improve: #3dd68c;
-    --regress: #f07178;
+    color-scheme: dark;
+    --bg: oklch(0.18 0.02 250);
+    --panel: oklch(0.23 0.025 250);
+    --panel-2: oklch(0.2 0.022 250);
+    --text: oklch(0.93 0.015 250);
+    --muted: oklch(0.72 0.03 250);
+    --border: oklch(0.32 0.03 250);
+    --pass: oklch(0.8 0.16 155);
+    --fail: oklch(0.72 0.16 20);
+    --skip: oklch(0.84 0.14 85);
+    --user-bubble: oklch(0.3 0.06 250);
+    --assistant-bubble: oklch(0.26 0.04 155);
+    --system-bubble: oklch(0.26 0.04 300);
+    --tool: oklch(0.82 0.12 80);
+    --tool-bubble: oklch(0.26 0.04 80);
+    --arm-a: oklch(0.72 0.12 250);
+    --arm-b: oklch(0.78 0.14 75);
   }
-  * { box-sizing: border-box; }
-  body {
-    margin: 0;
-    font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif;
-    background: var(--bg);
-    color: var(--text);
-    line-height: 1.45;
+  @layer reset {
+    * { box-sizing: border-box; }
+    body { margin: 0; }
+    h1, h2, h3, h4, p, ol { margin: 0; }
+    dl, dd { margin: 0; }
   }
-  main { max-width: 1180px; margin: 0 auto; padding: 1.25rem 1.25rem 3rem; }
-  h1 { font-size: 1.45rem; margin: 0; letter-spacing: -0.02em; }
-  h2 { font-size: 1.1rem; margin: 0; }
-  h3 { font-size: 0.78rem; margin: 0 0 0.5rem; color: var(--muted); text-transform: uppercase; letter-spacing: 0.07em; }
-  h4 { font-size: 0.72rem; margin: 0.9rem 0 0.35rem; color: var(--muted); text-transform: uppercase; letter-spacing: 0.05em; }
-  .muted { color: var(--muted); }
-  .empty { color: var(--muted); font-size: 0.85rem; font-style: italic; margin: 0; }
-  .empty.note { margin-bottom: 0.5rem; }
-  .report-header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 0.65rem; }
-  .report-kicker { color: var(--muted); font-size: 0.78rem; }
-  .summary {
-    background: var(--panel);
-    border: 1px solid var(--border);
-    border-radius: 10px;
-    padding: 0.7rem 0.9rem;
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    gap: 1rem;
-  }
-  .stats { display: flex; gap: 0.45rem; align-items: center; flex-wrap: wrap; }
-  .stat { padding: 0.3rem 0.55rem; border-radius: 6px; background: #111923; font-size: 0.8rem; }
-  .stat strong { font-size: 1rem; margin-right: 0.25rem; }
-  .stat-pass strong { color: var(--pass); }
-  .stat-fail strong { color: var(--fail); }
-  .stat-skip strong { color: var(--skip); }
-  .summary dl {
-    display: flex;
-    flex-wrap: wrap;
-    justify-content: flex-end;
-    gap: 0.15rem 1rem;
-    margin: 0;
-    font-size: 0.78rem;
-  }
-  .summary dt { color: var(--muted); margin-right: -0.7rem; }
-  .summary dd { margin: 0; }
-  .report-usage { margin-top: 0.75rem; }
-  .suite { margin-top: 1.25rem; }
-  .suite-header { display: flex; align-items: end; justify-content: space-between; margin: 0 0 0.5rem; padding: 0 0.2rem; }
-  .suite-header > div { display: flex; align-items: center; gap: 0.5rem; }
-  .host { color: var(--muted); font-size: 0.72rem; background: var(--panel); border: 1px solid var(--border); border-radius: 999px; padding: 0.1rem 0.4rem; }
-  .suite-meta { text-align: right; }
-  .suite-counts { color: var(--muted); margin: 0; font-size: 0.78rem; }
-  .suite-usage { color: var(--muted); margin: 0.15rem 0 0; font-size: 0.72rem; font-variant-numeric: tabular-nums; }
-  .tokens { color: var(--muted); font-size: 0.78rem; font-variant-numeric: tabular-nums; }
-  .usage-summary, .scenario-meta {
-    background: var(--panel-2);
-    border: 1px solid var(--border);
-    border-radius: 8px;
-    padding: 0.65rem 0.7rem;
-    margin: 0 0 0.7rem;
+  @layer base {
+    body {
+      font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
+      background: var(--bg);
+      color: var(--text);
+      line-height: 1.5;
+      word-spacing: 0.16em;
+    }
+    main { max-width: 68rem; margin-inline: auto; padding: 1.5rem 1.25rem 3rem; }
+    main:has(.compare-layout) { max-width: 96rem; }
+    h1 { font-size: 1.7rem; font-weight: 650; letter-spacing: -0.02em; }
+    h2 { font-size: 1.05rem; font-weight: 650; }
+    h3 { font-size: 0.8rem; color: var(--muted); font-weight: 650; }
+    h4 { font-size: 0.75rem; margin-block: 0.9rem 0.35rem; color: var(--muted); font-weight: 650; }
+    .muted { color: var(--muted); }
+    .empty { color: var(--muted); font-size: 0.85rem; font-style: italic; }
+    .empty.note { margin-bottom: 0.5rem; }
   }
-  .usage-compact { margin: 0.45rem 0 0; font-size: 0.72rem; font-variant-numeric: tabular-nums; }
-  .meta-grid {
-    display: grid;
-    grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
-    gap: 0.35rem 0.75rem;
+  @layer layout {
+    .report-header { display: grid; gap: 0.25rem; margin-bottom: 1rem; }
+    .brand { color: var(--muted); font-size: 0.75rem; font-weight: 700; letter-spacing: 0.06em; text-transform: uppercase; }
+    .lede, .when { color: var(--muted); font-size: 0.85rem; }
+    .summary, .cost, .guide, .compare {
+      background: var(--panel);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      padding: 0.9rem 1rem;
+    }
+    .summary { display: grid; gap: 0.65rem; }
+    .stats { display: flex; flex-wrap: wrap; gap: 0.5rem; }
+    .suite { margin-top: 1.75rem; display: grid; gap: 0.55rem; }
+    .suite-header { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 0.5rem 1rem; }
+    .suite-title { display: flex; align-items: center; gap: 0.5rem; }
+    .cost { margin-top: 0.85rem; display: grid; gap: 0.65rem; }
+    .cost-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(9.5rem, 1fr)); gap: 0.75rem; }
+    .guide { margin-top: 0.85rem; }
+    .diagnostics { display: grid; grid-template-columns: repeat(auto-fit, minmax(20rem, 1fr)); gap: 0.7rem; margin-bottom: 0.9rem; }
+    .meta-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(9rem, 1fr)); gap: 0.45rem 0.75rem; }
   }
-  .meta-item { display: flex; flex-direction: column; gap: 0.1rem; }
-  .meta-key { color: var(--muted); font-size: 0.7rem; text-transform: uppercase; letter-spacing: 0.04em; }
-  .meta-val { font-size: 0.88rem; font-variant-numeric: tabular-nums; word-break: break-word; }
-  .meta-row { margin-bottom: 0.7rem; }
+  @layer components {
+    .stat {
+      display: inline-flex;
+      align-items: baseline;
+      gap: 0.35rem;
+      padding: 0.4rem 0.65rem;
+      border-radius: 8px;
+      background: var(--panel-2);
+      font-size: 0.85rem;
+    }
+    .stat strong { font-size: 1.15rem; font-variant-numeric: tabular-nums; }
+    .stat-pass strong { color: var(--pass); }
+    .stat-fail strong { color: var(--fail); }
+    .stat-skip strong { color: var(--skip); }
+    .guide h2 { font-size: 0.95rem; }
+    .guide ol { margin: 0.65rem 0 0; padding-inline-start: 1.2rem; display: grid; gap: 0.35rem; color: var(--muted); font-size: 0.88rem; }
+    .cost-lede { color: var(--muted); font-size: 0.85rem; }
+    .cost-item { display: grid; gap: 0.15rem; }
+    .cost-value { font-size: 1.2rem; font-weight: 650; font-variant-numeric: tabular-nums; }
+    .cost-label { font-size: 0.8rem; font-weight: 650; }
+    .cost-detail { color: var(--muted); font-size: 0.75rem; }
+    .host {
+      color: var(--muted);
+      font-size: 0.72rem;
+      background: var(--panel-2);
+      border: 1px solid var(--border);
+      border-radius: 999px;
+      padding: 0.1rem 0.5rem;
+    }
+    .suite-counts { display: flex; flex-wrap: wrap; gap: 0.75rem; color: var(--muted); font-size: 0.85rem; }
+    .tokens { color: var(--muted); font-size: 0.78rem; font-variant-numeric: tabular-nums; }
+    .usage-summary, .scenario-meta {
+      background: var(--panel-2);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 0.65rem 0.7rem;
+    }
+    .meta-item { display: grid; gap: 0.1rem; }
+    .meta-key { color: var(--muted); font-size: 0.75rem; }
+    .meta-val { font-size: 0.88rem; font-variant-numeric: tabular-nums; word-break: break-word; }
+    .meta-row { margin-bottom: 0.7rem; }
   details.scenario {
     background: var(--panel);
     border: 1px solid var(--border);
@@ -613,7 +756,9 @@ function sharedReportCss() {
   }
   details.scenario[open] summary { border-bottom: 1px solid var(--border); background: #17202d; }
   details.scenario summary::-webkit-details-marker { display: none; }
+  .scenario-heading { display: grid; gap: 0.1rem; min-width: 12rem; flex: 1 1 16rem; }
   .scenario-name { font-weight: 600; font-size: 0.9rem; }
+  .scenario-lede { color: var(--muted); font-size: 0.78rem; font-weight: 400; }
   .duration { color: var(--muted); margin-left: auto; font-variant-numeric: tabular-nums; }
   .badge {
     display: inline-block;
@@ -633,6 +778,9 @@ function sharedReportCss() {
   .diagnostics section { background: var(--panel-2); border: 1px solid var(--border); border-radius: 8px; padding: 0.65rem 0.7rem; min-width: 0; }
   .conversation { min-width: 0; }
 
+  .story { display: grid; grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr)); gap: 0.85rem; margin-bottom: 0.85rem; }
+  .story-block h3 { margin: 0 0 0.35rem; font-size: 0.78rem; text-transform: uppercase; letter-spacing: 0.04em; color: var(--muted); }
+  .story-list { margin: 0; padding-left: 1.1rem; display: flex; flex-direction: column; gap: 0.25rem; color: var(--text); }
   .failures { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 0.55rem; }
   .failures li { border-left: 3px solid var(--fail); padding-left: 0.6rem; }
   .failure-label { margin: 0; font-weight: 600; font-size: 0.85rem; color: var(--fail); }
@@ -701,16 +849,61 @@ function sharedReportCss() {
   .shell-commands li { font-size: 0.8rem; background: #0b1017; border: 1px solid var(--border); border-radius: 6px; padding: 0.3rem 0.5rem; }
   code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.85em; }
 
+  .compare-layout {
+    container-type: inline-size;
+    display: grid;
+    gap: 0.9rem;
+  }
+  .compare-arms {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+    gap: 0.85rem;
+    align-items: stretch;
+  }
+  .compare-arm {
+    min-width: 0;
+    display: grid;
+    align-content: start;
+    gap: 0.65rem;
+    background: var(--panel-2);
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    padding: 0.75rem 0.8rem 0.85rem;
+    border-block-start-width: 3px;
+  }
+  .compare-arm-a { border-block-start-color: var(--arm-a); }
+  .compare-arm-b { border-block-start-color: var(--arm-b); }
+  .compare-arm-header { display: grid; gap: 0.15rem; padding-bottom: 0.55rem; border-bottom: 1px solid var(--border); }
+  .compare-arm-kicker {
+    color: var(--muted);
+    font-size: 0.66rem;
+    font-weight: 700;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+  }
+  .compare-arm-a .compare-arm-kicker { color: var(--arm-a); }
+  .compare-arm-b .compare-arm-kicker { color: var(--arm-b); }
+  .compare-arm-header h3 { color: var(--text); font-size: 0.95rem; }
+  .compare-arm-description { color: var(--muted); font-size: 0.8rem; }
+  .compare-arm-metrics { color: var(--muted); font-size: 0.78rem; font-variant-numeric: tabular-nums; }
+  .compare-arm .bubble, .compare-arm .tool-card { max-width: 100%; }
+
   .compare {
-    margin-top: 1.1rem;
+    margin-top: 0;
     background: var(--panel);
     border: 1px solid var(--border);
     border-radius: 10px;
     padding: 0.85rem 0.9rem 1rem;
   }
   .compare-header { margin-bottom: 0.65rem; }
-  .compare-header h2 { margin-bottom: 0.2rem; }
-  .compare-summary { margin-bottom: 0.75rem; }
+  .compare-header h3 { margin-bottom: 0.2rem; }
+  .compare-callouts {
+    margin: 0 0 0.75rem;
+    padding-left: 1.1rem;
+    display: grid;
+    gap: 0.25rem;
+    font-size: 0.85rem;
+  }
   .compare-table-wrap { overflow-x: auto; }
   .compare-table {
     width: 100%;
@@ -725,20 +918,23 @@ function sharedReportCss() {
     vertical-align: middle;
   }
   .compare-table th { color: var(--muted); font-weight: 600; font-size: 0.7rem; text-transform: uppercase; letter-spacing: 0.04em; }
-  .compare-name { font-weight: 600; }
-  .compare-regress { background: color-mix(in srgb, var(--regress) 10%, transparent); }
-  .compare-improve { background: color-mix(in srgb, var(--improve) 10%, transparent); }
   .delta-up { color: var(--fail); }
   .delta-down { color: var(--pass); }
   .delta-flat { color: var(--muted); }
+  .is-better { color: var(--pass); font-weight: 650; }
+  .is-worse { color: var(--muted); }
+
+  @container (max-width: 44rem) {
+    .compare-arms { grid-template-columns: minmax(0, 1fr); }
+  }
 
   @media (max-width: 720px) {
     main { padding: 0.75rem; }
-    .summary { align-items: flex-start; flex-direction: column; }
-    .summary dl { justify-content: flex-start; }
     .suite-header { align-items: flex-start; flex-direction: column; gap: 0.2rem; }
     .diagnostics { grid-template-columns: 1fr; }
     .bubble, .tool-card { max-width: 92%; }
+    .compare-arms { grid-template-columns: minmax(0, 1fr); }
+  }
   }
 `;
 }
@@ -748,22 +944,11 @@ export function renderHtmlReport(reports, meta = {}) {
     const totalPassed = reports.reduce((sum, report) => sum + report.passed, 0);
     const totalFailed = reports.reduce((sum, report) => sum + report.failed, 0);
     const totalSkipped = reports.reduce((sum, report) => sum + report.skipped, 0);
-    const host = meta.host ?? reports[0]?.host ?? "unknown";
+    const hostNames = [...new Set(reports.map((report) => report.host).filter(Boolean))];
+    const host = meta.host ?? (hostNames.length > 0 ? hostNames.join(", ") : "unknown");
     const runUsage = summarizeReports(reports).usage;
-    // Embed A/B only when explicitly requested (compare-pairs / compare labels), not for every 2-suite run.
-    const includeCompare = reports.length === 2 &&
-        (meta.includeCompare === true ||
-            meta.compareALabel !== undefined ||
-            meta.compareBLabel !== undefined);
-    const compareSection = includeCompare && reports[0] && reports[1]
-        ? renderCompareHtmlSection(compareSuiteReports({
-            aLabel: meta.compareALabel ?? reports[0].suite,
-            bLabel: meta.compareBLabel ?? reports[1].suite,
-            a: reports[0],
-            b: reports[1],
-        }))
-        : "";
     const suitesHtml = reports.map(renderSuite).join("\n");
+    const suiteWord = reports.length === 1 ? "suite" : "suites";
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -775,32 +960,28 @@ export function renderHtmlReport(reports, meta = {}) {
 <body>
 <main>
   <header class="report-header">
-    <h1>agent-test report</h1>
-    <span class="report-kicker">${reports.length} suite${reports.length === 1 ? "" : "s"}</span>
+    <p class="brand">agent-test</p>
+    <h1>Run report</h1>
+    <p class="lede">${escapeHtml(String(host))} · ${formatInteger(reports.length)} ${suiteWord}${meta.suitesDir ? ` · ${escapeHtml(meta.suitesDir)}` : ""}</p>
   </header>
-  <div class="summary">
+  <section class="summary" aria-label="Run verdict">
     <div class="stats">
-      <span class="stat stat-pass"><strong>${totalPassed}</strong> passed</span>
-      <span class="stat stat-fail"><strong>${totalFailed}</strong> failed</span>
-      <span class="stat stat-skip"><strong>${totalSkipped}</strong> skipped</span>
-      ${runUsage?.sumTotalTokens !== undefined
-        ? `<span class="stat"><strong>${runUsage.sumTotalTokens}</strong> tokens</span>`
-        : ""}
+      <span class="stat stat-pass"><strong>${formatInteger(totalPassed)}</strong><span>passed</span></span>
+      <span class="stat stat-fail"><strong>${formatInteger(totalFailed)}</strong><span>failed</span></span>
+      <span class="stat stat-skip"><strong>${formatInteger(totalSkipped)}</strong><span>skipped</span></span>
     </div>
-    <dl>
-      <dt>Host</dt><dd>${escapeHtml(String(host))}</dd>
-      <dt>Generated</dt><dd>${escapeHtml(generatedAt.toISOString())}</dd>
-      ${meta.suitesDir ? `<dt>Suites</dt><dd>${escapeHtml(meta.suitesDir)}</dd>` : ""}
-      ${runUsage?.p50TotalTokens !== undefined
-        ? `<dt>p50 tokens</dt><dd>${runUsage.p50TotalTokens}</dd>`
-        : ""}
-      ${runUsage?.p95TotalTokens !== undefined
-        ? `<dt>p95 tokens</dt><dd>${runUsage.p95TotalTokens}</dd>`
-        : ""}
-    </dl>
-  </div>
-  ${runUsage ? `<div class="report-usage">${renderUsageStatsBlock(runUsage, "Run token usage")}</div>` : ""}
-  ${compareSection}
+    <p class="when">Generated ${escapeHtml(generatedAt.toISOString())}</p>
+  </section>
+  <section class="guide" aria-labelledby="guide-heading">
+    <h2 id="guide-heading">How to read this report</h2>
+    <ol>
+      <li>The verdict is pass or fail. Tokens are cost, not the score.</li>
+      <li>Open a scenario for the criteria and the result. A compare scenario shows the two arms side by side, then a comparison of time, tokens, and tools.</li>
+      <li>Typical is the middle scenario cost. Largest is the heaviest scenario.</li>
+      <li>In is prompt and context. Out is generated text.</li>
+    </ol>
+  </section>
+  ${renderCostSection(runUsage)}
   ${suitesHtml}
 </main>
 </body>