@ainyc/canonry 4.2.2 → 4.8.0

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

@@ -4,7 +4,7 @@ import {
   configExists,
   loadConfig,
   saveConfigPatch
-} from "./chunk-SR7TGHHG.js";
+} from "./chunk-5KIFQH52.js";
 import {
   DEFAULT_RUN_HISTORY_LIMIT,
   IntelligenceService,
@@ -61,7 +61,7 @@ import {
   runs,
   schedules,
   usageCounters
-} from "./chunk-7YSI4GFA.js";
+} from "./chunk-QEPFB7UW.js";
 import {
   AGENT_MEMORY_VALUE_MAX_BYTES,
   AGENT_PROVIDER_IDS,
@@ -77,6 +77,7 @@ import {
   RunStatuses,
   RunTriggers,
   absolutizeProjectUrl,
+  actionConfidenceLabel,
   agentBusy,
   agentMemoryDeleteRequestSchema,
   agentMemoryUpsertRequestSchema,
@@ -89,12 +90,14 @@ import {
   categoryLabel,
   citationStateToCited,
   competitorBatchRequestSchema,
+  contentActionLabel,
   deliveryFailed,
   determineAnswerMentioned,
   effectiveDomains,
   emptyCitationVisibility,
   extractAnswerMentions,
   findDuplicateLocationLabels,
+  getProviderLocationHandling,
   hasLocationLabel,
   internalError,
   isAgentProviderId,
@@ -113,6 +116,11 @@ import {
   providerError,
   queryGenerateRequestSchema,
   registrableDomain,
+  reportActionCategoryLabel,
+  reportActionTone,
+  reportConfidenceLabel,
+  reportHorizonLabel,
+  reportSeverityLabel,
   resolveConfigSpecQueries,
   resolveSnapshotRequestQueries,
   runInProgress,
@@ -127,7 +135,7 @@ import {
   visibilityStateFromAnswerMentioned,
   windowCutoff,
   wordpressEnvSchema
-} from "./chunk-T2I6AO7D.js";
+} from "./chunk-IJEP6LB4.js";
 
 // src/telemetry.ts
 import crypto from "crypto";
@@ -2620,12 +2628,43 @@ function formatLandingPageHtml(raw) {
 function formatDate(iso) {
   if (!iso) return "\u2014";
   try {
-    const d = new Date(iso);
-    return d.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+    const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+    const options = { month: "short", day: "numeric", year: "numeric" };
+    const d = dateOnly && dateOnly[1] && dateOnly[2] && dateOnly[3] ? new Date(Date.UTC(Number(dateOnly[1]), Number(dateOnly[2]) - 1, Number(dateOnly[3]))) : new Date(iso);
+    if (Number.isNaN(d.getTime())) return iso;
+    return d.toLocaleDateString("en-US", dateOnly ? { ...options, timeZone: "UTC" } : options);
   } catch {
     return iso;
   }
 }
+function formatDateRange(start, end) {
+  if (!start && !end) return "";
+  if (start && end) return `${formatDate(start)} \u2192 ${formatDate(end)}`;
+  return formatDate(start || end);
+}
+function gscDateRange(report) {
+  const summary = report.executiveSummary.gsc;
+  const gsc = report.gsc;
+  const start = summary?.periodStart || gsc?.periodStart || gsc?.trend[0]?.date || "";
+  const end = summary?.periodEnd || gsc?.periodEnd || gsc?.trend.at(-1)?.date || "";
+  return formatDateRange(start, end);
+}
+function pluralize(count, singular, plural = `${singular}s`) {
+  return count === 1 ? singular : plural;
+}
+function compactInlineList(items, limit = 3) {
+  const visible = items.slice(0, limit);
+  const more = items.length - visible.length;
+  return `${visible.join(", ")}${more > 0 ? `, +${more} more` : ""}`;
+}
+function renderProofChips(items, limit = 3) {
+  if (items.length === 0) return "";
+  const visible = items.slice(0, limit);
+  const more = items.length - visible.length;
+  const chips = visible.map((item) => `<span class="proof-chip">${escapeHtml(item)}</span>`);
+  if (more > 0) chips.push(`<span class="proof-chip">+${more} more</span>`);
+  return `<div class="proof-chips">${chips.join("")}</div>`;
+}
 function pressureTone(label) {
   if (label === "High") return "negative";
   if (label === "Moderate") return "caution";
@@ -2672,7 +2711,7 @@ body {
   font-size: 32px;
   font-weight: 700;
   margin: 0 0 8px;
-  letter-spacing: -0.02em;
+  letter-spacing: 0;
 }
 .header .subtitle {
   color: ${COLORS.textMuted};
@@ -2680,7 +2719,7 @@ body {
 }
 .eyebrow {
   text-transform: uppercase;
-  letter-spacing: 0.08em;
+  letter-spacing: 0;
   font-size: 10px;
   color: ${COLORS.textFaint};
   font-weight: 600;
@@ -2693,11 +2732,75 @@ section.report-section h2 {
   font-size: 22px;
   font-weight: 700;
   margin: 0 0 24px;
-  letter-spacing: -0.01em;
+  letter-spacing: 0;
 }
 section.report-section .section-intro {
   color: ${COLORS.textMuted};
   margin-bottom: 24px;
+  max-width: 760px;
+}
+.executive-hero {
+  display: grid;
+  grid-template-columns: minmax(0, 1.35fr) minmax(240px, 0.65fr);
+  gap: 16px;
+  margin-bottom: 16px;
+}
+.headline-card {
+  background: #111827;
+  border: 1px solid ${COLORS.border};
+  border-radius: 8px;
+  padding: 28px;
+  min-height: 220px;
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+}
+.headline-card .hero-kicker {
+  color: ${COLORS.textMuted};
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0;
+}
+.headline-card .hero-title {
+  font-size: 44px;
+  line-height: 1.05;
+  font-weight: 800;
+  letter-spacing: 0;
+  margin: 18px 0;
+}
+.headline-card .hero-subtitle {
+  color: ${COLORS.textMuted};
+  font-size: 15px;
+  max-width: 620px;
+}
+.hero-proof-grid {
+  display: grid;
+  gap: 12px;
+}
+.hero-proof {
+  background: ${COLORS.surface};
+  border: 1px solid ${COLORS.border};
+  border-radius: 8px;
+  padding: 18px;
+}
+.hero-proof .mini-label {
+  color: ${COLORS.textFaint};
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0;
+  margin-bottom: 8px;
+}
+.hero-proof .mini-value {
+  font-size: 30px;
+  line-height: 1;
+  font-weight: 800;
+}
+.hero-proof .mini-copy {
+  color: ${COLORS.textMuted};
+  font-size: 12px;
+  margin-top: 8px;
 }
 .metric-grid {
   display: grid;
@@ -2712,7 +2815,7 @@ section.report-section .section-intro {
 }
 .metric .label {
   text-transform: uppercase;
-  letter-spacing: 0.08em;
+  letter-spacing: 0;
   font-size: 10px;
   color: ${COLORS.textFaint};
   font-weight: 600;
@@ -2721,7 +2824,7 @@ section.report-section .section-intro {
 .metric .value {
   font-size: 28px;
   font-weight: 700;
-  letter-spacing: -0.02em;
+  letter-spacing: 0;
 }
 .metric .delta {
   font-size: 12px;
@@ -2746,6 +2849,57 @@ section.report-section .section-intro {
 .finding.tone-neutral { border-left-color: ${COLORS.neutral}; }
 .finding strong { display: block; margin-bottom: 4px; }
 .finding span { color: ${COLORS.textMuted}; font-size: 13px; }
+.market-scope-card { margin-top: 16px; }
+.market-scope-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+  gap: 12px;
+}
+.scope-tile {
+  background: #09090b;
+  border: 1px solid ${COLORS.border};
+  border-radius: 8px;
+  padding: 14px;
+}
+.scope-tile .scope-label {
+  color: ${COLORS.textFaint};
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0;
+  margin-bottom: 8px;
+}
+.scope-tile .scope-value {
+  font-size: 18px;
+  line-height: 1.2;
+  font-weight: 700;
+}
+.scope-tile .scope-copy {
+  color: ${COLORS.textMuted};
+  font-size: 12px;
+  margin-top: 8px;
+}
+.scope-warning {
+  margin-top: 12px;
+  border: 1px solid ${COLORS.caution}55;
+  background: ${COLORS.caution}14;
+  border-radius: 8px;
+  padding: 12px 14px;
+  color: ${COLORS.textMuted};
+  font-size: 13px;
+}
+.scope-warning strong { color: ${COLORS.text}; display: block; margin-bottom: 4px; }
+.source-origin-headline { margin: 0 0 12px; font-size: 14px; color: ${COLORS.text}; }
+.source-origin-headline strong { color: ${COLORS.text}; }
+.source-bars { display: flex; flex-direction: column; gap: 6px; }
+.source-bar-row { display: grid; grid-template-columns: 220px 1fr 90px; align-items: center; gap: 12px; font-size: 13px; }
+.source-bar-label { color: ${COLORS.textMuted}; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.source-bar-track { height: 14px; background: ${COLORS.border}; border-radius: 3px; overflow: hidden; }
+.source-bar-fill { height: 100%; border-radius: 3px; }
+.source-bar-value { color: ${COLORS.text}; text-align: right; font-variant-numeric: tabular-nums; }
+.source-bar-pct { color: ${COLORS.textFaint}; font-size: 11px; }
+.driver-list { margin: 0; padding-left: 16px; font-size: 12px; color: ${COLORS.textMuted}; }
+.driver-list li { margin: 2px 0; }
 table.report-table {
   width: 100%;
   border-collapse: collapse;
@@ -2756,18 +2910,24 @@ table.report-table th, table.report-table td {
   padding: 10px 12px;
   border-bottom: 1px solid ${COLORS.border};
   vertical-align: top;
-  overflow-wrap: anywhere;
-  word-break: break-word;
+  overflow-wrap: break-word;
+  hyphens: auto;
 }
 table.report-table th {
   font-weight: 600;
   color: ${COLORS.textMuted};
   text-transform: uppercase;
-  letter-spacing: 0.06em;
+  letter-spacing: 0;
   font-size: 10px;
 }
 table.report-table td.numeric { text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; }
 table.report-table td.page-cell { max-width: 0; }
+table.insights-table { table-layout: fixed; }
+table.insights-table th.col-severity, table.insights-table td.col-severity { width: 96px; }
+table.insights-table th.col-query, table.insights-table td.col-query { width: 18%; }
+table.insights-table th.col-provider, table.insights-table td.col-provider { width: 88px; }
+table.insights-table th.col-title, table.insights-table td.col-title { width: 28%; }
+table.insights-table th.col-recommendation, table.insights-table td.col-recommendation { width: auto; }
 table.report-table td.page-cell .page-path {
   display: block;
   font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace;
@@ -2860,12 +3020,159 @@ table.report-table td .badge {
 .step .horizon {
   text-transform: uppercase;
   font-size: 10px;
-  letter-spacing: 0.08em;
+  letter-spacing: 0;
   color: ${COLORS.textFaint};
   font-weight: 600;
 }
 .step .title { font-weight: 600; }
 .step .rationale { color: ${COLORS.textMuted}; font-size: 13px; }
+.action-card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  gap: 16px;
+}
+.action-card {
+  background: ${COLORS.surface};
+  border: 1px solid ${COLORS.border};
+  border-radius: 8px;
+  padding: 18px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.action-card .action-head {
+  display: grid;
+  grid-template-columns: 42px 1fr;
+  gap: 12px;
+  align-items: start;
+}
+.action-card .action-rank {
+  border: 1px solid ${COLORS.border};
+  border-radius: 8px;
+  height: 42px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 16px;
+  font-weight: 800;
+  color: ${COLORS.text};
+  background: #09090b;
+}
+.action-card .action-meta {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+.action-card h3 {
+  font-size: 16px;
+  margin: 8px 0 0;
+}
+.action-card p {
+  margin: 0;
+  color: ${COLORS.textMuted};
+}
+.action-card ul {
+  margin: 0 0 12px;
+  padding-left: 18px;
+  color: ${COLORS.textMuted};
+  font-size: 13px;
+}
+.action-card li { margin: 4px 0; }
+.proof-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+.proof-chip {
+  border: 1px solid ${COLORS.border};
+  border-radius: 8px;
+  padding: 6px 8px;
+  color: ${COLORS.textMuted};
+  font-size: 12px;
+  background: #09090b;
+}
+.action-details {
+  color: ${COLORS.textMuted};
+  font-size: 12px;
+}
+.action-details summary {
+  cursor: pointer;
+  color: ${COLORS.text};
+  font-weight: 600;
+}
+.action-card .success-metric {
+  color: ${COLORS.text};
+  font-size: 13px;
+  border-top: 1px solid ${COLORS.border};
+  padding-top: 10px;
+  margin-top: 12px;
+}
+.client-notes {
+  margin-top: 18px;
+  display: grid;
+  gap: 8px;
+}
+.client-note {
+  color: ${COLORS.textMuted};
+  font-size: 13px;
+  background: ${COLORS.surface};
+  border: 1px solid ${COLORS.border};
+  border-radius: 8px;
+  padding: 10px 12px;
+}
+.diagnostics-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+  gap: 12px;
+}
+.diagnostic-card {
+  background: ${COLORS.surface};
+  border: 1px solid ${COLORS.border};
+  border-left-width: 3px;
+  border-radius: 8px;
+  padding: 14px 16px;
+}
+.diagnostic-card h3 { font-size: 14px; margin: 0 0 6px; }
+.diagnostic-card p { margin: 0 0 8px; color: ${COLORS.textMuted}; font-size: 13px; }
+.diagnostic-card ul { margin: 0; padding-left: 16px; color: ${COLORS.textMuted}; font-size: 12px; }
+.diagnostic-card .proof-chips { margin-top: 10px; }
+.diagnostic-card.tone-positive { border-left-color: ${COLORS.positive}; }
+.diagnostic-card.tone-caution { border-left-color: ${COLORS.caution}; }
+.diagnostic-card.tone-negative { border-left-color: ${COLORS.negative}; }
+.diagnostic-card.tone-neutral { border-left-color: ${COLORS.neutral}; }
+.opportunity-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: 12px;
+  margin-bottom: 16px;
+}
+.opportunity-card {
+  background: ${COLORS.surface};
+  border: 1px solid ${COLORS.border};
+  border-radius: 8px;
+  padding: 16px;
+}
+.opportunity-card .opportunity-score {
+  font-size: 32px;
+  line-height: 1;
+  font-weight: 800;
+  margin-bottom: 10px;
+}
+.opportunity-card .opportunity-score-suffix {
+  font-size: 14px;
+  font-weight: 600;
+  color: ${COLORS.textFaint};
+  margin-left: 4px;
+}
+.opportunity-card h3 {
+  font-size: 14px;
+  margin: 0 0 8px;
+}
+.opportunity-card p {
+  color: ${COLORS.textMuted};
+  font-size: 12px;
+  margin: 0;
+}
 .footer {
   margin-top: 96px;
   padding-top: 24px;
@@ -2874,6 +3181,14 @@ table.report-table td .badge {
   color: ${COLORS.textFaint};
   font-size: 12px;
 }
+@media (max-width: 760px) {
+  .container { padding: 32px 16px 72px; }
+  .executive-hero { grid-template-columns: 1fr; }
+  .headline-card .hero-title { font-size: 34px; }
+  .source-bar-row { grid-template-columns: 1fr; gap: 6px; }
+  .source-bar-value { text-align: left; }
+  .chart-grid { grid-template-columns: 1fr; }
+}
 @media print {
   body { background: white; color: black; }
   section.report-section { break-inside: avoid; }
@@ -2890,15 +3205,163 @@ function section(opts, body) {
 function renderEmpty(message) {
   return `<div class="empty-state">${escapeHtml(message)}</div>`;
 }
+function locationDisplay(location) {
+  if (!location) return "";
+  const place = [location.city, location.region, location.country].filter(Boolean).join(", ");
+  return place ? `${location.label} (${place})` : location.label;
+}
+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;
+  if (!location && handling.length === 0) return "";
+  const otherLocations = location?.otherConfiguredLabels ?? [];
+  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 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>
+        ${escapeHtml(compactInlineList(weakLocationProviders, 4))} used weak or indirect market handling. Treat provider-level differences cautiously.
+      </div>` : "";
+  return `<div class="chart-card market-scope-card">
+    <h3>Market Scope</h3>
+    <div class="market-scope-grid">
+      <div class="scope-tile">
+        <div class="scope-label">Current sweep</div>
+        <div class="scope-value">${escapeHtml(marketValue)}</div>
+        <div class="scope-copy">All findings below are scoped to this run.</div>
+      </div>
+      <div class="scope-tile">
+        <div class="scope-label">Not included</div>
+        <div class="scope-value">${escapeHtml(notIncluded)}</div>
+        <div class="scope-copy">${escapeHtml(interpretation)}</div>
+      </div>
+      <div class="scope-tile">
+        <div class="scope-label">Provider context</div>
+        <div class="scope-value">${handling.length > 0 ? formatNumber(handling.length) : "\u2014"}</div>
+        <div class="scope-copy">${escapeHtml(providerCopy)}</div>
+      </div>
+    </div>
+    ${warning}
+  </div>`;
+}
 function renderExecutiveSummary(report) {
   const s = report.executiveSummary;
   const trendLabel = s.trend === "up" ? "\u2191 Up" : s.trend === "down" ? "\u2193 Down" : s.trend === "flat" ? "\u2192 Flat" : "\u2014";
   const trendTone = s.trend === "up" ? "positive" : s.trend === "down" ? "negative" : "neutral";
+  const queryNoun = s.totalQueryCount === 1 ? "query" : "queries";
+  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 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-title">${escapeHtml(headlineTitle)}</div>
+      </div>
+      <div class="hero-subtitle">${escapeHtml(headlineSubtitle)}</div>
+    </div>
+    <div class="hero-proof-grid">
+      <div class="hero-proof">
+        <div class="mini-label">Citation trend</div>
+        <div class="mini-value tone-${trendTone}">${escapeHtml(trendLabel)}</div>
+        <div class="mini-copy">${escapeHtml(citedFragment)}</div>
+      </div>
+      <div class="hero-proof">
+        <div class="mini-label">Mention coverage</div>
+        <div class="mini-value">${s.mentionRate}%</div>
+        <div class="mini-copy">${escapeHtml(mentionedFragment)}</div>
+      </div>
+      <div class="hero-proof">
+        <div class="mini-label">Prioritized actions</div>
+        <div class="mini-value">${formatNumber(actionCount)}</div>
+        <div class="mini-copy">Sorted for agency follow-up.</div>
+      </div>
+    </div>
+  </div>`;
   const metrics = [
     {
       label: "Citation rate",
       value: `${s.citationRate}%`,
-      delta: `<span class="tone-${trendTone}">${trendLabel}</span> \xB7 ${s.providerCount} provider${s.providerCount === 1 ? "" : "s"}`
+      delta: `<span class="tone-${trendTone}">${trendLabel}</span> \xB7 ${citedFragment} \xB7 ${s.providerCount} provider${s.providerCount === 1 ? "" : "s"}`
+    },
+    {
+      label: "Mention rate",
+      value: `${s.mentionRate}%`,
+      delta: mentionedFragment
     },
     {
       label: "Queries tracked",
@@ -2907,10 +3370,11 @@ function renderExecutiveSummary(report) {
     }
   ];
   if (s.gsc) {
+    const dateRange = gscDateRange(report);
     metrics.push({
       label: "GSC clicks",
       value: formatNumber(s.gsc.clicks),
-      delta: `${formatNumber(s.gsc.impressions)} imp \xB7 ${formatRatio(s.gsc.ctr)} CTR`
+      delta: `${formatNumber(s.gsc.impressions)} imp \xB7 ${formatRatio(s.gsc.ctr)} CTR${dateRange ? ` \xB7 ${escapeHtml(dateRange)}` : ""}`
     });
   }
   if (s.ga) {
@@ -2932,14 +3396,15 @@ function renderExecutiveSummary(report) {
           <strong>${escapeHtml(f.title)}</strong>
           <span>${escapeHtml(f.detail)}</span>
         </div>`).join("")}</div>` : "";
+  const locationHtml = renderLocationCard(report);
   return section(
     {
       id: "executive-summary",
       eyebrow: "Section 1",
       title: "Executive Summary",
-      intro: "Top-line citation rate with trend versus the prior run, plus the most actionable findings from the latest visibility sweep."
+      intro: "Citation = source list. Mention = answer text. They are independent signals."
     },
-    metricsHtml + findingsHtml
+    heroHtml + metricsHtml + findingsHtml + locationHtml
   );
 }
 function renderProviderBars(rates) {
@@ -2977,16 +3442,16 @@ function renderCitationMatrix(scorecard) {
     const cells = scorecard.providers.map((_, pi) => {
       const cell = scorecard.matrix[qi]?.[pi];
       if (!cell) {
-        return '<td><span class="cell-pending">\u2014</span></td>';
-      }
-      if (cell.citationState === CitationStates.cited) {
-        return '<td><span class="cell-cited">Cited</span></td>';
+        return '<td><span class="cell-pending">\u2014 \u2014</span></td>';
       }
-      return '<td><span class="cell-not-cited">Not cited</span></td>';
+      const citedGlyph = cell.citationState === CitationStates.cited ? '<span class="cell-cited">C</span>' : '<span class="cell-not-cited">c</span>';
+      const mentionedGlyph = cell.answerMentioned === true ? '<span class="cell-cited">M</span>' : cell.answerMentioned === false ? '<span class="cell-not-cited">m</span>' : '<span class="cell-pending">\u2013</span>';
+      return `<td>${citedGlyph} ${mentionedGlyph}</td>`;
     }).join("");
     return `<tr><td>${escapeHtml(q)}</td>${cells}</tr>`;
   }).join("");
-  return `<table class="report-table">
+  const legend = '<p class="section-intro" style="margin-top:0;font-size:11px;">Legend: <span class="cell-cited">C</span>/<span class="cell-not-cited">c</span> = cited/not, <span class="cell-cited">M</span>/<span class="cell-not-cited">m</span> = mentioned/not, <span class="cell-pending">\u2013</span> = no data.</p>';
+  return `${legend}<table class="report-table">
     <thead><tr><th>Query</th>${headers}</tr></thead>
     <tbody>${rows}</tbody>
   </table>`;
@@ -2997,7 +3462,7 @@ function renderCitationScorecard(report) {
     ${renderCitationMatrix(report.citationScorecard)}
   `;
   return section(
-    { id: "citation-scorecard", eyebrow: "Section 2", title: "Citation Scorecard", intro: "Whether your domain appeared in each AI engine\u2019s source list for every tracked query in the latest sweep \u2014 a cell turns green when your domain was cited, red when it was not, and gray when no snapshot exists for that pair." },
+    { id: "citation-scorecard", eyebrow: "Section 2", title: "Citation Scorecard", intro: "Provider-by-provider citation and mention coverage for the latest sweep." },
     body
   );
 }
@@ -3079,49 +3544,65 @@ function renderCompetitorLandscape(report) {
       id: "competitor-landscape",
       eyebrow: "Section 3",
       title: "Competitor Landscape",
-      intro: "Where tracked competitors appear in AI answers compared to your domain \u2014 both in source citations and in the answer text itself."
+      intro: "Who AI engines cite and mention instead of the client."
     },
     `${charts}${table}`
   );
 }
-function renderDonut(buckets) {
+var SOURCE_CATEGORY_TONE = {
+  competitor: "negative",
+  directory: "caution",
+  forum: "caution",
+  news: "neutral",
+  reference: "neutral",
+  blog: "neutral",
+  social: "neutral",
+  video: "neutral",
+  ecommerce: "neutral",
+  academic: "neutral",
+  other: "neutral"
+};
+function renderCategoryBars(buckets) {
   if (buckets.length === 0) return "";
   const total = buckets.reduce((s, b) => s + b.count, 0);
   if (total === 0) return "";
-  const cx = 110;
-  const cy = 110;
-  const r = 80;
-  const innerR = 48;
-  let cumulative = 0;
-  const slices = [];
-  const legend = [];
-  buckets.forEach((b, i) => {
-    const startAngle = cumulative / total * Math.PI * 2 - Math.PI / 2;
-    const endAngle = (cumulative + b.count) / total * Math.PI * 2 - Math.PI / 2;
-    cumulative += b.count;
-    const x1 = cx + Math.cos(startAngle) * r;
-    const y1 = cy + Math.sin(startAngle) * r;
-    const x2 = cx + Math.cos(endAngle) * r;
-    const y2 = cy + Math.sin(endAngle) * r;
-    const ix1 = cx + Math.cos(endAngle) * innerR;
-    const iy1 = cy + Math.sin(endAngle) * innerR;
-    const ix2 = cx + Math.cos(startAngle) * innerR;
-    const iy2 = cy + Math.sin(startAngle) * innerR;
-    const largeArc = endAngle - startAngle > Math.PI ? 1 : 0;
-    const color = COLORS.series[i % COLORS.series.length];
-    if (b.count > 0) {
-      slices.push(`<path d="M ${x1} ${y1} A ${r} ${r} 0 ${largeArc} 1 ${x2} ${y2} L ${ix1} ${iy1} A ${innerR} ${innerR} 0 ${largeArc} 0 ${ix2} ${iy2} Z" fill="${color}" />`);
-      legend.push(`<span><span class="legend-swatch" style="background:${color}"></span>${escapeHtml(b.label)} (${b.count})</span>`);
-    }
-  });
+  const max = Math.max(...buckets.map((b) => b.count), 1);
+  const rows = buckets.map((b) => {
+    const pct = b.count / max * 100;
+    const tone = SOURCE_CATEGORY_TONE[b.category] ?? "neutral";
+    const color = tone === "negative" ? COLORS.negative : tone === "caution" ? COLORS.caution : COLORS.accent;
+    return `
+      <div class="source-bar-row">
+        <div class="source-bar-label">${escapeHtml(b.label)}</div>
+        <div class="source-bar-track">
+          <div class="source-bar-fill" style="width:${pct.toFixed(1)}%;background:${color}"></div>
+        </div>
+        <div class="source-bar-value">${b.count} <span class="source-bar-pct">(${b.sharePct}%)</span></div>
+      </div>`;
+  }).join("");
   return `<div class="chart-card">
-    <h3>AI source categories</h3>
-    <div style="display:flex;align-items:center;gap:24px;flex-wrap:wrap;">
-      <svg viewBox="0 0 220 220" width="220" height="220" role="img" aria-label="AI source category donut chart">
-        ${slices.join("")}
-      </svg>
-      <div class="legend" style="flex-direction:column;align-items:flex-start;gap:6px;">${legend.join("")}</div>
-    </div>
+    <h3>By source type</h3>
+    <div class="source-bars">${rows}</div>
+  </div>`;
+}
+function renderShareBars(heading, rows, countLabel) {
+  const visibleRows = rows.filter((r) => r.count > 0 || r.sharePct > 0);
+  if (visibleRows.length === 0) return "";
+  const bars = visibleRows.map((r, index) => {
+    const pct = Math.max(0, Math.min(100, r.sharePct));
+    const color = r.color ?? COLORS.series[index % COLORS.series.length];
+    return `
+      <div class="source-bar-row">
+        <div class="source-bar-label">${escapeHtml(r.label)}</div>
+        <div class="source-bar-track">
+          <div class="source-bar-fill" style="width:${pct.toFixed(1)}%;background:${color}"></div>
+        </div>
+        <div class="source-bar-value">${formatNumber(r.count)} <span class="source-bar-pct">${escapeHtml(countLabel)} \xB7 ${r.sharePct}%</span></div>
+      </div>`;
+  }).join("");
+  return `<div class="chart-card">
+    <h3>${escapeHtml(heading)}</h3>
+    <div class="source-bars">${bars}</div>
   </div>`;
 }
 function renderAiSourceOrigin(report) {
@@ -3132,24 +3613,28 @@ function renderAiSourceOrigin(report) {
       renderEmpty("No source data yet. Run a visibility sweep first.")
     );
   }
+  const competitorBucket = origin.categories.find((c) => c.category === "competitor");
+  const headlineFragment = competitorBucket ? `<p class="source-origin-headline"><strong>${competitorBucket.sharePct}%</strong> of citations went to tracked competitors (${competitorBucket.count} of ${origin.categories.reduce((s, c) => s + c.count, 0)}).</p>` : "";
   const rows = origin.topDomains.map((d) => `
     <tr>
       <td>${escapeHtml(d.domain)}</td>
       <td class="numeric">${d.count}</td>
-      <td>${d.isCompetitor ? '<span class="badge tone-negative">Competitor</span>' : '<span class="badge tone-neutral">External</span>'}</td>
+      <td>${d.isCompetitor ? '<span class="badge tone-negative">Tracked competitor</span>' : '<span class="badge tone-neutral">External</span>'}</td>
     </tr>`).join("");
-  const table = origin.topDomains.length > 0 ? `<table class="report-table">
-        <thead><tr><th>Domain</th><th>Citations</th><th>Tag</th></tr></thead>
-        <tbody>${rows}</tbody>
-      </table>` : "";
+  const table = origin.topDomains.length > 0 ? `<div class="chart-card"><h3>Top sources</h3>
+        <table class="report-table">
+          <thead><tr><th>Domain</th><th class="numeric">Citations</th><th>Tag</th></tr></thead>
+          <tbody>${rows}</tbody>
+        </table>
+      </div>` : "";
   return section(
     {
       id: "ai-source-origin",
       eyebrow: "Section 4",
       title: "AI Citation Sources",
-      intro: "Every external website AI engines cited as a source for your tracked keywords in the latest sweep \u2014 categorized by site type (Reddit, YouTube, news, etc.) on the left and ranked by citation count on the right. Your own domains are excluded; tracked competitors are flagged."
+      intro: "External domains AI engines trusted most in the latest sweep."
     },
-    `${renderDonut(origin.categories)}${table}`
+    `${headlineFragment}${table}${renderCategoryBars(origin.categories)}`
   );
 }
 function renderLineChart(points, color, title, height = 200) {
@@ -3201,13 +3686,16 @@ function renderGsc(report) {
       <td class="numeric">${q.avgPosition.toFixed(1)}</td>
       <td><span class="badge tone-neutral">${escapeHtml(q.category)}</span></td>
     </tr>`).join("");
-  const breakdownRows = gsc.categoryBreakdown.map((c) => `
-    <tr>
-      <td>${escapeHtml(c.category)}</td>
-      <td class="numeric">${formatNumber(c.clicks)}</td>
-      <td class="numeric">${formatNumber(c.impressions)}</td>
-      <td class="numeric">${c.sharePct}%</td>
-    </tr>`).join("");
+  const categoryBars = renderShareBars(
+    "Search demand by intent",
+    gsc.categoryBreakdown.map((c, index) => ({
+      label: c.category,
+      count: c.clicks,
+      sharePct: c.sharePct,
+      color: COLORS.series[index % COLORS.series.length]
+    })),
+    "clicks"
+  );
   const trendChart = renderLineChart(
     gsc.trend.map((t) => ({ x: t.date, y: t.clicks, label: t.date.slice(5) })),
     COLORS.accent,
@@ -3216,18 +3704,19 @@ function renderGsc(report) {
   const crossoverBlocks = [];
   if (gsc.trackedButNoGsc.length > 0) {
     crossoverBlocks.push(`<div class="chart-card"><h3>AEO queries without search demand</h3>
-      <p class="section-intro">Tracked AEO queries with no GSC impressions in this window \u2014 review whether they represent real search demand.</p>
-      <ul>${gsc.trackedButNoGsc.map((q) => `<li>${escapeHtml(q)}</li>`).join("")}</ul>
+      <p class="section-intro">Review whether these still belong in the tracking set.</p>
+      ${renderProofChips(gsc.trackedButNoGsc, 6)}
     </div>`);
   }
   if (gsc.gscButNotTracked.length > 0) {
     crossoverBlocks.push(`<div class="chart-card"><h3>Search queries you should track</h3>
-      <p class="section-intro">GSC top queries (by impressions) that aren't tracked in your AEO project \u2014 candidates to add as queries.</p>
-      <ul>${gsc.gscButNotTracked.map((q) => `<li>${escapeHtml(q)}</li>`).join("")}</ul>
+      <p class="section-intro">High-impression candidates to add to AEO tracking.</p>
+      ${renderProofChips(gsc.gscButNotTracked, 6)}
     </div>`);
   }
+  const dateRange = gscDateRange(report);
   return section(
-    { id: "gsc", eyebrow: "Section 5", title: "GSC Performance", intro: "Your site\u2019s performance in Google\u2019s regular (non-AI) search results \u2014 top queries that drove impressions, intent breakdown, and the click trend, sourced from Google Search Console for the most recent sync window." },
+    { id: "gsc", eyebrow: "Section 5", 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>
@@ -3241,12 +3730,7 @@ function renderGsc(report) {
         <tbody>${rows}</tbody>
       </table>
     </div>
-    <div class="chart-card"><h3>Category breakdown</h3>
-      <table class="report-table">
-        <thead><tr><th>Category</th><th class="numeric">Clicks</th><th class="numeric">Imp.</th><th class="numeric">Share</th></tr></thead>
-        <tbody>${breakdownRows}</tbody>
-      </table>
-    </div>
+    ${categoryBars}
     ${crossoverBlocks.join("\n")}`
   );
 }
@@ -3265,14 +3749,18 @@ function renderGa(report) {
       <td class="numeric">${formatNumber(p.users)}</td>
       <td class="numeric">${formatNumber(p.organicSessions)}</td>
     </tr>`).join("");
-  const channelRows = ga.channelBreakdown.map((c) => `
-    <tr>
-      <td>${escapeHtml(c.channel)}</td>
-      <td class="numeric">${formatNumber(c.sessions)}</td>
-      <td class="numeric">${c.sharePct}%</td>
-    </tr>`).join("");
+  const channelBars = renderShareBars(
+    "Channel mix",
+    ga.channelBreakdown.map((c, index) => ({
+      label: c.channel,
+      count: c.sessions,
+      sharePct: c.sharePct,
+      color: COLORS.series[index % COLORS.series.length]
+    })),
+    "sessions"
+  );
   return section(
-    { id: "ga", eyebrow: "Section 6", title: "GA4 Traffic", intro: `Total sessions and users on your site between ${formatDate(ga.periodStart)} and ${formatDate(ga.periodEnd)}, with the top landing pages and channel breakdown \u2014 sourced from Google Analytics 4.` },
+    { id: "ga", eyebrow: "Section 6", 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>
@@ -3284,12 +3772,7 @@ function renderGa(report) {
         <tbody>${pageRows}</tbody>
       </table>
     </div>
-    <div class="chart-card"><h3>Channel breakdown</h3>
-      <table class="report-table">
-        <thead><tr><th>Channel</th><th class="numeric">Sessions</th><th class="numeric">Share</th></tr></thead>
-        <tbody>${channelRows}</tbody>
-      </table>
-    </div>`
+    ${channelBars}`
   );
 }
 function renderSocial(report) {
@@ -3300,12 +3783,16 @@ function renderSocial(report) {
       renderEmpty("No social referral data yet.")
     );
   }
-  const channelRows = social.channels.map((c) => `
-    <tr>
-      <td>${escapeHtml(c.channelGroup)}</td>
-      <td class="numeric">${formatNumber(c.sessions)}</td>
-      <td class="numeric">${c.sharePct}%</td>
-    </tr>`).join("");
+  const channelBars = renderShareBars(
+    "Social channel mix",
+    social.channels.map((c, index) => ({
+      label: c.channelGroup,
+      count: c.sessions,
+      sharePct: c.sharePct,
+      color: COLORS.series[index % COLORS.series.length]
+    })),
+    "sessions"
+  );
   const campaignRows = social.topCampaigns.map((c) => `
     <tr>
       <td>${escapeHtml(c.source)}</td>
@@ -3313,18 +3800,13 @@ function renderSocial(report) {
       <td class="numeric">${formatNumber(c.sessions)}</td>
     </tr>`).join("");
   return section(
-    { id: "social-referrals", eyebrow: "Section 7", title: "Social Referrals", intro: "Sessions on your site sent by social platforms (LinkedIn, Facebook, X, etc.) \u2014 paid versus organic split and the top campaigns that drove them. Sourced from Google Analytics 4." },
+    { id: "social-referrals", eyebrow: "Section 7", 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>
       <div class="metric"><div class="label">Paid social</div><div class="value">${formatNumber(social.paidSessions)}</div></div>
     </div>
-    <div class="chart-card"><h3>Channel groups</h3>
-      <table class="report-table">
-        <thead><tr><th>Channel</th><th class="numeric">Sessions</th><th class="numeric">Share</th></tr></thead>
-        <tbody>${channelRows}</tbody>
-      </table>
-    </div>
+    ${channelBars}
     <div class="chart-card"><h3>Top campaigns</h3>
       <table class="report-table">
         <thead><tr><th>Source</th><th>Medium</th><th class="numeric">Sessions</th></tr></thead>
@@ -3341,13 +3823,16 @@ function renderAiReferrals(report) {
       renderEmpty("No AI referral traffic detected yet.")
     );
   }
-  const sourceRows = ai.bySource.map((s) => `
-    <tr>
-      <td>${escapeHtml(s.source)}</td>
-      <td class="numeric">${formatNumber(s.sessions)}</td>
-      <td class="numeric">${formatNumber(s.users)}</td>
-      <td class="numeric">${s.sharePct}%</td>
-    </tr>`).join("");
+  const sourceBars = renderShareBars(
+    "AI sessions by source",
+    ai.bySource.map((s, index) => ({
+      label: s.source,
+      count: s.sessions,
+      sharePct: s.sharePct,
+      color: COLORS.series[(index + 2) % COLORS.series.length]
+    })),
+    "sessions"
+  );
   const pageRows = ai.topLandingPages.map((p) => `
     <tr>
       <td class="page-cell">${formatLandingPageHtml(p.page)}</td>
@@ -3360,18 +3845,13 @@ function renderAiReferrals(report) {
     "AI referral sessions over time"
   );
   return section(
-    { id: "ai-referrals", eyebrow: "Section 8", title: "AI Referral Traffic", intro: "Sessions on your site referred by AI answer engines (ChatGPT, Perplexity, Claude, Copilot, Gemini, etc.) \u2014 broken down by referrer with a daily trend and the top landing pages. Sourced from Google Analytics 4." },
+    { id: "ai-referrals", eyebrow: "Section 8", 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>
     </div>
     ${trendChart}
-    <div class="chart-card"><h3>Sessions by source</h3>
-      <table class="report-table">
-        <thead><tr><th>Source</th><th class="numeric">Sessions</th><th class="numeric">Users</th><th class="numeric">Share</th></tr></thead>
-        <tbody>${sourceRows}</tbody>
-      </table>
-    </div>
+    ${sourceBars}
     <div class="chart-card"><h3>Top AI landing pages</h3>
       <table class="report-table">
         <thead><tr><th>Page</th><th class="numeric">Sessions</th><th class="numeric">Users</th></tr></thead>
@@ -3406,7 +3886,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: `What share of your tracked URLs are currently indexed in ${ih.provider === "google" ? "Google" : "Bing"} \u2014 sourced from ${ih.provider === "google" ? "Google Search Console URL Inspection" : "Bing Webmaster Tools URL Inspection"}. Pages absent from the index can\u2019t be retrieved by AI engines either.` },
+    { 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.` },
     `<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>
@@ -3442,15 +3922,15 @@ function renderCitationsTrend(report) {
   const rows = trend.map((t) => `
     <tr>
       <td>${formatDate(t.date)}</td>
-      <td class="numeric">${t.citationRate}%</td>
+      <td class="numeric">${t.citationRate}% <span class="cell-pending">(${t.citedQueryCount}/${t.totalQueryCount})</span></td>
       <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 rate across every visibility sweep \u2014 the share of (keyword \xD7 provider) pairs in each run where your domain appeared in the source list, with a per-provider breakdown beneath." },
+    { id: "citations-trend", eyebrow: "Section 10", title: "Citations Over Time", intro: "Citation coverage across completed visibility sweeps." },
     `${chart}
     <div class="chart-card"><h3>Run-by-run breakdown</h3>
       <table class="report-table">
-        <thead><tr><th>Run</th><th class="numeric">Overall rate</th><th>Per-provider rates</th></tr></thead>
+        <thead><tr><th>Run</th><th class="numeric">Cited queries</th><th>Per-provider rates</th></tr></thead>
         <tbody>${rows}</tbody>
       </table>
     </div>`
@@ -3469,36 +3949,51 @@ function renderInsights(report) {
     const tone = severityTone(i.severity);
     const countChip = count > 1 ? ` <span class="badge tone-neutral">\xD7 ${count}</span>` : "";
     return `<tr>
-        <td><span class="badge tone-${tone}">${escapeHtml(i.severity)}</span></td>
-        <td>${escapeHtml(i.title)}${countChip}</td>
-        <td>${escapeHtml(i.query)}</td>
-        <td>${escapeHtml(i.provider)}</td>
-        <td>${i.recommendation ? escapeHtml(i.recommendation) : '<span class="cell-pending">\u2014</span>'}</td>
+        <td class="col-severity"><span class="badge tone-${tone}">${escapeHtml(reportSeverityLabel(i.severity))}</span></td>
+        <td class="col-title">${escapeHtml(i.title)}${countChip}</td>
+        <td class="col-query">${escapeHtml(i.query)}</td>
+        <td class="col-provider">${escapeHtml(i.provider)}</td>
+        <td class="col-recommendation">${i.recommendation ? escapeHtml(i.recommendation) : '<span class="cell-pending">\u2014</span>'}</td>
       </tr>`;
   }).join("");
   return section(
-    { id: "insights", eyebrow: "Section 11", title: "Insights & Alerts", intro: "Regressions (citations lost), gains (citations won), and opportunities surfaced by the intelligence engine across the most recent sweeps \u2014 ordered by severity and recurrence." },
-    `<table class="report-table">
-      <thead><tr><th>Severity</th><th>Title</th><th>Query</th><th>Provider</th><th>Recommendation</th></tr></thead>
+    { id: "insights", eyebrow: "Section 11", 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>
+        <th class="col-title">Title</th>
+        <th class="col-query">Query</th>
+        <th class="col-provider">Provider</th>
+        <th class="col-recommendation">Recommendation</th>
+      </tr></thead>
       <tbody>${rows}</tbody>
     </table>`
   );
 }
 function renderOpportunities(report) {
-  const opps = report.contentOpportunities;
+  const opps = dedupeReportOpportunities(report);
   if (opps.length === 0) return "";
   const canonical = report.meta.project.canonicalDomain;
+  const highlights = `<div class="opportunity-grid">
+    ${opps.slice(0, 3).map((o) => `<article class="opportunity-card">
+      <div class="opportunity-score" title="Opportunity score (0\u2013100, higher = stronger)">${Math.round(o.score)}<span class="opportunity-score-suffix">/100</span></div>
+      <h3>${escapeHtml(o.query)}</h3>
+      <p>${escapeHtml(contentActionLabel(o.action))} \xB7 ${escapeHtml(actionConfidenceLabel(o.actionConfidence))} confidence</p>
+      ${renderProofChips(o.drivers, 2)}
+    </article>`).join("")}
+  </div>`;
   const rows = opps.slice(0, 10).map((o) => {
-    const ourPage = o.ourBestPage ? `<a href="${escapeHtml(absolutizeProjectUrl(o.ourBestPage.url, canonical))}">${escapeHtml(o.ourBestPage.url)}</a>` : '<span class="cell-not-cited">\u2014</span>';
+    const ourPage = o.ourBestPage ? `<a href="${escapeHtml(absolutizeProjectUrl(o.ourBestPage.url, canonical))}">${escapeHtml(o.ourBestPage.url)}</a>` : '<span class="cell-not-cited">No page yet</span>';
     const winning = o.winningCompetitor ? `<a href="${escapeHtml(o.winningCompetitor.url)}">${escapeHtml(o.winningCompetitor.domain)}</a>` : '<span class="cell-not-cited">\u2014</span>';
+    const drivers = o.drivers.length > 0 ? `<ul class="driver-list">${o.drivers.map((d) => `<li>${escapeHtml(d)}</li>`).join("")}</ul>` : '<span class="cell-not-cited">No driver signal yet</span>';
     return `<tr>
       <td>${escapeHtml(o.query)}</td>
-      <td><span class="badge tone-neutral">${escapeHtml(o.action)}</span></td>
-      <td class="numeric">${Math.round(o.score)}</td>
+      <td><span class="badge tone-neutral">${escapeHtml(contentActionLabel(o.action))}</span></td>
+      <td class="numeric" title="Opportunity score (0\u2013100)">${Math.round(o.score)}</td>
+      <td>${drivers}</td>
       <td>${ourPage}</td>
       <td>${winning}</td>
-      <td><span class="badge tone-neutral">${escapeHtml(o.demandSource)}</span></td>
-      <td><span class="badge tone-neutral">${escapeHtml(o.actionConfidence)}</span></td>
+      <td><span class="badge tone-neutral">${escapeHtml(actionConfidenceLabel(o.actionConfidence))}</span></td>
     </tr>`;
   }).join("");
   return section(
@@ -3506,10 +4001,36 @@ function renderOpportunities(report) {
       id: "content-opportunities",
       eyebrow: "Section 12",
       title: "Content Opportunities",
-      intro: "Queries where you have search demand or competitor citation pressure but aren\u2019t winning AI citations. Each row carries a suggested action (create / refresh / expand / add-schema). Top 10 shown."
+      intro: "Queries where content work has the clearest path to more AI citations. Opportunity score is 0\u2013100, higher = stronger."
+    },
+    `${highlights}<table class="report-table">
+      <thead><tr><th>Query</th><th>Action</th><th class="numeric" title="Opportunity score (0\u2013100)">Score</th><th>Why</th><th>Our page</th><th>Winning competitor</th><th>Confidence</th></tr></thead>
+      <tbody>${rows}</tbody>
+    </table>`
+  );
+}
+function renderContentGaps(report) {
+  const gaps = report.contentGaps;
+  if (gaps.length === 0) return "";
+  const rows = gaps.slice(0, 10).map((g) => {
+    const competitorList = g.competitorDomains.slice(0, 5).map(escapeHtml).join(", ");
+    const more = g.competitorDomains.length > 5 ? `, +${g.competitorDomains.length - 5} more` : "";
+    return `<tr>
+      <td>${escapeHtml(g.query)}</td>
+      <td class="numeric">${g.competitorCount}</td>
+      <td>${competitorList}${more}</td>
+      <td class="numeric">${Math.round(g.missRate * 100)}%</td>
+    </tr>`;
+  }).join("");
+  return section(
+    {
+      id: "content-gaps",
+      eyebrow: "Section 13",
+      title: "Content Gaps",
+      intro: "Tracked queries where competitors are cited and the client is missing."
     },
     `<table class="report-table">
-      <thead><tr><th>Query</th><th>Action</th><th class="numeric">Score</th><th>Our page</th><th>Winning competitor</th><th>Demand</th><th>Confidence</th></tr></thead>
+      <thead><tr><th>Query</th><th class="numeric">Competitors cited</th><th>Domains</th><th class="numeric">Miss rate</th></tr></thead>
       <tbody>${rows}</tbody>
     </table>`
   );
@@ -3518,7 +4039,7 @@ function renderRecommendedNextSteps(report) {
   const steps = report.recommendedNextSteps;
   if (steps.length === 0) {
     return section(
-      { id: "recommended-next-steps", eyebrow: "Section 13", title: "Recommended Next Steps", intro: "Action items bucketed by horizon (immediate, short-term, medium-term), drawn from open insights and the highest-ranked content opportunities." },
+      { id: "recommended-next-steps", eyebrow: "Section 14", title: "Recommended Next Steps", intro: "Action items bucketed by timing." },
       renderEmpty("No outstanding actions.")
     );
   }
@@ -3529,17 +4050,157 @@ function renderRecommendedNextSteps(report) {
       <span class="rationale">${escapeHtml(s.rationale)}</span>
     </div>`).join("");
   return section(
-    { id: "recommended-next-steps", eyebrow: "Section 13", title: "Recommended Next Steps", intro: "Action items bucketed by horizon (immediate, short-term, medium-term), drawn from open insights and the highest-ranked content opportunities." },
+    { id: "recommended-next-steps", eyebrow: "Section 14", title: "Recommended Next Steps", intro: "Action items bucketed by timing." },
     `<div class="steps">${items}</div>`
   );
 }
+function actionAudienceMatches(action, audience) {
+  return action.audience === "both" || action.audience === audience;
+}
+function renderActionCards(actions) {
+  if (actions.length === 0) return renderEmpty("No prioritized actions yet.");
+  return `<div class="action-card-grid">
+    ${actions.map((action, idx) => {
+    const tone = reportActionTone(action);
+    const why = action.why.length > 0 ? `<ul>${action.why.map((item) => `<li>${escapeHtml(item)}</li>`).join("")}</ul>` : "";
+    const evidence = action.evidence.length > 0 ? `<ul>${action.evidence.map((item) => `<li>${escapeHtml(item)}</li>`).join("")}</ul>` : "";
+    const proof = renderProofChips(action.evidence.length > 0 ? action.evidence : action.why, 3);
+    const details = why || evidence ? `<details class="action-details">
+            <summary>Evidence details</summary>
+            ${why ? `<div><strong>Why</strong>${why}</div>` : ""}
+            ${evidence ? `<div><strong>Evidence</strong>${evidence}</div>` : ""}
+          </details>` : "";
+    return `<article class="action-card">
+        <div class="action-head">
+          <div class="action-rank" title="Impact rank \u2014 1 is the highest-leverage action">${idx + 1}</div>
+          <div>
+            <div class="action-meta">
+              <span class="badge tone-${tone}">${escapeHtml(reportHorizonLabel(action.horizon))}</span>
+              <span class="badge tone-neutral">${escapeHtml(reportActionCategoryLabel(action.category))}</span>
+              <span class="badge tone-neutral">${escapeHtml(reportConfidenceLabel(action.confidence))} confidence</span>
+            </div>
+            <h3>${escapeHtml(action.title)}</h3>
+          </div>
+        </div>
+        <p>${escapeHtml(action.action)}</p>
+        ${proof}
+        ${details}
+        <div class="success-metric"><strong>Win condition:</strong> ${escapeHtml(action.successMetric)}</div>
+      </article>`;
+  }).join("")}
+  </div>`;
+}
+function renderAudienceActionPlan(report, audience) {
+  const rawActions = audience === "client" ? report.clientSummary.actionItems : report.agencyDiagnostics.priorities.length > 0 ? report.agencyDiagnostics.priorities : report.actionPlan.filter((a) => actionAudienceMatches(a, audience));
+  const actions = dedupeReportActions(report, rawActions);
+  return section(
+    {
+      id: audience === "client" ? "client-action-plan" : "agency-action-plan",
+      eyebrow: audience === "client" ? "Client actions" : "Agency actions",
+      title: audience === "client" ? "What We Recommend Next" : "Agency Action Plan",
+      intro: audience === "client" ? "The short list to approve and execute." : "The highest-leverage work, sorted by urgency and evidence strength."
+    },
+    renderActionCards(actions)
+  );
+}
+function renderClientSummary(report) {
+  const s = report.executiveSummary;
+  const metrics = `<div class="metric-grid">
+    <div class="metric"><div class="label">Citation coverage</div><div class="value">${s.citationRate}%</div><div class="delta">${s.citedQueryCount}/${s.totalQueryCount} tracked queries cited</div></div>
+    <div class="metric"><div class="label">Mention coverage</div><div class="value">${s.mentionRate}%</div><div class="delta">${s.mentionedQueryCount}/${s.totalQueryCount} tracked queries mentioned</div></div>
+    <div class="metric"><div class="label">Providers checked</div><div class="value">${formatNumber(s.providerCount)}</div><div class="delta">${formatNumber(s.queryCount)} tracked queries</div></div>
+  </div>`;
+  const notes = report.clientSummary.confidenceNotes.length > 0 ? `<div class="client-notes">${report.clientSummary.confidenceNotes.map((note) => `<div class="client-note">${escapeHtml(note)}</div>`).join("")}</div>` : "";
+  return section(
+    {
+      id: "client-summary",
+      eyebrow: "Client summary",
+      title: "How You're Appearing",
+      intro: report.clientSummary.overview
+    },
+    `<div class="chart-card">
+      <h3>${escapeHtml(report.clientSummary.headline)}</h3>
+      <p class="source-origin-headline">${escapeHtml(report.clientSummary.overview)}</p>
+    </div>
+    ${metrics}
+    ${notes}`
+  );
+}
+function renderClientEvidenceSummary(report) {
+  const evidenceCards = [];
+  if (report.aiSourceOrigin.topDomains.length > 0) {
+    evidenceCards.push(`<div class="diagnostic-card tone-neutral">
+      <h3>Sources AI engines trust</h3>
+      <p>These domains appeared most often as cited sources outside your owned domain.</p>
+      <ul>${report.aiSourceOrigin.topDomains.slice(0, 5).map((d) => `<li>${escapeHtml(d.domain)}: ${formatNumber(d.count)} citation${d.count === 1 ? "" : "s"}</li>`).join("")}</ul>
+    </div>`);
+  }
+  if (report.gsc) {
+    evidenceCards.push(`<div class="diagnostic-card tone-neutral">
+      <h3>Search demand</h3>
+      <p>Search Console shows ${formatNumber(report.gsc.totalImpressions)} impressions and ${formatNumber(report.gsc.totalClicks)} clicks in the report window.</p>
+      <ul>${report.gsc.topQueries.slice(0, 5).map((q) => `<li>${escapeHtml(q.query)}: ${formatNumber(q.impressions)} impressions</li>`).join("")}</ul>
+    </div>`);
+  }
+  if (report.indexingHealth) {
+    const tone = report.indexingHealth.indexedPct >= 90 ? "positive" : report.indexingHealth.indexedPct >= 70 ? "caution" : "negative";
+    evidenceCards.push(`<div class="diagnostic-card tone-${tone}">
+      <h3>Indexing readiness</h3>
+      <p>${report.indexingHealth.indexedPct}% of inspected URLs are indexed.</p>
+      <ul><li>${formatNumber(report.indexingHealth.indexed)} indexed</li><li>${formatNumber(report.indexingHealth.notIndexed)} not indexed</li></ul>
+    </div>`);
+  }
+  const opportunities = dedupeReportOpportunities(report);
+  if (opportunities.length > 0) {
+    evidenceCards.push(`<div class="diagnostic-card tone-caution">
+      <h3>Content opportunities</h3>
+      <p>Canonry found topics where better content could improve AI citations.</p>
+      <ul>${opportunities.slice(0, 5).map((o) => `<li>${escapeHtml(o.query)}: ${escapeHtml(o.action)} (${Math.round(o.score)})</li>`).join("")}</ul>
+    </div>`);
+  }
+  return section(
+    {
+      id: "client-evidence-summary",
+      eyebrow: "Evidence",
+      title: "Why This Is The Plan",
+      intro: "A concise evidence view for the client summary. The agency report keeps the full matrices and detailed tables."
+    },
+    evidenceCards.length > 0 ? `<div class="diagnostics-grid">${evidenceCards.join("")}</div>` : renderEmpty("No supporting evidence sections are populated yet.")
+  );
+}
+function renderAgencyDiagnostics(report) {
+  const diagnostics = report.agencyDiagnostics.diagnostics.filter((d) => d.title !== "Location caveat");
+  const body = diagnostics.length > 0 ? `<div class="diagnostics-grid">
+        ${diagnostics.map((d) => `<div class="diagnostic-card tone-${d.severity}">
+          <h3>${escapeHtml(d.title)}</h3>
+          <p>${escapeHtml(d.detail)}</p>
+          ${renderProofChips(d.evidence, 3)}
+        </div>`).join("")}
+      </div>` : renderEmpty("No agency diagnostics available yet.");
+  return section(
+    {
+      id: "agency-diagnostics",
+      eyebrow: "Agency diagnostics",
+      title: "Technical Diagnostics",
+      intro: "Fast-read operator flags behind the action plan."
+    },
+    body
+  );
+}
 function escapeJsonForScript(json) {
   return json.replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
 }
 function renderReportHtml(report, opts = {}) {
-  const title = opts.title ?? `Canonry report \u2014 ${report.meta.project.displayName}`;
-  const sections = [
+  const audience = opts.audience ?? "agency";
+  const title = opts.title ?? `Canonry ${audience} report \u2014 ${report.meta.project.displayName}`;
+  const sections = audience === "client" ? [
+    renderClientSummary(report),
+    renderAudienceActionPlan(report, "client"),
+    renderClientEvidenceSummary(report)
+  ].join("\n") : [
     renderExecutiveSummary(report),
+    renderAudienceActionPlan(report, "agency"),
+    renderAgencyDiagnostics(report),
     renderCitationScorecard(report),
     renderCompetitorLandscape(report),
     renderAiSourceOrigin(report),
@@ -3551,6 +4212,7 @@ function renderReportHtml(report, opts = {}) {
     renderCitationsTrend(report),
     renderInsights(report),
     renderOpportunities(report),
+    renderContentGaps(report),
     renderRecommendedNextSteps(report)
   ].join("\n");
   const json = escapeJsonForScript(JSON.stringify(report));
@@ -3565,9 +4227,9 @@ function renderReportHtml(report, opts = {}) {
 <body>
 <div class="container">
   <header class="header">
-    <div class="eyebrow">AEO Report</div>
+    <div class="eyebrow">${audience === "client" ? "AEO Client Summary" : "AEO Agency Report"}</div>
     <h1>${escapeHtml(report.meta.project.displayName)}</h1>
-    <div class="subtitle">${escapeHtml(report.meta.project.canonicalDomain)} \xB7 ${escapeHtml(report.meta.project.country)} / ${escapeHtml(report.meta.project.language.toUpperCase())} \xB7 Generated ${formatDate(report.meta.generatedAt)}</div>
+    <div class="subtitle">${escapeHtml(report.meta.project.canonicalDomain)} \xB7 ${escapeHtml(report.meta.project.country)} / ${escapeHtml(report.meta.project.language.toUpperCase())}${renderHeaderLocationFragment(report.meta.location)} \xB7 Generated ${formatDate(report.meta.generatedAt)}</div>
   </header>
   ${sections}
   <footer class="footer">Generated by canonry \xB7 ${escapeHtml(report.meta.generatedAt)}</footer>
@@ -3580,7 +4242,7 @@ function renderReportHtml(report, opts = {}) {
 // ../api-routes/src/content-data.ts
 import { and as and3, eq as eq12, desc as desc5, inArray as inArray3 } from "drizzle-orm";
 var RECENT_RUNS_WINDOW = 5;
-function loadOrchestratorInput(db, project) {
+function loadOrchestratorInput(db, project, locationFilter = void 0) {
   const projectId = project.id;
   const ownDomain = normalizeDomain(project.canonicalDomain);
   const ownedDomains = parseJsonColumn(project.ownedDomains, []);
@@ -3589,7 +4251,7 @@ function loadOrchestratorInput(db, project) {
   const candidateQueryStrings = trackedQueries.filter(isBlogShapedQuery);
   const trackedCompetitors = listCompetitorDomains(db, projectId).map(normalizeDomain);
   const competitorSet = new Set(trackedCompetitors);
-  const recentRunIds = listRecentAnswerVisibilityRunIds(db, projectId, RECENT_RUNS_WINDOW);
+  const recentRunIds = listRecentAnswerVisibilityRunIds(db, projectId, RECENT_RUNS_WINDOW, locationFilter);
   const latestRunId = recentRunIds[0] ?? "";
   const latestRunTimestamp = latestRunId ? lookupRunTimestamp(db, latestRunId) : "";
   const candidateQueries = buildCandidateQueries({
@@ -3614,6 +4276,7 @@ function loadOrchestratorInput(db, project) {
     ownDomain,
     competitors: trackedCompetitors,
     candidateQueries,
+    queryIntentModifiers: buildQueryIntentModifiers(project, locationFilter),
     inventory,
     wpSchemaAudit: /* @__PURE__ */ new Map(),
     gaTrafficByPage,
@@ -3623,6 +4286,74 @@ function loadOrchestratorInput(db, project) {
     inProgressActions: /* @__PURE__ */ new Map()
   };
 }
+function buildQueryIntentModifiers(project, locationFilter) {
+  if (locationFilter === void 0 || locationFilter === null) return [];
+  const locations = parseJsonColumn(project.locations, []);
+  const currentLocation = locations.find((location) => location.label === locationFilter);
+  const raw = currentLocation ? [
+    currentLocation.label,
+    currentLocation.city,
+    currentLocation.region,
+    regionAbbreviation(currentLocation.region),
+    currentLocation.country
+  ] : [locationFilter];
+  return [...new Set(raw.map((value) => value.trim().toLowerCase()).filter(Boolean))];
+}
+function regionAbbreviation(region) {
+  return US_REGION_ABBREVIATIONS[region.trim().toLowerCase()] ?? "";
+}
+var US_REGION_ABBREVIATIONS = {
+  alabama: "al",
+  alaska: "ak",
+  arizona: "az",
+  arkansas: "ar",
+  california: "ca",
+  colorado: "co",
+  connecticut: "ct",
+  delaware: "de",
+  florida: "fl",
+  georgia: "ga",
+  hawaii: "hi",
+  idaho: "id",
+  illinois: "il",
+  indiana: "in",
+  iowa: "ia",
+  kansas: "ks",
+  kentucky: "ky",
+  louisiana: "la",
+  maine: "me",
+  maryland: "md",
+  massachusetts: "ma",
+  michigan: "mi",
+  minnesota: "mn",
+  mississippi: "ms",
+  missouri: "mo",
+  montana: "mt",
+  nebraska: "ne",
+  nevada: "nv",
+  "new hampshire": "nh",
+  "new jersey": "nj",
+  "new mexico": "nm",
+  "new york": "ny",
+  "north carolina": "nc",
+  "north dakota": "nd",
+  ohio: "oh",
+  oklahoma: "ok",
+  oregon: "or",
+  pennsylvania: "pa",
+  "rhode island": "ri",
+  "south carolina": "sc",
+  "south dakota": "sd",
+  tennessee: "tn",
+  texas: "tx",
+  utah: "ut",
+  vermont: "vt",
+  virginia: "va",
+  washington: "wa",
+  "west virginia": "wv",
+  wisconsin: "wi",
+  wyoming: "wy"
+};
 function listQueries(db, projectId) {
   const rows = db.select({ text: queries.query }).from(queries).where(eq12(queries.projectId, projectId)).all();
   return rows.map((r) => r.text);
@@ -3631,8 +4362,8 @@ function listCompetitorDomains(db, projectId) {
   const rows = db.select({ domain: competitors.domain }).from(competitors).where(eq12(competitors.projectId, projectId)).all();
   return rows.map((r) => r.domain);
 }
-function listRecentAnswerVisibilityRunIds(db, projectId, limit) {
-  const rows = db.select({ id: runs.id }).from(runs).where(
+function listRecentAnswerVisibilityRunIds(db, projectId, limit, locationFilter) {
+  const rows = db.select({ id: runs.id, location: runs.location }).from(runs).where(
     and3(
       eq12(runs.projectId, projectId),
       eq12(runs.kind, RunKinds["answer-visibility"]),
@@ -3641,8 +4372,9 @@ function listRecentAnswerVisibilityRunIds(db, projectId, limit) {
       // no usable evidence.
       inArray3(runs.status, [RunStatuses.completed, RunStatuses.partial])
     )
-  ).orderBy(desc5(runs.createdAt)).limit(limit).all();
-  return rows.map((r) => r.id);
+  ).orderBy(desc5(runs.createdAt)).all();
+  const filtered = locationFilter === void 0 ? rows : rows.filter((r) => (r.location ?? null) === locationFilter);
+  return filtered.slice(0, limit).map((r) => r.id);
 }
 function lookupRunTimestamp(db, runId) {
   const row = db.select({ createdAt: runs.createdAt }).from(runs).where(eq12(runs.id, runId)).get();
@@ -3860,6 +4592,14 @@ var TOP_LANDING_PAGES_LIMIT = 20;
 var TOP_AI_REFERRAL_PAGES_LIMIT = 10;
 var TOP_CAMPAIGN_LIMIT = 10;
 var INSIGHT_LOOKBACK_RUNS = 5;
+var REPORT_WINDOW_DAYS = 30;
+function windowStartDate(endDate, windowDays) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(endDate);
+  if (!m) return endDate;
+  const d = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])));
+  d.setUTCDate(d.getUTCDate() - (windowDays - 1));
+  return d.toISOString().slice(0, 10);
+}
 function safeNum(value) {
   if (typeof value === "number") return value;
   if (typeof value === "string") {
@@ -3895,7 +4635,12 @@ function loadQueryLookup(db, projectId) {
   return { byId };
 }
 function buildGscSection(db, projectId, projectDisplayName, canonicalDomain, trackedQueries) {
-  const rows = db.select().from(gscSearchData).where(eq13(gscSearchData.projectId, projectId)).all();
+  const allRows = db.select().from(gscSearchData).where(eq13(gscSearchData.projectId, projectId)).all();
+  if (allRows.length === 0) return null;
+  let maxDate = "";
+  for (const r of allRows) if (r.date > maxDate) maxDate = r.date;
+  const startDate = windowStartDate(maxDate, REPORT_WINDOW_DAYS);
+  const rows = allRows.filter((r) => r.date >= startDate && r.date <= maxDate);
   if (rows.length === 0) return null;
   let totalClicks = 0;
   let totalImpressions = 0;
@@ -3941,11 +4686,15 @@ function buildGscSection(db, projectId, projectDisplayName, canonicalDomain, tra
     sharePct: totalClicks > 0 ? Math.round(agg.clicks / totalClicks * 100) : 0
   })).sort((a, b) => b.clicks - a.clicks);
   const trend = [...trendAgg.entries()].map(([date, agg]) => ({ date, clicks: agg.clicks, impressions: agg.impressions })).sort((a, b) => a.date.localeCompare(b.date));
+  const periodStart = trend[0]?.date ?? "";
+  const periodEnd = trend.at(-1)?.date ?? "";
   const trackedSet = new Set(trackedQueries.map((q) => q.toLowerCase()));
   const gscQuerySet = new Set([...queryAgg.keys()].map((q) => q.toLowerCase()));
   const trackedButNoGsc = trackedQueries.filter((q) => !gscQuerySet.has(q.toLowerCase())).sort();
   const gscButNotTracked = [...queryAgg.entries()].filter(([q]) => !trackedSet.has(q.toLowerCase())).filter(([q]) => categorizeQuery(q, projectDisplayName, canonicalDomain) !== "brand").sort((a, b) => b[1].impressions - a[1].impressions).map(([q]) => q).slice(0, TOP_QUERIES_LIMIT);
   return {
+    periodStart,
+    periodEnd,
     totalClicks,
     totalImpressions,
     ctr,
@@ -3958,14 +4707,24 @@ function buildGscSection(db, projectId, projectDisplayName, canonicalDomain, tra
   };
 }
 function buildGaSection(db, projectId) {
-  const summaryRow = db.select().from(gaTrafficSummaries).where(eq13(gaTrafficSummaries.projectId, projectId)).orderBy(desc6(gaTrafficSummaries.syncedAt)).limit(1).get();
-  const snapshotRows = db.select().from(gaTrafficSnapshots).where(eq13(gaTrafficSnapshots.projectId, projectId)).all();
-  if (!summaryRow && snapshotRows.length === 0) return null;
-  const totalSessions = summaryRow?.totalSessions ?? snapshotRows.reduce((s, r) => s + r.sessions, 0);
-  const totalUsers = summaryRow?.totalUsers ?? snapshotRows.reduce((s, r) => s + r.users, 0);
-  const totalOrganicSessions = summaryRow?.totalOrganicSessions ?? snapshotRows.reduce((s, r) => s + r.organicSessions, 0);
+  const windowSummary = db.select().from(gaTrafficWindowSummaries).where(
+    and4(
+      eq13(gaTrafficWindowSummaries.projectId, projectId),
+      eq13(gaTrafficWindowSummaries.windowKey, "30d")
+    )
+  ).limit(1).get();
+  const fallbackSummary = windowSummary ? null : db.select().from(gaTrafficSummaries).where(eq13(gaTrafficSummaries.projectId, projectId)).orderBy(desc6(gaTrafficSummaries.syncedAt)).limit(1).get();
+  const allSnapshotRows = db.select().from(gaTrafficSnapshots).where(eq13(gaTrafficSnapshots.projectId, projectId)).all();
+  if (!windowSummary && !fallbackSummary && allSnapshotRows.length === 0) return null;
+  let snapshotMaxDate = "";
+  for (const r of allSnapshotRows) if (r.date > snapshotMaxDate) snapshotMaxDate = r.date;
+  const snapshotStartDate = snapshotMaxDate ? windowStartDate(snapshotMaxDate, REPORT_WINDOW_DAYS) : "";
+  const snapshotRows = snapshotStartDate ? allSnapshotRows.filter((r) => r.date >= snapshotStartDate && r.date <= snapshotMaxDate) : allSnapshotRows;
+  const totalSessions = windowSummary?.totalSessions ?? fallbackSummary?.totalSessions ?? snapshotRows.reduce((s, r) => s + r.sessions, 0);
+  const totalUsers = windowSummary?.totalUsers ?? fallbackSummary?.totalUsers ?? snapshotRows.reduce((s, r) => s + r.users, 0);
+  const totalOrganicSessions = windowSummary?.totalOrganicSessions ?? fallbackSummary?.totalOrganicSessions ?? snapshotRows.reduce((s, r) => s + r.organicSessions, 0);
   const pageAgg = /* @__PURE__ */ new Map();
-  let directSessions = 0;
+  let directSessions = windowSummary?.totalDirectSessions ?? 0;
   for (const r of snapshotRows) {
     const page = r.landingPageNormalized ?? r.landingPage;
     const existing = pageAgg.get(page) ?? { sessions: 0, users: 0, organic: 0 };
@@ -3973,7 +4732,7 @@ function buildGaSection(db, projectId) {
     existing.users += r.users;
     existing.organic += r.organicSessions;
     pageAgg.set(page, existing);
-    if (r.directSessions != null) directSessions += r.directSessions;
+    if (!windowSummary && r.directSessions != null) directSessions += r.directSessions;
   }
   const topLandingPages = [...pageAgg.entries()].map(([page, data]) => ({
     page,
@@ -4001,12 +4760,14 @@ function buildGaSection(db, projectId) {
       }
     }
   }
+  const periodStart = windowSummary?.periodStart ?? (snapshotStartDate || fallbackSummary?.periodStart || "");
+  const periodEnd = windowSummary?.periodEnd ?? (snapshotMaxDate || fallbackSummary?.periodEnd || "");
   return {
     totalSessions,
     totalUsers,
     totalOrganicSessions,
-    periodStart: summaryRow?.periodStart ?? "",
-    periodEnd: summaryRow?.periodEnd ?? "",
+    periodStart,
+    periodEnd,
     topLandingPages,
     channelBreakdown
   };
@@ -4129,27 +4890,33 @@ function buildIndexingHealth(db, projectId) {
   }
   return null;
 }
-function buildCitationsTrend(db, projectId, queryLookup) {
-  const visibilityRuns = db.select().from(runs).where(and4(eq13(runs.projectId, projectId), eq13(runs.kind, RunKinds["answer-visibility"]))).all();
+function buildCitationsTrend(db, projectId, queryLookup, locationFilter) {
+  const visibilityRuns = db.select().from(runs).where(and4(eq13(runs.projectId, projectId), eq13(runs.kind, RunKinds["answer-visibility"]))).all().filter((r) => locationFilter === void 0 || (r.location ?? null) === locationFilter);
+  const totalQueries = queryLookup.byId.size;
   const points = [];
   for (const run of visibilityRuns) {
     if (run.status !== RunStatuses.completed) continue;
     const snaps = loadSnapshotsForRun(db, run.id);
     if (snaps.length === 0) continue;
-    let cited = 0;
+    const citedQueryIds = /* @__PURE__ */ new Set();
+    const mentionedQueryIds = /* @__PURE__ */ new Set();
     let considered = 0;
     const providerCounts = /* @__PURE__ */ new Map();
     for (const snap of snaps) {
       if (!queryLookup.byId.has(snap.queryId)) continue;
       considered++;
-      if (snap.citationState === CitationStates.cited) cited++;
+      if (snap.citationState === CitationStates.cited) citedQueryIds.add(snap.queryId);
+      if (snap.answerMentioned) mentionedQueryIds.add(snap.queryId);
       const counts = providerCounts.get(snap.provider) ?? { cited: 0, total: 0 };
       counts.total++;
       if (snap.citationState === CitationStates.cited) counts.cited++;
       providerCounts.set(snap.provider, counts);
     }
     if (considered === 0) continue;
-    const citationRate = Math.round(cited / considered * 100);
+    const citedQueryCount = citedQueryIds.size;
+    const mentionedQueryCount = mentionedQueryIds.size;
+    const citationRate = totalQueries > 0 ? Math.round(citedQueryCount / totalQueries * 100) : 0;
+    const mentionRate = totalQueries > 0 ? Math.round(mentionedQueryCount / totalQueries * 100) : 0;
     const providerRates = [...providerCounts.entries()].map(([provider, counts]) => ({
       provider,
       citationRate: counts.total > 0 ? Math.round(counts.cited / counts.total * 100) : 0
@@ -4158,20 +4925,24 @@ function buildCitationsTrend(db, projectId, queryLookup) {
       runId: run.id,
       date: run.finishedAt ?? run.createdAt,
       citationRate,
+      citedQueryCount,
+      totalQueryCount: totalQueries,
+      mentionRate,
+      mentionedQueryCount,
       providerRates
     });
   }
   points.sort((a, b) => a.date.localeCompare(b.date));
   return points;
 }
-function buildInsightList(db, projectId) {
-  const recentRunIds = db.select({ id: runs.id }).from(runs).where(
+function buildInsightList(db, projectId, locationFilter) {
+  const recentRunIds = db.select({ id: runs.id, location: runs.location }).from(runs).where(
     and4(
       eq13(runs.projectId, projectId),
       eq13(runs.kind, RunKinds["answer-visibility"]),
       or2(eq13(runs.status, RunStatuses.completed), eq13(runs.status, RunStatuses.partial))
     )
-  ).orderBy(desc6(runs.createdAt)).limit(INSIGHT_LOOKBACK_RUNS).all().map((r) => r.id);
+  ).orderBy(desc6(runs.createdAt)).all().filter((r) => locationFilter === void 0 || (r.location ?? null) === locationFilter).slice(0, INSIGHT_LOOKBACK_RUNS).map((r) => r.id);
   if (recentRunIds.length === 0) return [];
   const rows = db.select().from(insights).where(and4(eq13(insights.projectId, projectId), inArray4(insights.runId, recentRunIds))).orderBy(desc6(insights.createdAt)).all();
   const severityRank = { critical: 0, high: 1, medium: 2, low: 3 };
@@ -4243,7 +5014,7 @@ function buildRecommendedNextSteps(insightList) {
   }
   return steps;
 }
-function buildExecutiveFindings(citationRate, trend, trendsPoints, trendBaseline, insightList, competitorRows) {
+function buildExecutiveFindings(citationRate, citedQueryCount, totalQueryCount, trend, trendsPoints, trendBaseline, insightList, competitorRows) {
   const findings = [];
   if (trendsPoints.length > 0) {
     const tone = trendBaseline ? "neutral" : trend === "up" ? "positive" : trend === "down" ? "negative" : "neutral";
@@ -4266,8 +5037,10 @@ function buildExecutiveFindings(citationRate, trend, trendsPoints, trendBaseline
           break;
       }
     }
+    const queryNoun = totalQueryCount === 1 ? "query" : "queries";
+    const ratioFragment = totalQueryCount > 0 ? ` (${citedQueryCount} of ${totalQueryCount} ${queryNoun} cited)` : "";
     findings.push({
-      title: `Citation rate at ${citationRate}%`,
+      title: `Citation rate at ${citationRate}%${ratioFragment}`,
       detail,
       tone
     });
@@ -4290,6 +5063,317 @@ function buildExecutiveFindings(citationRate, trend, trendsPoints, trendBaseline
   }
   return findings.slice(0, 5);
 }
+function buildLocationMeta(runLocationLabel, configuredLocations) {
+  if (!runLocationLabel) return null;
+  const match = configuredLocations.find((loc) => loc.label === runLocationLabel);
+  const others = configuredLocations.map((loc) => loc.label).filter((label) => label !== runLocationLabel);
+  return {
+    label: runLocationLabel,
+    city: match?.city ?? "",
+    region: match?.region ?? "",
+    country: match?.country ?? "",
+    otherConfiguredLabels: others
+  };
+}
+function buildProviderLocationHandling(providersInRun) {
+  return [...providersInRun].sort().map((provider) => {
+    const handling = getProviderLocationHandling(provider);
+    return {
+      provider,
+      treatment: handling.treatment,
+      description: handling.description
+    };
+  });
+}
+function compactList(items, limit = 3) {
+  const visible = items.slice(0, limit);
+  const extra = items.length - visible.length;
+  return extra > 0 ? `${visible.join(", ")}, +${extra} more` : visible.join(", ");
+}
+function contentActionVerb(action) {
+  switch (action) {
+    case "create":
+      return "Create";
+    case "expand":
+      return "Expand";
+    case "refresh":
+      return "Refresh";
+    case "add-schema":
+      return "Add schema to";
+  }
+}
+function confidenceFromEvidence(count) {
+  if (count >= 3) return "high";
+  if (count >= 1) return "medium";
+  return "low";
+}
+function actionAudienceMatches2(action, audience) {
+  return action.audience === "both" || action.audience === audience;
+}
+function buildReportActionPlan(input) {
+  const actions = [];
+  if (input.competitorDomains.length === 0 && input.aiSourceOrigin.topDomains.length > 0) {
+    const topDomains = input.aiSourceOrigin.topDomains.slice(0, 5);
+    actions.push({
+      audience: "both",
+      priority: 10,
+      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.",
+      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."
+      ],
+      evidence: topDomains.map((d) => `${d.domain} appeared in ${d.count} cited source${d.count === 1 ? "" : "s"}`),
+      successMetric: "Next report separates tracked competitors from independent source domains in the competitor landscape.",
+      confidence: confidenceFromEvidence(topDomains.length)
+    });
+  }
+  for (const [index, opportunity] of input.contentOpportunities.slice(0, 2).entries()) {
+    const verb = contentActionVerb(opportunity.action);
+    const target = opportunity.ourBestPage?.url ?? `a new page for "${opportunity.query}"`;
+    const evidence = [
+      `Opportunity score ${Math.round(opportunity.score)} with ${opportunity.actionConfidence} confidence`,
+      `Demand source: ${opportunity.demandSource}`
+    ];
+    if (opportunity.winningCompetitor) {
+      evidence.push(`${opportunity.winningCompetitor.domain} is the current winning cited source`);
+    }
+    if (opportunity.ourBestPage) {
+      evidence.push(`Best matching owned page: ${opportunity.ourBestPage.url}`);
+    } else {
+      evidence.push("No matching owned page was found");
+    }
+    actions.push({
+      audience: "both",
+      priority: 20 + index,
+      horizon: opportunity.actionConfidence === "high" ? "short-term" : "medium-term",
+      category: "content",
+      title: `${verb} content for "${opportunity.query}"`,
+      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.`,
+      confidence: opportunity.actionConfidence
+    });
+  }
+  if (input.indexingHealth && input.indexingHealth.total > 0 && input.indexingHealth.indexedPct < 70) {
+    const ih = input.indexingHealth;
+    const evidence = [
+      `${ih.indexedPct}% indexed (${ih.indexed}/${ih.total})`,
+      `${ih.notIndexed} not indexed${ih.deindexed > 0 ? `, ${ih.deindexed} deindexed` : ""}`
+    ];
+    actions.push({
+      audience: "both",
+      priority: 30,
+      horizon: "immediate",
+      category: "indexing",
+      title: "Fix indexing coverage before expanding the content plan",
+      action: "Audit the not-indexed tracked URLs, resolve crawl/index blockers, and resubmit priority pages.",
+      why: [
+        "Pages missing from the search index are less likely to be retrieved or cited by AI answer engines.",
+        "Indexing issues can hide otherwise strong content from both search and AI systems."
+      ],
+      evidence,
+      successMetric: "Indexed share moves above 80% for tracked URLs and priority pages are eligible for retrieval.",
+      confidence: ih.total >= 5 ? "high" : "medium"
+    });
+  }
+  const zeroCitationProviders = input.citationScorecard.providerRates.filter((p) => p.totalCount > 0 && p.citedCount === 0);
+  if (zeroCitationProviders.length > 0) {
+    actions.push({
+      audience: "agency",
+      priority: 40,
+      horizon: "short-term",
+      category: "provider",
+      title: "Diagnose providers with zero citations",
+      action: "Inspect zero-citation provider answers and compare their cited domains against the pages currently available on the client site.",
+      why: [
+        "Provider-level misses show where one model family is not retrieving the client even when others might.",
+        "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.",
+      confidence: "high"
+    });
+  }
+  if (input.gsc && (input.gsc.trackedButNoGsc.length > 0 || input.gsc.gscButNotTracked.length > 0)) {
+    const evidence = [];
+    if (input.gsc.trackedButNoGsc.length > 0) {
+      evidence.push(`Tracked with no GSC demand: ${compactList(input.gsc.trackedButNoGsc)}`);
+    }
+    if (input.gsc.gscButNotTracked.length > 0) {
+      evidence.push(`Search demand not tracked in AEO: ${compactList(input.gsc.gscButNotTracked)}`);
+    }
+    actions.push({
+      audience: "agency",
+      priority: 50,
+      horizon: "short-term",
+      category: "search-demand",
+      title: "Align tracked AEO queries with search demand",
+      action: "Prune or relabel tracked queries with no search demand and add high-impression non-brand GSC queries to the AEO tracking set.",
+      why: [
+        "The strongest report actions come from overlap between real search demand and AI citation gaps.",
+        "Mismatch here can make the client report feel interesting but hard to act on."
+      ],
+      evidence,
+      successMetric: "Next report has fewer no-demand tracked queries and includes the highest-impression non-brand GSC candidates.",
+      confidence: evidence.length > 1 ? "high" : "medium"
+    });
+  }
+  if (input.contentGaps.length > 0) {
+    const topGap = input.contentGaps[0];
+    actions.push({
+      audience: "agency",
+      priority: 60,
+      horizon: "medium-term",
+      category: "content",
+      title: "Close competitor-cited content gaps",
+      action: "Map the top missing queries to owned pages or new briefs, starting with the gaps where multiple competitors are already cited.",
+      why: [
+        "These are explicit places where AI engines found competitor sources but not the client.",
+        "They are stronger evidence than a generic topic list because the model is already retrieving competing content."
+      ],
+      evidence: [
+        `"${topGap.query}" missed at ${Math.round(topGap.missRate * 100)}% with ${topGap.competitorCount} competitor${topGap.competitorCount === 1 ? "" : "s"} cited`,
+        `Cited competitors: ${compactList(topGap.competitorDomains)}`
+      ],
+      successMetric: "The top content-gap query moves from missed to cited or mentioned after the recommended content work ships.",
+      confidence: topGap.competitorCount >= 2 ? "high" : "medium"
+    });
+  }
+  if (input.reportLocation && input.reportLocation.otherConfiguredLabels.length > 0) {
+    const ignoredProviders = input.providerLocationHandling.filter((p) => p.treatment === "ignored" || p.treatment === "browser-geo").map((p) => p.provider);
+    const evidence = [
+      `Current report location: ${input.reportLocation.label}`,
+      `Other configured locations: ${compactList(input.reportLocation.otherConfiguredLabels)}`
+    ];
+    if (ignoredProviders.length > 0) {
+      evidence.push(`Providers with weak/indirect location handling: ${compactList(ignoredProviders)}`);
+    }
+    actions.push({
+      audience: "agency",
+      priority: 70,
+      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.",
+      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.",
+      confidence: "high"
+    });
+  }
+  if (actions.length === 0) {
+    actions.push({
+      audience: "both",
+      priority: 90,
+      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.",
+      why: [
+        "No urgent corrective action surfaced from the current evidence.",
+        "AEO performance is directional; repeated sweeps 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.",
+      confidence: "medium"
+    });
+  }
+  return actions.sort((a, b) => a.priority - b.priority).slice(0, 10);
+}
+function trendSentence(trend) {
+  switch (trend) {
+    case "up":
+      return "Citation coverage improved versus the prior comparable sweep.";
+    case "down":
+      return "Citation coverage declined versus the prior comparable sweep.";
+    case "flat":
+      return "Citation coverage is flat versus the prior comparable sweep.";
+    case "unknown":
+      return "There is not enough comparable run history yet to call a 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 confidenceNotes = [];
+  if (s.totalQueryCount === 0) {
+    confidenceNotes.push("Confidence is low until the first tracked query sweep 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.`);
+  }
+  if (!reportLike.gsc) {
+    confidenceNotes.push("Search Console is not connected, so content recommendations lean more heavily on citation and competitor evidence.");
+  }
+  if (reportLike.reportLocation) {
+    confidenceNotes.push(`This summary is scoped to the ${reportLike.reportLocation.label} run location.`);
+  }
+  return {
+    headline,
+    overview,
+    actionItems: reportLike.actionPlan.filter((a) => actionAudienceMatches2(a, "client")).slice(0, 3),
+    confidenceNotes
+  };
+}
+function buildAgencyDiagnostics(input) {
+  const diagnostics = [];
+  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.",
+    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.",
+    severity: input.aiSourceOrigin.topDomains.length > 0 ? "neutral" : "caution",
+    evidence: input.aiSourceOrigin.topDomains.slice(0, 5).map((d) => `${d.domain}: ${d.count}`)
+  });
+  if (input.gsc) {
+    diagnostics.push({
+      title: "GSC query mismatch",
+      detail: input.gsc.trackedButNoGsc.length > 0 || input.gsc.gscButNotTracked.length > 0 ? "The tracked AEO query set and real search demand are not fully aligned." : "Tracked AEO queries and high-impression non-brand GSC queries are aligned for the current window.",
+      severity: input.gsc.trackedButNoGsc.length > 0 || input.gsc.gscButNotTracked.length > 0 ? "caution" : "positive",
+      evidence: [
+        ...input.gsc.trackedButNoGsc.length > 0 ? [`Tracked with no GSC demand: ${compactList(input.gsc.trackedButNoGsc)}`] : [],
+        ...input.gsc.gscButNotTracked.length > 0 ? [`GSC queries not tracked in AEO: ${compactList(input.gsc.gscButNotTracked)}`] : []
+      ]
+    });
+  }
+  if (input.indexingHealth) {
+    diagnostics.push({
+      title: "Indexing health",
+      detail: `${input.indexingHealth.indexedPct}% of inspected URLs are indexed in ${input.indexingHealth.provider ?? "the connected provider"}.`,
+      severity: input.indexingHealth.indexedPct >= 90 ? "positive" : input.indexingHealth.indexedPct >= 70 ? "caution" : "negative",
+      evidence: [
+        `${input.indexingHealth.indexed}/${input.indexingHealth.total} indexed`,
+        `${input.indexingHealth.notIndexed} not indexed`
+      ]
+    });
+  }
+  diagnostics.push({
+    title: "Content opportunity pipeline",
+    detail: input.contentOpportunities.length > 0 ? `${input.contentOpportunities.length} ranked content opportunit${input.contentOpportunities.length === 1 ? "y" : "ies"} and ${input.contentGaps.length} content gap${input.contentGaps.length === 1 ? "" : "s"} are available.` : "No ranked content opportunities are available from the current evidence.",
+    severity: input.contentOpportunities.length > 0 ? "caution" : "neutral",
+    evidence: input.contentOpportunities.slice(0, 3).map((o) => `${o.query}: ${o.action} (${Math.round(o.score)})`)
+  });
+  return {
+    priorities: input.actionPlan.filter((a) => actionAudienceMatches2(a, "agency")).slice(0, 6),
+    diagnostics
+  };
+}
 function buildProjectReport(db, projectName) {
   const project = resolveProject(db, projectName);
   const queryLookup = loadQueryLookup(db, project.id);
@@ -4299,6 +5383,7 @@ function buildProjectReport(db, projectName) {
     (r) => r.status === RunStatuses.completed || r.status === RunStatuses.partial
   ) ?? visibilityRuns[0];
   const latestSnapshots = latestRun ? loadSnapshotsForRun(db, latestRun.id) : [];
+  const latestRunLocation = latestRun?.location ?? null;
   const competitorRows = db.select().from(competitors).where(eq13(competitors.projectId, project.id)).all();
   const competitorDomains = competitorRows.map((c) => c.domain);
   const ownedDomains = parseJsonColumn(project.ownedDomains, []);
@@ -4330,9 +5415,9 @@ function buildProjectReport(db, projectName) {
   const socialSection = buildSocialReferrals(db, project.id);
   const aiReferralsSection = buildAiReferrals(db, project.id);
   const indexingHealthSection = buildIndexingHealth(db, project.id);
-  const citationsTrend = buildCitationsTrend(db, project.id, queryLookup);
-  const insightList = buildInsightList(db, project.id);
-  const orchestratorInput = loadOrchestratorInput(db, project);
+  const citationsTrend = buildCitationsTrend(db, project.id, queryLookup, latestRunLocation);
+  const insightList = buildInsightList(db, project.id, latestRunLocation);
+  const orchestratorInput = loadOrchestratorInput(db, project, latestRunLocation);
   const contentOpportunities = buildContentTargetRows(orchestratorInput);
   const contentGaps = buildContentGapRows(orchestratorInput);
   const groundingSources = buildContentSourceRows(orchestratorInput);
@@ -4341,14 +5426,18 @@ function buildProjectReport(db, projectName) {
     contentOpportunities,
     insightDerivedSteps
   );
-  let latestCited = 0;
-  let latestConsidered = 0;
+  const totalQueryCount = queryLookup.byId.size;
+  const citedQueryIds = /* @__PURE__ */ new Set();
+  const mentionedQueryIds = /* @__PURE__ */ new Set();
   for (const snap of latestSnapshots) {
     if (!queryLookup.byId.has(snap.queryId)) continue;
-    latestConsidered++;
-    if (snap.citationState === CitationStates.cited) latestCited++;
+    if (snap.citationState === CitationStates.cited) citedQueryIds.add(snap.queryId);
+    if (snap.answerMentioned) mentionedQueryIds.add(snap.queryId);
   }
-  const citationRate = latestConsidered > 0 ? Math.round(latestCited / latestConsidered * 100) : 0;
+  const citedQueryCount = citedQueryIds.size;
+  const mentionedQueryCount = mentionedQueryIds.size;
+  const citationRate = totalQueryCount > 0 ? Math.round(citedQueryCount / totalQueryCount * 100) : 0;
+  const mentionRate = totalQueryCount > 0 ? Math.round(mentionedQueryCount / totalQueryCount * 100) : 0;
   const trendBaseline = isTrendBaseline(citationsTrend);
   const latestPoint = citationsTrend.at(-1);
   const previousPoint = citationsTrend.length >= 2 ? citationsTrend.at(-2) : null;
@@ -4365,6 +5454,8 @@ function buildProjectReport(db, projectName) {
   }
   const findings = buildExecutiveFindings(
     citationRate,
+    citedQueryCount,
+    totalQueryCount,
     trend,
     citationsTrend,
     trendBaseline,
@@ -4373,6 +5464,68 @@ function buildProjectReport(db, projectName) {
   );
   const periodStart = citationsTrend[0]?.date ?? null;
   const periodEnd = citationsTrend.at(-1)?.date ?? null;
+  const configuredLocations = parseJsonColumn(project.locations, []);
+  const reportLocation = buildLocationMeta(latestRun?.location ?? null, configuredLocations);
+  const providerLocationHandling = reportLocation ? buildProviderLocationHandling(citationScorecard.providers) : [];
+  const executiveSummary = {
+    citationRate,
+    citedQueryCount,
+    totalQueryCount,
+    mentionRate,
+    mentionedQueryCount,
+    trend,
+    queryCount: queryLookup.byId.size,
+    competitorCount: competitorDomains.length,
+    providerCount: citationScorecard.providers.length,
+    gsc: gscSection ? {
+      clicks: gscSection.totalClicks,
+      impressions: gscSection.totalImpressions,
+      ctr: gscSection.ctr,
+      avgPosition: gscSection.avgPosition,
+      periodStart: gscSection.periodStart,
+      periodEnd: gscSection.periodEnd
+    } : null,
+    ga: gaSection ? {
+      sessions: gaSection.totalSessions,
+      users: gaSection.totalUsers,
+      periodStart: gaSection.periodStart,
+      periodEnd: gaSection.periodEnd
+    } : null,
+    findings
+  };
+  const actionPlan = buildReportActionPlan({
+    canonicalDomain: project.canonicalDomain,
+    competitorDomains,
+    citationScorecard,
+    aiSourceOrigin,
+    gsc: gscSection,
+    indexingHealth: indexingHealthSection,
+    contentOpportunities,
+    contentGaps,
+    reportLocation,
+    providerLocationHandling
+  });
+  const clientSummary = buildClientSummary({
+    canonicalDomain: project.canonicalDomain,
+    reportLocation,
+    executiveSummary,
+    citationsTrend,
+    gsc: gscSection,
+    actionPlan
+  });
+  const agencyDiagnostics = buildAgencyDiagnostics({
+    canonicalDomain: project.canonicalDomain,
+    competitorDomains,
+    citationScorecard,
+    aiSourceOrigin,
+    gsc: gscSection,
+    indexingHealth: indexingHealthSection,
+    contentOpportunities,
+    contentGaps,
+    reportLocation,
+    providerLocationHandling,
+    actionPlan
+  });
   return {
     meta: {
       generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -4384,29 +5537,12 @@ function buildProjectReport(db, projectName) {
         country: project.country,
         language: project.language
       },
+      location: reportLocation,
+      providerLocationHandling,
       periodStart,
       periodEnd
     },
-    executiveSummary: {
-      citationRate,
-      trend,
-      queryCount: queryLookup.byId.size,
-      competitorCount: competitorDomains.length,
-      providerCount: citationScorecard.providers.length,
-      gsc: gscSection ? {
-        clicks: gscSection.totalClicks,
-        impressions: gscSection.totalImpressions,
-        ctr: gscSection.ctr,
-        avgPosition: gscSection.avgPosition
-      } : null,
-      ga: gaSection ? {
-        sessions: gaSection.totalSessions,
-        users: gaSection.totalUsers,
-        periodStart: gaSection.periodStart,
-        periodEnd: gaSection.periodEnd
-      } : null,
-      findings
-    },
+    executiveSummary,
     citationScorecard,
     competitorLandscape,
     mentionLandscape,
@@ -4419,14 +5555,22 @@ function buildProjectReport(db, projectName) {
     citationsTrend,
     insights: insightList,
     recommendedNextSteps,
+    actionPlan,
+    clientSummary,
+    agencyDiagnostics,
     contentOpportunities,
     contentGaps,
     groundingSources
   };
 }
-function reportFilenameFor(project, generatedAt) {
+function parseReportAudience(value) {
+  if (value === void 0 || value === "agency") return "agency";
+  if (value === "client") return "client";
+  throw validationError('"audience" must be "agency" or "client"');
+}
+function reportFilenameFor(project, generatedAt, audience) {
   const date = generatedAt.slice(0, 10);
-  return `canonry-report-${project.name}-${date}.html`;
+  return `canonry-report-${project.name}-${audience}-${date}.html`;
 }
 async function reportRoutes(app) {
   app.get("/projects/:name/report", async (request, reply) => {
@@ -4434,9 +5578,10 @@ async function reportRoutes(app) {
     return reply.send(dto);
   });
   app.get("/projects/:name/report.html", async (request, reply) => {
+    const audience = parseReportAudience(request.query.audience);
     const dto = buildProjectReport(app.db, request.params.name);
-    const html = renderReportHtml(dto);
-    const filename = reportFilenameFor(dto.meta.project, dto.meta.generatedAt);
+    const html = renderReportHtml(dto, { audience });
+    const filename = reportFilenameFor(dto.meta.project, dto.meta.generatedAt, audience);
     reply.header("Content-Type", "text/html; charset=utf-8");
     reply.header("Content-Disposition", `attachment; filename="${filename}"`);
     return reply.send(html);
@@ -5294,6 +6439,12 @@ var locationQueryParameter = {
   description: "Filter by location label. Use an empty value to request locationless results.",
   schema: stringSchema
 };
+var reportAudienceQueryParameter = {
+  name: "audience",
+  in: "query",
+  description: "HTML report audience mode. Defaults to agency.",
+  schema: { type: "string", enum: ["agency", "client"] }
+};
 var analyticsWindowParameter = {
   name: "window",
   in: "query",
@@ -7514,9 +8665,9 @@ var routeCatalog = [
   {
     method: "get",
     path: "/api/v1/projects/{name}/report",
-    summary: "Aggregated client-facing AEO report",
+    summary: "Aggregated canonical AEO report",
     tags: ["report"],
-    description: "Bundles every section the canonry-report HTML output needs (executive summary, citation scorecard, competitor landscape \u2014 citation + mention landscapes, AI citation sources, GSC, GA4, social/AI referrals, indexing health, citations trend, insights, and recommended next steps) into a single JSON payload. Backs `canonry report <project>`.",
+    description: "Bundles every section the canonry-report HTML output needs (executive summary, client summary, agency diagnostics, action plan, citation scorecard, competitor landscape \u2014 citation + mention landscapes, AI citation sources, GSC, GA4, social/AI referrals, indexing health, citations trend, insights, and recommended next steps) into a single canonical JSON payload. Backs `canonry report <project>` and MCP report reads.",
     parameters: [nameParameter],
     responses: {
       200: { description: "Report returned." },
@@ -7528,8 +8679,8 @@ var routeCatalog = [
     path: "/api/v1/projects/{name}/report.html",
     summary: "Standalone HTML AEO report",
     tags: ["report"],
-    description: "Server-rendered self-contained HTML version of the project report. Same data as `/projects/{name}/report` (JSON), rendered through the canonry HTML report renderer. Returns `text/html` with `Content-Disposition: attachment` so browsers download it as `canonry-report-<project>-YYYY-MM-DD.html`. Open in a browser and Print \u2192 Save as PDF for a PDF copy.",
-    parameters: [nameParameter],
+    description: "Server-rendered self-contained HTML version of the project report. Same data as `/projects/{name}/report` (JSON), rendered through the canonry HTML report renderer in agency or client mode. Returns `text/html` with `Content-Disposition: attachment` so browsers download it as `canonry-report-<project>-<audience>-YYYY-MM-DD.html`. Open in a browser and Print \u2192 Save as PDF for a PDF copy.",
+    parameters: [nameParameter, reportAudienceQueryParameter],
     responses: {
       200: { description: "HTML report returned." },
       404: { description: "Project not found." }