@gscdump/analysis 0.8.2 → 0.9.1

package/dist/report/index.mjs

@@ -0,0 +1,1814 @@
+import { computeInputHash, createReportRegistry, defineReport } from "@gscdump/engine/report";
+import { runAnalyzerFromSource } from "@gscdump/engine/analyzer";
+const SEVERITY_GLYPH = {
+	info: "i",
+	low: "·",
+	medium: "!",
+	high: "!!"
+};
+function formatReport(report, opts = {}) {
+	const lines = [];
+	lines.push(`# ${report.id} — ${report.site}`);
+	lines.push(`window: ${report.window.start} → ${report.window.end} (${report.window.days}d)`);
+	if (report.window.comparison) lines.push(`compare: ${report.window.comparison.start} → ${report.window.comparison.end}`);
+	if (report.meta.degraded) lines.push(`! degraded: ${report.meta.steps.filter((s) => s.status === "error").map((s) => s.key).join(", ")}`);
+	lines.push("");
+	if (report.sections.length === 0) {
+		lines.push("(no sections)");
+		return lines.join("\n");
+	}
+	for (const section of report.sections) lines.push(...renderSection(section, opts.maxFindingsPerSection));
+	return lines.join("\n");
+}
+function renderSection(section, cap) {
+	const lines = [];
+	const glyph = SEVERITY_GLYPH[section.severity] ?? "";
+	lines.push(`## ${glyph} ${section.title}${section.coverage === "partial" ? " (partial)" : ""}`);
+	if (section.summary.magnitudeLabel) lines.push(`   ${section.summary.magnitudeLabel}`);
+	const findings = cap ? section.findings.slice(0, cap) : section.findings;
+	for (const f of findings) {
+		const metricsStr = Object.entries(f.metrics).map(([k, v]) => `${k}=${formatNumber(v)}`).join(" ");
+		lines.push(`   - [${f.entity.kind}] ${f.entity.value} ${metricsStr}${f.why ? ` — ${f.why}` : ""}`);
+	}
+	if (section.truncated && section.truncated.kept < section.truncated.total) lines.push(`   … +${section.truncated.total - section.truncated.kept} more`);
+	for (const a of section.actions) {
+		const target = a.target ? ` ${a.target.kind}=${a.target.value}` : "";
+		lines.push(`   → ${a.kind}${target}: ${a.rationale}`);
+		if (a.cliHint) lines.push(`     $ ${a.cliHint}`);
+	}
+	lines.push("");
+	return lines;
+}
+function formatNumber(n) {
+	if (!Number.isFinite(n)) return String(n);
+	if (Number.isInteger(n)) return String(n);
+	return n.toFixed(2);
+}
+const DEFAULT_MAX$7 = 5;
+const brandReport = defineReport({
+	id: "brand",
+	description: "Brand vs non-brand share, top brand keywords, and site-wide keyword concentration.",
+	defaultPeriod: "last-28d",
+	defaultComparison: "none",
+	argsSpec: {
+		"brand-terms": {
+			type: "string",
+			description: "Comma-separated brand terms",
+			required: true
+		},
+		"max-findings": {
+			type: "number",
+			description: "Cap findings per section",
+			default: DEFAULT_MAX$7
+		}
+	},
+	plan: (params, window) => {
+		if (!params.brandTerms || !params.brandTerms.trim()) throw new Error("brand report requires --brand-terms <comma,separated,list>");
+		const brandTerms = params.brandTerms.split(",").map((t) => t.trim()).filter(Boolean);
+		const dates = {
+			startDate: window.start,
+			endDate: window.end
+		};
+		return [{
+			key: "brand",
+			type: "brand",
+			params: {
+				...dates,
+				brandTerms,
+				limit: 200
+			},
+			required: true
+		}, {
+			key: "concentration",
+			type: "concentration",
+			params: {
+				...dates,
+				dimension: "keywords",
+				limit: 50
+			}
+		}];
+	},
+	reduce: (results, ctx) => {
+		const max = ctx.params.maxFindings ?? DEFAULT_MAX$7;
+		return { sections: [buildBrandSplitSection(results.brand, max), buildConcentrationSection(results.concentration, max)] };
+	}
+});
+function buildBrandSplitSection(res, max) {
+	const rows = res?.results ?? [];
+	const summary = res?.meta?.summary;
+	const findings = rows.filter((r) => r.segment === "brand").sort((a, b) => b.clicks - a.clicks).slice(0, max).map((r) => ({
+		entity: {
+			kind: "query",
+			value: r.query
+		},
+		metrics: {
+			clicks: r.clicks,
+			impressions: r.impressions,
+			ctr: r.ctr,
+			position: r.position
+		},
+		why: r.page ? `on ${r.page}` : void 0
+	}));
+	const brandShare = summary?.brandShare ?? 0;
+	return {
+		id: "brand-split",
+		title: "Brand vs non-brand",
+		severity: "info",
+		summary: { magnitudeLabel: summary ? `brand share ${(brandShare * 100).toFixed(1)}% (${summary.brandClicks} brand vs ${summary.nonBrandClicks} non-brand clicks)` : "no summary available" },
+		findings,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "brand",
+			params: { type: "brand" }
+		} : void 0
+	};
+}
+function buildConcentrationSection(res, max) {
+	const head = (res?.results ?? [])[0];
+	const findings = (head?.topNItems ?? []).slice(0, max).map((it) => ({
+		entity: {
+			kind: "query",
+			value: it.key
+		},
+		metrics: {
+			clicks: it.clicks,
+			share: it.share
+		}
+	}));
+	const severity = head?.riskLevel === "high" ? "high" : head?.riskLevel === "medium" ? "medium" : "low";
+	return {
+		id: "concentration",
+		title: "Keyword concentration (site-wide)",
+		severity: head ? severity : "info",
+		summary: head ? { magnitudeLabel: `HHI ${head.hhi.toFixed(0)} (${head.riskLevel}); top-N share ${(head.topNConcentration * 100).toFixed(1)}%` } : {},
+		findings,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "concentration",
+			params: {
+				type: "concentration",
+				dimension: "keywords"
+			}
+		} : void 0
+	};
+}
+const DEFAULT_MAX$6 = 5;
+const growthReport = defineReport({
+	id: "growth",
+	description: "Strategic growth signals: content velocity, keyword breadth, intent atlas, and long-tail shape over a long window (default 90d / YoY).",
+	defaultPeriod: "last-90d",
+	defaultComparison: "yoy",
+	argsSpec: { "max-findings": {
+		type: "number",
+		description: "Cap findings per section (long-tail only)",
+		default: DEFAULT_MAX$6
+	} },
+	plan: (_params, window) => {
+		const dates = {
+			startDate: window.start,
+			endDate: window.end
+		};
+		return [
+			{
+				key: "content-velocity",
+				type: "content-velocity",
+				params: {
+					...dates,
+					days: window.days,
+					limit: 200
+				}
+			},
+			{
+				key: "keyword-breadth",
+				type: "keyword-breadth",
+				params: {
+					...dates,
+					limit: 50
+				}
+			},
+			{
+				key: "intent-atlas",
+				type: "intent-atlas",
+				params: {
+					...dates,
+					limit: 50
+				}
+			},
+			{
+				key: "long-tail",
+				type: "long-tail",
+				params: {
+					...dates,
+					limit: 100
+				}
+			}
+		];
+	},
+	reduce: (results, ctx) => {
+		const max = ctx.params.maxFindings ?? DEFAULT_MAX$6;
+		return { sections: [
+			buildContentVelocity(results["content-velocity"]),
+			buildKeywordBreadth(results["keyword-breadth"]),
+			buildIntentAtlas(results["intent-atlas"]),
+			buildLongTail(results["long-tail"], max)
+		] };
+	}
+});
+function buildContentVelocity(res) {
+	const rows = res?.results ?? [];
+	const totalNew = rows.reduce((s, r) => s + r.newKeywords, 0);
+	const avgPerWeek = rows.length > 0 ? totalNew / rows.length : 0;
+	return {
+		id: "content-velocity",
+		title: "Content velocity",
+		severity: "info",
+		summary: { magnitudeLabel: `${totalNew} new keywords across ${rows.length} weeks (avg ${avgPerWeek.toFixed(1)}/wk)` },
+		findings: [],
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "content-velocity",
+			params: { type: "content-velocity" }
+		} : void 0
+	};
+}
+function buildKeywordBreadth(res) {
+	const rows = res?.results ?? [];
+	const totalPages = rows.reduce((s, r) => s + r.pageCount, 0);
+	const top = rows[0];
+	return {
+		id: "keyword-breadth",
+		title: "Keyword breadth",
+		severity: "info",
+		summary: { magnitudeLabel: top ? `${totalPages} pages; modal bucket "${top.bucket}" (${top.pageCount} pages)` : "no data" },
+		findings: [],
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "keyword-breadth",
+			params: { type: "keyword-breadth" }
+		} : void 0
+	};
+}
+function buildIntentAtlas(res) {
+	const rows = res?.results ?? [];
+	return {
+		id: "intent-atlas",
+		title: "Intent atlas",
+		severity: "info",
+		summary: { magnitudeLabel: `${rows.length} clusters covering ${rows.reduce((s, r) => s + r.keywordCount, 0)} keywords` },
+		findings: [],
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "intent-atlas",
+			params: { type: "intent-atlas" }
+		} : void 0
+	};
+}
+function buildLongTail(res, max) {
+	const rows = (res?.results ?? []).sort((a, b) => {
+		const rank = {
+			"head-heavy": 0,
+			"balanced": 1,
+			"flat-tail": 2
+		};
+		const dr = rank[a.fingerprint] - rank[b.fingerprint];
+		return dr !== 0 ? dr : b.headShare - a.headShare;
+	});
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "page",
+			value: r.page
+		},
+		metrics: {
+			queryCount: r.queryCount,
+			impressions: r.totalImpressions,
+			headShare: r.headShare
+		},
+		why: `${r.fingerprint} (${(r.headShare * 100).toFixed(0)}% head share)`
+	}));
+	const headHeavy = rows.filter((r) => r.fingerprint === "head-heavy").length;
+	return {
+		id: "long-tail",
+		title: "Long-tail shape",
+		severity: headHeavy > rows.length / 3 ? "medium" : "info",
+		summary: { magnitudeLabel: `${rows.length} pages analysed; ${headHeavy} head-heavy` },
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "long-tail",
+			params: { type: "long-tail" }
+		} : void 0
+	};
+}
+const DEFAULT_MAX$5 = 5;
+const healthReport = defineReport({
+	id: "health",
+	description: "CTR anomalies, change-points, and position-volatility hot spots in the recent window.",
+	defaultPeriod: "last-28d",
+	defaultComparison: "none",
+	argsSpec: { "max-findings": {
+		type: "number",
+		description: "Cap findings per section",
+		default: DEFAULT_MAX$5
+	} },
+	plan: (_params, window) => {
+		const dates = {
+			startDate: window.start,
+			endDate: window.end
+		};
+		return [
+			{
+				key: "ctr-anomaly",
+				type: "ctr-anomaly",
+				params: {
+					...dates,
+					limit: 100
+				},
+				required: true
+			},
+			{
+				key: "change-point",
+				type: "change-point",
+				params: {
+					...dates,
+					limit: 100
+				}
+			},
+			{
+				key: "position-volatility",
+				type: "position-volatility",
+				params: {
+					...dates,
+					limit: 100
+				}
+			}
+		];
+	},
+	reduce: (results, ctx) => {
+		const max = ctx.params.maxFindings ?? DEFAULT_MAX$5;
+		return { sections: [
+			buildCtrAnomalySection(results["ctr-anomaly"], max),
+			buildChangePointSection$1(results["change-point"], max),
+			buildPositionVolatilitySection(results["position-volatility"], max)
+		] };
+	}
+});
+function buildCtrAnomalySection(res, max) {
+	const rows = (res?.results ?? []).filter((r) => r.breachDaysDown > 0).sort((a, b) => b.clicksLost - a.clicksLost);
+	const kept = rows.slice(0, max);
+	const totalLost = kept.reduce((s, r) => s + r.clicksLost, 0);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "query",
+			value: r.keyword
+		},
+		metrics: {
+			clicksLost: r.clicksLost,
+			breachDays: r.breachDaysDown,
+			severity: r.severity,
+			baselineCtr: r.baselineCtr
+		},
+		why: r.page ? `on ${r.page}` : void 0
+	}));
+	return {
+		id: "ctr-anomaly",
+		title: "CTR anomalies",
+		severity: totalLost >= 100 ? "high" : totalLost >= 25 ? "medium" : kept.length ? "low" : "info",
+		summary: {
+			delta: -totalLost,
+			direction: totalLost > 0 ? "down" : "flat",
+			magnitudeLabel: `${Math.round(totalLost)} clicks lost vs baseline`
+		},
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "ctr-anomaly",
+			params: { type: "ctr-anomaly" }
+		} : void 0
+	};
+}
+function buildChangePointSection$1(res, max) {
+	const rows = (res?.results ?? []).filter((r) => r.direction === "worsened").sort((a, b) => b.llr - a.llr);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "query",
+			value: r.keyword
+		},
+		metrics: {
+			llr: r.llr,
+			delta: r.delta
+		},
+		why: `worsened on ${r.changeDate}${r.page ? ` (${r.page})` : ""}`
+	}));
+	return {
+		id: "change-point",
+		title: "Change-points (worsening)",
+		severity: kept.length ? "medium" : "info",
+		summary: { magnitudeLabel: `${kept.length} worsening segments` },
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "change-point",
+			params: { type: "change-point" }
+		} : void 0
+	};
+}
+function buildPositionVolatilitySection(res, max) {
+	const rows = (res?.results ?? []).sort((a, b) => b.peakVolatility - a.peakVolatility);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "page",
+			value: r.page
+		},
+		metrics: {
+			avgVolatility: r.avgVolatility,
+			peakVolatility: r.peakVolatility,
+			impressions: r.totalImpressions
+		}
+	}));
+	return {
+		id: "position-volatility",
+		title: "Position volatility",
+		severity: kept.length ? "low" : "info",
+		summary: {},
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "position-volatility",
+			params: { type: "position-volatility" }
+		} : void 0
+	};
+}
+const DEFAULT_MAX$4 = 5;
+const DEFAULT_MIN_CHANGE = 5;
+const moversReport = defineReport({
+	id: "movers",
+	description: "Risers, decliners, and striking-distance opportunities over a current vs prior window.",
+	defaultPeriod: "last-7d",
+	defaultComparison: "prev-period",
+	argsSpec: {
+		"max-findings": {
+			type: "number",
+			description: "Cap findings per section",
+			default: DEFAULT_MAX$4
+		},
+		"min-clicks-change": {
+			type: "number",
+			description: "Min absolute click change",
+			default: DEFAULT_MIN_CHANGE
+		}
+	},
+	plan: (_params, window) => {
+		if (!window.comparison) throw new Error("movers report requires a comparison window — pass --vs prev-period");
+		const cur = {
+			startDate: window.start,
+			endDate: window.end
+		};
+		const prev = {
+			prevStartDate: window.comparison.start,
+			prevEndDate: window.comparison.end
+		};
+		return [
+			{
+				key: "movers",
+				type: "movers",
+				params: {
+					...cur,
+					...prev,
+					limit: 200
+				},
+				required: true
+			},
+			{
+				key: "decay",
+				type: "decay",
+				params: {
+					...cur,
+					...prev,
+					limit: 100
+				}
+			},
+			{
+				key: "striking",
+				type: "striking-distance",
+				params: {
+					...cur,
+					limit: 100
+				}
+			}
+		];
+	},
+	reduce: (results, ctx) => {
+		const max = ctx.params.maxFindings ?? DEFAULT_MAX$4;
+		const minChange = ctx.params.minClicksChange ?? DEFAULT_MIN_CHANGE;
+		const sections = [];
+		const moversRes = results.movers;
+		const decayRes = results.decay;
+		const strikingRes = results.striking;
+		sections.push(buildMoversSection(moversRes, "rising", max, minChange));
+		sections.push(buildDeclinersSection(moversRes, decayRes, max, minChange));
+		sections.push(buildStrikingSection$1(strikingRes, max));
+		return { sections };
+	}
+});
+function buildMoversSection(res, direction, max, minChange) {
+	const rows = (res?.results ?? []).filter((r) => r.direction === direction && Math.abs(r.clicksChange) >= minChange).sort((a, b) => Math.abs(b.clicksChange) - Math.abs(a.clicksChange));
+	const total = rows.length;
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "query",
+			value: r.keyword
+		},
+		metrics: {
+			clicks: r.recentClicks,
+			clicksChange: r.clicksChange,
+			clicksChangePercent: r.clicksChangePercent,
+			positionChange: r.positionChange
+		},
+		delta: {
+			metric: "clicks",
+			prior: r.baselineClicks,
+			current: r.recentClicks,
+			pct: r.clicksChangePercent
+		},
+		why: r.page ? `on ${r.page}` : void 0
+	}));
+	const totalDelta = kept.reduce((sum, r) => sum + r.clicksChange, 0);
+	return {
+		id: direction,
+		title: direction === "rising" ? "Rising queries" : "Declining queries",
+		severity: direction === "rising" ? "info" : "medium",
+		summary: {
+			delta: totalDelta,
+			direction: totalDelta > 0 ? "up" : totalDelta < 0 ? "down" : "flat"
+		},
+		findings,
+		truncated: total > max ? {
+			kept: kept.length,
+			total
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "movers",
+			params: { type: "movers" }
+		} : void 0
+	};
+}
+function buildDeclinersSection(moversRes, decayRes, max, minChange) {
+	const decliningQueries = (moversRes?.results ?? []).filter((r) => r.direction === "declining" && Math.abs(r.clicksChange) >= minChange).slice(0, max);
+	const lostPages = (decayRes?.results ?? []).sort((a, b) => b.lostClicks - a.lostClicks).slice(0, max);
+	const findings = [...decliningQueries.map((r) => ({
+		entity: {
+			kind: "query",
+			value: r.keyword
+		},
+		metrics: {
+			clicks: r.recentClicks,
+			clicksChange: r.clicksChange
+		},
+		delta: {
+			metric: "clicks",
+			prior: r.baselineClicks,
+			current: r.recentClicks,
+			pct: r.clicksChangePercent
+		}
+	})), ...lostPages.map((r) => ({
+		entity: {
+			kind: "page",
+			value: r.page
+		},
+		metrics: {
+			clicks: r.currentClicks,
+			lostClicks: r.lostClicks,
+			declinePercent: r.declinePercent
+		},
+		delta: {
+			metric: "clicks",
+			prior: r.previousClicks,
+			current: r.currentClicks,
+			pct: -r.declinePercent * 100
+		},
+		why: "page-level decay"
+	}))];
+	const totalLost = decliningQueries.reduce((s, r) => s + Math.abs(r.clicksChange), 0) + lostPages.reduce((s, r) => s + r.lostClicks, 0);
+	return {
+		id: "decliners",
+		title: "Decliners",
+		severity: totalLost >= 100 ? "high" : totalLost >= 25 ? "medium" : "low",
+		summary: {
+			delta: -totalLost,
+			direction: totalLost > 0 ? "down" : "flat",
+			magnitudeLabel: `${Math.round(totalLost)} clicks lost`
+		},
+		findings,
+		coverage: decayRes && moversRes ? "full" : "partial",
+		actions: lostPages.slice(0, 1).map((r) => ({
+			kind: "analyzer",
+			target: {
+				kind: "page",
+				value: r.page
+			},
+			params: { type: "change-point" },
+			rationale: "Investigate the change-point on the worst-affected page",
+			cliHint: `gscdump analyze change-point --start <date> --end <date>`
+		}))
+	};
+}
+function buildStrikingSection$1(res, max) {
+	const rows = (res?.results ?? []).sort((a, b) => b.potentialClicks - a.potentialClicks);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "query",
+			value: r.keyword
+		},
+		metrics: {
+			position: r.position,
+			impressions: r.impressions,
+			clicks: r.clicks,
+			potentialClicks: r.potentialClicks
+		},
+		why: r.page ? `currently on ${r.page}` : void 0
+	}));
+	return {
+		id: "striking-distance",
+		title: "Striking-distance opportunities",
+		severity: "low",
+		summary: { magnitudeLabel: `${kept.reduce((s, r) => s + r.potentialClicks, 0)} potential clicks` },
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "striking-distance",
+			params: { type: "striking-distance" }
+		} : void 0
+	};
+}
+const DEFAULT_MAX$3 = 5;
+const opportunitiesReport = defineReport({
+	id: "opportunities",
+	description: "Striking-distance, low-CTR, zero-click, and query-migration opportunities.",
+	defaultPeriod: "last-28d",
+	defaultComparison: "none",
+	argsSpec: { "max-findings": {
+		type: "number",
+		description: "Cap findings per section",
+		default: DEFAULT_MAX$3
+	} },
+	plan: (_params, window) => {
+		const dates = {
+			startDate: window.start,
+			endDate: window.end
+		};
+		return [
+			{
+				key: "striking",
+				type: "striking-distance",
+				params: {
+					...dates,
+					limit: 100
+				},
+				required: true
+			},
+			{
+				key: "opportunity",
+				type: "opportunity",
+				params: {
+					...dates,
+					limit: 100
+				}
+			},
+			{
+				key: "zero-click",
+				type: "zero-click",
+				params: {
+					...dates,
+					limit: 100
+				}
+			},
+			{
+				key: "query-migration",
+				type: "query-migration",
+				params: {
+					...dates,
+					limit: 50
+				}
+			}
+		];
+	},
+	reduce: (results, ctx) => {
+		const max = ctx.params.maxFindings ?? DEFAULT_MAX$3;
+		return { sections: [
+			buildStrikingSection(results.striking, max),
+			buildOpportunitySection(results.opportunity, max),
+			buildZeroClickSection(results["zero-click"], max),
+			buildMigrationSection$1(results["query-migration"], max)
+		] };
+	}
+});
+function buildStrikingSection(res, max) {
+	const rows = (res?.results ?? []).sort((a, b) => b.potentialClicks - a.potentialClicks);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "query",
+			value: r.keyword
+		},
+		metrics: {
+			position: r.position,
+			impressions: r.impressions,
+			clicks: r.clicks,
+			potentialClicks: r.potentialClicks
+		},
+		why: r.page ? `on ${r.page}` : void 0
+	}));
+	const totalPotential = kept.reduce((s, r) => s + r.potentialClicks, 0);
+	return {
+		id: "striking-distance",
+		title: "Striking distance",
+		severity: "low",
+		summary: { magnitudeLabel: `${Math.round(totalPotential)} potential clicks` },
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "striking-distance",
+			params: { type: "striking-distance" }
+		} : void 0
+	};
+}
+function buildOpportunitySection(res, max) {
+	const rows = (res?.results ?? []).sort((a, b) => b.opportunityScore - a.opportunityScore);
+	const kept = rows.slice(0, max);
+	return {
+		id: "low-ctr",
+		title: "Underperforming CTR",
+		severity: "low",
+		summary: {},
+		findings: kept.map((r) => ({
+			entity: {
+				kind: "query",
+				value: r.keyword
+			},
+			metrics: {
+				opportunityScore: r.opportunityScore,
+				ctr: r.ctr,
+				position: r.position,
+				impressions: r.impressions,
+				potentialClicks: r.potentialClicks
+			},
+			why: r.page ? `low CTR on ${r.page}` : "low CTR vs position"
+		})),
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: kept.slice(0, 1).map((r) => ({
+			kind: "fix",
+			target: r.page ? {
+				kind: "page",
+				value: r.page
+			} : {
+				kind: "query",
+				value: r.keyword
+			},
+			rationale: "Rewrite title/description to lift CTR at this position"
+		})),
+		artifact: res ? {
+			analyzer: "opportunity",
+			params: { type: "opportunity" }
+		} : void 0
+	};
+}
+function buildZeroClickSection(res, max) {
+	const rows = (res?.results ?? []).sort((a, b) => b.impressions - a.impressions);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "query",
+			value: r.query
+		},
+		metrics: {
+			impressions: r.impressions,
+			position: r.position,
+			ctr: r.ctr
+		},
+		why: `0 clicks on ${r.page}`
+	}));
+	return {
+		id: "zero-click",
+		title: "Zero-click queries",
+		severity: "info",
+		summary: { magnitudeLabel: `${kept.reduce((s, r) => s + r.impressions, 0)} impressions wasted` },
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "zero-click",
+			params: { type: "zero-click" }
+		} : void 0
+	};
+}
+function buildMigrationSection$1(res, max) {
+	const rows = (res?.results ?? []).sort((a, b) => b.weight - a.weight);
+	const kept = rows.slice(0, max);
+	return {
+		id: "query-migration",
+		title: "Query migration",
+		severity: "info",
+		summary: {},
+		findings: kept.map((r) => ({
+			entity: {
+				kind: "page",
+				value: r.targetPage
+			},
+			metrics: {
+				weight: r.weight,
+				queryCount: r.queryCount
+			},
+			why: `migrating from ${r.sourcePage}`
+		})),
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "query-migration",
+			params: { type: "query-migration" }
+		} : void 0
+	};
+}
+const DEFAULT_MAX$2 = 10;
+const prePublishReport = defineReport({
+	id: "pre-publish",
+	description: "Pre-publish guard: cannibalization risk and striking-distance peers for a candidate topic or URL.",
+	defaultPeriod: "last-90d",
+	defaultComparison: "none",
+	argsSpec: {
+		"topic": {
+			type: "string",
+			description: "Topic / keyword / URL slug to check",
+			required: true
+		},
+		"max-findings": {
+			type: "number",
+			description: "Cap findings per section",
+			default: DEFAULT_MAX$2
+		}
+	},
+	plan: (params, window) => {
+		if (!params.topic) throw new Error("pre-publish report requires --topic <topic-or-url>");
+		const dates = {
+			startDate: window.start,
+			endDate: window.end
+		};
+		return [{
+			key: "cannibalization",
+			type: "cannibalization",
+			params: {
+				...dates,
+				limit: 200
+			}
+		}, {
+			key: "striking",
+			type: "striking-distance",
+			params: {
+				...dates,
+				limit: 200
+			}
+		}];
+	},
+	reduce: (results, ctx) => {
+		const topic = (ctx.params.topic ?? "").trim().toLowerCase();
+		const max = ctx.params.maxFindings ?? DEFAULT_MAX$2;
+		const matches = (val) => !!val && val.toLowerCase().includes(topic);
+		return { sections: [buildCannibalizationSection$1(results.cannibalization, matches, max), buildStrikingPeersSection(results.striking, matches, max, topic)] };
+	}
+});
+function buildCannibalizationSection$1(res, matches, max) {
+	const rows = (res?.results ?? []).filter((r) => matches(r.keyword) || (r.competitors ?? []).some((p) => matches(p.url))).sort((a, b) => b.totalClicks - a.totalClicks);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => {
+		const pageCount = r.competitorCount ?? r.competitors?.length ?? 0;
+		return {
+			entity: {
+				kind: "query",
+				value: r.keyword
+			},
+			metrics: {
+				pages: pageCount,
+				totalClicks: r.totalClicks,
+				totalImpressions: r.totalImpressions
+			},
+			why: `${pageCount} page(s) already targeting`
+		};
+	});
+	return {
+		id: "cannibalization-risk",
+		title: "Cannibalization risk",
+		severity: kept.length ? "high" : "info",
+		summary: { magnitudeLabel: kept.length ? `${kept.length} existing competition` : "no existing competition" },
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: kept.slice(0, 1).map(() => ({
+			kind: "fix",
+			rationale: "Decide before publishing: redirect existing page, target a different angle, or accept overlap."
+		})),
+		artifact: res ? {
+			analyzer: "cannibalization",
+			params: { type: "cannibalization" }
+		} : void 0
+	};
+}
+function buildStrikingPeersSection(res, matches, max, topic) {
+	const rows = (res?.results ?? []).filter((r) => matches(r.keyword) || matches(r.page)).sort((a, b) => b.potentialClicks - a.potentialClicks);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "query",
+			value: r.keyword
+		},
+		metrics: {
+			position: r.position,
+			impressions: r.impressions,
+			potentialClicks: r.potentialClicks
+		},
+		why: r.page ? `currently on ${r.page}` : void 0
+	}));
+	return {
+		id: "striking-peers",
+		title: "Existing striking-distance peers",
+		severity: kept.length ? "low" : "info",
+		summary: { magnitudeLabel: kept.length ? `${kept.length} adjacent rankings for "${topic}"` : "no adjacent rankings" },
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "striking-distance",
+			params: { type: "striking-distance" }
+		} : void 0
+	};
+}
+function clamp01(value) {
+	if (value < 0) return 0;
+	if (value > 1) return 1;
+	return value;
+}
+function clamp(value, min, max) {
+	if (value < min) return min;
+	if (value > max) return max;
+	return value;
+}
+const DEFAULT_PRIORITY_SOURCES = [
+	"striking-distance",
+	"opportunity",
+	"cannibalization",
+	"ctr-anomaly",
+	"change-point"
+];
+const EFFORT_BY_SOURCE = {
+	"striking-distance": "low",
+	"opportunity": "low",
+	"cannibalization": "medium",
+	"ctr-anomaly": "high",
+	"change-point": "high"
+};
+const EFFORT_MULTIPLIER = {
+	low: 1.3,
+	medium: 1,
+	high: .7
+};
+const EFFORT_RANK = {
+	low: 0,
+	medium: 1,
+	high: 2
+};
+function idKey(keyword, page) {
+	return `${keyword.toLowerCase()}|${page.toLowerCase()}`;
+}
+function truncate(s, n) {
+	return s.length <= n ? s : `${s.slice(0, n - 1)}...`;
+}
+function buildAction(spec) {
+	return {
+		id: idKey(spec.keyword, spec.page),
+		title: spec.title,
+		keyword: spec.keyword,
+		page: spec.page,
+		sources: [spec.source],
+		severity: spec.severity,
+		impressions: spec.impressions,
+		impact: spec.impact,
+		effort: EFFORT_BY_SOURCE[spec.source],
+		why: spec.why,
+		priorityScore: 0,
+		data: { [spec.source]: spec.data }
+	};
+}
+function fromStrikingDistance(rows) {
+	const out = [];
+	for (const r of rows) {
+		if (r.page == null) continue;
+		const impact = Math.max(0, r.potentialClicks);
+		if (impact <= 0) continue;
+		const posScore = clamp01((20 - r.position) / 16);
+		const imprScore = Math.min(1, r.impressions / 5e3);
+		out.push(buildAction({
+			source: "striking-distance",
+			keyword: r.keyword,
+			page: r.page,
+			title: `Push "${truncate(r.keyword, 40)}" onto page 1`,
+			why: `Ranks #${r.position.toFixed(1)} with ${Math.round(r.impressions)} impressions; small gains unlock page-1 clicks.`,
+			severity: Math.round(100 * Math.sqrt(posScore * imprScore)),
+			impressions: r.impressions,
+			impact,
+			data: r
+		}));
+	}
+	return out;
+}
+function fromOpportunity(rows) {
+	const out = [];
+	for (const r of rows) {
+		if (r.page == null) continue;
+		const impact = Math.max(0, r.potentialClicks);
+		if (impact <= 0) continue;
+		out.push(buildAction({
+			source: "opportunity",
+			keyword: r.keyword,
+			page: r.page,
+			title: `Improve on-page for "${truncate(r.keyword, 40)}"`,
+			why: `Opportunity score ${Math.round(r.opportunityScore)}; CTR ${(r.ctr * 100).toFixed(1)}% vs expected at pos ${r.position.toFixed(1)}.`,
+			severity: Math.round(r.opportunityScore),
+			impressions: r.impressions,
+			impact,
+			data: r
+		}));
+	}
+	return out;
+}
+function fromCannibalization(events) {
+	const out = [];
+	for (const ev of events) {
+		if (ev.severity < 30) continue;
+		out.push(buildAction({
+			source: "cannibalization",
+			keyword: ev.keyword,
+			page: ev.leaderUrl,
+			title: `Consolidate cannibalization on "${truncate(ev.keyword, 36)}"`,
+			why: `${ev.competitorCount} URLs split ${Math.round(ev.totalImpressions)} impressions; leader loses ~${Math.round(ev.stolenClicks)} clicks to siblings.`,
+			severity: Math.round(ev.severity),
+			impressions: ev.totalImpressions,
+			impact: Math.max(0, ev.stolenClicks),
+			data: ev
+		}));
+	}
+	return out;
+}
+function fromCtrAnomaly(rows) {
+	const out = [];
+	let maxRaw = 0;
+	for (const r of rows) if (r.severity > maxRaw) maxRaw = r.severity;
+	for (const r of rows) {
+		const impact = Math.max(0, r.clicksLost);
+		if (impact <= 0) continue;
+		out.push(buildAction({
+			source: "ctr-anomaly",
+			keyword: r.keyword,
+			page: r.page,
+			title: `Lift CTR on "${truncate(r.keyword, 36)}"`,
+			why: `CTR collapsed ${r.breachDaysDown} days at flat position; ~${Math.round(r.clicksLost)} clicks lost vs baseline ${(r.baselineCtr * 100).toFixed(1)}%.`,
+			severity: maxRaw > 0 ? Math.round(r.severity / maxRaw * 100) : 0,
+			impressions: r.totalImpressions,
+			impact,
+			data: r
+		}));
+	}
+	return out;
+}
+function fromChangePoint(rows) {
+	const out = [];
+	for (const r of rows) {
+		if (r.direction !== "worsened") continue;
+		const days = Math.max(1, r.totalDays / 2);
+		const impact = Math.abs(r.leftMean - r.rightMean) * days;
+		if (impact <= 0) continue;
+		out.push(buildAction({
+			source: "change-point",
+			keyword: r.keyword,
+			page: r.page,
+			title: `Diagnose drop on "${truncate(r.keyword, 34)}"`,
+			why: `Significant regression around ${r.changeDate} (${r.leftMean.toFixed(1)} -> ${r.rightMean.toFixed(1)}, LLR ${r.llr.toFixed(0)}).`,
+			severity: clamp(Math.round(Math.log10(Math.max(10, r.llr)) / 3 * 100), 0, 100),
+			impressions: r.totalImpressions,
+			impact,
+			data: r
+		}));
+	}
+	return out;
+}
+function normalizePriorityActions(source, result) {
+	const rows = result.results;
+	if (source === "striking-distance") return fromStrikingDistance(rows);
+	if (source === "opportunity") return fromOpportunity(rows);
+	if (source === "cannibalization") return fromCannibalization(rows);
+	if (source === "ctr-anomaly") return fromCtrAnomaly(rows);
+	return fromChangePoint(rows);
+}
+function mergePriorityActions(all) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const a of all) {
+		const existing = byId.get(a.id);
+		if (existing == null) {
+			byId.set(a.id, {
+				...a,
+				sources: [...a.sources],
+				data: { ...a.data }
+			});
+			continue;
+		}
+		const mergedSources = [...new Set([...existing.sources, ...a.sources])];
+		const preferNew = a.severity > existing.severity;
+		const mergedEffort = EFFORT_RANK[a.effort] < EFFORT_RANK[existing.effort] ? a.effort : existing.effort;
+		byId.set(a.id, {
+			id: existing.id,
+			title: preferNew ? a.title : existing.title,
+			keyword: existing.keyword,
+			page: existing.page,
+			sources: mergedSources,
+			severity: Math.max(existing.severity, a.severity),
+			impressions: Math.max(existing.impressions, a.impressions),
+			impact: existing.impact + a.impact,
+			why: preferNew ? a.why : existing.why,
+			effort: mergedEffort,
+			priorityScore: 0,
+			data: {
+				...existing.data,
+				...a.data
+			}
+		});
+	}
+	return [...byId.values()];
+}
+function scorePriorityActions(actions) {
+	for (const a of actions) {
+		const mult = EFFORT_MULTIPLIER[a.effort];
+		a.priorityScore = a.impact * (1 + a.severity / 100) * mult;
+	}
+	actions.sort((a, b) => b.priorityScore - a.priorityScore);
+	return actions;
+}
+const DEFAULT_LIMIT = 40;
+const DEFAULT_ACTIONS = 10;
+const priorityReport = defineReport({
+	id: "priority",
+	description: "Ranked priority actions composed from striking-distance, opportunity, cannibalization, ctr-anomaly, and change-point signals.",
+	defaultPeriod: "last-28d",
+	defaultComparison: "prev-period",
+	argsSpec: {
+		"limit": {
+			type: "number",
+			description: "Max actions in the section",
+			default: DEFAULT_LIMIT
+		},
+		"max-actions": {
+			type: "number",
+			description: "Top-N rendered as ReportAction",
+			default: DEFAULT_ACTIONS
+		}
+	},
+	plan: (_params, window) => {
+		const dates = {
+			startDate: window.start,
+			endDate: window.end
+		};
+		const cmp = window.comparison ? {
+			prevStartDate: window.comparison.start,
+			prevEndDate: window.comparison.end
+		} : {};
+		return DEFAULT_PRIORITY_SOURCES.map((source) => ({
+			key: source,
+			type: source,
+			params: {
+				...dates,
+				...cmp,
+				limit: 100
+			},
+			required: false
+		}));
+	},
+	reduce: (results, ctx) => {
+		const limit = ctx.params.limit ?? DEFAULT_LIMIT;
+		const maxActions = ctx.params.maxActions ?? DEFAULT_ACTIONS;
+		const all = [];
+		let anyMissing = false;
+		for (const source of DEFAULT_PRIORITY_SOURCES) {
+			const r = results[source];
+			if (!r) {
+				anyMissing = true;
+				continue;
+			}
+			all.push(...normalizePriorityActions(source, r));
+		}
+		const ranked = scorePriorityActions(mergePriorityActions(all)).slice(0, limit);
+		const findings = ranked.map((a) => ({
+			entity: {
+				kind: "query",
+				value: a.keyword
+			},
+			metrics: {
+				priorityScore: a.priorityScore,
+				severity: a.severity,
+				impact: a.impact,
+				impressions: a.impressions
+			},
+			why: `${a.title} — ${a.why} (page: ${a.page})`
+		}));
+		const actions = ranked.slice(0, maxActions).map((a) => {
+			const primarySource = a.sources[0];
+			return {
+				kind: primarySource === "cannibalization" ? "fix" : "analyzer",
+				target: {
+					kind: "page",
+					value: a.page
+				},
+				params: { type: primarySource },
+				rationale: a.title
+			};
+		});
+		const topSeverity = ranked[0]?.severity ?? 0;
+		return { sections: [{
+			id: "priority",
+			title: "Priority actions",
+			severity: topSeverity >= 70 ? "high" : topSeverity >= 40 ? "medium" : ranked.length ? "low" : "info",
+			summary: { magnitudeLabel: `${ranked.length} actions ranked` },
+			findings,
+			truncated: all.length > ranked.length ? {
+				kept: ranked.length,
+				total: all.length
+			} : void 0,
+			coverage: anyMissing ? "partial" : "full",
+			actions
+		}] };
+	}
+});
+const DEFAULT_MAX$1 = 5;
+const risksReport = defineReport({
+	id: "risks",
+	description: "Decay, cannibalization, dark-traffic and device-gap risks vs prior period.",
+	defaultPeriod: "last-28d",
+	defaultComparison: "prev-period",
+	argsSpec: { "max-findings": {
+		type: "number",
+		description: "Cap findings per section",
+		default: DEFAULT_MAX$1
+	} },
+	plan: (_params, window) => {
+		if (!window.comparison) throw new Error("risks report requires a comparison window — pass --vs prev-period");
+		const dates = {
+			startDate: window.start,
+			endDate: window.end
+		};
+		const prev = {
+			prevStartDate: window.comparison.start,
+			prevEndDate: window.comparison.end
+		};
+		return [
+			{
+				key: "decay",
+				type: "decay",
+				params: {
+					...dates,
+					...prev,
+					limit: 100
+				},
+				required: true
+			},
+			{
+				key: "cannibalization",
+				type: "cannibalization",
+				params: {
+					...dates,
+					limit: 50
+				}
+			},
+			{
+				key: "dark-traffic",
+				type: "dark-traffic",
+				params: {
+					...dates,
+					limit: 50
+				}
+			},
+			{
+				key: "device-gap",
+				type: "device-gap",
+				params: {
+					...dates,
+					limit: 50
+				}
+			}
+		];
+	},
+	reduce: (results, ctx) => {
+		const max = ctx.params.maxFindings ?? DEFAULT_MAX$1;
+		return { sections: [
+			buildDecaySection(results.decay, max),
+			buildCannibalizationSection(results.cannibalization, max),
+			buildDarkTrafficSection(results["dark-traffic"], max),
+			buildDeviceGapSection(results["device-gap"], max)
+		] };
+	}
+});
+function buildDecaySection(res, max) {
+	const rows = (res?.results ?? []).sort((a, b) => b.lostClicks - a.lostClicks);
+	const kept = rows.slice(0, max);
+	const totalLost = kept.reduce((s, r) => s + r.lostClicks, 0);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "page",
+			value: r.page
+		},
+		metrics: {
+			lostClicks: r.lostClicks,
+			currentClicks: r.currentClicks,
+			declinePercent: r.declinePercent
+		},
+		delta: {
+			metric: "clicks",
+			prior: r.previousClicks,
+			current: r.currentClicks,
+			pct: -r.declinePercent * 100
+		}
+	}));
+	return {
+		id: "decay",
+		title: "Decaying pages",
+		severity: totalLost >= 200 ? "high" : totalLost >= 50 ? "medium" : "low",
+		summary: {
+			delta: -totalLost,
+			direction: totalLost > 0 ? "down" : "flat",
+			magnitudeLabel: `${Math.round(totalLost)} clicks lost`
+		},
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: kept.slice(0, 1).map((r) => ({
+			kind: "analyzer",
+			target: {
+				kind: "page",
+				value: r.page
+			},
+			params: { type: "change-point" },
+			rationale: "Investigate change-point on the worst-affected page"
+		})),
+		artifact: res ? {
+			analyzer: "decay",
+			params: { type: "decay" }
+		} : void 0
+	};
+}
+function buildCannibalizationSection(res, max) {
+	const rows = (res?.results ?? []).sort((a, b) => b.totalClicks - a.totalClicks);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => {
+		const pageCount = r.competitorCount ?? r.competitors?.length ?? 0;
+		return {
+			entity: {
+				kind: "query",
+				value: r.keyword
+			},
+			metrics: {
+				pages: pageCount,
+				totalClicks: r.totalClicks,
+				totalImpressions: r.totalImpressions
+			},
+			why: `${pageCount} pages competing`
+		};
+	});
+	return {
+		id: "cannibalization",
+		title: "Cannibalizing queries",
+		severity: kept.length ? "medium" : "info",
+		summary: {},
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "cannibalization",
+			params: { type: "cannibalization" }
+		} : void 0
+	};
+}
+function buildDarkTrafficSection(res, max) {
+	const rows = (res?.results ?? []).sort((a, b) => b.darkClicks - a.darkClicks);
+	const kept = rows.slice(0, max);
+	const totalDark = kept.reduce((s, r) => s + r.darkClicks, 0);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "page",
+			value: r.url
+		},
+		metrics: {
+			darkClicks: r.darkClicks,
+			darkPercent: r.darkPercent,
+			totalClicks: r.totalClicks
+		}
+	}));
+	return {
+		id: "dark-traffic",
+		title: "Dark traffic",
+		severity: kept.length ? "low" : "info",
+		summary: { magnitudeLabel: `${Math.round(totalDark)} unattributed clicks` },
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "dark-traffic",
+			params: { type: "dark-traffic" }
+		} : void 0
+	};
+}
+function buildDeviceGapSection(res, max) {
+	const rows = (res?.results ?? []).sort((a, b) => Math.abs(b.gaps.positionGap) - Math.abs(a.gaps.positionGap));
+	const kept = rows.slice(0, max);
+	return {
+		id: "device-gap",
+		title: "Device gap",
+		severity: "info",
+		summary: {},
+		findings: kept.map((r) => ({
+			entity: {
+				kind: "page",
+				value: r.date
+			},
+			metrics: {
+				ctrGap: r.gaps.ctrGap,
+				positionGap: r.gaps.positionGap,
+				desktopCtr: r.desktop.ctr,
+				mobileCtr: r.mobile.ctr
+			},
+			why: `desktop vs mobile delta`
+		})),
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "device-gap",
+			params: { type: "device-gap" }
+		} : void 0
+	};
+}
+function resolveTarget(opts) {
+	const needle = opts.input.trim();
+	if (!needle) return {
+		exact: null,
+		matches: [],
+		unresolved: true
+	};
+	const candidates = opts.candidates;
+	if (!candidates || candidates.length === 0) return {
+		exact: needle,
+		matches: [needle],
+		unresolved: false
+	};
+	const lower = needle.toLowerCase();
+	let exact = null;
+	const matches = [];
+	for (const c of candidates) {
+		const cl = c.toLowerCase();
+		if (cl === lower) {
+			exact = c;
+			if (!matches.includes(c)) matches.unshift(c);
+			continue;
+		}
+		if (cl.includes(lower)) matches.push(c);
+	}
+	return {
+		exact,
+		matches,
+		unresolved: matches.length === 0
+	};
+}
+const DEFAULT_MAX = 10;
+const triageReport = defineReport({
+	id: "triage",
+	description: "Focused investigation: change-points, query migration, and position volatility scoped to one page or query.",
+	defaultPeriod: "last-90d",
+	defaultComparison: "none",
+	argsSpec: {
+		"target": {
+			type: "string",
+			description: "Target page URL or query string",
+			required: true
+		},
+		"target-kind": {
+			type: "string",
+			description: "page | query",
+			default: "page"
+		},
+		"max-findings": {
+			type: "number",
+			description: "Cap findings per section",
+			default: DEFAULT_MAX
+		}
+	},
+	plan: (params, window) => {
+		if (!params.target) throw new Error("triage report requires --target <page-or-query>");
+		const dates = {
+			startDate: window.start,
+			endDate: window.end
+		};
+		return [
+			{
+				key: "change-point",
+				type: "change-point",
+				params: {
+					...dates,
+					limit: 200
+				}
+			},
+			{
+				key: "query-migration",
+				type: "query-migration",
+				params: {
+					...dates,
+					limit: 200
+				}
+			},
+			{
+				key: "position-volatility",
+				type: "position-volatility",
+				params: {
+					...dates,
+					limit: 200
+				}
+			}
+		];
+	},
+	reduce: (results, ctx) => {
+		const target = ctx.params.target;
+		const kind = ctx.params.targetKind ?? "page";
+		const max = ctx.params.maxFindings ?? DEFAULT_MAX;
+		const needle = (resolveTarget({
+			kind,
+			input: target
+		}).exact ?? target).toLowerCase();
+		const matches = (val) => val.toLowerCase().includes(needle);
+		return { sections: [
+			buildChangePointSection(results["change-point"], kind, matches, max),
+			buildMigrationSection(results["query-migration"], kind, matches, max, target),
+			buildVolatilitySection(results["position-volatility"], kind, matches, max)
+		] };
+	}
+});
+function buildChangePointSection(res, kind, matches, max) {
+	const rows = (res?.results ?? []).filter((r) => matches(kind === "page" ? r.page : r.keyword)).sort((a, b) => b.llr - a.llr);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: kind === "page" ? "page" : "query",
+			value: kind === "page" ? r.page : r.keyword
+		},
+		metrics: {
+			llr: r.llr,
+			delta: r.delta
+		},
+		why: `${r.direction} on ${r.changeDate}`
+	}));
+	return {
+		id: "change-point",
+		title: "Change-points",
+		severity: kept.length ? "medium" : "info",
+		summary: { magnitudeLabel: `${kept.length} change-point${kept.length === 1 ? "" : "s"}` },
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "change-point",
+			params: { type: "change-point" }
+		} : void 0
+	};
+}
+function buildMigrationSection(res, kind, matches, max, _rawTarget) {
+	const rows = (res?.results ?? []).filter((r) => kind === "page" ? matches(r.sourcePage) || matches(r.targetPage) : false).sort((a, b) => b.weight - a.weight);
+	const kept = rows.slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "page",
+			value: r.targetPage
+		},
+		metrics: {
+			weight: r.weight,
+			queryCount: r.queryCount
+		},
+		why: `from ${r.sourcePage}`
+	}));
+	return {
+		id: "query-migration",
+		title: "Query migration",
+		severity: "info",
+		summary: { magnitudeLabel: kind === "page" ? `${kept.length} migration edges touching target` : "N/A for query target" },
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "query-migration",
+			params: { type: "query-migration" }
+		} : void 0
+	};
+}
+function buildVolatilitySection(res, kind, matches, max) {
+	const rows = kind === "page" ? (res?.results ?? []).filter((r) => matches(r.page)) : [];
+	const kept = rows.sort((a, b) => b.peakVolatility - a.peakVolatility).slice(0, max);
+	const findings = kept.map((r) => ({
+		entity: {
+			kind: "page",
+			value: r.page
+		},
+		metrics: {
+			avgVolatility: r.avgVolatility,
+			peakVolatility: r.peakVolatility,
+			impressions: r.totalImpressions
+		}
+	}));
+	return {
+		id: "position-volatility",
+		title: "Position volatility",
+		severity: kept.length ? "low" : "info",
+		summary: { magnitudeLabel: kind === "page" ? `${kept.length} volatile day${kept.length === 1 ? "" : "s"}` : "N/A for query target" },
+		findings,
+		truncated: rows.length > max ? {
+			kept: kept.length,
+			total: rows.length
+		} : void 0,
+		coverage: res ? "full" : "partial",
+		actions: [],
+		artifact: res ? {
+			analyzer: "position-volatility",
+			params: { type: "position-volatility" }
+		} : void 0
+	};
+}
+const REPORTS = [
+	brandReport,
+	growthReport,
+	healthReport,
+	moversReport,
+	opportunitiesReport,
+	prePublishReport,
+	priorityReport,
+	risksReport,
+	triageReport
+];
+const defaultReportRegistry = createReportRegistry({
+	reports: REPORTS,
+	version: "0"
+});
+async function analyzeFromSource(source, params, registry) {
+	return runAnalyzerFromSource(source, params, registry);
+}
+async function executeStep(source, analyzers, step) {
+	return analyzeFromSource(source, {
+		...step.params,
+		type: step.type
+	}, analyzers).then((result) => ({
+		state: {
+			key: step.key,
+			type: step.type,
+			status: "done"
+		},
+		result
+	})).catch((err) => {
+		const message = err?.message ?? String(err);
+		return { state: {
+			key: step.key,
+			type: step.type,
+			status: "error",
+			error: message
+		} };
+	});
+}
+async function runReport(report, opts) {
+	const startedAt = Date.now();
+	const generatedAt = new Date(startedAt).toISOString();
+	const inputHash = await computeInputHash({
+		id: report.id,
+		site: opts.ctx.site,
+		window: opts.ctx.window,
+		params: opts.ctx.params,
+		registryVersion: opts.ctx.registryVersion
+	});
+	const steps = report.plan(opts.ctx.params, opts.ctx.window);
+	const outcomes = await Promise.all(steps.map((s) => executeStep(opts.source, opts.analyzers, s)));
+	const required = new Map(steps.filter((s) => s.required).map((s) => [s.key, s]));
+	const errored = outcomes.filter((o) => o.state.status === "error");
+	for (const o of errored) if (required.has(o.state.key)) throw new Error(`runReport(${report.id}): required step "${o.state.key}" failed: ${o.state.error}`);
+	const resultsByKey = {};
+	for (const o of outcomes) if (o.result) resultsByKey[o.state.key] = o.result;
+	const sections = report.reduce(resultsByKey, opts.ctx).sections;
+	const degraded = errored.length > 0;
+	const stepStates = outcomes.map((o) => o.state);
+	return {
+		id: report.id,
+		site: opts.ctx.site,
+		inputHash,
+		generatedAt,
+		window: opts.ctx.window,
+		sections,
+		meta: {
+			durationMs: Date.now() - startedAt,
+			rowsScanned: 0,
+			degraded,
+			steps: stepStates
+		}
+	};
+}
+async function dryRunReport(report, ctx) {
+	return {
+		steps: report.plan(ctx.params, ctx.window).map((s) => ({
+			key: s.key,
+			type: s.type
+		})),
+		windowResolved: {
+			start: ctx.window.start,
+			end: ctx.window.end,
+			days: ctx.window.days
+		}
+	};
+}
+export { REPORTS, defaultReportRegistry, dryRunReport, formatReport, resolveTarget, runReport };