@ainyc/canonry 4.8.0 → 4.11.0

package/dist/{chunk-O4VXWABZ.js → chunk-NG2PJHVL.js}

@@ -4,7 +4,7 @@ import {
   configExists,
   loadConfig,
   saveConfigPatch
-} from "./chunk-5KIFQH52.js";
+} from "./chunk-ZR4AVT4T.js";
 import {
   DEFAULT_RUN_HISTORY_LIMIT,
   IntelligenceService,
@@ -61,7 +61,7 @@ import {
   runs,
   schedules,
   usageCounters
-} from "./chunk-QEPFB7UW.js";
+} from "./chunk-5G6WYP2S.js";
 import {
   AGENT_MEMORY_VALUE_MAX_BYTES,
   AGENT_PROVIDER_IDS,
@@ -91,6 +91,8 @@ import {
   citationStateToCited,
   competitorBatchRequestSchema,
   contentActionLabel,
+  dedupeReportActions,
+  dedupeReportOpportunities,
   deliveryFailed,
   determineAnswerMentioned,
   effectiveDomains,
@@ -135,7 +137,7 @@ import {
   visibilityStateFromAnswerMentioned,
   windowCutoff,
   wordpressEnvSchema
-} from "./chunk-IJEP6LB4.js";
+} from "./chunk-WWU65YPN.js";
 
 // src/telemetry.ts
 import crypto from "crypto";
@@ -3214,71 +3216,6 @@ function renderHeaderLocationFragment(location) {
   if (!location) return " \xB7 No market set";
   return ` \xB7 Market: ${escapeHtml(locationDisplay(location))}`;
 }
-var REPORT_INTENT_STOPWORDS = /* @__PURE__ */ new Set([
-  "a",
-  "an",
-  "and",
-  "for",
-  "from",
-  "in",
-  "near",
-  "of",
-  "on",
-  "or",
-  "the",
-  "to"
-]);
-function reportIntentModifiers(report) {
-  const location = report.meta.location;
-  if (!location) return /* @__PURE__ */ new Set();
-  return new Set(
-    [location.label, location.city, location.region, location.country].flatMap(tokenizeReportIntent).map(normalizeReportIntentToken).filter(Boolean)
-  );
-}
-function dedupeReportActions(report, actions) {
-  const modifiers = reportIntentModifiers(report);
-  if (actions.length <= 1 || modifiers.size === 0) return [...actions];
-  const seen = /* @__PURE__ */ new Set();
-  const result = [];
-  for (const action of actions) {
-    if (action.category !== "content") {
-      result.push(action);
-      continue;
-    }
-    const key = reportIntentKey(extractActionQuery(action), modifiers);
-    if (!key || seen.has(key)) continue;
-    seen.add(key);
-    result.push(action);
-  }
-  return result;
-}
-function dedupeReportOpportunities(report) {
-  const modifiers = reportIntentModifiers(report);
-  const opportunities = report.contentOpportunities;
-  if (opportunities.length <= 1 || modifiers.size === 0) return opportunities;
-  const seen = /* @__PURE__ */ new Set();
-  return opportunities.filter((opportunity) => {
-    const key = reportIntentKey(opportunity.query, modifiers);
-    if (!key || seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-}
-function extractActionQuery(action) {
-  return action.title.match(/"([^"]+)"/)?.[1] ?? action.successMetric.match(/"([^"]+)"/)?.[1] ?? action.title;
-}
-function reportIntentKey(value, modifiers) {
-  const tokens = tokenizeReportIntent(value).map(normalizeReportIntentToken).filter(Boolean).filter((token) => !REPORT_INTENT_STOPWORDS.has(token)).filter((token) => !modifiers.has(token));
-  return [...new Set(tokens)].sort().join(" ");
-}
-function tokenizeReportIntent(value) {
-  return value.toLowerCase().match(/[a-z0-9]+/g) ?? [];
-}
-function normalizeReportIntentToken(token) {
-  if (token.length > 4 && token.endsWith("ies")) return `${token.slice(0, -3)}y`;
-  if (token.length > 4 && token.endsWith("s") && !token.endsWith("ss")) return token.slice(0, -1);
-  return token;
-}
 function renderLocationCard(report) {
   const location = report.meta.location;
   const handling = report.meta.providerLocationHandling;
@@ -3287,7 +3224,7 @@ function renderLocationCard(report) {
   const weakLocationProviders = handling.filter((h) => h.treatment === "ignored" || h.treatment === "browser-geo").map((h) => h.provider);
   const marketValue = location ? locationDisplay(location) : "No market set";
   const notIncluded = otherLocations.length > 0 ? compactInlineList(otherLocations, 4) : "None";
-  const interpretation = location ? otherLocations.length > 0 ? `${otherLocations.length} configured ${pluralize(otherLocations.length, "market")} still ${otherLocations.length === 1 ? "needs" : "need"} a matching sweep before cross-market recommendations.` : "Single-market report; findings can be read as the current market view." : "No geographic hint was attached to this sweep; read findings as default-market or national results.";
+  const interpretation = location ? otherLocations.length > 0 ? `${otherLocations.length} configured ${pluralize(otherLocations.length, "market")} still ${otherLocations.length === 1 ? "needs" : "need"} a matching check before cross-market recommendations.` : "Single-market report; findings can be read as the current market view." : "No geographic hint was attached to this check; read findings as default-market or national results.";
   const providerCopy = handling.length > 0 ? weakLocationProviders.length > 0 ? `${weakLocationProviders.length} ${pluralize(weakLocationProviders.length, "provider")} need a closer location check.` : `${handling.length} ${pluralize(handling.length, "provider")} received the market context.` : "No provider-level location metadata is available for this report.";
   const warning = weakLocationProviders.length > 0 ? `<div class="scope-warning">
         <strong>Location handling needs review</strong>
@@ -3297,7 +3234,7 @@ function renderLocationCard(report) {
     <h3>Market Scope</h3>
     <div class="market-scope-grid">
       <div class="scope-tile">
-        <div class="scope-label">Current sweep</div>
+        <div class="scope-label">Current check</div>
         <div class="scope-value">${escapeHtml(marketValue)}</div>
         <div class="scope-copy">All findings below are scoped to this run.</div>
       </div>
@@ -3323,13 +3260,13 @@ function renderExecutiveSummary(report) {
   const citedFragment = s.totalQueryCount > 0 ? `${s.citedQueryCount}/${s.totalQueryCount} ${queryNoun} cited` : "no queries";
   const mentionedFragment = s.totalQueryCount > 0 ? `${s.mentionedQueryCount}/${s.totalQueryCount} ${queryNoun} mentioned` : "no queries";
   const headlineTitle = s.totalQueryCount > 0 ? `${s.citedQueryCount} of ${s.totalQueryCount} tracked ${queryNoun} cite ${report.meta.project.displayName}` : "No AI citation data yet";
-  const headlineSubtitle = s.totalQueryCount > 0 ? `${s.citationRate}% citation coverage and ${s.mentionRate}% mention coverage across ${s.providerCount} ${pluralize(s.providerCount, "provider")}.` : "Run a visibility sweep to populate the first citation and mention baseline.";
+  const headlineSubtitle = s.totalQueryCount > 0 ? `${s.citationRate}% citation coverage and ${s.mentionRate}% mention coverage across ${s.providerCount} ${pluralize(s.providerCount, "provider")}.` : "Run a check to populate the first citation and mention baseline.";
   const priorityActions = report.agencyDiagnostics.priorities.length > 0 ? report.agencyDiagnostics.priorities : report.actionPlan;
   const actionCount = dedupeReportActions(report, priorityActions).length;
   const heroHtml = `<div class="executive-hero">
     <div class="headline-card">
       <div>
-        <div class="hero-kicker">Latest AI visibility sweep</div>
+        <div class="hero-kicker">Latest AI visibility check</div>
         <div class="hero-title">${escapeHtml(headlineTitle)}</div>
       </div>
       <div class="hero-subtitle">${escapeHtml(headlineSubtitle)}</div>
@@ -3407,6 +3344,107 @@ function renderExecutiveSummary(report) {
     heroHtml + metricsHtml + findingsHtml + locationHtml
   );
 }
+function deltaToneClass(direction) {
+  if (direction === "up") return "tone-positive";
+  if (direction === "down") return "tone-negative";
+  return "";
+}
+function deltaArrow(direction) {
+  if (direction === "up") return "\u2191";
+  if (direction === "down") return "\u2193";
+  return "\u2192";
+}
+function renderRateDeltaTile(label, delta, unit) {
+  if (!delta) {
+    return `<div class="metric"><div class="label">${escapeHtml(label)}</div><div class="value">\u2014</div><div class="delta">No prior data</div></div>`;
+  }
+  const valueSuffix = unit === "%" ? "%" : "";
+  const deltaSign = delta.deltaAbs > 0 ? "+" : "";
+  const deltaText = `${deltaSign}${delta.deltaAbs.toFixed(unit === "%" ? 1 : 0)}${valueSuffix} vs ${delta.prior}${valueSuffix}`;
+  return `<div class="metric">
+    <div class="label">${escapeHtml(label)}</div>
+    <div class="value ${deltaToneClass(delta.direction)}">${delta.current}${valueSuffix} <span style="font-size:14px;font-weight:500;">${deltaArrow(delta.direction)}</span></div>
+    <div class="delta">${deltaText}</div>
+  </div>`;
+}
+function renderTrafficDeltaTile(label, delta, countLabel) {
+  if (!delta) {
+    return `<div class="metric"><div class="label">${escapeHtml(label)}</div><div class="value">\u2014</div><div class="delta">Not enough trend data</div></div>`;
+  }
+  const deltaSign = delta.deltaAbs > 0 ? "+" : "";
+  const deltaText = `${deltaSign}${formatNumber(delta.deltaAbs)} ${countLabel} vs prior ${WHATS_CHANGED_PERIOD_DAYS} days`;
+  return `<div class="metric">
+    <div class="label">${escapeHtml(label)}</div>
+    <div class="value ${deltaToneClass(delta.direction)}">${formatNumber(delta.current)} <span style="font-size:14px;font-weight:500;">${deltaArrow(delta.direction)}</span></div>
+    <div class="delta">${deltaText}</div>
+  </div>`;
+}
+var WHATS_CHANGED_PERIOD_DAYS = 14;
+function renderProviderMovements(movements) {
+  const meaningful = movements.filter((m) => m.direction !== "flat");
+  if (meaningful.length === 0) return "";
+  const rows = meaningful.map((m) => {
+    const sign = m.deltaAbs > 0 ? "+" : "";
+    return `<tr>
+      <td>${escapeHtml(m.provider)}</td>
+      <td class="numeric">${m.prior}%</td>
+      <td class="numeric">${m.current}%</td>
+      <td class="numeric ${deltaToneClass(m.direction)}">${sign}${m.deltaAbs.toFixed(1)}% ${deltaArrow(m.direction)}</td>
+    </tr>`;
+  }).join("");
+  return `<div class="chart-card"><h3>AI engine movements</h3>
+    <table class="report-table">
+      <thead><tr><th>Engine</th><th class="numeric">Prior</th><th class="numeric">Current</th><th class="numeric">Change</th></tr></thead>
+      <tbody>${rows}</tbody>
+    </table>
+  </div>`;
+}
+function renderWinsLosses(insights2, heading, emptyMessage) {
+  if (insights2.length === 0) {
+    return `<div class="chart-card"><h3>${escapeHtml(heading)}</h3>
+      <p class="section-intro">${escapeHtml(emptyMessage)}</p>
+    </div>`;
+  }
+  const rows = insights2.map((i) => {
+    const tone = severityTone(i.severity);
+    const countChip = i.instanceCount > 1 ? ` <span class="badge tone-neutral">\xD7 ${i.instanceCount}</span>` : "";
+    return `<tr>
+      <td><span class="badge tone-${tone}">${escapeHtml(reportSeverityLabel(i.severity))}</span></td>
+      <td>${escapeHtml(i.title)}${countChip}</td>
+      <td>${escapeHtml(i.query)}</td>
+      <td>${escapeHtml(i.provider)}</td>
+    </tr>`;
+  }).join("");
+  return `<div class="chart-card"><h3>${escapeHtml(heading)}</h3>
+    <table class="report-table">
+      <thead><tr><th>Severity</th><th>Title</th><th>Query</th><th>Provider</th></tr></thead>
+      <tbody>${rows}</tbody>
+    </table>
+  </div>`;
+}
+function renderWhatsChanged(report) {
+  const w = report.whatsChanged;
+  if (!w.enoughHistory && !w.gscClicksDelta && !w.aiReferralsDelta && w.wins.length === 0 && w.regressions.length === 0) {
+    return section(
+      { id: "whats-changed", eyebrow: "Section 2", title: "What's Changed", intro: w.headline },
+      renderEmpty("Trends will appear after a few more checks.")
+    );
+  }
+  const rateTiles = `<div class="metric-grid">
+    ${renderRateDeltaTile("Citation rate", w.citationRate, "%")}
+    ${renderRateDeltaTile("Mention rate", w.mentionRate, "%")}
+    ${renderRateDeltaTile("Cited queries", w.citedQueryCount, "count")}
+    ${renderTrafficDeltaTile("GSC clicks", w.gscClicksDelta, "clicks")}
+    ${renderTrafficDeltaTile("AI referral sessions", w.aiReferralsDelta, "sessions")}
+  </div>`;
+  const movements = renderProviderMovements(w.providerMovements);
+  const wins = renderWinsLosses(w.wins, "Wins", "No new gains in the latest check.");
+  const regressions = renderWinsLosses(w.regressions, "Regressions", "No new regressions in the latest check.");
+  return section(
+    { id: "whats-changed", eyebrow: "Section 2", title: "What's Changed", intro: w.headline },
+    `${rateTiles}${movements}${wins}${regressions}`
+  );
+}
 function renderProviderBars(rates) {
   if (rates.length === 0) return "";
   const max = Math.max(...rates.map((r) => r.citationRate), 100);
@@ -3435,7 +3473,7 @@ function renderProviderBars(rates) {
 }
 function renderCitationMatrix(scorecard) {
   if (scorecard.queries.length === 0 || scorecard.providers.length === 0) {
-    return renderEmpty("Run a visibility sweep to populate the citation matrix.");
+    return renderEmpty("Run a check to populate the citation matrix.");
   }
   const headers = scorecard.providers.map((p) => `<th>${escapeHtml(p)}</th>`).join("");
   const rows = scorecard.queries.map((q, qi) => {
@@ -3462,7 +3500,7 @@ function renderCitationScorecard(report) {
     ${renderCitationMatrix(report.citationScorecard)}
   `;
   return section(
-    { id: "citation-scorecard", eyebrow: "Section 2", title: "Citation Scorecard", intro: "Provider-by-provider citation and mention coverage for the latest sweep." },
+    { id: "citation-scorecard", eyebrow: "Section 3", title: "Citation Scorecard", intro: "Per-engine citation and mention coverage from the latest check." },
     body
   );
 }
@@ -3510,8 +3548,8 @@ function renderCompetitorLandscape(report) {
   const noMentionData = mentionLandscape.competitors.length === 0 && mentionLandscape.projectMentionCount === 0;
   if (noCitationData && noMentionData) {
     return section(
-      { id: "competitor-landscape", eyebrow: "Section 3", title: "Competitor Landscape" },
-      renderEmpty("No competitor data yet. Add competitors and run a visibility sweep.")
+      { id: "competitor-landscape", eyebrow: "Section 4", title: "Competitor Landscape" },
+      renderEmpty("No competitor data yet. Add competitors and run a check.")
     );
   }
   const mentionByDomain = new Map(mentionLandscape.competitors.map((m) => [m.domain, m]));
@@ -3542,7 +3580,7 @@ function renderCompetitorLandscape(report) {
   return section(
     {
       id: "competitor-landscape",
-      eyebrow: "Section 3",
+      eyebrow: "Section 4",
       title: "Competitor Landscape",
       intro: "Who AI engines cite and mention instead of the client."
     },
@@ -3609,8 +3647,8 @@ function renderAiSourceOrigin(report) {
   const origin = report.aiSourceOrigin;
   if (origin.categories.length === 0 && origin.topDomains.length === 0) {
     return section(
-      { id: "ai-source-origin", eyebrow: "Section 4", title: "AI Citation Sources" },
-      renderEmpty("No source data yet. Run a visibility sweep first.")
+      { id: "ai-source-origin", eyebrow: "Section 5", title: "AI Citation Sources" },
+      renderEmpty("No source data yet. Run a check first.")
     );
   }
   const competitorBucket = origin.categories.find((c) => c.category === "competitor");
@@ -3630,9 +3668,9 @@ function renderAiSourceOrigin(report) {
   return section(
     {
       id: "ai-source-origin",
-      eyebrow: "Section 4",
+      eyebrow: "Section 5",
       title: "AI Citation Sources",
-      intro: "External domains AI engines trusted most in the latest sweep."
+      intro: "External domains AI engines cited most in the latest check."
     },
     `${headlineFragment}${table}${renderCategoryBars(origin.categories)}`
   );
@@ -3673,7 +3711,7 @@ function renderGsc(report) {
   const gsc = report.gsc;
   if (!gsc) {
     return section(
-      { id: "gsc", eyebrow: "Section 5", title: "GSC Performance" },
+      { id: "gsc", eyebrow: "Section 6", title: "GSC Performance" },
       renderEmpty("Connect Google Search Console to populate this section.")
     );
   }
@@ -3716,7 +3754,7 @@ function renderGsc(report) {
   }
   const dateRange = gscDateRange(report);
   return section(
-    { id: "gsc", eyebrow: "Section 5", title: "GSC Performance", intro: `Search demand signals to compare against AI visibility${dateRange ? ` for ${dateRange}` : ""}.` },
+    { id: "gsc", eyebrow: "Section 6", title: "GSC Performance", intro: `Search demand signals to compare against AI visibility${dateRange ? ` for ${dateRange}` : ""}.` },
     `<div class="metric-grid">
       <div class="metric"><div class="label">Total clicks</div><div class="value">${formatNumber(gsc.totalClicks)}</div></div>
       <div class="metric"><div class="label">Total impressions</div><div class="value">${formatNumber(gsc.totalImpressions)}</div></div>
@@ -3738,7 +3776,7 @@ function renderGa(report) {
   const ga = report.ga;
   if (!ga) {
     return section(
-      { id: "ga", eyebrow: "Section 6", title: "GA4 Traffic" },
+      { id: "ga", eyebrow: "Section 7", title: "GA4 Traffic" },
       renderEmpty("Connect Google Analytics 4 to populate this section.")
     );
   }
@@ -3760,7 +3798,7 @@ function renderGa(report) {
     "sessions"
   );
   return section(
-    { id: "ga", eyebrow: "Section 6", title: "GA4 Traffic", intro: `Site traffic from ${formatDate(ga.periodStart)} to ${formatDate(ga.periodEnd)}.` },
+    { id: "ga", eyebrow: "Section 7", title: "GA4 Traffic", intro: `Site traffic from ${formatDate(ga.periodStart)} to ${formatDate(ga.periodEnd)}.` },
     `<div class="metric-grid">
       <div class="metric"><div class="label">Total sessions</div><div class="value">${formatNumber(ga.totalSessions)}</div></div>
       <div class="metric"><div class="label">Total users</div><div class="value">${formatNumber(ga.totalUsers)}</div></div>
@@ -3779,7 +3817,7 @@ function renderSocial(report) {
   const social = report.socialReferrals;
   if (!social) {
     return section(
-      { id: "social-referrals", eyebrow: "Section 7", title: "Social Referrals" },
+      { id: "social-referrals", eyebrow: "Section 8", title: "Social Referrals" },
       renderEmpty("No social referral data yet.")
     );
   }
@@ -3800,7 +3838,7 @@ function renderSocial(report) {
       <td class="numeric">${formatNumber(c.sessions)}</td>
     </tr>`).join("");
   return section(
-    { id: "social-referrals", eyebrow: "Section 7", title: "Social Referrals", intro: "Social traffic split by channel and campaign." },
+    { id: "social-referrals", eyebrow: "Section 8", title: "Social Referrals", intro: "Social traffic split by channel and campaign." },
     `<div class="metric-grid">
       <div class="metric"><div class="label">Total sessions</div><div class="value">${formatNumber(social.totalSessions)}</div></div>
       <div class="metric"><div class="label">Organic social</div><div class="value">${formatNumber(social.organicSessions)}</div></div>
@@ -3819,7 +3857,7 @@ function renderAiReferrals(report) {
   const ai = report.aiReferrals;
   if (!ai) {
     return section(
-      { id: "ai-referrals", eyebrow: "Section 8", title: "AI Referral Traffic" },
+      { id: "ai-referrals", eyebrow: "Section 9", title: "AI Referral Traffic" },
       renderEmpty("No AI referral traffic detected yet.")
     );
   }
@@ -3845,7 +3883,7 @@ function renderAiReferrals(report) {
     "AI referral sessions over time"
   );
   return section(
-    { id: "ai-referrals", eyebrow: "Section 8", title: "AI Referral Traffic", intro: "Traffic arriving from AI answer engines." },
+    { id: "ai-referrals", eyebrow: "Section 9", title: "AI Referral Traffic", intro: "Traffic arriving from AI answer engines." },
     `<div class="metric-grid">
       <div class="metric"><div class="label">Total sessions</div><div class="value">${formatNumber(ai.totalSessions)}</div></div>
       <div class="metric"><div class="label">Total users</div><div class="value">${formatNumber(ai.totalUsers)}</div></div>
@@ -3864,7 +3902,7 @@ function renderIndexingHealth(report) {
   const ih = report.indexingHealth;
   if (!ih) {
     return section(
-      { id: "indexing-health", eyebrow: "Section 9", title: "Indexing Health" },
+      { id: "indexing-health", eyebrow: "Section 10", title: "Indexing Health" },
       renderEmpty("Connect Google Search Console or Bing Webmaster Tools and run a sitemap inspection.")
     );
   }
@@ -3886,7 +3924,7 @@ function renderIndexingHealth(report) {
   }).join("");
   const legend = segments.map((s) => `<span><span class="legend-swatch" style="background:${s.color}"></span>${escapeHtml(s.label)}: ${s.count}</span>`).join("");
   return section(
-    { id: "indexing-health", eyebrow: "Section 9", title: "Indexing Health", intro: `Pages absent from ${ih.provider === "google" ? "Google" : "Bing"} are harder for AI engines to retrieve.` },
+    { id: "indexing-health", eyebrow: "Section 10", title: "Indexing Health", intro: `Pages absent from ${ih.provider === "google" ? "Google" : "Bing"} are harder for AI engines to retrieve.` },
     `<div class="metric-grid">
       <div class="metric"><div class="label">Indexed</div><div class="value tone-positive">${formatNumber(ih.indexed)}</div></div>
       <div class="metric"><div class="label">Total inspected</div><div class="value">${formatNumber(ih.total)}</div></div>
@@ -3903,14 +3941,14 @@ function renderCitationsTrend(report) {
   const trend = report.citationsTrend;
   if (trend.length === 0) {
     return section(
-      { id: "citations-trend", eyebrow: "Section 10", title: "Citations Over Time" },
-      renderEmpty("Run multiple visibility sweeps to see a trend.")
+      { id: "citations-trend", eyebrow: "Section 11", title: "Citations Over Time" },
+      renderEmpty("Run multiple checks to see a trend.")
     );
   }
   if (isTrendBaseline(trend)) {
     return section(
-      { id: "citations-trend", eyebrow: "Section 10", title: "Citations Over Time" },
-      renderEmpty(`Establishing baseline (${trend.length} of ${MIN_TREND_POINTS} runs collected). Trend will appear once more sweeps are recorded.`)
+      { id: "citations-trend", eyebrow: "Section 11", title: "Citations Over Time" },
+      renderEmpty(`Building baseline (${trend.length} of ${MIN_TREND_POINTS} checks completed). Trend will appear once more checks are recorded.`)
     );
   }
   const chart = renderLineChart(
@@ -3926,11 +3964,11 @@ function renderCitationsTrend(report) {
       <td>${t.providerRates.map((r) => `${escapeHtml(r.provider)}: ${r.citationRate}%`).join(" \xB7 ")}</td>
     </tr>`).join("");
   return section(
-    { id: "citations-trend", eyebrow: "Section 10", title: "Citations Over Time", intro: "Citation coverage across completed visibility sweeps." },
+    { id: "citations-trend", eyebrow: "Section 11", title: "Citations Over Time", intro: "Citation coverage across recent checks." },
     `${chart}
-    <div class="chart-card"><h3>Run-by-run breakdown</h3>
+    <div class="chart-card"><h3>Check-by-check breakdown</h3>
       <table class="report-table">
-        <thead><tr><th>Run</th><th class="numeric">Cited queries</th><th>Per-provider rates</th></tr></thead>
+        <thead><tr><th>Check</th><th class="numeric">Cited queries</th><th>Per-engine rates</th></tr></thead>
         <tbody>${rows}</tbody>
       </table>
     </div>`
@@ -3940,8 +3978,8 @@ function renderInsights(report) {
   const list = report.insights;
   if (list.length === 0) {
     return section(
-      { id: "insights", eyebrow: "Section 11", title: "Insights & Alerts" },
-      renderEmpty("No insights yet \u2014 run a visibility sweep to generate alerts.")
+      { id: "insights", eyebrow: "Section 12", title: "Insights & Alerts" },
+      renderEmpty("No insights yet \u2014 run a check to generate alerts.")
     );
   }
   const haveDeduped = list.every((i) => typeof i.instanceCount === "number");
@@ -3957,7 +3995,7 @@ function renderInsights(report) {
       </tr>`;
   }).join("");
   return section(
-    { id: "insights", eyebrow: "Section 11", title: "Insights & Alerts", intro: "Regressions, gains, and recurring alerts ordered by severity." },
+    { id: "insights", eyebrow: "Section 12", title: "Insights & Alerts", intro: "Regressions, gains, and recurring alerts ordered by severity." },
     `<table class="report-table insights-table">
       <thead><tr>
         <th class="col-severity">Severity</th>
@@ -3999,7 +4037,7 @@ function renderOpportunities(report) {
   return section(
     {
       id: "content-opportunities",
-      eyebrow: "Section 12",
+      eyebrow: "Section 13",
       title: "Content Opportunities",
       intro: "Queries where content work has the clearest path to more AI citations. Opportunity score is 0\u2013100, higher = stronger."
     },
@@ -4025,7 +4063,7 @@ function renderContentGaps(report) {
   return section(
     {
       id: "content-gaps",
-      eyebrow: "Section 13",
+      eyebrow: "Section 14",
       title: "Content Gaps",
       intro: "Tracked queries where competitors are cited and the client is missing."
     },
@@ -4039,7 +4077,7 @@ function renderRecommendedNextSteps(report) {
   const steps = report.recommendedNextSteps;
   if (steps.length === 0) {
     return section(
-      { id: "recommended-next-steps", eyebrow: "Section 14", title: "Recommended Next Steps", intro: "Action items bucketed by timing." },
+      { id: "recommended-next-steps", eyebrow: "Section 15", title: "Recommended Next Steps", intro: "Action items bucketed by timing." },
       renderEmpty("No outstanding actions.")
     );
   }
@@ -4050,7 +4088,7 @@ function renderRecommendedNextSteps(report) {
       <span class="rationale">${escapeHtml(s.rationale)}</span>
     </div>`).join("");
   return section(
-    { id: "recommended-next-steps", eyebrow: "Section 14", title: "Recommended Next Steps", intro: "Action items bucketed by timing." },
+    { id: "recommended-next-steps", eyebrow: "Section 15", title: "Recommended Next Steps", intro: "Action items bucketed by timing." },
     `<div class="steps">${items}</div>`
   );
 }
@@ -4195,10 +4233,12 @@ function renderReportHtml(report, opts = {}) {
   const title = opts.title ?? `Canonry ${audience} report \u2014 ${report.meta.project.displayName}`;
   const sections = audience === "client" ? [
     renderClientSummary(report),
+    renderWhatsChanged(report),
     renderAudienceActionPlan(report, "client"),
     renderClientEvidenceSummary(report)
   ].join("\n") : [
     renderExecutiveSummary(report),
+    renderWhatsChanged(report),
     renderAudienceActionPlan(report, "agency"),
     renderAgencyDiagnostics(report),
     renderCitationScorecard(report),
@@ -5020,7 +5060,7 @@ function buildExecutiveFindings(citationRate, citedQueryCount, totalQueryCount,
     const tone = trendBaseline ? "neutral" : trend === "up" ? "positive" : trend === "down" ? "negative" : "neutral";
     let detail;
     if (trendBaseline) {
-      detail = `Establishing baseline (${trendsPoints.length} of ${MIN_TREND_POINTS} runs collected).`;
+      detail = `Building baseline (${trendsPoints.length} of ${MIN_TREND_POINTS} checks completed).`;
     } else {
       switch (trend) {
         case "up":
@@ -5120,7 +5160,7 @@ function buildReportActionPlan(input) {
       horizon: "immediate",
       category: "competitors",
       title: "Define the competitor set Canonry should benchmark against",
-      action: "Review the recurring external source domains and add the true competitors before the next sweep.",
+      action: "Review the recurring external source domains and add the true competitors before the next check.",
       why: [
         "The report can identify repeated external sources, but it cannot separate competitors from publishers until competitors are configured.",
         "A clean competitor set makes future share-of-voice and content-gap reporting easier to explain to clients."
@@ -5154,7 +5194,7 @@ function buildReportActionPlan(input) {
       action: opportunity.ourBestPage ? `${verb} ${target} so it directly answers the tracked query and cites the strongest supporting evidence.` : `${verb} ${target} that directly answers the query and earns citations from AI answer engines.`,
       why: opportunity.drivers.length > 0 ? opportunity.drivers : ["Canonry ranked this as a content opportunity from search-demand and citation evidence."],
       evidence,
-      successMetric: `A future sweep cites ${input.canonicalDomain} for "${opportunity.query}" and the matching GSC query/page improves.`,
+      successMetric: `A future check cites ${input.canonicalDomain} for "${opportunity.query}" and the matching GSC query/page improves.`,
       confidence: opportunity.actionConfidence
     });
   }
@@ -5194,7 +5234,7 @@ function buildReportActionPlan(input) {
         "This points the agency toward provider-specific evidence gaps instead of a generic content recommendation."
       ],
       evidence: zeroCitationProviders.map((p) => `${p.provider}: 0/${p.totalCount} cited query-provider pairs`),
-      successMetric: "At least one zero-citation provider cites the client on a priority query in a later sweep.",
+      successMetric: "At least one zero-citation engine cites the client on a priority query in a later check.",
       confidence: "high"
     });
   }
@@ -5258,13 +5298,13 @@ function buildReportActionPlan(input) {
       horizon: "medium-term",
       category: "location",
       title: "Keep location-scoped reporting separate by market",
-      action: "Run and compare separate sweeps for each configured location before making market-level recommendations.",
+      action: "Run and compare separate checks for each configured location before making market-level recommendations.",
       why: [
         "A multi-location client can appear differently by market.",
         "Keeping each report location-scoped avoids mixing Florida and Michigan evidence in the same client story."
       ],
       evidence,
-      successMetric: "Each configured market has its own current sweep and trend before cross-market decisions are made.",
+      successMetric: "Each configured market has its own current check and trend before cross-market decisions are made.",
       confidence: "high"
     });
   }
@@ -5275,10 +5315,10 @@ function buildReportActionPlan(input) {
       horizon: "short-term",
       category: "monitoring",
       title: "Keep monitoring citation and mention coverage",
-      action: "Run the next scheduled visibility sweep and watch for citation gains, losses, and provider-specific misses.",
+      action: "Run the next scheduled check and watch for citation gains, losses, and engine-specific misses.",
       why: [
         "No urgent corrective action surfaced from the current evidence.",
-        "AEO performance is directional; repeated sweeps are needed before overreacting to a single sample."
+        "AEO performance is directional; repeated checks are needed before overreacting to a single sample."
       ],
       evidence: ["No critical insights, content gaps, indexing blockers, or provider-zero issues were detected in this report."],
       successMetric: "Coverage stays stable or improves across the next trend window.",
@@ -5290,11 +5330,11 @@ function buildReportActionPlan(input) {
 function trendSentence(trend) {
   switch (trend) {
     case "up":
-      return "Citation coverage improved versus the prior comparable sweep.";
+      return "Citation coverage improved versus the prior comparable check.";
     case "down":
-      return "Citation coverage declined versus the prior comparable sweep.";
+      return "Citation coverage declined versus the prior comparable check.";
     case "flat":
-      return "Citation coverage is flat versus the prior comparable sweep.";
+      return "Citation coverage is flat versus the prior comparable check.";
     case "unknown":
       return "There is not enough comparable run history yet to call a trend.";
   }
@@ -5302,16 +5342,16 @@ function trendSentence(trend) {
 function buildClientSummary(reportLike) {
   const s = reportLike.executiveSummary;
   const queryNoun = s.totalQueryCount === 1 ? "query" : "queries";
-  const headline = s.totalQueryCount > 0 ? `${s.citedQueryCount} of ${s.totalQueryCount} tracked ${queryNoun} are cited by AI engines` : "No tracked queries have completed a visibility sweep yet";
-  const overview = s.totalQueryCount > 0 ? `${reportLike.canonicalDomain} is cited on ${s.citationRate}% of tracked queries and mentioned on ${s.mentionRate}% of tracked queries. ${trendSentence(s.trend)}` : "Canonry needs at least one completed visibility sweep before it can summarize how the brand appears in AI answers.";
+  const headline = s.totalQueryCount > 0 ? `${s.citedQueryCount} of ${s.totalQueryCount} tracked ${queryNoun} are cited by AI engines` : "No tracked queries have completed a check yet";
+  const overview = s.totalQueryCount > 0 ? `${reportLike.canonicalDomain} is cited on ${s.citationRate}% of tracked queries and mentioned on ${s.mentionRate}% of tracked queries. ${trendSentence(s.trend)}` : "At least one completed check is needed before this can summarize how the brand appears in AI answers.";
   const confidenceNotes = [];
   if (s.totalQueryCount === 0) {
-    confidenceNotes.push("Confidence is low until the first tracked query sweep completes.");
+    confidenceNotes.push("Confidence is low until the first tracked query check completes.");
   } else if (s.totalQueryCount < 5) {
     confidenceNotes.push("Directional read: the tracked query set is still small, so each query has outsized impact on the percentage.");
   }
   if (isTrendBaseline(reportLike.citationsTrend)) {
-    confidenceNotes.push(`Trend confidence is still developing; ${MIN_TREND_POINTS} comparable sweeps are needed for a stable trend.`);
+    confidenceNotes.push(`Trend confidence is still developing; ${MIN_TREND_POINTS} comparable checks are needed for a stable trend.`);
   }
   if (!reportLike.gsc) {
     confidenceNotes.push("Search Console is not connected, so content recommendations lean more heavily on citation and competitor evidence.");
@@ -5331,13 +5371,13 @@ function buildAgencyDiagnostics(input) {
   const zeroCitationProviders = input.citationScorecard.providerRates.filter((p) => p.totalCount > 0 && p.citedCount === 0);
   diagnostics.push({
     title: "Provider citation coverage",
-    detail: zeroCitationProviders.length > 0 ? `${zeroCitationProviders.length} provider${zeroCitationProviders.length === 1 ? "" : "s"} returned zero client citations in the latest sweep.` : "Every provider with completed snapshots produced at least one client citation or no provider data is available yet.",
+    detail: zeroCitationProviders.length > 0 ? `${zeroCitationProviders.length} engine${zeroCitationProviders.length === 1 ? "" : "s"} returned zero client citations in the latest check.` : "Every provider with completed snapshots produced at least one client citation or no provider data is available yet.",
     severity: zeroCitationProviders.length > 0 ? "negative" : "positive",
     evidence: zeroCitationProviders.length > 0 ? zeroCitationProviders.map((p) => `${p.provider}: 0/${p.totalCount}`) : input.citationScorecard.providerRates.map((p) => `${p.provider}: ${p.citedCount}/${p.totalCount}`)
   });
   diagnostics.push({
     title: "AI source domains",
-    detail: input.aiSourceOrigin.topDomains.length > 0 ? "Repeated external source domains show what AI engines are currently trusting for this topic set." : "No external source-domain evidence is available from the latest sweep yet.",
+    detail: input.aiSourceOrigin.topDomains.length > 0 ? "Repeated external source domains show what AI engines are currently trusting for this topic set." : "No external source-domain evidence is available from the latest check yet.",
     severity: input.aiSourceOrigin.topDomains.length > 0 ? "neutral" : "caution",
     evidence: input.aiSourceOrigin.topDomains.slice(0, 5).map((d) => `${d.domain}: ${d.count}`)
   });
@@ -5374,6 +5414,112 @@ function buildAgencyDiagnostics(input) {
     diagnostics
   };
 }
+var WHATS_CHANGED_PERIOD_DAYS2 = 14;
+var WHATS_CHANGED_MIN_TREND_POINTS = WHATS_CHANGED_PERIOD_DAYS2 * 2;
+var WIN_REGRESSION_LIMIT = 5;
+function rateDirection(delta, threshold = 0.5) {
+  if (delta > threshold) return "up";
+  if (delta < -threshold) return "down";
+  return "flat";
+}
+function periodOverPeriodDelta(trend) {
+  if (trend.length < WHATS_CHANGED_MIN_TREND_POINTS) return null;
+  const tail = trend.slice(-WHATS_CHANGED_PERIOD_DAYS2);
+  const prior = trend.slice(-WHATS_CHANGED_PERIOD_DAYS2 * 2, -WHATS_CHANGED_PERIOD_DAYS2);
+  const current = tail.reduce((s, p) => s + p.value, 0);
+  const priorTotal = prior.reduce((s, p) => s + p.value, 0);
+  const deltaAbs = current - priorTotal;
+  return {
+    current,
+    prior: priorTotal,
+    deltaAbs,
+    direction: rateDirection(deltaAbs, 0)
+  };
+}
+function buildWhatsChangedHeadline(citation, gscClicks, aiReferrals, enoughHistory, trendLength) {
+  if (!enoughHistory) {
+    return `Building baseline (${trendLength} of ${MIN_TREND_POINTS} checks completed). Trends appear after a few more checks.`;
+  }
+  const parts = [];
+  if (citation) {
+    const arrow = citation.direction === "up" ? "\u2191" : citation.direction === "down" ? "\u2193" : "\u2192";
+    const verb = citation.direction === "up" ? "rose" : citation.direction === "down" ? "fell" : "held";
+    parts.push(`Citation rate ${verb} ${citation.prior}% ${arrow} ${citation.current}%`);
+  }
+  if (aiReferrals && aiReferrals.direction !== "flat") {
+    const arrow = aiReferrals.direction === "up" ? "\u2191" : "\u2193";
+    parts.push(`AI referrals ${arrow}${Math.abs(aiReferrals.deltaAbs)} sessions vs prior 14 days`);
+  } else if (gscClicks && gscClicks.direction !== "flat") {
+    const arrow = gscClicks.direction === "up" ? "\u2191" : "\u2193";
+    parts.push(`GSC clicks ${arrow}${Math.abs(gscClicks.deltaAbs)} vs prior 14 days`);
+  }
+  return parts.length > 0 ? `${parts.join(" \xB7 ")}.` : "No meaningful movement vs the prior period.";
+}
+function buildWhatsChanged(input) {
+  const { citationsTrend, gsc, aiReferrals, insights: insightList } = input;
+  const baseline = isTrendBaseline(citationsTrend);
+  const latest = citationsTrend.at(-1);
+  const prior = citationsTrend.length >= 2 ? citationsTrend.at(-2) : null;
+  const enoughHistory = !baseline && latest !== void 0 && prior !== void 0;
+  const citationRate = enoughHistory ? {
+    current: latest.citationRate,
+    prior: prior.citationRate,
+    deltaAbs: latest.citationRate - prior.citationRate,
+    direction: rateDirection(latest.citationRate - prior.citationRate)
+  } : null;
+  const mentionRate = enoughHistory ? {
+    current: latest.mentionRate,
+    prior: prior.mentionRate,
+    deltaAbs: latest.mentionRate - prior.mentionRate,
+    direction: rateDirection(latest.mentionRate - prior.mentionRate)
+  } : null;
+  const citedQueryCount = enoughHistory ? {
+    current: latest.citedQueryCount,
+    prior: prior.citedQueryCount,
+    deltaAbs: latest.citedQueryCount - prior.citedQueryCount,
+    direction: rateDirection(latest.citedQueryCount - prior.citedQueryCount, 0)
+  } : null;
+  const providerMovements = [];
+  if (enoughHistory) {
+    const priorByProvider = new Map(prior.providerRates.map((p) => [p.provider, p.citationRate]));
+    for (const cur of latest.providerRates) {
+      const priorRate = priorByProvider.get(cur.provider);
+      if (priorRate === void 0) continue;
+      const deltaAbs = cur.citationRate - priorRate;
+      providerMovements.push({
+        provider: cur.provider,
+        current: cur.citationRate,
+        prior: priorRate,
+        deltaAbs,
+        direction: rateDirection(deltaAbs)
+      });
+    }
+    providerMovements.sort((a, b) => Math.abs(b.deltaAbs) - Math.abs(a.deltaAbs));
+  }
+  const gscClicksDelta = gsc ? periodOverPeriodDelta(gsc.trend.map((t) => ({ date: t.date, value: t.clicks }))) : null;
+  const aiReferralsDelta = aiReferrals ? periodOverPeriodDelta(aiReferrals.trend.map((t) => ({ date: t.date, value: t.sessions }))) : null;
+  const wins = insightList.filter((i) => i.type === "gain").slice(0, WIN_REGRESSION_LIMIT);
+  const regressions = insightList.filter((i) => i.type === "regression").slice(0, WIN_REGRESSION_LIMIT);
+  const headline = buildWhatsChangedHeadline(
+    citationRate,
+    gscClicksDelta,
+    aiReferralsDelta,
+    enoughHistory,
+    citationsTrend.length
+  );
+  return {
+    enoughHistory,
+    headline,
+    citationRate,
+    mentionRate,
+    citedQueryCount,
+    gscClicksDelta,
+    aiReferralsDelta,
+    providerMovements,
+    wins,
+    regressions
+  };
+}
 function buildProjectReport(db, projectName) {
   const project = resolveProject(db, projectName);
   const queryLookup = loadQueryLookup(db, project.id);
@@ -5426,6 +5572,12 @@ function buildProjectReport(db, projectName) {
     contentOpportunities,
     insightDerivedSteps
   );
+  const whatsChanged = buildWhatsChanged({
+    citationsTrend,
+    gsc: gscSection,
+    aiReferrals: aiReferralsSection,
+    insights: insightList
+  });
   const totalQueryCount = queryLookup.byId.size;
   const citedQueryIds = /* @__PURE__ */ new Set();
   const mentionedQueryIds = /* @__PURE__ */ new Set();
@@ -5553,6 +5705,7 @@ function buildProjectReport(db, projectName) {
     aiReferrals: aiReferralsSection,
     indexingHealth: indexingHealthSection,
     citationsTrend,
+    whatsChanged,
     insights: insightList,
     recommendedNextSteps,
     actionPlan,