mjolnir-qa 0.5.2 → 0.5.3

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";
@@ -8960,8 +8960,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 +9075,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 +9207,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 +9485,28 @@ 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);
+	appendDimensions(lines, result, ui);
+	appendDeductions(lines, result, counts, ui);
+	appendFixThisFirst(lines, result, ui);
+	appendFindings(lines, result, 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 +9540,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 +9593,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 +9665,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,7 +9707,8 @@ 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;
 	const byRule = /* @__PURE__ */ new Map();
 	for (const f of result.findings) {
@@ -9660,7 +9741,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 +9752,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 +9764,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 +9792,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 +9822,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 +9841,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 +9887,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.2",
+			version: "0.5.3",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -9945,6 +10030,492 @@ function renderMermaid(result) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/reporter/progress.ts
+/**
+* Live scan progress (Terminal + CI UX Overhaul plan, M3).
+*
+* 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.
+*
+* 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.
+*/
+/** 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
+		});
+	});
+}
+/** 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;
+}
+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("");
+	}
+	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");
+}
+//#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;
+/** 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. Module-private: the command is
+* the only consumer; tests exercise it through runSummaryCommand. */
+function validateReportJson(text) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (err) {
+		throw new Error(`not valid JSON (${errorText(err)})`, { cause: err });
+	}
+	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 scoreBar(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(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: []
+	};
+	for (const f of result.findings) bySeverity[f.severity].push(f);
+	const icons = {
+		error: "🔴",
+		warning: "🟡",
+		info: "🔵"
+	};
+	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 = validateReportJson(readFileSync(reportPath, "utf8"));
+	} 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/scope/changed.ts
 /**
 * Changed-scope engine (Sprint-Plan W6, Product-MVP §9 `--scope changed`).
@@ -10602,8 +11173,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 +11201,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 +11247,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 +11340,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 +11357,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 +11414,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 +11448,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 +11675,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 +11704,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.");
@@ -11144,7 +11735,7 @@ function renderTriageMd(report) {
 	lines.push("| Status | Test | File | Attempts | Duration | Suggested action | Quarantine? |");
 	lines.push("|--------|------|------|----------|----------|------------------|-------------|");
 	for (const r of rows) {
-		const status = r.passedOnRetry ? "🔥 TRUE-FLAKE" : "❌ FAILING";
+		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;
@@ -11223,7 +11814,340 @@ function writeBadge(result, options) {
 	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: "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"]
+	}
+];
+/** 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"
+	}
+];
+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");
+}
+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"]
+	}
+];
+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("🔨 mjölnir — verification trust engine for test suites and CI pipelines");
+	lines.push("");
+	lines.push("Usage: mjolnir [path] [options] · mjolnir <subcommand> [args] · mjolnir help <verb>");
+	lines.push("");
+	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("  -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("");
+	}
+	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("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/debt.ts
+const ui$12 = plainContext();
 /** Cost model (documented, conservative): hours/quarter per occurrence. */
 const COST_MODEL = {
 	"QA-TEST-004": {
@@ -11304,21 +12228,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 +12258,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 +12396,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 +12409,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 +12479,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 +12511,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 +12686,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,6 +12740,7 @@ 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");
 function fingerprint(f) {
 	return `${f.ruleId}\u0000${f.file}\u0000${f.message}`;
@@ -11910,21 +12832,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 +12892,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 +12980,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 +13004,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 +13015,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 +13065,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 +13074,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 +13092,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 +13112,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 +13143,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 +13500,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 +13508,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 +13568,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 +13767,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 +13877,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 +13950,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 +14077,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 +14096,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 +14486,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 +14563,7 @@ function computeSpecHealth(file, lines) {
 function renderSelectorHealth(specs) {
 	const lines = [
 		"",
-		"▚▞ SELECTOR HEALTH",
+		sectionHeader("SELECTOR HEALTH", ui),
 		""
 	];
 	for (const spec of specs) {
@@ -13768,7 +14618,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.3";
 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 +14673,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 +14682,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 +14698,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,18 +14725,101 @@ 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 === "--no-progress") args.noProgress = true;
 		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;
+}
 /**
 * Workspace fallback for targets with no discoverable project root
 * (package.json-less repos, Python/Java/C# trees). Exported pure so the
@@ -13972,6 +14916,11 @@ async function runScan(args, hooks = {}) {
 		testFiles: wfBucket
 	});
 	ctx.testFiles.push(...wfBucket);
+	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 +14959,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 +14973,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 +15054,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, {
@@ -14231,7 +15198,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 +15252,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 +15298,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,25 +15338,33 @@ 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}`);
@@ -14425,7 +15400,7 @@ async function runScanCommand(argv, io = {
 			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 +15439,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 +15448,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 +15464,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 +15473,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 +15486,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 +15496,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 +15510,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 +15535,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 +15566,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 +15581,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 +15590,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 +15605,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 +15614,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 +15640,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 +15649,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 +15661,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 +15683,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 +15692,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 +15710,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 +15731,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 +15754,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 +15778,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 +15789,52 @@ 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);
+	if (argv[0] === "help") return runHelpCommand(argv.slice(1), io);
 	return runScanCommand(argv);
 }
+/**
+* `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 +15847,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 };