mjolnir-qa 0.5.2 → 0.5.4

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { accessSync, chmodSync, constants, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { accessSync, appendFileSync, chmodSync, constants, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { execFileSync, execSync } from "node:child_process";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import process$1 from "node:process";
@@ -25,6 +25,15 @@ const QA_IMPACT_LABELS = {
 	"FALSE-GREEN": "False-green risk",
 	HYGIENE: "Test hygiene debt"
 };
+/** The closed set of rule categories (plan §5.5). `--category` values
+* are validated against this list — unknown categories are a usage
+* error, not a silent no-op. */
+const RULE_CATEGORIES = [
+	"QA-TEST",
+	"QA-TQUAL",
+	"QA-PW",
+	"QA-CI"
+];
 /**
 * Honest default evidence level for a finding (Honesty Core Phase 1).
 * Derivation is deterministic and conservative:
@@ -8960,8 +8969,17 @@ const off = {
 function rgb([r, g, b]) {
 	return (s) => `\x1b[38;2;${r};${g};${b}m${sanitizeData(s)}\x1b[0m`;
 }
-/** True when colors should be emitted for this render call. */
+/**
+* True when colors should be emitted for this render call.
+*
+* Precedence (chalk convention): FORCE_COLOR wins over everything —
+* `FORCE_COLOR=0` (or "false"/empty) forces plain output even on a TTY,
+* any other value forces color even when piped. Without FORCE_COLOR,
+* NO_COLOR disables color and the rest follows TTY-ness.
+*/
 function shouldColorize(isTTY) {
+	const forced = process.env["FORCE_COLOR"];
+	if (forced !== void 0) return forced !== "0" && forced !== "false" && forced !== "";
 	return isTTY && !process.env["NO_COLOR"];
 }
 function palette(enabled) {
@@ -9066,23 +9084,90 @@ function gaugeColorForBand(band, p) {
 	if (band === "unmeasured") return p.dim;
 	return band === "warning" ? p.warning : p.error;
 }
-/** Severity glyph + label, themed. Falls back to plain ASCII glyphs
-* (X/!/i) when `ascii` is set — ✗/⚠/ℹ render as "?" boxes on some
-* legacy Windows consoles, and color already carries the same signal
-* (color-blind-safe symbols remain: the label text itself). */
-function severityTag(severity, p, ascii = false) {
-	const glyphs = ascii ? {
-		error: "X",
-		warning: "!",
-		info: "i"
-	} : {
+//#endregion
+//#region src/reporter/ui.ts
+/**
+* Neutral context for direct calls (tests, library use) and as the
+* safe default when a command runner is invoked without wiring: no
+* color, unicode glyphs, 80 columns. cli.ts builds the real context
+* once per run (TTY, width, ASCII heuristic) and passes it down.
+*/
+function plainContext(width = 80) {
+	return {
+		p: palette(false),
+		ascii: false,
+		width
+	};
+}
+/** Canonical severity glyphs. Symbols always accompany color (R11). */
+const SEVERITY_GLYPHS = {
+	unicode: {
 		error: "✗",
 		warning: "⚠",
 		info: "ℹ"
-	};
-	if (severity === "error") return `${p.error(glyphs.error)} ${p.error("ERROR  ")}`;
-	if (severity === "warning") return `${p.warning(glyphs.warning)} ${p.warning("WARN   ")}`;
-	return `${p.info(glyphs.info)} ${p.info("INFO   ")}`;
+	},
+	ascii: {
+		error: "X",
+		warning: "!",
+		info: "i"
+	}
+};
+const FLAKE_GLYPH = "🔥";
+/** Section header: `▚ TITLE` (ascii `= TITLE`). The one header style. */
+function sectionHeader(title, ui) {
+	const glyph = ui.ascii ? "=" : "▚";
+	return `  ${ui.p.accent(`${glyph} ${title}`)}`;
+}
+/** Rounded panel around wrapped text lines, indented two spaces. */
+function panel(lines, ui, pad = 1) {
+	return box(lines, pad, {
+		maxWidth: ui.width - 2,
+		ascii: ui.ascii
+	}).map((l) => `  ${l}`);
+}
+/** Horizontal rule under a section block. */
+function divider(ui) {
+	return ui.p.dim((ui.ascii ? "-" : "─").repeat(58));
+}
+/**
+* Next-step affordance: dim `$ command` line. The `$` prefix is the
+* universal "type this in your shell" marker; the command itself is
+* plain (not dimmed) so it copies cleanly from a terminal.
+*/
+function nextStep(command, ui) {
+	return `  ${ui.p.dim("$")} ${command}`;
+}
+/** Themed severity icon: glyph + padded label, e.g. `✗ ERROR  `. */
+function severityIcon(severity, ui) {
+	const g = (ui.ascii ? SEVERITY_GLYPHS.ascii : SEVERITY_GLYPHS.unicode)[severity];
+	if (severity === "error") return `${ui.p.error(g)} ${ui.p.error("ERROR  ")}`;
+	if (severity === "warning") return `${ui.p.warning(g)} ${ui.p.warning("WARN   ")}`;
+	return `${ui.p.info(g)} ${ui.p.info("INFO   ")}`;
+}
+/** Themed success icon (`✓` / `v` in ascii). */
+function okIcon(ui) {
+	const g = ui.ascii ? "v" : "✓";
+	return ui.p.ok(g);
+}
+/**
+* Footer builder: `Analysis complete · <duration>ms` + optional
+* suppressed count + optional next action. `durationMs` is formatted
+* by formatDuration; `next` is rendered as a `$ command` line.
+*/
+function buildFooter(opts) {
+	const { ui } = opts;
+	const lines = [];
+	lines.push(divider(ui));
+	const status = opts.complete ? `${ui.p.ok("complete")} · ${formatDuration(opts.durationMs)}` : `${ui.p.warning("PARTIAL — verdict may be incomplete")} · ${formatDuration(opts.durationMs)}`;
+	lines.push(`  Analysis: ${status}`);
+	if (opts.suppressedCount && opts.suppressedCount > 0) lines.push(ui.p.dim(`  ${opts.suppressedCount} finding(s) suppressed by config`));
+	if (opts.next) lines.push(nextStep(opts.next, ui));
+	return lines;
+}
+/** Human duration: `1.2s` above a second, `850ms` below. */
+function formatDuration(ms) {
+	if (ms === void 0) return "?";
+	return ms >= 1e3 ? `${(ms / 1e3).toFixed(1)}s` : `${ms}ms`;
 }
 //#endregion
 //#region src/reporter/art.ts
@@ -9131,8 +9216,7 @@ String.raw`
    | \IIIIII/ |
    \          /
     ` + "";
-/** Small divider. */
-const DIVIDER = "─".repeat(58);
+"─".repeat(58);
 /** ASCII-mode state caption — the text marker that carries the state
 * when color is absent (symbols-accompany-color doctrine, R11). */
 const HAMMER_CAPTIONS = {
@@ -9410,23 +9494,42 @@ function renderTerminal(result, opts) {
 	const p = palette(shouldColorize(opts.isTTY));
 	const width = Math.max(MIN_BOX_WIDTH, opts.width ?? process.stdout.columns ?? 80);
 	const ascii = opts.ascii ?? shouldUseAscii();
+	const ui = {
+		p,
+		ascii,
+		width
+	};
 	const lines = [];
 	const logo = ascii ? LOGO_ASCII : LOGO;
 	for (const l of logo.split("\n")) if (l.trim()) lines.push(p.accent(l));
 	lines.push("");
-	if (result.score === null) return renderNoTests(p, ascii);
+	if (result.score === null) return renderNoTests(ui);
 	const counts = countBySeverity(result);
 	appendScoreSection(lines, {
 		...result,
 		score: result.score
 	}, p, width, ascii);
-	appendFrameworks(lines, result, p);
-	appendDimensions(lines, result, p, ascii);
-	appendDeductions(lines, result, counts, p, width, ascii);
-	appendFixThisFirst(lines, result, p);
-	appendFindings(lines, result, counts, opts.verbose === true, p, ascii, width, opts.tone);
+	appendFrameworks(lines, result, ui);
+	if (result.staged !== void 0) {
+		lines.push(ui.p.dim(`  staged surface: ${result.staged.files} file(s) scanned; score reflects that surface`));
+		lines.push("");
+	}
+	appendDimensions(lines, result, ui);
+	appendDeductions(lines, result, counts, ui);
+	const filtered = opts.visibleFindings;
+	const filtering = filtered !== void 0 && filtered.length < result.findings.length;
+	const display = filtering ? {
+		...result,
+		findings: filtered
+	} : result;
+	appendFixThisFirst(lines, display, ui);
+	if (filtering) {
+		lines.push(ui.p.dim(`  filtered view: ${filtered?.length} of ${result.findings.length} findings shown; score reflects the full scan`));
+		lines.push("");
+	}
+	appendFindings(lines, display, counts, opts.verbose === true, ui, opts.tone);
 	if (counts.total === 0 && result.score === 100) appendForgedBlock(lines, p, ascii);
-	appendFooter(lines, result, p);
+	appendFooter(lines, result, ui);
 	return lines.join("\n");
 }
 /**
@@ -9460,28 +9563,30 @@ function colorizeVerdict(verdict, band, p) {
 	if (band === "warning") return p.warning(verdict);
 	return p.error(verdict);
 }
-function appendFrameworks(lines, result, p) {
+function appendFrameworks(lines, result, ui) {
+	const { p } = ui;
 	if (result.frameworks.length > 0) {
 		const tags = result.frameworks.map((f) => `[${f}]`).join(" ");
 		lines.push(`  ${p.dim("DETECTED")} ${p.info(tags)}`);
 	} else if (result.frameworkDetectionUnknown) lines.push(`  ${p.dim("FRAMEWORK")} unknown — scanning all test-looking files. Add a package.json/config the detector recognizes for framework-aware scoring.`);
 	lines.push("");
 }
-function appendDimensions(lines, result, p, ascii) {
+function appendDimensions(lines, result, ui) {
 	const dims = result.dimensions.length > 0 ? result.dimensions : computeDimensions(result.findings);
 	if (dims.length === 0) return;
-	lines.push(`  ${p.accent("▚ DIAGNOSTICS BY CATEGORY")}`);
+	lines.push(sectionHeader("DIAGNOSTICS BY CATEGORY", ui));
 	const width = Math.max(...dims.map((d) => d.category.length));
 	for (const d of dims) {
 		const label = padTo(d.category, width);
 		const scoreText = String(d.score).padStart(3);
-		lines.push(`  ${label}  ${scoreGauge(d.score, p, 16, ascii)} ${scoreText}`);
+		lines.push(`  ${label}  ${scoreGauge(d.score, ui.p, 16, ui.ascii)} ${scoreText}`);
 	}
 	lines.push("");
 }
-function appendDeductions(lines, result, counts, p, width, ascii) {
+function appendDeductions(lines, result, counts, ui) {
+	const { p } = ui;
 	if (counts.total === 0) return;
-	lines.push(`  ${p.accent("▚ WHERE POINTS WERE LOST")}`);
+	lines.push(sectionHeader("WHERE POINTS WERE LOST", ui));
 	const rows = [];
 	const bySeverity = {
 		error: {
@@ -9511,21 +9616,18 @@ function appendDeductions(lines, result, counts, p, width, ascii) {
 		const discounted = s.ded < s.n * DEDUCTIONS[sev];
 		rows.push(`${s.n} × ${sev.padEnd(7)} −${String(s.ded).padStart(3)}${discounted ? p.dim(" (evidence-discounted)") : ""}`);
 	}
-	for (const row of box(rows, 1, {
-		maxWidth: width - 2,
-		ascii
-	})) lines.push(`  ${row}`);
+	for (const row of panel(rows, ui)) lines.push(row);
 	lines.push("");
 }
-function appendFixThisFirst(lines, result, p) {
+function appendFixThisFirst(lines, result, ui) {
 	const fixes = topFixes(result.findings, 3);
 	if (fixes.length === 0) return;
-	lines.push(`  ${p.accent("▚ FIX THIS FIRST")}`);
+	lines.push(sectionHeader("FIX THIS FIRST", ui));
 	for (const { finding: f, scoreGain, autofixable } of fixes) {
 		const gainText = `+${scoreGain} pt${scoreGain === 1 ? "" : "s"}`;
-		const autofixTag = autofixable ? p.ok(" [autofix available]") : "";
+		const autofixTag = autofixable ? ui.p.ok(" [autofix available]") : "";
 		const loc = `${sanitizeData(f.ruleId)} · ${sanitizeData(f.file)}:${f.line}`;
-		lines.push(`  ${p.bold(gainText)}  ${loc}${autofixTag}`);
+		lines.push(`  ${ui.p.bold(gainText)}  ${loc}${autofixTag}`);
 	}
 	lines.push("");
 }
@@ -9586,9 +9688,10 @@ function wrapLines(text, width) {
 }
 const CARD_LABEL_PAD = 8;
 const CARD_GUTTER = "    ";
-function pushCard(lines, card, p, width, ascii) {
+function pushCard(lines, card, ui) {
+	const { p, width } = ui;
 	const contentWidth = Math.max(20, width - 2 - 4 - CARD_LABEL_PAD);
-	lines.push(`  ${severityTag(card.severity, p, ascii)} ${p.bold(card.loc)}  ${p.dim(card.evidence)}`);
+	lines.push(`  ${severityIcon(card.severity, ui)} ${p.bold(card.loc)}  ${p.dim(card.evidence)}`);
 	const fields = [
 		{
 			label: "Problem",
@@ -9627,8 +9730,14 @@ function pushCard(lines, card, p, width, ascii) {
 * "same fix applies" header. Non-verbose shows MAX_CARDS cards plus an
 * overflow line; --verbose shows everything.
 */
-function appendFindings(lines, result, counts, verbose, p, ascii, width, tone) {
+function appendFindings(lines, result, counts, verbose, ui, tone) {
+	const { p } = ui;
 	if (counts.total === 0) return;
+	if (result.findings.length === 0) {
+		lines.push(ui.p.dim("  filtered view: no findings in the selected category"));
+		lines.push("");
+		return;
+	}
 	const byRule = /* @__PURE__ */ new Map();
 	for (const f of result.findings) {
 		const list = byRule.get(f.ruleId) ?? [];
@@ -9660,7 +9769,7 @@ function appendFindings(lines, result, counts, verbose, p, ascii, width, tone) {
 	let shown = 0;
 	let hidden = 0;
 	const hiddenRules = /* @__PURE__ */ new Set();
-	lines.push(`  ${p.accent("▚ FINDINGS")}`);
+	lines.push(sectionHeader("FINDINGS", ui));
 	lines.push("");
 	for (const unit of units) {
 		if (unit.kind === "group") {
@@ -9671,7 +9780,7 @@ function appendFindings(lines, result, counts, verbose, p, ascii, width, tone) {
 				hiddenRules.add(unit.ruleId);
 				continue;
 			}
-			lines.push(`  ${severityTag(maxSeverity(unit.findings), p, ascii)} ${p.bold(sanitizeData(unit.ruleId))} ${p.dim(`× ${n} — same fix applies`)} ${p.dim(evidenceTag$1(first))}`);
+			lines.push(`  ${severityIcon(maxSeverity(unit.findings), ui)} ${p.bold(sanitizeData(unit.ruleId))} ${p.dim(`× ${n} — same fix applies`)} ${p.dim(evidenceTag$1(first))}`);
 			lines.push(`${CARD_GUTTER}${p.accent("Fix".padEnd(CARD_LABEL_PAD))}${p.dim(sanitizeData(first.fix))}`);
 			for (const f of unit.findings) lines.push(`${CARD_GUTTER}${" ".repeat(CARD_LABEL_PAD)}${p.dim(`· ${sanitizeData(f.file)}:${f.line} — ${sanitizeData(f.message)}`)}`);
 			lines.push("");
@@ -9683,7 +9792,7 @@ function appendFindings(lines, result, counts, verbose, p, ascii, width, tone) {
 			hiddenRules.add(unit.finding.ruleId);
 			continue;
 		}
-		pushCard(lines, toCard(unit.finding, tone), p, width, ascii);
+		pushCard(lines, toCard(unit.finding, tone), ui);
 		shown++;
 	}
 	if (hidden > 0) lines.push(`  ${p.dim(`… +${hidden} more across ${hiddenRules.size} rule${hiddenRules.size === 1 ? "" : "s"}. Run with --verbose for all findings.`)}`);
@@ -9711,10 +9820,13 @@ function appendForgedBlock(lines, p, ascii) {
 	lines.push(p.forged(TROPHY));
 	lines.push("");
 }
-function appendFooter(lines, result, p) {
-	lines.push(p.dim(DIVIDER));
-	const status = result.analysisStatus.discovery === "partial" ? p.warning("PARTIAL — verdict may be incomplete") : p.ok("complete");
-	lines.push(`  Analysis: ${status} · ${result.analysisStatus.durationMs}ms`);
+function appendFooter(lines, result, ui) {
+	const { p } = ui;
+	lines.push(...buildFooter({
+		ui,
+		complete: result.analysisStatus.discovery !== "partial",
+		durationMs: result.analysisStatus.durationMs
+	}));
 	const advisory = result.findings.filter((f) => (f.evidenceLevel ?? deriveEvidenceLevel(f.findingType, f.confidence)) === "E0").length;
 	if (advisory > 0) lines.push(p.dim(`  ${advisory} advisory finding${advisory === 1 ? "" : "s"} (E0 — observation only, no score impact)`));
 	if (result.findings.length > 0) {
@@ -9738,7 +9850,8 @@ function appendFooter(lines, result, p) {
 	}
 	lines.push("");
 }
-function renderNoTests(p, ascii) {
+function renderNoTests(ui) {
+	const { p, ascii } = ui;
 	const warnGlyph = ascii ? "!" : "⚠";
 	const searched = SEARCHED_FOR.map((e) => `${e.label}: ${e.globs.join("  ")}`);
 	return [
@@ -9756,7 +9869,7 @@ function renderNoTests(p, ascii) {
 			maxWidth: 78
 		}).map((l) => `  ${l}`),
 		"",
-		"  If your tests live elsewhere: mjolnir <path-to-your-tests>",
+		nextStep("mjolnir <path-to-your-tests>", ui),
 		""
 	].join("\n");
 }
@@ -9802,7 +9915,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.2",
+			version: "0.5.4",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -9945,97 +10058,1367 @@ function renderMermaid(result) {
 	return lines.join("\n");
 }
 //#endregion
-//#region src/scope/changed.ts
+//#region src/reporter/progress.ts
 /**
-* Changed-scope engine (Sprint-Plan W6, Product-MVP §9 `--scope changed`).
+* Live scan progress (Terminal + CI UX Overhaul plan, M3).
 *
-* Compares the current branch against its merge-base and reports only
-* findings on NEW/CHANGED lines. Handles: new files, modified files,
-* renames (treated as modified), shallow clones (graceful fallback to
-* full-file attribution), and detached HEAD.
+* Determinism model: render-on-event, NO wall-clock timer. Frames
+* advance and lines repaint only when `onProgress` fires — testable
+* with a fake stream, no fake timers, no flaky CI.
 *
-* Audits H-9/H-10: the changed-file predicate is derived from the real
-* adapter registry (isKnownTestFile) so Python, Java, C#, and workflow
-* changes are not silently dropped; the default base falls back
-* main → master → origin/HEAD, an explicit --base is honored, and the
-* WORKING TREE (uncommitted + untracked files) is included so running
-* locally before committing still sees the change.
+* Stream discipline: every cursor-control ANSI sequence goes to the
+* injected stream only. The stream is gated by the caller (cli.ts
+* auto-disables on non-TTY stderr, --json/--format machine modes,
+* --no-progress, GITHUB_ACTIONS/CI env), so stdout purity and
+* byte-identical JSON are untouched by construction.
+*
+* Zero new dependencies: braille + ASCII spinner frames are inline
+* constants; erasure is plain `\r` + ESC[K.
 */
-function git$1(root, args) {
-	try {
-		return execFileSync("git", [
-			"-C",
-			root,
-			...args
-		], {
-			encoding: "utf8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			],
-			timeout: 15e3
+/** Spinner frames: braille, ASCII fallback. */
+const BRAILLE_FRAMES = [..."⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"];
+const ASCII_FRAMES = [..."|/-\\"];
+/** True when a live progress renderer may write to the stream at all.
+* `env` is required: the caller owns the ambient-vs-test distinction
+* (cli.ts passes process.env; tests pass a controlled object). */
+function shouldRenderProgress(opts) {
+	if (opts.noProgress) return false;
+	if (opts.machineFormat) return false;
+	if (!opts.isTTY) return false;
+	if (opts.env["GITHUB_ACTIONS"] === "true" || opts.env["CI"] === "true") return false;
+	return true;
+}
+/** Frame at `index`, defensive against an empty frames list. Exported
+* so the fallback arms stay pinned (renderProgressLine always passes a
+* non-empty constant list and an in-range index). */
+function pickFrame(frames, index) {
+	return frames[index % frames.length] ?? frames[0] ?? " ";
+}
+const PHASE_LABELS = {
+	discover: "Discovering files",
+	parse: "Parsing frameworks",
+	rules: "Running rules",
+	score: "Scoring"
+};
+/** One rendered progress line for an event and frame index. */
+function renderProgressLine(event, frameIndex, opts = {}) {
+	let line = `${pickFrame(opts.ascii ? ASCII_FRAMES : BRAILLE_FRAMES, frameIndex)} ${PHASE_LABELS[event.phase]}…`;
+	const parts = [];
+	if (event.total !== void 0) parts.push(`${event.done ?? 0}/${event.total}`);
+	if (event.detail) parts.push(sanitizeData(event.detail));
+	if (parts.length > 0) line += ` (${parts.join(" · ")})`;
+	return line;
+}
+const ERASE_TAIL = "\x1B[K";
+/**
+* The event-driven progress renderer. All writes go to the injected
+* stream; the internal `lines` count tracks what must be erased when
+* the phase changes or the scan completes.
+*/
+var ProgressRenderer = class {
+	frameIndex = 0;
+	activeLines = 0;
+	stream;
+	ascii;
+	enabled;
+	constructor(opts) {
+		this.stream = opts.stream;
+		this.ascii = opts.ascii === true;
+		this.enabled = opts.isTTY;
+	}
+	get active() {
+		return this.enabled;
+	}
+	/** Test-visible frame index (render-on-event determinism). */
+	get frame() {
+		return this.frameIndex;
+	}
+	write(s) {
+		this.stream.write(s);
+	}
+	erase() {
+		if (this.activeLines > 0) {
+			this.write(`\r\x1b[${this.activeLines}A${ERASE_TAIL}${"\n\x1B[K".repeat(Math.max(0, this.activeLines - 1))}\r`);
+			this.activeLines = 0;
+		}
+	}
+	/** Handle one onProgress event: erase, paint, advance the frame. */
+	onEvent(event) {
+		if (!this.enabled) return;
+		this.erase();
+		const line = renderProgressLine(event, this.frameIndex, { ascii: this.ascii });
+		this.write(`${line}\n`);
+		this.activeLines = 1;
+		this.frameIndex++;
+	}
+	/** Scan finished (or formats are about to print): clear the line. */
+	done() {
+		if (!this.enabled) return;
+		this.erase();
+	}
+};
+//#endregion
+//#region src/reporter/github.ts
+/** Escape a workflow-command PROPERTY value. */
+function escapeAnnotationProperty(value) {
+	return value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A").replaceAll(":", "%3A").replaceAll(",", "%2C");
+}
+/** Escape a workflow-command MESSAGE. */
+function escapeAnnotationMessage(value) {
+	return value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+}
+/** ANSI-injection guard for the summary path (belt + braces). */
+function stripAnsiForSummary(value) {
+	return value.replace(/\x1b\[[0-9;:?]*[ -/]*[@-~]/g, "");
+}
+const SEVERITY_TO_COMMAND = {
+	error: "error",
+	warning: "warning",
+	info: "notice"
+};
+/** Render ONE workflow-command annotation line (no trailing newline). */
+function renderAnnotation(a) {
+	const props = [`file=${escapeAnnotationProperty(a.file)}`, `line=${Math.max(1, a.line ?? 1)}`];
+	if (a.column !== void 0) props.push(`column=${Math.max(1, a.column)}`);
+	props.push(`title=${escapeAnnotationProperty(a.title)}`);
+	return `::${SEVERITY_TO_COMMAND[a.severity]} ${props.join(",")}::${escapeAnnotationMessage(a.message)}`;
+}
+/** Render annotations for every finding in a report's findings array. */
+function renderAnnotations(findings) {
+	return findings.map((f) => {
+		return renderAnnotation({
+			severity: f.severity === "error" || f.severity === "warning" ? f.severity : "info",
+			file: f.file,
+			line: f.line,
+			column: f.column,
+			title: f.ruleId,
+			message: f.message
 		});
-	} catch {
-		return null;
+	});
+}
+/** GitHub caps annotation messages — keep the head, point at the summary. */
+function truncateMessage(message, max = 250) {
+	if (message.length <= max) return message;
+	return `${message.slice(0, max)}… (full text in the step summary)`;
+}
+//#endregion
+//#region src/commands/pr-comment.ts
+const MARKER = "<!-- mjolnir-pr-comment -->";
+/**
+* Bug-audit QA-2026-08-30 QA-10: finding metadata rendered into the PR
+* comment body is untrusted (hostile filenames, plugin messages). A raw
+* `|` breaks the markdown layout, a raw backtick escapes the code span,
+* and `<\/script>`/link syntax could inject content into the PR page.
+* Escape markdown-significant characters and strip control/ANSI escapes.
+*/
+function escapeMarkdown(s) {
+	return sanitizeData(s).replace(/([\\`*_{}[\]()#+!|<>])/g, "\\$1");
+}
+/** True when a fix recommendation reads as code rather than prose —
+* those render as a code span, the rest stay italic. */
+function looksLikeCode(s) {
+	return /[(;={]|await |expect\(/.test(s);
+}
+/** Evidence tag per finding — Evidence > Assumption in the fabric: a
+* measured false-positive rate is shown right on the line when present. */
+function evidenceTag(f) {
+	const level = f.evidenceLevel ?? deriveEvidenceLevel(f.findingType, f.confidence);
+	let tag = `${level} · ${level === "E2" ? "deterministic" : level === "E1" ? "heuristic" : "observation"}`;
+	if (f.measuredFpRate !== void 0) {
+		tag += ` · measured FP ${Math.round(f.measuredFpRate * 100)}%`;
+		if (f.measuredFpN !== void 0) tag += ` · n=${f.measuredFpN}`;
 	}
+	return tag;
 }
-/** Candidates for the default base branch, in fallback order (H-10). */
-const DEFAULT_BASE_CANDIDATES = [
-	"main",
-	"master",
-	"origin/main",
-	"origin/master",
-	"origin/HEAD"
-];
-function resolveMergeBase(root, baseBranch) {
-	const candidates = baseBranch ? [baseBranch, `origin/${baseBranch}`] : DEFAULT_BASE_CANDIDATES;
-	for (const candidate of candidates) {
-		if (candidate.startsWith("-")) continue;
-		const mergeBase = git$1(root, [
-			"merge-base",
-			"HEAD",
-			candidate
-		])?.trim();
-		if (mergeBase) return mergeBase;
+function findingLine(f) {
+	const icon = f.severity === "error" ? "🔴" : f.severity === "warning" ? "🟡" : "🔵";
+	const fix = escapeMarkdown(f.fix);
+	const fixBody = looksLikeCode(f.fix) ? `\`${fix}\`` : `_${fix}_`;
+	return `${icon} **${escapeMarkdown(f.ruleId)}** \`${escapeMarkdown(f.file)}:${f.line}\` — ${escapeMarkdown(f.message)} ${escapeMarkdown(`[${evidenceTag(f)}]`)}\n  Fix: ${fixBody}`;
+}
+/**
+* Render the full comment body (plan M5 redesign). Idempotent by
+* design — the leading HTML comment marker lets the posting workflow
+* find and update its own prior comment instead of spamming a new one
+* on every push.
+*/
+function renderPrComment(result, options = {}) {
+	const lines = [MARKER, ""];
+	lines.push("### 🔨 Mjölnir — Verification Trust");
+	lines.push("");
+	const diff = options.diff;
+	const usingDiff = diff?.hasBaseline === true;
+	const findings = usingDiff ? diff.newFindings : result.findings;
+	if (usingDiff) lines.push(`Comparing against the stored baseline (commit \`${diff.baselineCommit ?? "unknown"}\`) — showing only what this PR changed.`);
+	else if (result.scope === "changed") lines.push("Showing only findings on lines this PR changed.");
+	else lines.push("No baseline was found — showing the full scan. Run `mjolnir baseline` on the base branch to scope future comments to just what changed.");
+	lines.push("");
+	if (result.score !== null) {
+		const state = deriveScoreState(result.score);
+		const verdict = verdictFor(result.score);
+		const baseScore = diff?.baselineScore;
+		if (baseScore !== void 0) {
+			const delta = result.score - baseScore;
+			const sign = delta > 0 ? "+" : "";
+			const commit = diff?.baselineCommit?.slice(0, 7) || "unknown";
+			lines.push(`**Score:** ${result.score}/100 (${sign}${delta} since baseline \`${commit}\`)`);
+		} else lines.push(`**Score:** ${result.score}/100 · ${verdict} (${state.band})`);
+		lines.push("");
+		lines.push(`_${headlineFor(state, result.findings.length)}_`);
+		lines.push("");
 	}
-	return null;
+	if (result.dimensions && result.dimensions.length > 0) {
+		lines.push("| Category | Score |");
+		lines.push("|---|---|");
+		for (const d of result.dimensions) lines.push(`| ${escapeMarkdown(d.category)} | ${d.score}/100 |`);
+		lines.push("");
+	}
+	if (findings.length === 0) lines.push("✅ No new issues found in this PR's changes.");
+	else {
+		const errors = findings.filter((f) => f.severity === "error");
+		const warnings = findings.filter((f) => f.severity === "warning");
+		const infos = findings.filter((f) => f.severity === "info");
+		lines.push(`**${findings.length} new finding${findings.length === 1 ? "" : "s"}** (${errors.length} error, ${warnings.length} warning):`);
+		lines.push("");
+		const groups = [
+			{
+				icon: "🔴",
+				label: "errors",
+				list: errors,
+				open: true
+			},
+			{
+				icon: "🟡",
+				label: "warnings",
+				list: warnings,
+				open: false
+			},
+			{
+				icon: "🔵",
+				label: "infos",
+				list: infos,
+				open: false
+			}
+		];
+		let rendered = 0;
+		for (const g of groups) {
+			if (g.list.length === 0) continue;
+			rendered += Math.min(g.list.length, 25);
+			lines.push("<details" + (g.open ? " open" : "") + ">");
+			lines.push(`<summary>${g.icon} ${g.list.length} ${g.label}</summary>`);
+			lines.push("");
+			for (const f of g.list.slice(0, 25)) lines.push(`- ${findingLine(f)}`);
+			if (g.list.length > 25) {
+				lines.push("");
+				lines.push(`_...and ${g.list.length - 25} more ${g.label}. Run \`mjolnir\` locally for the full list._`);
+			}
+			lines.push("");
+			lines.push("</details>");
+			lines.push("");
+		}
+		const overflow = findings.length - rendered;
+		if (overflow > 0) lines.push(`_...and ${overflow} more overall — run \`mjolnir\` locally (or \`--verbose\`) for the full list._`);
+	}
+	lines.push("");
+	const version = options.version ? `@${options.version}` : "";
+	lines.push("**What to run next:**");
+	lines.push("");
+	lines.push("```bash");
+	lines.push(`npx mjolnir-qa${version} .            # full scan + score`);
+	lines.push(`npx mjolnir-qa${version} . --verbose # every finding, uncapped`);
+	lines.push("```");
+	lines.push("");
+	lines.push(`_Advisory only — this comment never blocks merging. Generated by [Mjölnir](${options.repoUrl ?? "https://github.com/Sergey-Bar/Mjolnir"})._`);
+	if (usingDiff && diff.resolvedFindings.length > 0) {
+		lines.push("");
+		lines.push(`✨ ${diff.resolvedFindings.length} pre-existing finding${diff.resolvedFindings.length === 1 ? "" : "s"} fixed in this PR.`);
+	}
+	return lines.join("\n");
 }
-/** Parse `git diff --name-status -z` output → changed file paths. */
-function collectNameStatus(output) {
-	const entries = output.split("\0").filter(Boolean);
-	const files = [];
-	for (let i = 0; i < entries.length; i++) {
-		const status = entries[i];
-		if (status.startsWith("R") || status.startsWith("C")) i++;
-		const file = entries[i + 1];
-		if (file && isKnownTestFile(file)) files.push(file);
+//#endregion
+//#region src/commands/report-io.ts
+/**
+* Shared saved-report loading (agent-handoff plan §9.0).
+*
+* `summary`, `handoff` and `why` all consume a saved `--json` report.
+* One loader, one validation, one error shape — previously
+* validateReportJson was private to summary.ts; extracting it keeps
+* the three commands byte-identical in their loading behavior without
+* duplication. The exit-code mapping stays in the callers (they own
+* their io), but the error MESSAGES are identical because they come
+* from here.
+*/
+/** Human message for any thrown value — never "undefined"/"[object Object]". */
+function errorText(err) {
+	if (err instanceof Error) return err.message;
+	if (typeof err === "string") return err;
+	if (typeof err === "object" && err !== null) return JSON.stringify(err);
+	return String(err);
+}
+/**
+* Parse-and-validate a saved report. Throws Error with a
+* human-explanatory message on: invalid JSON, non-object document,
+* wrong schemaVersion, missing findings array.
+*/
+function validateReportJson(text) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (err) {
+		throw new Error(`not valid JSON (${errorText(err)})`, { cause: err });
 	}
-	return files;
+	if (typeof parsed !== "object" || parsed === null) throw new Error("the file is a JSON value but not an object");
+	const doc = parsed;
+	if (doc.schemaVersion !== 1) throw new Error(`unsupported schemaVersion ${JSON.stringify(doc.schemaVersion)} — expected 1`);
+	if (!Array.isArray(doc.findings)) throw new Error("missing a \"findings\" array — is this a Mjölnir --json report?");
+	return parsed;
 }
-function computeChangedScope(root, baseBranch) {
-	if (!existsSync(join(root, ".git"))) return {
-		changed: {},
-		degraded: true,
-		reason: "not-a-git-repo"
+/** Load + validate a saved report from disk. Throws on any problem. */
+function loadSavedReport(reportPath) {
+	return validateReportJson(readFileSync(reportPath, "utf8"));
+}
+/** True when the report file exists (callers own the not-found message). */
+function reportExists(reportPath) {
+	return existsSync(reportPath);
+}
+//#endregion
+//#region src/commands/summary.ts
+/**
+* `mjolnir summary [report.json]` — CI annotations + step summary
+* (Terminal + CI UX Overhaul plan, M4).
+*
+* Additive command; default report path `mjolnir.json`. Reads a saved
+* ScanResult JSON (the `--json` scan output) and emits:
+*  1. GitHub annotations to stdout, only when GITHUB_ACTIONS=true —
+*     one per finding, via the single github.ts emitter.
+*  2. A step-summary markdown document to $GITHUB_STEP_SUMMARY when
+*     set (else stdout; --stdout forces stdout): score + band, text
+*     score bar, dimensions table, top deductions, collapsible
+*     per-severity details with fix lines, and an honesty notice for
+*     partial/no-score reports.
+*
+* Exit codes (frozen contract): 0 on success — this command NEVER
+* blocks; the gate step decides. 10 missing file argument. 2
+* unreadable/invalid JSON (a data problem; the message explains).
+*
+* Paths: findings are scan-target-relative. The generated workflow
+* scans the repo root, so the default output is directly usable;
+* `--path-prefix <dir>` re-scopes for subdirectory scans.
+*/
+const DETAILS_PER_SEVERITY_CAP = 25;
+function scoreBar$1(score, width = 20) {
+	const filled = Math.round(score / 100 * width);
+	return `${"█".repeat(filled)}${"░".repeat(Math.max(0, width - filled))}`;
+}
+/** Markdown step summary. Pure over (result, options) — testable. */
+function renderStepSummary(result, options = {}) {
+	const lines = [];
+	lines.push("### 🔨 Mjölnir — Verification Trust");
+	lines.push("");
+	if (result.score === null) {
+		lines.push("Score: **not measurable** — no test files found (`reason: no-tests-found`).");
+		lines.push("");
+		lines.push("> No fake numbers: a repo without tests has no score to show.");
+	} else {
+		const state = deriveScoreState(result.score);
+		const verdict = verdictFor(result.score);
+		lines.push(`Score: **${result.score}/100** · ${verdict} (${state.band}) · ${headlineFor(state, result.findings.length)}`);
+		lines.push("");
+		lines.push("```text");
+		lines.push(`${scoreBar$1(result.score)}  ${result.score}/100`);
+		lines.push("```");
+	}
+	lines.push("");
+	if (result.frameworks.length > 0) {
+		lines.push(`Detected: ${result.frameworks.map((f) => `\`${f}\``).join(" · ")}`);
+		lines.push("");
+	}
+	if (result.dimensions.length > 0) {
+		lines.push("| Category | Score |");
+		lines.push("|----------|-------|");
+		for (const d of result.dimensions) lines.push(`| ${escapeMarkdown(d.category)} | ${d.score}/100 |`);
+		lines.push("");
+	}
+	if (result.rawDeductions !== void 0 && result.testDeclarationCount) {
+		lines.push(`Transparency: ${result.rawDeductions} raw pts over ${result.testDeclarationCount} test declarations (normalized).`);
+		lines.push("");
+	}
+	const bySeverity = {
+		error: [],
+		warning: [],
+		info: []
 	};
-	const mergeBase = resolveMergeBase(root, baseBranch);
-	if (!mergeBase) return {
-		changed: {},
-		degraded: true,
-		reason: "no-merge-base"
+	for (const f of result.findings) bySeverity[f.severity].push(f);
+	const icons = {
+		error: "🔴",
+		warning: "🟡",
+		info: "🔵"
 	};
-	const committed = git$1(root, [
-		"diff",
-		"--name-status",
-		"-z",
-		"--diff-filter=AMR",
-		mergeBase,
-		"HEAD"
-	]);
-	if (committed === null) return {
-		changed: {},
-		degraded: true,
+	for (const sev of [
+		"error",
+		"warning",
+		"info"
+	]) {
+		const list = bySeverity[sev];
+		if (list.length === 0) continue;
+		const open = sev === "error" ? " open" : "";
+		lines.push(`<details${open}>`, `<summary>${icons[sev]} ${list.length} ${sev}${list.length === 1 ? "" : "s"}</summary>`, "");
+		for (const f of list.slice(0, DETAILS_PER_SEVERITY_CAP)) {
+			const path = options.pathPrefix ? `${options.pathPrefix.replace(/\/$/, "")}/${f.file}` : f.file;
+			lines.push(`- **${escapeMarkdown(f.ruleId)}** \`${escapeMarkdown(path)}:${f.line}\` — ${escapeMarkdown(stripAnsiForSummary(f.message))}`);
+			lines.push(`  - Fix: ${escapeMarkdown(stripAnsiForSummary(f.fix))}`);
+		}
+		if (list.length > DETAILS_PER_SEVERITY_CAP) lines.push(`- … and ${list.length - DETAILS_PER_SEVERITY_CAP} more — see the full JSON artifact.`);
+		lines.push("", "</details>", "");
+	}
+	if (result.findings.length === 0 && result.score !== null) {
+		lines.push("Zero findings — nothing to fix.");
+		lines.push("");
+	}
+	if (result.partial) {
+		lines.push("> ⚠ Partial scan: the budget expired or files were skipped — verdict may be incomplete.");
+		lines.push("");
+	}
+	lines.push("<!-- mjolnir-honesty: scores derive from rules with published evidence levels and measured false-positive rates where available. -->");
+	return lines.join("\n");
+}
+/** Render one finding as an escaped annotation line. Fields are
+* sanitized with the same sanitizeData layer the terminal uses
+* (github.ts's escapers cover %/CR/LF, not OSC/C0), then %/CR/LF-escaped. */
+function annotationForFinding(f) {
+	return renderAnnotations([{
+		...f,
+		file: sanitizeData(f.file),
+		ruleId: sanitizeData(f.ruleId),
+		message: truncateMessage(stripAnsiForSummary(sanitizeData(f.message)))
+	}])[0];
+}
+const KNOWN_SUMMARY_FLAGS = /* @__PURE__ */ new Set([
+	"--stdout",
+	"--path-prefix",
+	"--help",
+	"-h"
+]);
+/**
+* Testable summary command core. Returns the process exit code.
+* Streams: annotations → stdout (always; GitHub greps them), summary →
+* step-summary file when set unless --stdout. Unknown flags are a
+* usage error (exit 10) — a typo'd --stdout must not silently route
+* the summary to $GITHUB_STEP_SUMMARY.
+*/
+function runSummaryCommand(argv, io = {
+	out: (line) => console.log(line),
+	err: (line) => console.error(line)
+}) {
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i] ?? "";
+		if (!a.startsWith("-")) continue;
+		if (a === "--path-prefix") {
+			const val = argv[i + 1];
+			if (val === void 0 || val.startsWith("-")) {
+				io.err(usageErrorMessage({
+					flag: "--path-prefix",
+					token: val
+				}));
+				return 10;
+			}
+			i++;
+			continue;
+		}
+		if (KNOWN_SUMMARY_FLAGS.has(a)) continue;
+		io.err(usageErrorMessage({ token: a }));
+		return 10;
+	}
+	const stdout = argv.includes("--stdout");
+	const prefixIdx = argv.indexOf("--path-prefix");
+	const pathPrefix = prefixIdx !== -1 ? argv[prefixIdx + 1] : void 0;
+	const reportPath = argv.filter((a, i) => a !== void 0 && !a.startsWith("-") && (prefixIdx === -1 || i !== prefixIdx + 1))[0] ?? "mjolnir.json";
+	if (!existsSync(reportPath)) {
+		io.err(`mjolnir summary: report file not found: ${reportPath}`);
+		io.err("  Run the scan with --json first: mjolnir --json > mjolnir.json");
+		return 10;
+	}
+	let result;
+	try {
+		result = loadSavedReport(reportPath);
+	} catch (err) {
+		io.err(`mjolnir summary: cannot read ${reportPath}: ${errorText(err)}`);
+		return 2;
+	}
+	const env = process.env;
+	if (env["GITHUB_ACTIONS"] === "true") for (const f of result.findings) {
+		const file = pathPrefix ? `${pathPrefix.replace(/\/$/, "")}/${f.file}` : f.file;
+		io.out(annotationForFinding({
+			...f,
+			file
+		}));
+	}
+	const summary = renderStepSummary(result, {
+		stdout,
+		...pathPrefix !== void 0 ? { pathPrefix } : {}
+	});
+	const stepSummaryPath = stdout ? void 0 : env["GITHUB_STEP_SUMMARY"];
+	if (stepSummaryPath) try {
+		appendFileSync(stepSummaryPath, `${summary}\n`);
+	} catch (err) {
+		io.err(`mjolnir summary: could not write $GITHUB_STEP_SUMMARY (${errorText(err)}); printing to stdout instead.`);
+		io.out(summary);
+	}
+	else io.out(summary);
+	return 0;
+}
+//#endregion
+//#region src/commands/why.ts
+/**
+* `mjolnir why <file>:<line>` — occurrence-level evidence/explanation
+* query (agent-handoff plan M2).
+*
+* Role: an INFORMATIONAL query, not a gate. It works regardless of
+* verdict or tier, shows evidence tags, measured FP rates, runtime
+* corroboration, why/fix, and suppression guidance. Matching is exact
+* file + exact line — the occurrence location as reported, not a
+* durable identity (the fingerprint contract, baseline.ts, governs
+* before/after correlation instead).
+*
+* Two modes:
+* - `--json <mjolnir.json>`: the saved report is AUTHORITATIVE — the
+*   query runs against exactly what the saved scan found (deterministic,
+*   offline).
+* - live (default): runs a fresh scan of the target.
+*
+* Exit codes: 0 match · 1 no finding at that location · 10 usage ·
+* 2 invalid saved report · 20 crash.
+*/
+/** Exact file + exact line match over a finding list. Pure. */
+function explainAt(findings, file, line) {
+	const normalized = file.replace(/\\/g, "/");
+	return {
+		findings: findings.filter((f) => f.file === normalized && f.line === line),
+		file: normalized,
+		line
+	};
+}
+/** Parse the `<file>:<line>` positional (split at the LAST colon). */
+function parseFileLine(token) {
+	const idx = token.lastIndexOf(":");
+	if (idx === -1) return null;
+	const file = token.slice(0, idx);
+	const line = Number(token.slice(idx + 1));
+	if (!file || !Number.isInteger(line) || line < 1) return null;
+	return {
+		file,
+		line
+	};
+}
+function evidenceLines(f, ui) {
+	const lines = [];
+	if (f.evidenceLevel !== void 0 || f.trustLevel !== void 0) {
+		const parts = [];
+		if (f.evidenceLevel !== void 0) parts.push(`evidence ${f.evidenceLevel}`);
+		if (f.trustLevel !== void 0) parts.push(`trust ${f.trustLevel}`);
+		lines.push(`  Evidence: ${parts.join(" · ")}`);
+	}
+	if (f.measuredFpRate !== void 0) {
+		const pct = Math.round(f.measuredFpRate * 100);
+		const n = f.measuredFpN !== void 0 ? ` over ${f.measuredFpN} classified verdicts` : "";
+		lines.push(`  Measured FP rate: ${pct}%${n}`);
+	} else lines.push("  Measured FP rate: none — this rule ships on assumption.");
+	if (f.runtimeCorroboration !== void 0) {
+		const c = f.runtimeCorroboration;
+		const label = c.level === "defect" ? "defect corroborated by the run report" : c.level === "test" ? "the containing test executed in the run report" : "the containing file executed in the run report";
+		lines.push(`  Runtime corroboration: ${label} (${c.source})`);
+	}
+	return lines;
+}
+const SUPPRESSION_HINT = "Suppression (only with cause): an `ignore` entry in mjolnir.config.json — reason REQUIRED, expires after 90 days. Prefer fixing the root cause.";
+/** Render the why answer. Pure over (match, ui). */
+function renderWhy(match, ui = plainContext()) {
+	const { p } = ui;
+	if (match.findings.length === 0) return [
+		sectionHeader(`WHY — ${match.file}:${match.line}`, ui),
+		"",
+		`  No finding at ${match.file}:${match.line} in this report.`,
+		"",
+		p.dim("  Locations are exact (file + line as reported). If the code"),
+		p.dim("  moved since the scan, re-run mjolnir to refresh locations."),
+		""
+	].join("\n");
+	const lines = [
+		sectionHeader(`WHY — ${match.file}:${match.line}`, ui),
+		"",
+		`${match.findings.length} finding${match.findings.length === 1 ? "" : "s"} at this location:`,
+		""
+	];
+	for (const f of match.findings) {
+		lines.push(`  ${severityIcon(f.severity, ui)} ${p.bold(escapeMarkdown(f.ruleId))} — ${escapeMarkdown(f.message)}`);
+		lines.push(`  Why it matters: ${escapeMarkdown(f.why)}`);
+		lines.push(`  Fix: ${escapeMarkdown(f.fix)}`);
+		for (const line of evidenceLines(f, ui)) lines.push(line);
+		lines.push(SUPPRESSION_HINT);
+		lines.push("");
+	}
+	lines.push(nextStep("mjolnir explain <RULE-ID>", ui) + " — full rule context.");
+	return lines.join("\n");
+}
+/**
+* Testable why command core. Returns the process exit code.
+* Live mode awaits the real scan; saved-report mode is synchronous.
+*/
+async function runWhyCommand(argv, io = {
+	out: (line) => console.log(line),
+	err: (line) => console.error(line)
+}) {
+	const locationToken = argv.find((a) => !a.startsWith("-"));
+	if (!locationToken) {
+		io.err("Usage: mjolnir why <file>:<line> [--json <mjolnir.json>]");
+		return 10;
+	}
+	const location = parseFileLine(locationToken);
+	if (!location) {
+		io.err(`mjolnir why: cannot parse location "${locationToken}" — expected <file>:<line>`);
+		return 10;
+	}
+	const jsonIdx = argv.indexOf("--json");
+	const reportPath = jsonIdx !== -1 ? argv[jsonIdx + 1] : void 0;
+	const targetIdx = argv.findIndex((a, i) => !a.startsWith("-") && i !== 0 && (jsonIdx === -1 || i !== jsonIdx + 1));
+	const target = targetIdx !== -1 ? argv[targetIdx] : ".";
+	let result;
+	if (reportPath !== void 0) {
+		if (!reportExists(reportPath)) {
+			io.err(`mjolnir why: report file not found: ${reportPath}`);
+			io.err("  Run the scan with --json first: mjolnir --json > mjolnir.json");
+			return 10;
+		}
+		try {
+			result = loadSavedReport(reportPath);
+		} catch (err) {
+			io.err(`mjolnir why: cannot read ${reportPath}: ${errorText(err)}`);
+			return 2;
+		}
+	} else {
+		if (!existsSync(target)) {
+			io.err(`mjolnir why: scan target does not exist: ${target}`);
+			return 10;
+		}
+		try {
+			result = await runScan({
+				target,
+				json: false,
+				verbose: false,
+				maxDurationMs: Number.POSITIVE_INFINITY,
+				scopeChanged: false,
+				format: "terminal",
+				strict: argv.includes("--strict")
+			});
+		} catch (err) {
+			io.err(`mjolnir why: scan failed: ${errorText(err)}`);
+			return 20;
+		}
+	}
+	const match = explainAt(result.findings, location.file, location.line);
+	const catIdxs = [];
+	argv.forEach((a, i) => {
+		if (a === "--category") catIdxs.push(i + 1);
+	});
+	const categories = catIdxs.map((i) => argv[i]).filter((c) => c !== void 0);
+	const filtered = categories.length > 0 ? match.findings.filter((f) => categories.includes(f.category)) : match.findings;
+	io.out(renderWhy({
+		...match,
+		findings: filtered
+	}));
+	return filtered.length > 0 ? 0 : 1;
+}
+//#endregion
+//#region src/commands/handoff.ts
+const OCCURRENCE_CAP = 25;
+const EVIDENCE_BOUNDARY = {
+	E2: "The detector's evidence is deterministic for this pattern. Check the location, then apply the prescribed fix — the finding is a deterministic defect at its boundary.",
+	E1: "REQUIRES CONFIRMATION before editing. This is a heuristic finding — the detector's observation alone does not prove the defect. Establish the runtime/product context first, and treat the fix as a hypothesis to validate.",
+	E0: "Observation only — informational by definition. This finding can never deduct points or gate CI. Decide whether it matters in context; do NOT 'fix' it blindly."
+};
+function evidenceBoundary(f) {
+	const level = f.evidenceLevel ?? "E1";
+	const base = EVIDENCE_BOUNDARY[level];
+	if (f.runtimeCorroboration !== void 0) return `${base}\n${f.runtimeCorroboration.level === "defect" ? "Runtime corroboration: the run report directly corroborates this defect." : f.runtimeCorroboration.level === "test" ? "Runtime corroboration: the containing test executed in the run report." : "Runtime corroboration: the containing file executed in the run report."}`;
+	return base;
+}
+function fpLine(f) {
+	if (f.measuredFpRate === void 0) return "Measured FP rate: none — this rule ships on assumption (no measured false-positive rate).";
+	return `Measured FP rate: ${Math.round(f.measuredFpRate * 100)}%${f.measuredFpN !== void 0 ? ` over ${f.measuredFpN} classified verdicts` : ""}.`;
+}
+function scoreBar(score, width = 20) {
+	const filled = Math.round(score / 100 * width);
+	return `${"█".repeat(filled)}${"░".repeat(Math.max(0, width - filled))}`;
+}
+function scopeNote(options) {
+	const parts = [];
+	if (options.categories && options.categories.length > 0) parts.push(`categories: ${options.categories.join(", ")}`);
+	if (options.rules && options.rules.length > 0) parts.push(`rules: ${options.rules.join(", ")}`);
+	return parts.length > 0 ? ` (filtered — ${parts.join("; ")})` : "";
+}
+/**
+* The verification procedure block — the Trust contract rendered into
+* every artifact (plan §5.3). `version` is pinned at render time.
+*/
+function verificationBlock(version) {
+	return [
+		"## Verification procedure",
+		"",
+		"1. Before editing (recommended): `mjolnir baseline` captures the pre-fix report.",
+		"2. After the fixes: `npx mjolnir-qa@" + version + " . --scope changed` re-verifies the targeted surface.",
+		"3. Correlate before/after by finding fingerprint (ruleId + file + message — line numbers are occurrence locations, not identity; edits may move lines).",
+		"",
+		"Outcomes:",
+		"",
+		"- **TARGET_RESOLVED** — every fingerprint in this document is absent from the post-fix scan.",
+		"- **TARGET_REMAINS** — at least one target fingerprint is still present. Report it honestly; do not suppress to clear the report.",
+		"- **NEW_FINDINGS_INTRODUCED** — the post-fix scan contains fingerprints absent from the pre-fix report. Report them; do not silently accept them.",
+		"- **VERIFICATION_NOT_RUN** — no post-fix scan, or a partial scan. Never claim a fix is verified without it.",
+		"",
+		"> ⚠ A clean `--scope changed` run re-verifies the targeted changed-scope remediation. It is NOT a statement that the entire repository is clean — run a full scan for that.",
+		"",
+		"Report files changed. Report checks not run. Report unresolved findings honestly."
+	];
+}
+/** The per-rule remediation copy block (fenced, self-contained). */
+function ruleCopyBlock(group, version) {
+	const f = group.findings[0];
+	const occurrences = group.findings.slice(0, OCCURRENCE_CAP).map((x) => `- \`${escapeMarkdown(x.file)}:${x.line}\``).join("\n");
+	const overflow = group.findings.length > OCCURRENCE_CAP ? `\n- … and ${group.findings.length - OCCURRENCE_CAP} more — see the JSON report.` : "";
+	return [
+		"```text",
+		`Remediation task: ${escapeMarkdown(group.ruleId)} (fix group: ${escapeMarkdown(group.fixGroupId ?? group.ruleId)})`,
+		"",
+		`What was detected: ${escapeMarkdown(f.message)}`,
+		"",
+		`Evidence boundary: ${evidenceBoundary(f).replace(/\n/g, " ")}`,
+		escapeMarkdown(fpLine(f)),
+		"",
+		`What should change: ${escapeMarkdown(f.fix)}`,
+		"",
+		"Constraints:",
+		"- Make the smallest behavior-preserving change that fixes the root cause.",
+		"- Preserve public interfaces, failure semantics, and repository conventions.",
+		"- Adapt identifiers and framework details instead of copying blindly.",
+		"- Do NOT disable the rule or suppress matching code merely to obtain a green scan.",
+		"",
+		"Occurrences (validate each):",
+		occurrences,
+		overflow,
+		"",
+		"Verification:",
+		`  npx mjolnir-qa@${version} . --scope changed`,
+		"",
+		"Expected verification behavior: the fingerprint (ruleId + file + message) of every occurrence above disappears from the post-fix scan, and no NEW fingerprint appears.",
+		"",
+		"Report files changed. Report checks not run. Report unresolved findings honestly.",
+		"```"
+	].join("\n");
+}
+/** The full deterministic handoff artifact. Pure over (result, options). */
+function renderHandoff(result, options = {}, version = CLI_VERSION) {
+	const lines = [];
+	lines.push("### 🔨 Mjölnir — Fix Handoff");
+	lines.push("");
+	if (result.score !== null) {
+		const state = deriveScoreState(result.score);
+		const verdict = verdictFor(result.score);
+		lines.push(`Score: **${result.score}/100** · ${verdict} (${state.band}) · ${headlineFor(state, result.findings.length)}`);
+		lines.push("");
+		lines.push("```text");
+		lines.push(`${scoreBar(result.score)}  ${result.score}/100`);
+		lines.push("```");
+	} else lines.push("Score: **not measurable** — no test files found (`reason: no-tests-found`).");
+	lines.push("");
+	if (result.partial) {
+		lines.push("> ⚠ Partial scan: the budget expired or files were skipped — the finding list may be incomplete. Treat VERIFICATION claims accordingly.");
+		lines.push("");
+	}
+	if (result.findings.length === 0) {
+		lines.push("Zero findings — nothing to fix.");
+		lines.push("");
+		lines.push("No remediation prompt is included. Do not modify the repository on the basis of this document.");
+		lines.push("");
+		if (result.partial) {
+			lines.push("> The scan was partial — the absence of findings is only as trustworthy as the scan's coverage.");
+			lines.push("");
+		}
+		return lines.join("\n");
+	}
+	lines.push(`This document turns ${result.findings.length} finding${result.findings.length === 1 ? "" : "s"} into a remediation plan. Work top-down (errors before warnings); validate each occurrence according to its evidence level before editing.`);
+	lines.push("");
+	const groups = /* @__PURE__ */ new Map();
+	for (const f of result.findings) {
+		const gid = f.fixGroupId ?? f.ruleId;
+		const g = groups.get(gid);
+		if (g) g.findings.push(f);
+		else groups.set(gid, {
+			ruleId: f.ruleId,
+			fixGroupId: gid,
+			findings: [f]
+		});
+	}
+	const ruleFilter = options.rules && options.rules.length > 0 ? new Set(options.rules) : void 0;
+	const catFilter = options.categories && options.categories.length > 0 ? new Set(options.categories) : void 0;
+	const selected = [...groups.values()].filter((g) => !ruleFilter || ruleFilter.has(g.ruleId)).map((g) => ({
+		...g,
+		findings: catFilter ? g.findings.filter((f) => catFilter.has(f.category)) : g.findings
+	})).filter((g) => g.findings.length > 0);
+	if (selected.length === 0) {
+		lines.push("No findings match the requested filters — no remediation prompt is included.");
+		lines.push("");
+		return lines.join("\n");
+	}
+	const sevOrder = {
+		error: 0,
+		warning: 1,
+		info: 2
+	};
+	const sortable = selected;
+	sortable.sort((a, b) => {
+		const sa = sevOrder[a.findings[0].severity];
+		const sb = sevOrder[b.findings[0].severity];
+		if (sa !== sb) return sa - sb;
+		if (b.findings.length !== a.findings.length) return b.findings.length - a.findings.length;
+		return a.ruleId < b.ruleId ? -1 : 1;
+	});
+	lines.push("## How to use this document");
+	lines.push("");
+	lines.push("- Validate each occurrence according to its evidence level before editing.", "- Apply the smallest behavior-preserving fix.", "- Re-run the verification procedure below; correlate by fingerprint.", "- Never suppress a finding merely to obtain a green scan (suppressions live in `mjolnir.config.json`, require a reason, and expire after 90 days).");
+	lines.push("");
+	lines.push(scopeNote(options) ? scopeNote(options).trim() : "");
+	if (!scopeNote(options)) lines.pop();
+	lines.push("");
+	for (const g of sortable) {
+		const first = g.findings[0];
+		lines.push(`### ${escapeMarkdown(g.ruleId)} — ${first.severity} × ${g.findings.length} (fix group: ${escapeMarkdown(g.fixGroupId)})`);
+		lines.push("");
+		lines.push(`**What is wrong:** ${escapeMarkdown(first.message)}`);
+		lines.push("");
+		lines.push(`**Why Mjölnir believes it:** ${escapeMarkdown(first.why)}`);
+		lines.push("");
+		lines.push(`**How trustworthy (evidence boundary):**`);
+		lines.push("");
+		lines.push(evidenceBoundary(first));
+		lines.push("");
+		lines.push(escapeMarkdown(fpLine(first)));
+		lines.push("");
+		lines.push(`**What should change:** ${escapeMarkdown(first.fix)}`);
+		lines.push("");
+		lines.push("**What must NOT change:** behavior unrelated to this finding — public interfaces, failure semantics, accessibility, and repository conventions stay intact.");
+		lines.push("");
+		lines.push(`**Occurrences (${g.findings.length}):**`);
+		lines.push("");
+		for (const f of g.findings.slice(0, OCCURRENCE_CAP)) lines.push(`- \`${escapeMarkdown(f.file)}:${f.line}\` — ${escapeMarkdown(f.message)}`);
+		if (g.findings.length > OCCURRENCE_CAP) lines.push(`- … and ${g.findings.length - OCCURRENCE_CAP} more — see the JSON report.`);
+		lines.push("");
+		lines.push(ruleCopyBlock(g, version));
+		lines.push("");
+	}
+	lines.push("## One-shot handoff prompt");
+	lines.push("");
+	lines.push("```text");
+	lines.push(`Work through the ${selected.length} remediation group(s) above IN ORDER. For each:`);
+	lines.push("- Validate the occurrences according to that group's evidence boundary (E2 = deterministic, act after a location check; E1/E0 = confirm in context first, never assume the observation alone proves the defect).");
+	lines.push("- Apply the smallest behavior-preserving fix from the group's instruction.");
+	lines.push("- Do NOT suppress findings merely to make the scan green.");
+	lines.push(`- Re-run: npx mjolnir-qa@${version} . --scope changed`);
+	lines.push("- Correlate before/after by fingerprint (ruleId + file + message).");
+	lines.push("- Report: files changed, checks not run, and any findings that remain (TARGET_REMAINS) or newly appeared (NEW_FINDINGS_INTRODUCED).");
+	lines.push("- Stop and ask the user when an evidence boundary cannot be resolved.");
+	lines.push("```");
+	lines.push("");
+	lines.push(...verificationBlock(version));
+	lines.push("");
+	lines.push(`_Generated by [Mjölnir](https://github.com/Sergey-Bar/Mjolnir) — evidence and verification; the agent remains responsible for every change._`);
+	return lines.join("\n");
+}
+const KNOWN_FLAGS = /* @__PURE__ */ new Set([
+	"--category",
+	"--rules",
+	"--help",
+	"-h"
+]);
+/**
+* Testable handoff command core. Returns the process exit code.
+* `mjolnir handoff [mjolnir.json] [--category <cat>]... [--rules <ids>]`
+*/
+function runHandoffCommand(argv, io = {
+	out: (line) => console.log(line),
+	err: (line) => console.error(line)
+}) {
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (!a.startsWith("-")) continue;
+		if (a === "--category" || a === "--rules") {
+			const val = argv[i + 1];
+			if (val === void 0 || val.startsWith("-")) {
+				io.err(usageErrorMessage({
+					flag: a,
+					token: val
+				}));
+				return 10;
+			}
+			i++;
+			continue;
+		}
+		if (KNOWN_FLAGS.has(a)) continue;
+		io.err(usageErrorMessage({ token: a }));
+		return 10;
+	}
+	const positional = [];
+	const categories = [];
+	let rules;
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--category") {
+			categories.push(argv[i + 1]);
+			i++;
+			continue;
+		}
+		if (a === "--rules") {
+			rules = argv[i + 1].split(",").map((r) => r.trim()).filter((r) => r.length > 0);
+			i++;
+			continue;
+		}
+		if (!a.startsWith("-")) positional.push(a);
+	}
+	const reportPath = positional[0] ?? "mjolnir.json";
+	if (!reportExists(reportPath)) {
+		io.err(`mjolnir handoff: report file not found: ${reportPath}`);
+		io.err("  Run the scan with --json first: mjolnir --json > mjolnir.json");
+		return 10;
+	}
+	let result;
+	try {
+		result = loadSavedReport(reportPath);
+	} catch (err) {
+		io.err(`mjolnir handoff: cannot read ${reportPath}: ${errorText(err)}`);
+		return 2;
+	}
+	io.out(renderHandoff(result, {
+		categories,
+		...rules ? { rules } : {}
+	}));
+	return 0;
+}
+//#endregion
+//#region src/commands/install-agents.ts
+/**
+* `mjolnir install` — instruction-surface installer (agent-handoff
+* plan M4).
+*
+* Directory probes detect INSTRUCTION SURFACES, not agents: the probe
+* is a deterministic, offline existence check. All detected surfaces
+* are written; none take precedence over another.
+*
+* Safety contract (plan §17):
+* - Writes are planned by a pure `planInstall()` and executed by
+*   `executeInstall()`; `--dry-run` never executes.
+* - A target file that exists WITHOUT a Mjölnir marker is user-owned →
+*   refusal (exit 10). `--force` overwrites ONLY marker-identified
+*   Mjölnir-owned files.
+* - Re-running rewrites Mjölnir-owned regions idempotently; identical
+*   content → no write at all.
+* - Content is deterministic (no timestamps) and version-pinned to the
+*   running CLI_VERSION — never @latest.
+*
+* Exit codes: 0 installed/updated/nothing-detected (honest message) ·
+* 10 refusal/usage · 20 crash.
+*/
+const MARKER_OPEN = "<!-- mjolnir:managed";
+const MARKER_CLOSE = "<!-- /mjolnir:managed -->";
+function agentBrief(surface, cwdNote) {
+	return [
+		`# Mjölnir — verification trust loop (${surface})`,
+		"",
+		`${MARKER_OPEN} v${CLI_VERSION} -->`,
+		"",
+		`Run \`${cwdNote}npx mjolnir-qa@${CLI_VERSION} . --scope changed\` before finishing any task that touched test code.`,
+		"",
+		"- Exit 0 = clean. Exit 1 = new findings on changed lines: fix them (smallest behavior-preserving change) or justify them to the user.",
+		`- npx mjolnir-qa@${CLI_VERSION} why <file>:<line> explains any finding (evidence level, measured FP rate, fix).`,
+		`- npx mjolnir-qa@${CLI_VERSION} handoff renders a full remediation plan from a saved --json report.`,
+		"- NEVER suppress a finding merely to obtain a green scan (suppressions live in mjolnir.config.json, require a reason, and expire after 90 days).",
+		"- After fixing: re-run the scan, report files changed, report checks not run, report unresolved findings honestly.",
+		"",
+		`<!-- /mjolnir:managed -->`,
+		""
+	].join("\n");
+}
+/** Enumerate every detected surface with its planned content. Pure. */
+function detectSurfaces(cwd) {
+	const surfaces = [];
+	if (existsSync(join(cwd, ".claude"))) surfaces.push({
+		name: "Claude Code command surface",
+		dir: join(cwd, ".claude", "commands"),
+		file: join(cwd, ".claude", "commands", "mjolnir.md"),
+		content: agentBrief("Claude Code command", "/"),
+		mode: "whole-file"
+	});
+	if (existsSync(join(cwd, ".kilo"))) surfaces.push({
+		name: "Kilo command surface",
+		dir: join(cwd, ".kilo", "command"),
+		file: join(cwd, ".kilo", "command", "mjolnir.md"),
+		content: agentBrief("Kilo command", ""),
+		mode: "whole-file"
+	});
+	if (existsSync(join(cwd, ".cursor"))) surfaces.push({
+		name: "Cursor rule surface",
+		dir: join(cwd, ".cursor", "rules"),
+		file: join(cwd, ".cursor", "rules", "mjolnir.mdc"),
+		content: agentBrief("Cursor rule", ""),
+		mode: "whole-file"
+	});
+	if (existsSync(join(cwd, "AGENTS.md"))) surfaces.push({
+		name: "AGENTS.md instruction surface",
+		dir: cwd,
+		file: join(cwd, "AGENTS.md"),
+		content: agentBrief("AGENTS.md", ""),
+		mode: "append-block"
+	});
+	return surfaces;
+}
+function hasMjolnirMarker(content) {
+	return content.includes("<!-- mjolnir:managed") && content.includes("<!-- /mjolnir:managed -->");
+}
+function mergedBlock(existing, content) {
+	const openIdx = existing.indexOf(MARKER_OPEN);
+	const closeIdx = existing.indexOf(MARKER_CLOSE);
+	if (openIdx !== -1 && closeIdx !== -1 && closeIdx > openIdx) {
+		const body = content.slice(content.indexOf(MARKER_OPEN), content.indexOf(MARKER_CLOSE) + 25);
+		return existing.slice(0, openIdx) + body + existing.slice(closeIdx + 25);
+	}
+	return `${existing}${existing.endsWith("\n") ? "" : "\n"}\n${content}`;
+}
+/** Pure plan: what install WOULD do. Zero I/O. */
+function planInstall(cwd, options = {}) {
+	const surfaces = detectSurfaces(cwd);
+	const entries = [];
+	for (const s of surfaces) {
+		if (s.mode === "append-block") {
+			const existing = readFileSync(s.file, "utf8");
+			if (hasMjolnirMarker(existing)) {
+				const merged = mergedBlock(existing, s.content);
+				entries.push(merged === existing ? {
+					action: "no-op",
+					surface: s.name,
+					file: s.file,
+					content: existing
+				} : {
+					action: "update-in-place",
+					surface: s.name,
+					file: s.file,
+					content: merged
+				});
+				continue;
+			}
+			entries.push({
+				action: "create",
+				surface: s.name,
+				file: s.file,
+				content: mergedBlock(existing, s.content)
+			});
+			continue;
+		}
+		if (existsSync(s.file)) {
+			const existing = readFileSync(s.file, "utf8");
+			if (existing === s.content) {
+				entries.push({
+					action: "no-op",
+					surface: s.name,
+					file: s.file,
+					content: existing
+				});
+				continue;
+			}
+			if (!hasMjolnirMarker(existing)) {
+				entries.push({
+					action: "refuse",
+					surface: s.name,
+					file: s.file,
+					reason: "existing file is not Mjölnir-managed (no marker) — pass --force ONLY after reviewing it"
+				});
+				continue;
+			}
+			if (options.force !== true) {
+				entries.push({
+					action: "refuse",
+					surface: s.name,
+					file: s.file,
+					reason: "Mjölnir-managed file has local edits — pass --force to overwrite"
+				});
+				continue;
+			}
+			entries.push({
+				action: "update-in-place",
+				surface: s.name,
+				file: s.file,
+				content: s.content
+			});
+			continue;
+		}
+		entries.push({
+			action: "create",
+			surface: s.name,
+			file: s.file,
+			content: s.content
+		});
+	}
+	return {
+		entries,
+		detected: surfaces.length
+	};
+}
+/** Execute a plan. Returns the number of files written. */
+function executeInstall(entries) {
+	let written = 0;
+	for (const e of entries) {
+		if (e.action === "refuse" || e.action === "no-op") continue;
+		const dir = join(e.file, "..");
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(e.file, e.content);
+		written++;
+	}
+	return written;
+}
+/**
+* Testable install command core. Returns the process exit code.
+* `mjolnir install [--dry-run] [--force]` — probes the given cwd
+* (production default: process.cwd()).
+*/
+function runInstallCommand(argv, io = {
+	out: (line) => console.log(line),
+	err: (line) => console.error(line)
+}, cwd = process.cwd()) {
+	const dryRun = argv.includes("--dry-run");
+	const force = argv.includes("--force");
+	const stagedHook = argv.includes("--staged-hook");
+	for (const a of argv) {
+		if (a === "--dry-run" || a === "--force" || a === "--staged-hook") continue;
+		if (a === "--help" || a === "-h") continue;
+		io.err(usageMessageFor(a));
+		return 10;
+	}
+	const { entries, detected } = planInstall(cwd, { force });
+	if (detected === 0 && !stagedHook) {
+		io.out("No instruction surfaces detected — nothing to install. Surfaces probed: .claude/ (Claude Code), .kilo/ (Kilo), .cursor/ (Cursor), AGENTS.md.");
+		return 0;
+	}
+	if (dryRun) {
+		io.out("Install plan (dry run — nothing written):");
+		for (const e of entries) if (e.action === "refuse") io.err(`  REFUSE ${e.file}: ${e.reason}`);
+		else io.out(`  ${e.action} ${e.file}`);
+		if (stagedHook) {
+			const hook = planHookInstall(cwd);
+			io.out(`  ${hook.action} ${hook.file} (non-blocking pre-commit hook)`);
+		}
+		return 0;
+	}
+	let refused = false;
+	for (const e of entries) {
+		if (e.action === "refuse") {
+			io.err(`mjolnir install: refusing ${e.file} — ${e.reason}`);
+			refused = true;
+			continue;
+		}
+		if (e.action === "no-op") continue;
+	}
+	const written = executeInstall(entries);
+	for (const e of entries) if (e.action !== "refuse" && e.action !== "no-op") io.out(`  ${e.action}: ${e.surface} → ${e.file} (mjolnir-qa@${CLI_VERSION})`);
+	if (stagedHook) {
+		const hook = planHookInstall(cwd);
+		executeHookInstall(hook);
+		io.out(`  ${hook.action}: non-blocking pre-commit hook → ${hook.file} (mjolnir-qa@${CLI_VERSION} --staged --blocking warning)`);
+	}
+	for (const e of entries) if (e.action !== "refuse" && e.action !== "no-op") io.out(`  ${e.action}: ${e.surface} → ${e.file} (mjolnir-qa@${CLI_VERSION})`);
+	if (refused) {
+		io.err("Some surfaces were skipped — see refusals above. Nothing was overwritten.");
+		return 10;
+	}
+	io.out(`Installed on ${detected} instruction surface(s); ${written} file(s) written.`);
+	return 0;
+}
+function usageMessageFor(token) {
+	return `mjolnir install: unknown argument "${token}" — supported: --dry-run, --force`;
+}
+const HOOK_MARKER_OPEN = "# mjolnir:managed pre-commit (non-blocking)";
+const HOOK_MARKER_CLOSE = "# /mjolnir:managed pre-commit";
+function hookBlock(version) {
+	return [
+		`${HOOK_MARKER_OPEN} v${version}`,
+		`# Advisory: surfaces staged-file findings without blocking the commit.`,
+		`mjolnir --staged --blocking warning || true`,
+		HOOK_MARKER_CLOSE
+	].join("\n");
+}
+/** The hook file an existing hook manager (husky / core.hooksPath) owns. */
+function resolveHookTarget(cwd) {
+	const huskyDir = join(cwd, ".husky");
+	if (existsSync(huskyDir)) return join(huskyDir, "pre-commit");
+	try {
+		const hooksPath = execFileSync("git", [
+			"-C",
+			cwd,
+			"config",
+			"core.hooksPath"
+		], { stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		] }).toString().trim();
+		return join(cwd, hooksPath, "pre-commit");
+	} catch {}
+	return join(cwd, ".git", "hooks", "pre-commit");
+}
+/**
+* Pure plan for `--staged-hook` (plan M5). Reuses husky/core.hooksPath
+* when present; otherwise the default .git/hooks path. Marker-based:
+* an existing hook WITHOUT the marker is user-owned → refuse.
+*/
+function planHookInstall(cwd) {
+	const file = resolveHookTarget(cwd);
+	if (!existsSync(file)) return {
+		action: "create",
+		file
+	};
+	let existing;
+	try {
+		existing = readFileSync(file, "utf8");
+	} catch {
+		return {
+			action: "refuse",
+			file,
+			reason: "existing hook is unreadable"
+		};
+	}
+	if (existing.includes(HOOK_MARKER_OPEN)) return {
+		action: "update",
+		file
+	};
+	return {
+		action: "append",
+		file
+	};
+}
+function executeHookInstall(entry) {
+	switch (entry.action) {
+		case "create":
+			mkdirSync(join(entry.file, ".."), { recursive: true });
+			writeFileSync(entry.file, `#!/bin/sh\n${hookBlock(CLI_VERSION)}\n`);
+			return true;
+		case "append": {
+			const existing = readFileSync(entry.file, "utf8");
+			const sep = existing.endsWith("\n") ? "" : "\n";
+			writeFileSync(entry.file, `${existing}${sep}\n${hookBlock(CLI_VERSION)}\n`);
+			return true;
+		}
+		case "update": {
+			const existing = readFileSync(entry.file, "utf8");
+			const openIdx = existing.indexOf(HOOK_MARKER_OPEN);
+			const closeIdx = existing.indexOf(HOOK_MARKER_CLOSE);
+			if (openIdx !== -1 && closeIdx !== -1) writeFileSync(entry.file, existing.slice(0, openIdx) + hookBlock(CLI_VERSION) + existing.slice(closeIdx + 29));
+			else {
+				const sep = existing.endsWith("\n") ? "" : "\n";
+				writeFileSync(entry.file, `${existing}${sep}\n${hookBlock(CLI_VERSION)}\n`);
+			}
+			return true;
+		}
+		default: return false;
+	}
+}
+//#endregion
+//#region src/scope/changed.ts
+/**
+* Changed-scope engine (Sprint-Plan W6, Product-MVP §9 `--scope changed`).
+*
+* Compares the current branch against its merge-base and reports only
+* findings on NEW/CHANGED lines. Handles: new files, modified files,
+* renames (treated as modified), shallow clones (graceful fallback to
+* full-file attribution), and detached HEAD.
+*
+* Audits H-9/H-10: the changed-file predicate is derived from the real
+* adapter registry (isKnownTestFile) so Python, Java, C#, and workflow
+* changes are not silently dropped; the default base falls back
+* main → master → origin/HEAD, an explicit --base is honored, and the
+* WORKING TREE (uncommitted + untracked files) is included so running
+* locally before committing still sees the change.
+*/
+function git$1(root, args) {
+	try {
+		return execFileSync("git", [
+			"-C",
+			root,
+			...args
+		], {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			],
+			timeout: 15e3
+		});
+	} catch {
+		return null;
+	}
+}
+/** Candidates for the default base branch, in fallback order (H-10). */
+const DEFAULT_BASE_CANDIDATES = [
+	"main",
+	"master",
+	"origin/main",
+	"origin/master",
+	"origin/HEAD"
+];
+function resolveMergeBase(root, baseBranch) {
+	const candidates = baseBranch ? [baseBranch, `origin/${baseBranch}`] : DEFAULT_BASE_CANDIDATES;
+	for (const candidate of candidates) {
+		if (candidate.startsWith("-")) continue;
+		const mergeBase = git$1(root, [
+			"merge-base",
+			"HEAD",
+			candidate
+		])?.trim();
+		if (mergeBase) return mergeBase;
+	}
+	return null;
+}
+/** Parse `git diff --name-status -z` output → changed file paths. */
+function collectNameStatus(output) {
+	const entries = output.split("\0").filter(Boolean);
+	const files = [];
+	for (let i = 0; i < entries.length; i++) {
+		const status = entries[i];
+		if (status.startsWith("R") || status.startsWith("C")) i++;
+		const file = entries[i + 1];
+		if (file && isKnownTestFile(file)) files.push(file);
+	}
+	return files;
+}
+function computeChangedScope(root, baseBranch) {
+	if (!existsSync(join(root, ".git"))) return {
+		changed: {},
+		degraded: true,
+		reason: "not-a-git-repo"
+	};
+	const mergeBase = resolveMergeBase(root, baseBranch);
+	if (!mergeBase) return {
+		changed: {},
+		degraded: true,
+		reason: "no-merge-base"
+	};
+	const committed = git$1(root, [
+		"diff",
+		"--name-status",
+		"-z",
+		"--diff-filter=AMR",
+		mergeBase,
+		"HEAD"
+	]);
+	if (committed === null) return {
+		changed: {},
+		degraded: true,
 		reason: "diff-failed"
 	};
 	const workingTree = git$1(root, [
@@ -10153,6 +11536,23 @@ function filterToChanged(findings, diff) {
 		return false;
 	});
 }
+/**
+* --staged (agent-handoff plan §5.7): the staged file names, as a
+* *scan-surface restriction*. Returns null when git data is
+* unavailable (degraded — callers fall back to the full surface with
+* an honest stderr note). Empty list = genuinely nothing staged.
+*/
+function computeStagedFiles(root) {
+	if (!existsSync(join(root, ".git"))) return null;
+	const raw = git$1(root, [
+		"diff",
+		"--cached",
+		"--name-only",
+		"-z"
+	]);
+	if (raw === null) return null;
+	return raw.split("\0").map((s) => s.trim()).filter((s) => s.length > 0);
+}
 //#endregion
 //#region src/engine/rule-runner.ts
 /**
@@ -10602,8 +12002,18 @@ function gateScript(gate) {
 		"process.exit(0);"
 	].join("\n");
 }
-/** Renders findings into `$GITHUB_STEP_SUMMARY`; tolerates a missing scan result. */
-const SUMMARY_SCRIPT = [
+/**
+* Template v2 (Terminal + CI UX Overhaul plan, M4): the summary step
+* calls `mjolnir summary mjolnir.json` — annotations + step summary via
+* ONE emitter — instead of the v1 inline SUMMARY_SCRIPT. The gate
+* script is unchanged (reads `partial`, `findings[].severity`).
+*/
+/** Renders findings into `$GITHUB_STEP_SUMMARY`; tolerates a missing scan result.
+* v1 inline script, retained ONLY for overwrite-refusal recognition of
+* workflows generated by older versions (they are treated as ours, so
+* a frictionless `ci install` upgrade stays possible). Exported for the
+* recognition test that reconstructs the embedded form. */
+const SUMMARY_SCRIPT_V1 = [
 	"const fs = require(\"fs\");",
 	"let r = {};",
 	"try { r = JSON.parse(fs.readFileSync(\"mjolnir.json\", \"utf8\")); } catch (e) {}",
@@ -10620,6 +12030,13 @@ const SUMMARY_SCRIPT = [
 	"}",
 	"process.stdout.write(lines.length + \" finding(s)\\n\");"
 ].join("\n");
+/** True when a workflow was generated by any Mjölnir template (v1 or v2).
+* The v1 needle is matched in its INDENTED form: the v1 template embedded
+* the script via indentBlock(…, 10) inside the `run: |` scalar, so the
+* raw unindented substring never appears in a real v1 file. */
+function isKnownTemplate(content) {
+	return GATES.some((g) => content === TEMPLATE(g)) || content.includes(indentBlock(SUMMARY_SCRIPT_V1, 10));
+}
 /** Indents an embedded script so it sits inside a YAML `run: |` block scalar. */
 function indentBlock(text, spaces) {
 	const pad = " ".repeat(spaces);
@@ -10659,16 +12076,17 @@ jobs:
       - name: Scan changed code (exit 1/2 is data — the gate step decides)
         continue-on-error: true
         run: npx --yes mjolnir-qa@${CLI_VERSION} . --scope changed --json > mjolnir.json
+      # Reporting, not gating: a crashed scan leaves mjolnir.json empty/missing
+      # and the summary step exits 2/10 — continue-on-error keeps the advisory
+      # job green, exactly like the v1 inline script did (the gate step decides).
+      - name: Annotations + Job Summary
+        if: always()
+        continue-on-error: true
+        run: npx --yes mjolnir-qa@${CLI_VERSION} summary mjolnir.json
       - name: Render PR comment
         if: always()
         continue-on-error: true
         run: npx --yes mjolnir-qa@${CLI_VERSION} pr-comment . > mjolnir-comment.md
-      - name: Append findings to the Job Summary
-        if: always()
-        run: |
-          node -e '
-${indentBlock(SUMMARY_SCRIPT, 10)}
-          '
       # Best-effort: on a pull_request event from a fork the GITHUB_TOKEN is
       # read-only and this step will 403 for every external contributor. The
       # Job Summary above is the fallback that always renders.
@@ -10751,7 +12169,7 @@ function ciInstall(root, gate = "advisory", options = {}) {
 	const existed = existsSync(target);
 	if (existed) {
 		const current = readFileSync(target, "utf8");
-		if (!GATES.some((g) => current === TEMPLATE(g)) && !(options.force ?? false)) return {
+		if (!isKnownTemplate(current) && !(options.force ?? false)) return {
 			written: target,
 			existed,
 			refused: true,
@@ -10768,6 +12186,7 @@ function ciInstall(root, gate = "advisory", options = {}) {
 }
 //#endregion
 //#region src/forensics/analyze.ts
+const ui$14 = plainContext();
 const MAX_RECORDS = 1e5;
 function analyze(records, source) {
 	const verdicts = [];
@@ -10824,7 +12243,7 @@ function bar(ms, maxMs, width = 20) {
 }
 function renderLeaderboard(report) {
 	const lines = [];
-	lines.push("▚▞ FLAKINESS LEADERBOARD");
+	lines.push(sectionHeader("FLAKINESS LEADERBOARD", ui$14));
 	lines.push("");
 	lines.push(`${report.totalTests} tests · ${report.failed} failed · ${report.flakyTests} flaky · ${report.retriedTests} retried`);
 	lines.push("");
@@ -10858,7 +12277,7 @@ function renderFlakyMd(report) {
 	lines.push("| Status | Test | File | Attempts | Duration |");
 	lines.push("|--------|------|------|----------|----------|");
 	for (const v of top) {
-		const status = v.passedOnRetry ? "🔥 TRUE-FLAKE" : "❌ failing";
+		const status = v.passedOnRetry ? `${FLAKE_GLYPH} TRUE-FLAKE` : "❌ failing";
 		lines.push(`| ${status} | \`${v.title}\` | \`${v.file}\` | ${v.attempts} | ${(v.totalDurationMs / 1e3).toFixed(1)}s |`);
 	}
 	lines.push("");
@@ -11085,6 +12504,7 @@ function listFiles(dir) {
 }
 //#endregion
 //#region src/forensics/triage.ts
+const ui$13 = plainContext();
 const QUARANTINE_MIN_ATTEMPTS = 2;
 /** Deterministic triage table rows, worst first. */
 function triageRows(report) {
@@ -11113,7 +12533,7 @@ function suggestAction(v) {
 function renderTriage(report) {
 	const rows = triageRows(report);
 	const lines = [];
-	lines.push("▚▞ FLAKY TRIAGE — auto-generated, do not edit");
+	lines.push(sectionHeader("FLAKY TRIAGE — auto-generated, do not edit", ui$13));
 	lines.push("");
 	if (rows.length === 0) {
 		lines.push("Nothing to triage — no failures or retries in this run.");
@@ -11125,105 +12545,478 @@ function renderTriage(report) {
 		lines.push(`• [${flag}] ${r.title} (${r.file}) — ${r.attempts} attempt${r.attempts === 1 ? "" : "s"} → ${r.suggestedAction}`);
 	}
 	lines.push("");
-	lines.push(`Auto-quarantine proposal: ${quarantineCount} test${quarantineCount === 1 ? "" : "s"} (retried ≥${QUARANTINE_MIN_ATTEMPTS} and failed at least once).`);
-	lines.push("Quarantined tests should run nightly, not per-PR — quarantine is not deletion.");
+	lines.push(`Auto-quarantine proposal: ${quarantineCount} test${quarantineCount === 1 ? "" : "s"} (retried ≥${QUARANTINE_MIN_ATTEMPTS} and failed at least once).`);
+	lines.push("Quarantined tests should run nightly, not per-PR — quarantine is not deletion.");
+	return lines.join("\n");
+}
+/** TRIAGE.md — the meeting artifact. */
+function renderTriageMd(report) {
+	const rows = triageRows(report);
+	const lines = [];
+	lines.push("# TRIAGE.md");
+	lines.push("");
+	lines.push("> Auto-generated by `mjolnir triage` from real run data. Do not edit by hand.");
+	lines.push("");
+	if (rows.length === 0) {
+		lines.push("_No flaky or failing tests this run — nothing to triage._ 🎉");
+		return lines.join("\n");
+	}
+	lines.push("| Status | Test | File | Attempts | Duration | Suggested action | Quarantine? |");
+	lines.push("|--------|------|------|----------|----------|------------------|-------------|");
+	for (const r of rows) {
+		const status = r.passedOnRetry ? `${FLAKE_GLYPH} TRUE-FLAKE` : "❌ FAILING";
+		lines.push(`| ${status} | \`${r.title}\` | \`${r.file}\` | ${r.attempts} | ${(r.totalDurationMs / 1e3).toFixed(1)}s | ${r.suggestedAction} | ${r.proposedQuarantine ? "✅ propose" : "—"} |`);
+	}
+	const q = rows.filter((r) => r.proposedQuarantine).length;
+	lines.push("");
+	lines.push(`**Auto-quarantine proposal: ${q}** — move them to the nightly suite and open tracked tickets.`);
+	lines.push("");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/badge.ts
+/**
+* `mjolnir badge` — evidentiary shields.io endpoint JSON (Tier 1 #5).
+*
+* Static JSON, no server. The badge makes falsifiable claims:
+* score + date + commit. Anyone can click through and verify.
+*/
+/**
+* Badge colors follow the SAME ScoreState bands as the terminal
+* (≥80 trusted / ≥50 warning / <50 critical / 100 forged) — this
+* retarget fixes the historical threshold drift (the badge used
+* ≥90/≥75/≥50 with four bands while the reporter used ≥80/≥50).
+*
+* Shields.io has no cyan or white-gold, so the mapping is documented
+* here: trusted → `important` (blue-family, closest to aurora-cyan),
+* forged → `success` (the strongest positive signal shields offers).
+* The badge is a peripheral surface; ScoreState remains the truth.
+*/
+function colorFor(score) {
+	const band = deriveScoreState(score).band;
+	if (band === "unmeasured") return "lightgrey";
+	if (band === "forged") return "success";
+	if (band === "trusted") return "important";
+	return band === "warning" ? "yellow" : "red";
+}
+/** Build the shields.io endpoint payload from a scan result. */
+function buildBadge(result) {
+	const errors = result.findings.filter((f) => f.severity === "error").length;
+	const score = result.score;
+	return {
+		schemaVersion: 1,
+		label: "MJÖLNIR",
+		message: score === null ? "no tests found" : score === 100 && errors === 0 ? "100/100 · forged" : `${score}/100 · ${errors} error${errors === 1 ? "" : "s"}`,
+		color: colorFor(score),
+		namedLogo: "vitest"
+	};
+}
+/**
+* Full README-ready markdown snippet with commit-bound verification line
+* (the falsifiable claim: "verified at commit X on date Y").
+*/
+function renderBadgeSnippet(result, repoUrl = "https://github.com/Sergey-Bar/Mjolnir") {
+	let commit = "unknown";
+	try {
+		commit = execSync("git rev-parse --short HEAD", {
+			cwd: process.cwd(),
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {}
+	const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+	const errors = result.findings.filter((f) => f.severity === "error").length;
+	return [
+		"```markdown",
+		"[![MJÖLNIR](https://img.shields.io/endpoint?url=<your-badge-json-url>)](" + repoUrl + ")",
+		"<!-- Mjölnir verified at commit " + commit + " on " + date + ": " + (result.score === null ? "no tests found" : result.score + "/100") + ", " + errors + " blocking error(s) -->",
+		"```"
+	].join("\n");
+}
+function writeBadge(result, options) {
+	const path = join(options.outDir, "mjolnir-badge.json");
+	writeFileSync(path, JSON.stringify(buildBadge(result), null, 2));
+	return path;
+}
+//#endregion
+//#region src/commands/help.ts
+/** Ordered registry — grouped by the same categories the overview uses. */
+const HELP_ENTRIES = [
+	{
+		verb: "ci install",
+		summary: "generate the PR workflow (scan + annotations + gate)",
+		usage: "mjolnir ci install [--gate advisory|error|warning] [--force]",
+		examples: ["mjolnir ci install", "mjolnir ci install --gate error --force"],
+		next: "mjolnir --scope changed"
+	},
+	{
+		verb: "pr-comment",
+		summary: "render a scoped PR comment (Markdown)",
+		usage: "mjolnir pr-comment [path] [--base <ref>]",
+		examples: ["mjolnir pr-comment .", "mjolnir pr-comment . --base origin/main"]
+	},
+	{
+		verb: "summary",
+		summary: "CI annotations + step summary from a saved --json report",
+		usage: "mjolnir summary [mjolnir.json] [--stdout] [--path-prefix <dir>]",
+		examples: ["mjolnir --json > mjolnir.json && mjolnir summary mjolnir.json", "mjolnir summary mjolnir.json --stdout"]
+	},
+	{
+		verb: "forensics",
+		summary: "runtime evidence from a real run: retries, flakes, durations",
+		usage: "mjolnir forensics <test-results-dir-or-report-file> [--no-flaky-md]",
+		examples: ["mjolnir forensics test-results"]
+	},
+	{
+		verb: "triage",
+		summary: "flaky-triage proposal + TRIAGE.md meeting artifact",
+		usage: "mjolnir triage <test-results-dir-or-report-file> [--no-md]",
+		examples: ["mjolnir triage test-results --no-md"]
+	},
+	{
+		verb: "pw-report",
+		summary: "Playwright run summary (counts, true flakes, slowest tests)",
+		usage: "mjolnir pw-report <playwright-report.json | test-results-dir>",
+		examples: ["mjolnir pw-report test-results"]
+	},
+	{
+		verb: "doctor:playwright",
+		summary: "Playwright deep scan + Selector Health report",
+		usage: "mjolnir doctor:playwright [path]",
+		examples: ["mjolnir doctor:playwright e2e"]
+	},
+	{
+		verb: "fix",
+		summary: "apply safe auto-fixes with proof (re-scan verifies each)",
+		usage: "mjolnir fix [path] [--dry-run]",
+		examples: ["mjolnir fix --dry-run", "mjolnir fix ."]
+	},
+	{
+		verb: "baseline",
+		summary: "snapshot the current finding set as the comparison point",
+		usage: "mjolnir baseline [path]",
+		examples: ["mjolnir baseline", "mjolnir diff"],
+		next: "mjolnir diff"
+	},
+	{
+		verb: "diff",
+		summary: "compare a fresh scan against the baseline — new/worsened only",
+		usage: "mjolnir diff [path]",
+		examples: ["mjolnir diff"]
+	},
+	{
+		verb: "impact",
+		summary: "what a commit introduced vs resolved, since a prior commit",
+		usage: "mjolnir impact [path] [--since <ref>]",
+		examples: ["mjolnir impact . --since HEAD~1"]
+	},
+	{
+		verb: "debt",
+		summary: "test-debt register with an estimated quarterly cost",
+		usage: "mjolnir debt [path]",
+		examples: ["mjolnir debt"]
+	},
+	{
+		verb: "handover",
+		summary: "new-QA onboarding map of the suite",
+		usage: "mjolnir handover [path]",
+		examples: ["mjolnir handover"]
+	},
+	{
+		verb: "stats",
+		summary: "all-time local counters of fixes seen via diff",
+		usage: "mjolnir stats",
+		examples: ["mjolnir stats"]
+	},
+	{
+		verb: "badge",
+		summary: "shields.io endpoint JSON + snippet from a scan",
+		usage: "mjolnir badge [path]",
+		examples: ["mjolnir badge ."]
+	},
+	{
+		verb: "init",
+		summary: "detect frameworks + setup checklist (never overwrites)",
+		usage: "mjolnir init [--interactive]",
+		examples: ["mjolnir init"]
+	},
+	{
+		verb: "why",
+		summary: "why did Mjölnir flag <file>:<line>? evidence + fix (not a gate)",
+		usage: "mjolnir why <file>:<line> [path] [--json <mjolnir.json>]",
+		examples: ["mjolnir why e2e/a.spec.ts:3", "mjolnir why e2e/a.spec.ts:3 --json mjolnir.json"]
+	},
+	{
+		verb: "handoff",
+		summary: "deterministic fix-handoff artifact from a saved --json report",
+		usage: "mjolnir handoff [mjolnir.json] [--category <cat>] [--rules <ids>]",
+		examples: ["mjolnir --json > mjolnir.json && mjolnir handoff mjolnir.json", "mjolnir handoff mjolnir.json --category QA-PW"]
+	},
+	{
+		verb: "explain",
+		summary: "what/why/fix + measured FP rate for one rule",
+		usage: "mjolnir explain <RULE-ID> [--fixtures-root <dir>]",
+		examples: ["mjolnir explain QA-TEST-001", "mjolnir rules --unmeasured"]
+	},
+	{
+		verb: "rules",
+		summary: "rule catalog with trust metadata (md/json/unmeasured)",
+		usage: "mjolnir rules [--md] [--unmeasured|--measured] [--external]",
+		examples: ["mjolnir rules --md --unmeasured"]
+	},
+	{
+		verb: "suppressions",
+		summary: "list suppressed findings (governance transparency)",
+		usage: "mjolnir suppressions",
+		examples: ["mjolnir suppressions"]
+	},
+	{
+		verb: "create-rule",
+		summary: "scaffold a new rule + fixtures (must-fire, must-not-fire)",
+		usage: "mjolnir create-rule <QA-XXX-nnn> --title \"Rule title\"",
+		examples: ["mjolnir create-rule QA-PW-131 --title \"No request waits\""]
+	},
+	{
+		verb: "doctor",
+		summary: "self-audit of the rule base (fixture firewall, tiers, caps)",
+		usage: "mjolnir doctor [repo-root]",
+		examples: ["mjolnir doctor"]
+	},
+	{
+		verb: "install",
+		summary: "install the agent instruction surfaces + optional staged hook",
+		usage: "mjolnir install [--staged-hook] [--dry-run] [--force]",
+		examples: ["mjolnir install --dry-run", "mjolnir install --staged-hook"]
+	}
+];
+/** Scan-flag entries documented per-flag via the overview. */
+const HELP_FLAGS = [
+	{
+		flag: "--json",
+		summary: "machine-readable output"
+	},
+	{
+		flag: "--format sarif",
+		summary: "SARIF 2.1 for GitHub Code Scanning"
+	},
+	{
+		flag: "--format mermaid",
+		summary: "test-architecture diagram"
+	},
+	{
+		flag: "--tone blunt",
+		summary: "blunter, pattern-mocking messages"
+	},
+	{
+		flag: "--verbose",
+		summary: "show all findings"
+	},
+	{
+		flag: "--scope changed",
+		summary: "only new/changed lines vs merge-base"
+	},
+	{
+		flag: "--max-duration <sec>",
+		summary: "analysis time budget"
+	},
+	{
+		flag: "--width <cols>",
+		summary: "override terminal width"
+	},
+	{
+		flag: "--ascii / --no-ascii",
+		summary: "force glyph mode"
+	},
+	{
+		flag: "--strict",
+		summary: "include quarantine-tier rules"
+	},
+	{
+		flag: "--debug",
+		summary: "print swallowed rule crashes"
+	},
+	{
+		flag: "--cache",
+		summary: "reuse local per-file verdicts"
+	},
+	{
+		flag: "--no-progress",
+		summary: "no live scan-progress line on stderr"
+	},
+	{
+		flag: "--score",
+		summary: "print only the numeric score (or `unknown`)"
+	},
+	{
+		flag: "--category <cat>",
+		summary: "presentation filter (repeatable)"
+	},
+	{
+		flag: "--staged",
+		summary: "scan only git staged files"
+	},
+	{
+		flag: "--blocking <level>",
+		summary: "exit-status override: error|warning|none"
+	}
+];
+const EXIT_CODE_TABLE = [
+	["0", "clean — no findings or the requested artifact was produced"],
+	["1", "errors found (or the diff/impact verdict says the PR should not merge)"],
+	["2", "partial — the scan ran but was truncated, or input was unreadable"],
+	["10", "usage — bad flags or arguments; help is printed"],
+	["20", "crash — internal error; rerun with --debug for the stack trace"]
+];
+function findEntry(verb) {
+	return HELP_ENTRIES.find((e) => e.verb === verb);
+}
+/** True when `mjolnir help <verb>` has a detailed page. */
+function hasVerbHelp(verb) {
+	return findEntry(verb) !== void 0;
+}
+/** One per-verb help page: summary, usage, examples, next step. */
+function renderVerbHelp(verb) {
+	const e = findEntry(verb);
+	if (!e) return [
+		`  No detailed help for "${verb}".`,
+		"",
+		"  $ mjolnir --help",
+		""
+	].join("\n");
+	const lines = [];
+	lines.push(`  ${e.verb} — ${e.summary}`);
+	lines.push("");
+	lines.push(`  Usage:`);
+	lines.push(`    ${e.usage}`);
+	lines.push("");
+	lines.push(`  Examples:`);
+	for (const ex of e.examples) lines.push(`    $ ${ex}`);
+	if (e.next) {
+		lines.push("");
+		lines.push(`  Next step:`);
+		lines.push(`    $ ${e.next}`);
+	}
+	lines.push("");
 	return lines.join("\n");
 }
-/** TRIAGE.md — the meeting artifact. */
-function renderTriageMd(report) {
-	const rows = triageRows(report);
+const DOCS_URL = "https://github.com/Sergey-Bar/Mjolnir#readme";
+/** The overview's grouped one-line sections, in display order. */
+const GROUPS = [
+	{
+		title: "Scan",
+		verbs: []
+	},
+	{
+		title: "CI & PRs",
+		verbs: [
+			"ci install",
+			"summary",
+			"pr-comment",
+			"badge",
+			"impact",
+			"baseline",
+			"diff"
+		]
+	},
+	{
+		title: "Forensics",
+		verbs: [
+			"forensics",
+			"triage",
+			"pw-report",
+			"doctor:playwright"
+		]
+	},
+	{
+		title: "Maintenance",
+		verbs: [
+			"fix",
+			"debt",
+			"stats",
+			"suppressions",
+			"handover",
+			"init",
+			"doctor",
+			"create-rule"
+		]
+	},
+	{
+		title: "Meta",
+		verbs: [
+			"rules",
+			"explain",
+			"why",
+			"handoff",
+			"install"
+		]
+	}
+];
+const SCAN_SUMMARY_LINES = ["mjolnir [path]                 full-repo scan + WORTHINESS score"];
+/**
+* The redesigned root help (plan M2): grouped sections, one-line
+* descriptions, copy-pasteable examples, the frozen exit-code table and
+* the docs link. Content is identical whether colored or piped — the
+* caller decides (runHelpCommand passes a resolved palette; printUsage
+* stays plain).
+*/
+function renderRootHelp(schemaVersion = 1) {
+	const byVerb = new Map(HELP_ENTRIES.map((e) => [e.verb, e]));
 	const lines = [];
-	lines.push("# TRIAGE.md");
+	lines.push("🔨 mjölnir — verification trust engine for test suites and CI pipelines");
 	lines.push("");
-	lines.push("> Auto-generated by `mjolnir triage` from real run data. Do not edit by hand.");
+	lines.push("Usage: mjolnir [path] [options] · mjolnir <subcommand> [args] · mjolnir help <verb>");
 	lines.push("");
-	if (rows.length === 0) {
-		lines.push("_No flaky or failing tests this run — nothing to triage._ 🎉");
-		return lines.join("\n");
+	lines.push("The product is one command in CI:");
+	lines.push("");
+	lines.push("  mjolnir --scope changed        scan only what the branch touched; exit 1 on");
+	lines.push("                                 new findings. `mjolnir ci install` writes the");
+	lines.push("                                 workflow for you.");
+	lines.push("");
+	lines.push("Everything else is optional.");
+	lines.push("");
+	lines.push("  " + SCAN_SUMMARY_LINES[0]);
+	lines.push("  mjolnir explain <RULE-ID>      what/why/fix + measured FP rate for one rule");
+	lines.push("  mjolnir rules --unmeasured     the rules running on assumption, not measurement");
+	lines.push("");
+	lines.push("Options:");
+	for (const f of HELP_FLAGS) {
+		const pad = f.flag.padEnd(22);
+		lines.push(`  ${pad}${f.summary}`);
 	}
-	lines.push("| Status | Test | File | Attempts | Duration | Suggested action | Quarantine? |");
-	lines.push("|--------|------|------|----------|----------|------------------|-------------|");
-	for (const r of rows) {
-		const status = r.passedOnRetry ? "🔥 TRUE-FLAKE" : "❌ FAILING";
-		lines.push(`| ${status} | \`${r.title}\` | \`${r.file}\` | ${r.attempts} | ${(r.totalDurationMs / 1e3).toFixed(1)}s | ${r.suggestedAction} | ${r.proposedQuarantine ? "✅ propose" : "—"} |`);
+	lines.push("  -v, --version         print the installed version and exit");
+	lines.push("  -h, --help            show this help");
+	lines.push("");
+	for (const g of GROUPS) {
+		lines.push(`Subcommands — ${g.title}:`);
+		for (const verb of g.verbs) {
+			const e = byVerb.get(verb);
+			if (!e) continue;
+			const usage = e.usage.replace(/^mjolnir /, "").padEnd(46);
+			lines.push(`  ${usage}${e.summary}`);
+		}
+		lines.push("");
 	}
-	const q = rows.filter((r) => r.proposedQuarantine).length;
+	lines.push("Copy-paste starts:");
+	lines.push("  $ mjolnir                         score this repo's test suite");
+	lines.push("  $ mjolnir --scope changed         CI gate: only what the branch touched");
+	lines.push("  $ mjolnir ci install              write the PR workflow");
+	lines.push("  $ mjolnir forensics test-results  where the flakes hide");
 	lines.push("");
-	lines.push(`**Auto-quarantine proposal: ${q}** — move them to the nightly suite and open tracked tickets.`);
+	lines.push("Per-command help: mjolnir help <verb>   (e.g. mjolnir help fix)");
+	lines.push("");
+	lines.push(`Exit codes: ${EXIT_CODE_TABLE.map(([c]) => c).join(" · ")}`);
+	for (const [code, meaning] of EXIT_CODE_TABLE) lines.push(`  ${code.padEnd(3)} ${meaning}`);
 	lines.push("");
+	lines.push(`Docs: ${DOCS_URL}   (JSON schemaVersion ${schemaVersion}, additive-only)`);
 	return lines.join("\n");
 }
 //#endregion
-//#region src/commands/badge.ts
-/**
-* `mjolnir badge` — evidentiary shields.io endpoint JSON (Tier 1 #5).
-*
-* Static JSON, no server. The badge makes falsifiable claims:
-* score + date + commit. Anyone can click through and verify.
-*/
-/**
-* Badge colors follow the SAME ScoreState bands as the terminal
-* (≥80 trusted / ≥50 warning / <50 critical / 100 forged) — this
-* retarget fixes the historical threshold drift (the badge used
-* ≥90/≥75/≥50 with four bands while the reporter used ≥80/≥50).
-*
-* Shields.io has no cyan or white-gold, so the mapping is documented
-* here: trusted → `important` (blue-family, closest to aurora-cyan),
-* forged → `success` (the strongest positive signal shields offers).
-* The badge is a peripheral surface; ScoreState remains the truth.
-*/
-function colorFor(score) {
-	const band = deriveScoreState(score).band;
-	if (band === "unmeasured") return "lightgrey";
-	if (band === "forged") return "success";
-	if (band === "trusted") return "important";
-	return band === "warning" ? "yellow" : "red";
-}
-/** Build the shields.io endpoint payload from a scan result. */
-function buildBadge(result) {
-	const errors = result.findings.filter((f) => f.severity === "error").length;
-	const score = result.score;
-	return {
-		schemaVersion: 1,
-		label: "MJÖLNIR",
-		message: score === null ? "no tests found" : score === 100 && errors === 0 ? "100/100 · forged" : `${score}/100 · ${errors} error${errors === 1 ? "" : "s"}`,
-		color: colorFor(score),
-		namedLogo: "vitest"
-	};
-}
-/**
-* Full README-ready markdown snippet with commit-bound verification line
-* (the falsifiable claim: "verified at commit X on date Y").
-*/
-function renderBadgeSnippet(result, repoUrl = "https://github.com/Sergey-Bar/Mjolnir") {
-	let commit = "unknown";
-	try {
-		commit = execSync("git rev-parse --short HEAD", {
-			cwd: process.cwd(),
-			encoding: "utf8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			]
-		}).trim();
-	} catch {}
-	const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-	const errors = result.findings.filter((f) => f.severity === "error").length;
-	return [
-		"```markdown",
-		"[![MJÖLNIR](https://img.shields.io/endpoint?url=<your-badge-json-url>)](" + repoUrl + ")",
-		"<!-- Mjölnir verified at commit " + commit + " on " + date + ": " + (result.score === null ? "no tests found" : result.score + "/100") + ", " + errors + " blocking error(s) -->",
-		"```"
-	].join("\n");
-}
-function writeBadge(result, options) {
-	const path = join(options.outDir, "mjolnir-badge.json");
-	writeFileSync(path, JSON.stringify(buildBadge(result), null, 2));
-	return path;
-}
-//#endregion
 //#region src/commands/debt.ts
+const ui$12 = plainContext();
 /** Cost model (documented, conservative): hours/quarter per occurrence. */
 const COST_MODEL = {
 	"QA-TEST-004": {
@@ -11304,21 +13097,17 @@ function computeDebt(result) {
 function renderDebt(result) {
 	const { classes, totalHours } = computeDebt(result);
 	const lines = [];
-	lines.push("▚▞ TEST DEBT REGISTER");
+	lines.push(sectionHeader("TEST DEBT REGISTER", ui$12));
 	lines.push("");
 	if (classes.length === 0) {
 		lines.push("No tracked debt classes found — the suite is clean.");
 		return lines.join("\n");
 	}
-	lines.push("DEBT CLASS                  COUNT   EST. HOURS/QUARTER");
-	lines.push("╞══════════════════════════════════════════════════════╡");
-	for (const c of classes) {
-		const cells = `${c.label.padEnd(26)} ${String(c.count).padStart(5)}   ${c.estHoursPerQuarter.toFixed(1).padStart(8)}`;
-		lines.push(`│ ${cells} │`);
-	}
-	lines.push("╞══════════════════════════════════════════════════════╡");
-	lines.push(`│ TOTAL ESTIMATED DRAG:       ~${totalHours.toFixed(1)} engineer-hours/qtr │`);
-	lines.push("╘══════════════════════════════════════════════════════╛");
+	const rows = ["DEBT CLASS", ""];
+	rows[0] = `DEBT CLASS                  COUNT   EST. HOURS/QUARTER`;
+	for (const c of classes) rows.push(`${c.label.padEnd(26)} ${String(c.count).padStart(5)}   ${c.estHoursPerQuarter.toFixed(1).padStart(8)}`);
+	rows.push(`TOTAL ESTIMATED DRAG:       ~${totalHours.toFixed(1)} engineer-hours/qtr`);
+	for (const row of panel(rows, ui$12)) lines.push(row);
 	lines.push("");
 	lines.push("Cost model is conservative and documented in src/commands/debt.ts.");
 	return lines.join("\n");
@@ -11338,6 +13127,7 @@ function renderDebt(result) {
 * The generated rule intentionally FAILS its fixtures until the author
 * implements it — you cannot ship a stub.
 */
+const ui$11 = plainContext();
 /** Map rule family prefix → source directory + default category. */
 const FAMILY_META = {
 	test: {
@@ -11475,7 +13265,7 @@ function camel(idLower) {
 function renderScaffoldReport(result) {
 	if (!result.ok) return `create-rule failed: ${result.error}`;
 	const lines = [];
-	lines.push("▚▞ RULE SCAFFOLD CREATED");
+	lines.push(sectionHeader("RULE SCAFFOLD CREATED", ui$11));
 	lines.push("");
 	for (const f of result.files) lines.push(`  + ${f}`);
 	lines.push("");
@@ -11488,6 +13278,7 @@ function renderScaffoldReport(result) {
 }
 //#endregion
 //#region src/commands/handover.ts
+const ui$10 = plainContext();
 const FAKE_GREEN_RULES = /* @__PURE__ */ new Set([
 	"QA-TEST-003",
 	"QA-PY-003",
@@ -11557,9 +13348,7 @@ function buildHandover(scan, forensics) {
 }
 function renderHandover(map) {
 	const lines = [];
-	lines.push("╔══════════════════════════════════════════════╗");
-	lines.push("║ WELCOME TO THE TEST SUITE — WHAT YOU NEED TO KNOW");
-	lines.push("╚══════════════════════════════════════════════╝");
+	lines.push(sectionHeader("WELCOME TO THE TEST SUITE — WHAT YOU NEED TO KNOW", ui$10));
 	lines.push("");
 	lines.push(map.summaryLine);
 	for (const s of map.sections) {
@@ -11591,6 +13380,7 @@ function renderHandover(map) {
 * catch in *other* tools. Local-only, zero network (verified by
 * tests/privacy-network-isolation.spec.ts, which scans this file too).
 */
+const ui$9 = plainContext();
 function git(root, args) {
 	try {
 		return execFileSync("git", [
@@ -11765,7 +13555,7 @@ async function computeImpact(root, options) {
 }
 function renderImpact(report) {
 	const lines = [];
-	lines.push("▚▞ IMPACT REPORT");
+	lines.push(sectionHeader("IMPACT REPORT", ui$9));
 	lines.push("");
 	if (!report.hasComparison) {
 		lines.push(`UNKNOWN — no comparison could be made (${report.unknownReason ?? "unknown reason"}).`);
@@ -11819,7 +13609,17 @@ function renderImpact(report) {
 * file if they want a shared baseline; that's a deliberate choice this
 * command does not make for them.
 */
+const ui$8 = plainContext();
 const DEFAULT_BASELINE_PATH = join(".mjolnir", "baseline.json");
+/**
+* Correlation identity for before/after comparison (agent-handoff plan
+* §5.2): ruleId + file + message, deliberately EXCLUDING `line` — a
+* source edit that shifts a finding still correlates. file:line is an
+* occurrence location, not a durable identity; message rewording,
+* file renames and rule-id changes correlate as resolved+new
+* (documented limitation). Exported for the handoff verification
+* contract — do not duplicate this algorithm.
+*/
 function fingerprint(f) {
 	return `${f.ruleId}\u0000${f.file}\u0000${f.message}`;
 }
@@ -11910,21 +13710,21 @@ function diffAgainstBaseline(result, baseline) {
 }
 function renderBaselineSaved(path, count, replaced) {
 	const lines = [
-		"▚▞ BASELINE SAVED",
+		sectionHeader("BASELINE SAVED", ui$8),
 		"",
 		`Captured ${count} finding${count === 1 ? "" : "s"} to ${path}.`
 	];
 	if (replaced?.backupPath !== void 0) lines.push(`Replaced an existing baseline — the previous one was saved to ${replaced.backupPath}.`);
-	lines.push("Run \"mjolnir diff\" after future changes to see only what's new.");
+	lines.push(nextStep("mjolnir diff", ui$8) + " — see only what's new.");
 	return lines.join("\n");
 }
 function renderBaselineDiff(diff) {
 	const lines = [];
-	lines.push("▚▞ DIFF AGAINST BASELINE");
+	lines.push(sectionHeader("DIFF AGAINST BASELINE", ui$8));
 	lines.push("");
 	if (!diff.hasBaseline) {
 		lines.push("UNKNOWN — no baseline found.");
-		lines.push("Run \"mjolnir baseline\" first to capture a comparison point.");
+		lines.push(nextStep("mjolnir baseline", ui$8) + " to capture a comparison point.");
 		return lines.join("\n");
 	}
 	lines.push(`Baseline captured ${diff.baselineCapturedAt ?? "unknown time"} at commit ${diff.baselineCommit ?? "unknown"}.`);
@@ -11970,6 +13770,7 @@ function renderBaselineDiff(diff) {
 * fix recorded by `diff`), announced once and never repeated. Display-only:
 * it does not change scores, exit codes or the JSON schema.
 */
+const ui$7 = plainContext();
 const DEFAULT_STATS_PATH = join(".mjolnir", "stats.json");
 const MILESTONE_MESSAGES = {
 	"first-clean-scan": "MILESTONE: first flawless scan recorded for this repo (score 100, zero findings).",
@@ -12057,12 +13858,13 @@ function saveStats(stats, outPath) {
 }
 function renderStats(stats) {
 	const lines = [];
-	lines.push("▚▞ ALL-TIME STATS (this machine, this repo)");
+	lines.push(sectionHeader("ALL-TIME STATS (this machine, this repo)", ui$7));
 	lines.push("");
 	if (!stats || stats.recordedFixEvents === 0) {
 		lines.push("No fixes recorded yet.");
-		lines.push("Run \"mjolnir baseline\" then \"mjolnir diff\" after making fixes —");
-		lines.push("every real fix diff observes gets counted here, honestly.");
+		lines.push("Fixes are counted here only when observed by mjolnir diff —", "capture a baseline first, then diff after making fixes:");
+		lines.push(nextStep("mjolnir baseline", ui$7));
+		lines.push(nextStep("mjolnir diff", ui$7));
 		lines.push("");
 		lines.push("UNKNOWN: totals before tracking started. This command only counts");
 		lines.push("what it has personally witnessed via mjolnir diff.");
@@ -12080,87 +13882,6 @@ function renderStats(stats) {
 	return lines.join("\n");
 }
 //#endregion
-//#region src/commands/pr-comment.ts
-const MARKER = "<!-- mjolnir-pr-comment -->";
-/**
-* Bug-audit QA-2026-08-30 QA-10: finding metadata rendered into the PR
-* comment body is untrusted (hostile filenames, plugin messages). A raw
-* `|` breaks the markdown layout, a raw backtick escapes the code span,
-* and `<\/script>`/link syntax could inject content into the PR page.
-* Escape markdown-significant characters and strip control/ANSI escapes.
-*/
-function escapeMarkdown(s) {
-	return sanitizeData(s).replace(/([\\`*_{}[\]()#+!|<>])/g, "\\$1");
-}
-/** True when a fix recommendation reads as code rather than prose —
-* those render as a code span, the rest stay italic. */
-function looksLikeCode(s) {
-	return /[(;={]|await |expect\(/.test(s);
-}
-/** Evidence tag per finding — Evidence > Assumption in the fabric: a
-* measured false-positive rate is shown right on the line when present. */
-function evidenceTag(f) {
-	const level = f.evidenceLevel ?? deriveEvidenceLevel(f.findingType, f.confidence);
-	let tag = `${level} · ${level === "E2" ? "deterministic" : level === "E1" ? "heuristic" : "observation"}`;
-	if (f.measuredFpRate !== void 0) {
-		tag += ` · measured FP ${Math.round(f.measuredFpRate * 100)}%`;
-		if (f.measuredFpN !== void 0) tag += ` · n=${f.measuredFpN}`;
-	}
-	return tag;
-}
-function findingLine(f) {
-	const icon = f.severity === "error" ? "🔴" : f.severity === "warning" ? "🟡" : "🔵";
-	const fix = escapeMarkdown(f.fix);
-	const fixBody = looksLikeCode(f.fix) ? `\`${fix}\`` : `_${fix}_`;
-	return `${icon} **${escapeMarkdown(f.ruleId)}** \`${escapeMarkdown(f.file)}:${f.line}\` — ${escapeMarkdown(f.message)} ${escapeMarkdown(`[${evidenceTag(f)}]`)}\n  ${fixBody}`;
-}
-/**
-* Render the full comment body. Idempotent by design — the leading HTML
-* comment marker lets the posting workflow find and update its own prior
-* comment instead of spamming a new one on every push.
-*/
-function renderPrComment(result, options = {}) {
-	const lines = [MARKER, ""];
-	lines.push("### 🔨 Mjölnir scan");
-	lines.push("");
-	const diff = options.diff;
-	const usingDiff = diff?.hasBaseline === true;
-	const findings = usingDiff ? diff.newFindings : result.findings;
-	if (usingDiff) lines.push(`Comparing against the stored baseline (commit \`${diff.baselineCommit ?? "unknown"}\`) — showing only what this PR changed.`);
-	else if (result.scope === "changed") lines.push("Showing only findings on lines this PR changed.");
-	else lines.push("No baseline was found — showing the full scan. Run `mjolnir baseline` on the base branch to scope future comments to just what changed.");
-	lines.push("");
-	if (result.score !== null) {
-		const baseScore = diff?.baselineScore;
-		if (baseScore !== void 0) {
-			const delta = result.score - baseScore;
-			const sign = delta > 0 ? "+" : "";
-			const commit = diff?.baselineCommit?.slice(0, 7) || "unknown";
-			lines.push(`**Score:** ${result.score}/100 (${sign}${delta} since baseline \`${commit}\`)`);
-		} else lines.push(`**Score:** ${result.score}/100`);
-		lines.push("");
-	}
-	if (findings.length === 0) lines.push("✅ No new issues found in this PR's changes.");
-	else {
-		const errors = findings.filter((f) => f.severity === "error").length;
-		const warnings = findings.filter((f) => f.severity === "warning").length;
-		lines.push(`**${findings.length} new finding${findings.length === 1 ? "" : "s"}** (${errors} error, ${warnings} warning):`);
-		lines.push("");
-		for (const f of findings.slice(0, 25)) lines.push(`- ${findingLine(f)}`);
-		if (findings.length > 25) {
-			lines.push("");
-			lines.push(`_...and ${findings.length - 25} more. Run \`mjolnir\` locally for the full list._`);
-		}
-	}
-	if (usingDiff && diff.resolvedFindings.length > 0) {
-		lines.push("");
-		lines.push(`✨ This PR also fixed ${diff.resolvedFindings.length} pre-existing finding${diff.resolvedFindings.length === 1 ? "" : "s"}.`);
-	}
-	lines.push("");
-	lines.push(`_Advisory only — this comment never blocks merging. Generated by [Mjölnir](${options.repoUrl ?? "https://github.com/Sergey-Bar/Mjolnir"})._`);
-	return lines.join("\n");
-}
-//#endregion
 //#region src/commands/init.ts
 /**
 * `mjolnir init` — onboarding wizard (Tier 2 #10).
@@ -12172,6 +13893,7 @@ function renderPrComment(result, options = {}) {
 *
 * Idempotent: existing files are reported, never overwritten.
 */
+const ui$6 = plainContext();
 function runInit(rootDir, workspace, options = {}) {
 	const steps = [];
 	const nextCommands = [];
@@ -12221,7 +13943,7 @@ function runInit(rootDir, workspace, options = {}) {
 }
 function renderInit(result) {
 	const lines = [];
-	lines.push("🔨 MJÖLNIR INIT");
+	lines.push(sectionHeader("MJÖLNIR INIT", ui$6));
 	lines.push("");
 	for (const s of result.steps) {
 		const icon = s.status === "advice" ? "·" : s.status === "exists" ? "=" : "-";
@@ -12230,7 +13952,7 @@ function renderInit(result) {
 	if (result.nextCommands.length > 0) {
 		lines.push("");
 		lines.push("Next commands:");
-		for (const c of result.nextCommands) lines.push(`  $ ${c}`);
+		for (const c of result.nextCommands) lines.push(nextStep(c, ui$6));
 	}
 	lines.push("");
 	lines.push("Existing files are never overwritten — init is safe to re-run.");
@@ -12248,6 +13970,7 @@ function tryReadPackageJson(rootDir) {
 }
 //#endregion
 //#region src/commands/pw-report.ts
+const ui$5 = plainContext();
 function summarizePwRun(report) {
 	const slowest = [...report.verdicts].sort((a, b) => b.totalDurationMs - a.totalDurationMs).slice(0, 5).map((v) => ({
 		title: v.title,
@@ -12267,10 +13990,10 @@ function summarizePwRun(report) {
 }
 function renderPwRunSummary(s) {
 	const lines = [];
-	lines.push("🔨 MJÖLNIR — RUN SUMMARY");
+	lines.push(sectionHeader("MJÖLNIR — RUN SUMMARY", ui$5));
 	lines.push("");
 	lines.push(`${s.total} tests · ${s.passed} passed · ${s.failed} failed · ${s.skipped} skipped`);
-	if (s.retried > 0 || s.trueFlakes > 0) lines.push(`↻ ${s.retried} retried · 🔥 ${s.trueFlakes} TRUE-FLAKE${s.trueFlakes === 1 ? "" : "S"} (passed only on attempt ≥2)`);
+	if (s.retried > 0 || s.trueFlakes > 0) lines.push(`↻ ${s.retried} retried · ${FLAKE_GLYPH} ${s.trueFlakes} TRUE-FLAKE${s.trueFlakes === 1 ? "" : "S"} (passed only on attempt ≥2)`);
 	const secs = (s.wallTimeMs / 1e3).toFixed(1);
 	lines.push(`⏱ total test time: ${secs}s`);
 	if (s.slowest.length > 0 && s.slowest[0].ms > 0) {
@@ -12298,6 +14021,7 @@ function renderPwRunSummary(s) {
 * Everything else stays suggestion-only. No AST surgery on heuristic
 * findings — false fixes would break the brand promise.
 */
+const ui$4 = plainContext();
 const MAX_FILE_BYTES = 524288;
 /**
 * Path-containment guard (adversarial-audit wave; hardened per audit
@@ -12654,7 +14378,7 @@ function fixVerified(edit, fixedText, originalText) {
 }
 function renderFixReport(results, dryRun) {
 	const lines = [];
-	lines.push(dryRun ? "▚▞ FIX PLAN (dry-run)" : "▚▞ FIX REPORT");
+	lines.push(sectionHeader(dryRun ? "FIX PLAN (dry-run)" : "FIX REPORT", ui$4));
 	lines.push("");
 	if (results.length === 0) {
 		lines.push("No safe auto-fixes available for these findings.");
@@ -12662,7 +14386,7 @@ function renderFixReport(results, dryRun) {
 		return lines.join("\n");
 	}
 	for (const r of results) {
-		const icon = r.status === "applied" ? "✔" : r.status === "planned" ? "▸" : r.status === "failed" ? "✗" : "·";
+		const icon = r.status === "applied" ? okIcon(ui$4) : r.status === "planned" ? "▸" : r.status === "failed" ? "✗" : "·";
 		lines.push(`${icon} [${r.ruleId}] ${r.file}:${r.line} — ${r.description}`);
 	}
 	const applied = results.filter((r) => r.status === "applied").length;
@@ -12722,6 +14446,7 @@ function isProvisional(rule) {
 *
 * Exit codes reuse the frozen set: 0 healthy · 1 violations · 20 crash.
 */
+const ui$3 = plainContext();
 const VALID_ID = /^QA-(?:TEST|TQUAL|PW|CI|PY|ENV|JV|CS|CYP|SE|WDIO|PPTR|APM)-\d{3}$/;
 function nonHiddenFiles(dir) {
 	if (!existsSync(dir)) return [];
@@ -12920,7 +14645,7 @@ function runDoctorSelfAudit(fixturesRoot) {
 function renderDoctorReport(report) {
 	const lines = [
 		"",
-		"🔨 MJÖLNIR — SELF-AUDIT",
+		sectionHeader("MJÖLNIR — SELF-AUDIT", ui$3),
 		""
 	];
 	for (const c of report.checks) {
@@ -13030,6 +14755,7 @@ function firstFixtureFile(dir) {
 * must-fire fixture, so the example shown is real detector output, not
 * hand-written prose that can drift from what the rule actually does.
 */
+const ui$2 = plainContext();
 /**
 * Runs the rule against its own must-fire fixture to get one real,
 * concrete example finding. `fixturesRoot` defaults to this repo's own
@@ -13102,7 +14828,7 @@ function renderExplain(result) {
 	const r = result.rule;
 	const evidenceLevel = r.evidenceLevel ?? deriveEvidenceLevel(r.findingType, r.confidence);
 	const lines = [];
-	lines.push(`▚▞ ${r.id} — ${r.title}`);
+	lines.push(sectionHeader(`${r.id} — ${r.title}`, ui$2));
 	lines.push("");
 	lines.push(`Severity:    ${r.severity}`);
 	lines.push(`Confidence:  ${r.confidence}`);
@@ -13229,6 +14955,7 @@ function applySeverityOverrides(findings, cfg) {
 * Suppression governance (Sprint-Plan W7, Product-MVP §12).
 * `mjolnir suppressions` — every suppression stays visible.
 */
+const ui$1 = plainContext();
 function loadSuppressions(root) {
 	const { config, path } = loadConfig(root);
 	const anchor = path ? statSync(path).mtime : void 0;
@@ -13247,7 +14974,7 @@ function renderSuppressions(report) {
 	if (report.total === 0) return "\nNo suppressed findings. Full transparency maintained.\n";
 	const lines = [
 		"",
-		"▚▞ QUALITY GOVERNANCE",
+		sectionHeader("QUALITY GOVERNANCE", ui$1),
 		"",
 		`Suppressed findings: ${report.total}`,
 		`Active:              ${report.active}`,
@@ -13637,6 +15364,7 @@ const LOCATOR_RISK = {
 *   OK    — data-testid attribute selectors
 *   BAD   — CSS class chains, structural selectors, XPath (brittle)
 */
+const ui = plainContext();
 function classifyLocator(line) {
 	if (!/locator|getBy|\$x/.test(line)) return null;
 	if (/getBy(?:Role|Text|Label|Placeholder|AltText|Title|TestId)\s*\(/.test(line)) return "role-based";
@@ -13713,7 +15441,7 @@ function computeSpecHealth(file, lines) {
 function renderSelectorHealth(specs) {
 	const lines = [
 		"",
-		"▚▞ SELECTOR HEALTH",
+		sectionHeader("SELECTOR HEALTH", ui),
 		""
 	];
 	for (const spec of specs) {
@@ -13768,7 +15496,7 @@ function computeSelectorHealth(root, ignoreMatcher = DEFAULT_IGNORE_MATCHER) {
 * `scripts/sync-sarif-version.cjs` on release and guarded by
 * `tests/version-consistency.spec.ts` locally.
 */
-const CLI_VERSION = "0.5.2";
+const CLI_VERSION = "0.5.4";
 const UNIVERSAL_RULES = RULES.map(asUniversal);
 /** Registered rule IDs — used to warn on unknown severityOverrides keys (M4). */
 const KNOWN_RULE_IDS = new Set(RULES.map((r) => r.id));
@@ -13823,7 +15551,7 @@ async function buildUniversalRules(root, strict) {
 * Built from the registry so the scorer never has to import it.
 */
 const SUITE_INVALIDATING_RULE_IDS = new Set(RULES.filter((r) => r.suiteInvalidating === true).map((r) => r.id));
-function parseArgs(argv) {
+function parseArgs(argv, onError) {
 	const args = {
 		target: ".",
 		json: false,
@@ -13832,6 +15560,10 @@ function parseArgs(argv) {
 		scopeChanged: false,
 		format: "terminal"
 	};
+	const reject = (detail) => {
+		onError?.(detail);
+		return null;
+	};
 	for (let i = 0; i < argv.length; i++) {
 		const a = argv[i] ?? "";
 		if (a === "--json") {
@@ -13844,11 +15576,18 @@ function parseArgs(argv) {
 			else if (fmt === "json") {
 				args.format = "json";
 				args.json = true;
-			} else if (fmt !== "terminal") return null;
+			} else if (fmt !== "terminal") return reject({
+				flag: "--format",
+				token: fmt
+			});
 		} else if (a === "--verbose") args.verbose = true;
 		else if (a === "--scope") {
-			if (argv[++i] === "changed") args.scopeChanged = true;
-			else return null;
+			const mode = argv[++i];
+			if (mode === "changed") args.scopeChanged = true;
+			else return reject({
+				flag: "--scope",
+				token: mode
+			});
 		} else if (a === "--base") {
 			const ref = argv[++i];
 			if (!ref || ref.startsWith("-")) return null;
@@ -13864,16 +15603,115 @@ function parseArgs(argv) {
 		} else if (a === "--ascii") args.ascii = true;
 		else if (a === "--no-ascii") args.ascii = false;
 		else if (a === "--tone") {
-			if (argv[++i] === "blunt") args.tone = "blunt";
-			else return null;
+			const tone = argv[++i];
+			if (tone === "blunt") args.tone = "blunt";
+			else return reject({
+				flag: "--tone",
+				token: tone
+			});
 		} else if (a === "--strict") args.strict = true;
 		else if (a === "--debug") args.debug = true;
 		else if (a === "--record-milestones") args.recordMilestones = true;
 		else if (a === "--cache") args.cache = true;
-		else if (a === "--help" || a === "-h") return null;
+		else if (a === "--no-progress") args.noProgress = true;
+		else if (a === "--category") {
+			const cat = argv[++i];
+			if (cat === void 0 || !RULE_CATEGORIES.includes(cat)) return reject({
+				flag: "--category",
+				token: cat
+			});
+			args.categories = [...args.categories ?? [], cat];
+		} else if (a === "--score") args.scoreOnly = true;
+		else if (a === "--staged") args.staged = true;
+		else if (a === "--blocking") {
+			const level = argv[++i];
+			if (level === "error" || level === "warning" || level === "none") args.blocking = level;
+			else return reject({
+				flag: "--blocking",
+				token: level
+			});
+		} else if (a === "--help" || a === "-h") return null;
 		else if (!a.startsWith("-")) args.target = a;
-		else return null;
+		else return reject({ token: a });
+	}
+	return args;
+}
+/** Scan flags that exist — the "did you mean" candidate pool. */
+const KNOWN_SCAN_FLAGS = [
+	"--json",
+	"--format",
+	"--verbose",
+	"--scope",
+	"--base",
+	"--max-duration",
+	"--width",
+	"--ascii",
+	"--no-ascii",
+	"--tone",
+	"--strict",
+	"--debug",
+	"--record-milestones",
+	"--cache",
+	"--help",
+	"-h",
+	"--version",
+	"-v",
+	"--dry-run"
+];
+/** Hand-rolled Levenshtein distance (plan M2: no new dependencies). */
+function levenshtein(a, b) {
+	if (a === b) return 0;
+	if (a.length === 0) return b.length;
+	if (b.length === 0) return a.length;
+	const memo = /* @__PURE__ */ new Map();
+	const walk = (i, j) => {
+		if (i === a.length) return b.length - j;
+		if (j === b.length) return a.length - i;
+		const key = `${i}:${j}`;
+		const hit = memo.get(key);
+		if (hit !== void 0) return hit;
+		const cost = a[i] === b[j] ? 0 : 1;
+		const best = Math.min(walk(i + 1, j) + 1, walk(i, j + 1) + 1, walk(i + 1, j + 1) + cost);
+		memo.set(key, best);
+		return best;
+	};
+	return walk(0, 0);
+}
+/** Nearest known flags within distance ≤ 2, nearest first. */
+function nearestFlags(flag, max = 3) {
+	return KNOWN_SCAN_FLAGS.map((f) => ({
+		f,
+		d: levenshtein(flag, f)
+	})).filter((x) => x.d <= 2).sort((x, y) => x.d - y.d).slice(0, max).map((x) => x.f);
+}
+/**
+* Friendly usage error (plan M2, exit 10 preserved): nearest-flag
+* suggestion, the valid neighbors, and the exact help command. Printed
+* to stderr; findings/usage stay on their documented streams.
+*/
+function usageErrorMessage(detail) {
+	const lines = [];
+	if (detail.flag) lines.push(`mjolnir: invalid value "${detail.token ?? ""}" for ${detail.flag}`);
+	else lines.push(`mjolnir: unknown flag "${detail.token ?? ""}"`);
+	if (detail.token) {
+		const near = nearestFlags(detail.token);
+		if (near.length > 0) lines.push(`  Did you mean: ${near.join("  ")}`);
 	}
+	lines.push(`  Run mjolnir --help for the full flag list.`);
+	return lines.join("\n");
+}
+/**
+* Shared parse-or-report path for scan-backed subcommands: friendly
+* usage errors on stderr (exit 10), the full overview only for an
+* explicit help flag. Returns null when the caller must exit 10.
+*/
+function parseArgsOrUsage(argv, io) {
+	let reported = false;
+	const args = parseArgs(argv, (detail) => {
+		reported = true;
+		io.err(usageErrorMessage(detail));
+	});
+	if (!args && !reported) printUsage(io.out);
 	return args;
 }
 /**
@@ -13972,6 +15810,22 @@ async function runScan(args, hooks = {}) {
 		testFiles: wfBucket
 	});
 	ctx.testFiles.push(...wfBucket);
+	let stagedSurface = false;
+	if (args.staged) {
+		const staged = computeStagedFiles(scanRoot.root);
+		if (staged === null) hooks.onConfigWarning?.("mjolnir: --staged ignored — not a git repository (scanning the full surface).");
+		else {
+			const stagedSet = new Set(staged.map((s) => s.replace(/\\/g, "/")));
+			ctx.testFiles = ctx.testFiles.filter((f) => stagedSet.has(relative(scanRoot.root, f).replace(/\\/g, "/")));
+			stagedSurface = true;
+			if (ctx.testFiles.length === 0) hooks.onConfigWarning?.("mjolnir: --staged — no staged files match the scan surface.");
+		}
+	}
+	hooks.onProgress?.({
+		phase: "discover",
+		done: ctx.testFiles.length,
+		total: ctx.testFiles.length
+	});
 	let scanned = 0;
 	for (const path of ctx.testFiles) {
 		if (Date.now() > deadline) {
@@ -14010,6 +15864,12 @@ async function runScan(args, hooks = {}) {
 			for (const f of cachedFindings) findings.push(f);
 			continue;
 		}
+		hooks.onProgress?.({
+			phase: "parse",
+			done: scanned,
+			total: ctx.testFiles.length,
+			detail: relPath
+		});
 		const adapter = isWorkflow ? githubActionsAdapter : isPython ? pythonAdapter : isJava ? javaAdapter : isCs ? csharpAdapter : typescriptAdapter;
 		const parsedFile = {
 			path: relPath,
@@ -14018,7 +15878,15 @@ async function runScan(args, hooks = {}) {
 		let parsed;
 		const findingsStart = findings.length;
 		try {
-			if (adapter.parseAst && Date.now() <= deadline) parsed = await adapter.parseAst(parsedFile);
+			if (adapter.parseAst && Date.now() <= deadline) {
+				hooks.onProgress?.({
+					phase: "rules",
+					done: scanned,
+					total: ctx.testFiles.length,
+					detail: relPath
+				});
+				parsed = await adapter.parseAst(parsedFile);
+			}
 			const fileForRules = parsed ? {
 				...parsedFile,
 				ast: parsed.ast
@@ -14091,6 +15959,10 @@ async function runScan(args, hooks = {}) {
 	if (runtimeReportPath) try {
 		stampRuntimeCorroboration(findings, runForensics(runtimeReportPath, { writeFlakyMd: false }).report);
 	} catch {}
+	hooks.onProgress?.({
+		phase: "score",
+		done: findings.length
+	});
 	const dimensions = computeDimensions(findings);
 	const rawDeductions = findings.reduce((sum, f) => sum + deductionFor(f), 0);
 	const total = computeTotal(dimensions, findings, {
@@ -14100,8 +15972,10 @@ async function runScan(args, hooks = {}) {
 	});
 	const elapsed = Date.now() - started;
 	const hasTests = testFileCount > 0;
+	for (const f of findings) f.fixGroupId = f.ruleId;
 	const result = {
 		schemaVersion: 1,
+		...stagedSurface ? { staged: { files: testFileCount } } : {},
 		partial: discoveryTruncated || rulesPartial || skippedFiles > 0,
 		score: hasTests ? total : null,
 		...hasTests ? {} : { reason: "no-tests-found" },
@@ -14231,7 +16105,7 @@ function runForensicsCommand(argv, io = {
 		}
 		return report.flakyTests > 0 || report.failed > 0 ? 1 : 0;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
 		return 20;
 	}
 }
@@ -14285,7 +16159,7 @@ function runDoctorCommand(argv, io = {
 		io.out(renderDoctorReport(report));
 		return report.healthy ? 0 : 1;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
 		return 20;
 	}
 }
@@ -14331,7 +16205,7 @@ function runExplainCommand(argv, io = {
 		if (!result.ok) return 10;
 		return 0;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
 		return 20;
 	}
 }
@@ -14371,37 +16245,54 @@ async function runScanCommand(argv, io = {
 	out,
 	err
 }) {
-	const args = parseArgs(argv);
-	if (!args) {
-		printUsage(io.out);
-		return 10;
-	}
+	const args = parseArgsOrUsage(argv, io);
+	if (!args) return 10;
 	const target = resolve(args.target);
 	const invalid = validateScanTarget(target, io.err);
 	if (invalid !== null) return invalid;
 	try {
 		const crashLog = [];
+		const progress = new ProgressRenderer({
+			stream: process$1.stderr,
+			isTTY: shouldRenderProgress({
+				isTTY: process$1.stderr.isTTY === true,
+				noProgress: args.noProgress === true,
+				machineFormat: args.format !== "terminal",
+				env: process$1.env
+			})
+		});
 		const result = await runScan({
 			...args,
 			target
 		}, {
 			onConfigWarning: (message) => io.err(message),
+			onProgress: (e) => progress.onEvent(e),
 			...args.debug ? { onRuleCrash: (ruleId, file, error) => {
 				crashLog.push(`${ruleId} crashed on ${file}: ${error instanceof Error ? error.message : String(error)}`);
 			} } : {}
 		});
+		progress.done();
 		if (args.debug && crashLog.length > 0) {
 			io.err(`debug: ${crashLog.length} rule crash(es) were swallowed by crash isolation:`);
 			for (const line of crashLog.slice(0, 50)) io.err(`  ${line}`);
 			if (crashLog.length > 50) io.err(`  … and ${crashLog.length - 50} more`);
 		}
+		if (args.scoreOnly) {
+			if (args.json) io.err("--score overrides --json; stdout is the bare score.");
+			const { config: scoreConfig } = loadConfig(target, { knownRuleIds: KNOWN_RULE_IDS });
+			io.out(result.score === null ? "unknown" : String(result.score));
+			return exitForFindings(result.findings, args.blocking === "none" ? "advisory" : args.blocking ?? scoreConfig.gate ?? "error");
+		}
 		if (args.format === "sarif") io.out(renderSarif(result));
 		else if (args.format === "mermaid") io.out(renderMermaid(result));
 		else if (args.json) io.out(JSON.stringify(result, null, 2));
 		else {
+			const categories = args.categories;
+			const visible = categories && categories.length > 0 ? result.findings.filter((f) => categories.includes(f.category)) : result.findings;
 			io.out(renderTerminal(result, {
 				isTTY: process$1.stdout.isTTY ?? false,
 				verbose: args.verbose,
+				...categories && categories.length > 0 ? { visibleFindings: visible } : {},
 				...args.width !== void 0 ? { width: args.width } : {},
 				...args.ascii !== void 0 ? { ascii: args.ascii } : {},
 				...args.tone !== void 0 ? { tone: args.tone } : {}
@@ -14419,13 +16310,13 @@ async function runScanCommand(argv, io = {
 		if (result.partial) return 2;
 		const { config, warnings } = loadConfig(target, { knownRuleIds: KNOWN_RULE_IDS });
 		for (const w of warnings) io.err(w);
-		return exitForFindings(result.findings, config.gate ?? "error");
+		return exitForFindings(result.findings, args.blocking === "none" ? "advisory" : args.blocking ?? config.gate ?? "error");
 	} catch (err) {
 		if (err instanceof ConfigValidationError) {
 			io.err(err.message);
 			return 10;
 		}
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, args?.debug === true);
 		return 20;
 	}
 }
@@ -14464,7 +16355,7 @@ function runTriageCommand(argv, io = {
 		}
 		return 0;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
 		return 20;
 	}
 }
@@ -14473,11 +16364,8 @@ async function runBadgeCommand(argv, io = {
 	out,
 	err
 }) {
-	const args = parseArgs(argv);
-	if (!args) {
-		printUsage(io.out);
-		return 10;
-	}
+	const args = parseArgsOrUsage(argv, io);
+	if (!args) return 10;
 	try {
 		const target = resolve(args.target);
 		const invalid = validateScanTarget(target, io.err);
@@ -14492,7 +16380,7 @@ async function runBadgeCommand(argv, io = {
 		io.out(renderBadgeSnippet(result));
 		return 0;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, args?.debug === true);
 		return 20;
 	}
 }
@@ -14501,11 +16389,8 @@ async function runDebtCommand(argv, io = {
 	out,
 	err
 }) {
-	const args = parseArgs(argv);
-	if (!args) {
-		printUsage(io.out);
-		return 10;
-	}
+	const args = parseArgsOrUsage(argv, io);
+	if (!args) return 10;
 	try {
 		const target = resolve(args.target);
 		const invalid = validateScanTarget(target, io.err);
@@ -14517,7 +16402,7 @@ async function runDebtCommand(argv, io = {
 		io.out(renderDebt(result));
 		return 0;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, args?.debug === true);
 		return 20;
 	}
 }
@@ -14527,11 +16412,8 @@ async function runFixCommand(argv, io = {
 	err
 }) {
 	const dryRun = argv.includes("--dry-run");
-	const args = parseArgs(argv.filter((a) => a !== "--dry-run"));
-	if (!args) {
-		printUsage(io.out);
-		return 10;
-	}
+	const args = parseArgsOrUsage(argv.filter((a) => a !== "--dry-run"), io);
+	if (!args) return 10;
 	try {
 		const target = resolve(args.target);
 		const invalid = validateScanTarget(target, io.err);
@@ -14544,7 +16426,7 @@ async function runFixCommand(argv, io = {
 		io.out(renderFixReport(fixes, dryRun));
 		return fixes.some((f) => f.status === "failed") ? 1 : 0;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, args?.debug === true);
 		return 20;
 	}
 }
@@ -14569,7 +16451,7 @@ function runCreateRuleCommand(argv, io = {
 		io.out(renderScaffoldReport(result));
 		return result.ok ? 0 : 1;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
 		return 20;
 	}
 }
@@ -14600,10 +16482,7 @@ async function runImpactCommand(argv, io = {
 	const sinceIdx = argv.indexOf("--since");
 	const since = sinceIdx !== -1 ? argv[sinceIdx + 1] : void 0;
 	const args = parseArgs(sinceIdx === -1 ? argv : argv.filter((_a, i) => i !== sinceIdx && i !== sinceIdx + 1));
-	if (!args) {
-		printUsage(io.out);
-		return 10;
-	}
+	if (!args) return 10;
 	try {
 		const target = resolve(args.target);
 		const invalid = validateScanTarget(target, io.err);
@@ -14618,7 +16497,7 @@ async function runImpactCommand(argv, io = {
 		io.out(renderImpact(report));
 		return report.hasComparison ? 0 : 2;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, args?.debug === true);
 		return 20;
 	}
 }
@@ -14627,11 +16506,8 @@ async function runBaselineCommand(argv, io = {
 	out,
 	err
 }) {
-	const args = parseArgs(argv);
-	if (!args) {
-		printUsage(io.out);
-		return 10;
-	}
+	const args = parseArgsOrUsage(argv, io);
+	if (!args) return 10;
 	try {
 		const target = resolve(args.target);
 		const invalid = validateScanTarget(target, io.err);
@@ -14645,7 +16521,7 @@ async function runBaselineCommand(argv, io = {
 		io.out(renderBaselineSaved(DEFAULT_BASELINE_PATH, result.findings.length, { ...saved.backupPath !== void 0 ? { backupPath: saved.backupPath } : {} }));
 		return 0;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, args?.debug === true);
 		return 20;
 	}
 }
@@ -14654,11 +16530,8 @@ async function runDiffCommand(argv, io = {
 	out,
 	err
 }) {
-	const args = parseArgs(argv);
-	if (!args) {
-		printUsage(io.out);
-		return 10;
-	}
+	const args = parseArgsOrUsage(argv, io);
+	if (!args) return 10;
 	try {
 		const target = resolve(args.target);
 		const invalid = validateScanTarget(target, io.err);
@@ -14683,7 +16556,7 @@ async function runDiffCommand(argv, io = {
 		if (!diff.hasBaseline) return 2;
 		return diff.newFindings.some((f) => f.severity === "error") ? 1 : 0;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, args?.debug === true);
 		return 20;
 	}
 }
@@ -14692,11 +16565,8 @@ async function runPrCommentCommand(argv, io = {
 	out,
 	err
 }) {
-	const args = parseArgs(argv);
-	if (!args) {
-		printUsage(io.out);
-		return 10;
-	}
+	const args = parseArgsOrUsage(argv, io);
+	if (!args) return 10;
 	try {
 		const target = resolve(args.target);
 		const invalid = validateScanTarget(target, io.err);
@@ -14707,10 +16577,13 @@ async function runPrCommentCommand(argv, io = {
 		});
 		const baseline = loadBaseline(join(target, DEFAULT_BASELINE_PATH));
 		const diff = baseline ? diffAgainstBaseline(result, baseline) : void 0;
-		io.out(renderPrComment(result, diff ? { diff } : {}));
+		io.out(renderPrComment(result, {
+			...diff ? { diff } : {},
+			version: CLI_VERSION
+		}));
 		return 0;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, args?.debug === true);
 		return 20;
 	}
 }
@@ -14726,7 +16599,7 @@ function runStatsCommand(argv, io = {
 		io.out(renderStats(stats));
 		return 0;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
 		return 20;
 	}
 }
@@ -14735,11 +16608,8 @@ async function runHandoverCommand(argv, io = {
 	out,
 	err
 }) {
-	const args = parseArgs(argv);
-	if (!args) {
-		printUsage(io.out);
-		return 10;
-	}
+	const args = parseArgsOrUsage(argv, io);
+	if (!args) return 10;
 	try {
 		const target = resolve(args.target);
 		const invalid = validateScanTarget(target, io.err);
@@ -14756,7 +16626,7 @@ async function runHandoverCommand(argv, io = {
 		io.out(renderHandover(buildHandover(result, forensics)));
 		return 0;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, args?.debug === true);
 		return 20;
 	}
 }
@@ -14777,7 +16647,7 @@ function runInitCommand(argv, io = {
 		io.out(renderInit(result));
 		return 0;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
 		return 20;
 	}
 }
@@ -14800,15 +16670,20 @@ function runPwReportCommand(argv, io = {
 		io.out(renderPwRunSummary(summarizePwRun(report)));
 		return report.failed > 0 || report.flakyTests > 0 ? 1 : 0;
 	} catch (err) {
-		io.err("mjolnir internal error:", err instanceof Error ? err.message : String(err));
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
 		return 20;
 	}
 }
-async function main(argv = process$1.argv.slice(2)) {
+async function main(argv = process$1.argv.slice(2), io = {
+	out,
+	err
+}) {
 	if (argv[0] === "--version" || argv[0] === "-v") {
-		out(`mjolnir-qa ${CLI_VERSION}\n`);
+		io.out(`mjolnir-qa ${CLI_VERSION}\n`);
 		return 0;
 	}
+	if (argv.length >= 2 && (argv[1] === "--help" || argv[1] === "-h")) return runHelpCommand([argv[0]], io);
+	if (argv[0] === "ci" && argv.length >= 3 && (argv[2] === "--help" || argv[2] === "-h")) return runHelpCommand(["ci", "install"], io);
 	if (argv[0] === "ci" && argv[1] === "install") return runCiInstall(argv.slice(2));
 	if (argv[0] === "suppressions") return runSuppressions();
 	if (argv[0] === "forensics") return runForensicsCommand(argv.slice(1));
@@ -14819,6 +16694,7 @@ async function main(argv = process$1.argv.slice(2)) {
 	if (argv[0] === "baseline") return runBaselineCommand(argv.slice(1));
 	if (argv[0] === "diff") return runDiffCommand(argv.slice(1));
 	if (argv[0] === "pr-comment") return runPrCommentCommand(argv.slice(1));
+	if (argv[0] === "summary") return runSummaryCommand(argv.slice(1), io);
 	if (argv[0] === "stats") return runStatsCommand(argv.slice(1));
 	if (argv[0] === "fix") return runFixCommand(argv.slice(1));
 	if (argv[0] === "create-rule") return runCreateRuleCommand(argv.slice(1));
@@ -14829,84 +16705,55 @@ async function main(argv = process$1.argv.slice(2)) {
 	if (argv[0] === "rules") return runRulesCommand(argv.slice(1));
 	if (argv[0] === "explain") return runExplainCommand(argv.slice(1));
 	if (argv[0] === "doctor:playwright") return runDoctorPlaywright(argv);
-	return runScanCommand(argv);
+	if (argv[0] === "why") return runWhyCommand(argv.slice(1), io);
+	if (argv[0] === "handoff") return runHandoffCommand(argv.slice(1), io);
+	if (argv[0] === "install") return runInstallCommand(argv.slice(1), io);
+	if (argv[0] === "help") return runHelpCommand(argv.slice(1), io);
+	return runScanCommand(argv, io);
+}
+/**
+* `mjolnir help` / `mjolnir help <verb>` (plan M2). `--help`/`-h` and
+* `<verb> --help` route here too. Exit 0 — help answers a question.
+* Two-word verbs (`ci install`) are resolved first via the join of the
+* leading non-flag tokens, then the single-word form.
+*/
+function runHelpCommand(argv, io = {
+	out,
+	err
+}) {
+	const tokens = argv.filter((a) => !a.startsWith("-"));
+	if (tokens.length >= 2) {
+		const joined = `${tokens[0]} ${tokens[1]}`;
+		if (hasVerbHelp(joined)) {
+			io.out(renderVerbHelp(joined));
+			return 0;
+		}
+	}
+	if (tokens.length > 0) {
+		io.out(renderVerbHelp(tokens[0]));
+		return 0;
+	}
+	io.out(renderRootHelp(1));
+	return 0;
 }
 function printUsage(print) {
-	print(`🔨 mjölnir — verification trust engine for test suites and CI pipelines
-
-Usage: mjolnir [path] [options] · mjolnir <subcommand> [args]
-
-The product is one command in CI:
-
-  mjolnir --scope changed        scan only what the branch touched; exit 1 on
-                                 new findings. \`mjolnir ci install\` writes the
-                                 workflow for you.
-
-Everything else is optional.
-
-  mjolnir [path]                 full-repo scan + WORTHINESS score
-  mjolnir explain <RULE-ID>      what/why/fix + measured FP rate for one rule
-  mjolnir rules --unmeasured     the rules running on assumption, not measurement
-
-Options:
-  --json                machine-readable output (schemaVersion 1)
-  --format sarif        SARIF 2.1 output for GitHub Code Scanning
-  --format mermaid      test-architecture diagram (frameworks → rule
-                        categories → severity), pastes directly into a
-                        GitHub/GitLab markdown comment or a slide
-  --tone blunt          blunter, pattern-mocking messages (opt-in)
-  --verbose             show all findings
-  --scope changed       only findings on new/changed lines vs merge-base
-  --base <ref>          base ref for --scope changed (default: main, then
-                        master, then origin/HEAD); uncommitted local
-                        changes are always included
-  --max-duration <sec>  stop analysis after N seconds (partial results flagged)
-  --width <cols>        override terminal width for box/gauge wrapping
-                        (defaults to the detected terminal width, or 80)
-  --ascii               force plain-ASCII glyphs/box-drawing (auto-detected
-                        for cmd.exe/legacy consoles; use this to force it
-                        anywhere, e.g. an unrecognized CI log renderer)
-  --no-ascii            force Unicode box-drawing even where auto-detection
-                        would have chosen ASCII
-  --strict              include quarantine-tier rules (higher FP risk) in scan
-  --debug               print errors swallowed by rule crash isolation
-                        (display-only; exit codes unchanged)
-  --record-milestones   allow this scan to write .mjolnir/stats.json for
-                        milestone tracking (default: scans never write)
-  --cache               reuse per-file verdicts from the local cache
-                        (.mjolnir/cache/, content-addressed, never leaves
-                        this machine); identical results, faster re-scans
-  -v, --version         print the installed version and exit
-  -h, --help            show this help
-
-Subcommands — everyday:
-  ci install [--gate advisory|error|warning] [--force]
-                                   generate the PR workflow; --force overwrites
-                                   a hand-customized one (default: refuse)
-  explain <RULE-ID> [--fixtures-root <dir>]     what/why/fix + measured FP rate
-  rules [--md] [--unmeasured|--measured] [--external]   rule catalog with trust metadata
-  suppressions                                  list suppressed findings
-
-Subcommands — when something's flaky:
-  forensics <dir|file> [--no-flaky-md]          runtime evidence: retries, flakes
-  triage <dir|file> [--no-md]                   flaky-triage proposal + TRIAGE.md
-  pw-report <dir|file>                          Playwright run summary
-  doctor:playwright                             Playwright deep scan + Selector Health
-
-Subcommands — occasional / reporting:
-  fix [--dry-run]                               apply safe auto-fixes with proof
-  baseline / diff                               snapshot findings, then new/worsened only
-  impact [--since <ref>]                        what changed since a prior commit
-  debt                                          test-debt register with a cost model
-  handover                                      new-QA onboarding map of the suite
-  stats                                         all-time local counters of fixes seen
-  badge                                         shields.io endpoint JSON + snippet
-  pr-comment                                    render a scoped PR comment (Markdown)
-  init [--interactive]                          detect frameworks + setup checklist
-  create-rule <ID> --title "..."                scaffold a new rule + fixtures
-  doctor                                        self-audit of the rule base
-
-Exit codes: 0 clean · 1 errors found · 2 partial · 10 usage · 20 crash`);
+	print(renderRootHelp());
+}
+/**
+* Friendly exit-20 path (plan M2): the crash says it's Mjölnir's bug,
+* not the user's repo, carries the underlying message for a report, and
+* prints the stack ONLY when `debug` is set (uniform across
+* subcommands — they don't parse scan flags). Tests pin
+* /internal error/i. Exported so the --debug stack arm is directly
+* spec-coverable (spawning a real crash under --debug would be flaky).
+*/
+function internalErrorMessage(err, emit, debug) {
+	const message = err instanceof Error ? err.message : String(err);
+	emit("mjolnir internal error — this is a bug in Mjölnir, not your repo:");
+	emit(`  ${message}`);
+	if (debug && err instanceof Error && err.stack) emit(err.stack);
+	emit("Rerun with --debug for the stack trace. Please report this:");
+	emit("  https://github.com/Sergey-Bar/Mjolnir/issues");
 }
 function isEntryPoint() {
 	const argv1 = process$1.argv[1];
@@ -14919,4 +16766,4 @@ function isEntryPoint() {
 }
 if (isEntryPoint()) process$1.exitCode = await main();
 //#endregion
-export { CLI_VERSION, buildUniversalRules, exitForFindings, fallbackWorkspace, isEntryPoint, main, parseArgs, pathMatchesGlob, runBadgeCommand, runBaselineCommand, runCiInstall, runCreateRuleCommand, runDebtCommand, runDiffCommand, runDoctorCommand, runDoctorPlaywright, runExplainCommand, runFixCommand, runForensicsCommand, runHandoverCommand, runImpactCommand, runInitCommand, runPrCommentCommand, runPwReportCommand, runRulesCommand, runScan, runScanCommand, runStatsCommand, runSuppressions, runTriageCommand };
+export { CLI_VERSION, buildUniversalRules, exitForFindings, fallbackWorkspace, internalErrorMessage, isEntryPoint, levenshtein, main, nearestFlags, parseArgs, pathMatchesGlob, runBadgeCommand, runBaselineCommand, runCiInstall, runCreateRuleCommand, runDebtCommand, runDiffCommand, runDoctorCommand, runDoctorPlaywright, runExplainCommand, runFixCommand, runForensicsCommand, runHandoverCommand, runHelpCommand, runImpactCommand, runInitCommand, runPrCommentCommand, runPwReportCommand, runRulesCommand, runScan, runScanCommand, runStatsCommand, runSuppressions, runTriageCommand, usageErrorMessage };