@ainyc/canonry 4.2.2 → 4.7.2

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

@@ -4,7 +4,7 @@ import {
   configExists,
   loadConfig,
   saveConfigPatch
-} from "./chunk-SR7TGHHG.js";
+} from "./chunk-VDEMEI64.js";
 import {
   DEFAULT_RUN_HISTORY_LIMIT,
   IntelligenceService,
@@ -61,7 +61,7 @@ import {
   runs,
   schedules,
   usageCounters
-} from "./chunk-7YSI4GFA.js";
+} from "./chunk-OOADR2Q5.js";
 import {
   AGENT_MEMORY_VALUE_MAX_BYTES,
   AGENT_PROVIDER_IDS,
@@ -95,6 +95,7 @@ import {
   emptyCitationVisibility,
   extractAnswerMentions,
   findDuplicateLocationLabels,
+  getProviderLocationHandling,
   hasLocationLabel,
   internalError,
   isAgentProviderId,
@@ -113,6 +114,7 @@ import {
   providerError,
   queryGenerateRequestSchema,
   registrableDomain,
+  reportActionTone,
   resolveConfigSpecQueries,
   resolveSnapshotRequestQueries,
   runInProgress,
@@ -127,7 +129,7 @@ import {
   visibilityStateFromAnswerMentioned,
   windowCutoff,
   wordpressEnvSchema
-} from "./chunk-T2I6AO7D.js";
+} from "./chunk-XAW66QUX.js";
 
 // src/telemetry.ts
 import crypto from "crypto";
@@ -2746,6 +2748,21 @@ 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; }
+.location-card { margin-top: 16px; }
+.location-card .location-line { margin: 0 0 12px; font-size: 13px; color: ${COLORS.text}; }
+.location-card .location-line strong { color: ${COLORS.text}; }
+.location-card .location-line .cell-pending { font-size: 12px; }
+.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;
@@ -2866,6 +2883,77 @@ table.report-table td .badge {
 }
 .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 20px;
+}
+.action-card .action-meta {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-bottom: 10px;
+}
+.action-card h3 {
+  font-size: 16px;
+  margin: 0 0 8px;
+}
+.action-card p {
+  margin: 0 0 12px;
+  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; }
+.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.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}; }
 .footer {
   margin-top: 96px;
   padding-top: 24px;
@@ -2890,15 +2978,68 @@ 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 location set";
+  return ` \xB7 Location: ${escapeHtml(locationDisplay(location))}`;
+}
+function renderLocationCard(report) {
+  const location = report.meta.location;
+  const handling = report.meta.providerLocationHandling;
+  if (!location && handling.length === 0) return "";
+  const treatmentTone = {
+    "request-param": "positive",
+    prompt: "positive",
+    "browser-geo": "caution",
+    ignored: "negative"
+  };
+  const treatmentLabel = {
+    "request-param": "Request parameter",
+    prompt: "Prompt-injected",
+    "browser-geo": "Browser geo",
+    ignored: "Ignored"
+  };
+  const locationLine = location ? `<p class="location-line"><strong>Location for this run:</strong> ${escapeHtml(locationDisplay(location))}${location.otherConfiguredLabels.length > 0 ? ` <span class="cell-pending">\u2014 other configured locations (${location.otherConfiguredLabels.map(escapeHtml).join(", ")}) need their own sweep to compare</span>` : ""}</p>` : `<p class="location-line"><strong>Location for this run:</strong> none \u2014 providers received the queries verbatim with no geographic hint.</p>`;
+  const handlingRows = handling.length > 0 ? handling.map((h) => {
+    const tone = treatmentTone[h.treatment] ?? "neutral";
+    const label = treatmentLabel[h.treatment] ?? h.treatment;
+    return `<tr>
+          <td>${escapeHtml(h.provider)}</td>
+          <td><span class="badge tone-${tone}">${escapeHtml(label)}</span></td>
+          <td>${escapeHtml(h.description)}</td>
+        </tr>`;
+  }).join("") : "";
+  const handlingTable = handlingRows ? `<table class="report-table">
+        <thead><tr><th>Provider</th><th>Treatment</th><th>How the location reached the model</th></tr></thead>
+        <tbody>${handlingRows}</tbody>
+      </table>` : "";
+  return `<div class="chart-card location-card">
+    <h3>Location handling</h3>
+    ${locationLine}
+    ${handlingTable}
+  </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 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",
@@ -2932,14 +3073,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: "Two independent signals: Citation rate = share of tracked queries where your domain appeared in the source list the AI used. Mention rate = share of tracked queries where your brand or domain appeared in the answer text itself. A model can mention you without citing your domain, or cite your domain without naming you in the prose. Both are computed per-query so they stay comparable when provider count changes."
     },
-    metricsHtml + findingsHtml
+    metricsHtml + findingsHtml + locationHtml
   );
 }
 function renderProviderBars(rates) {
@@ -2977,16 +3119,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;">Each cell shows two flags \u2014 <span class="cell-cited">C</span>/<span class="cell-not-cited">c</span> = cited / not cited (your domain in the source list), <span class="cell-cited">M</span>/<span class="cell-not-cited">m</span> = mentioned / not mentioned (your brand in the answer text), <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 +3139,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: "Per (query \xD7 provider) view of both signals \u2014 citations (your domain in the source list) and mentions (your brand in the answer text) \u2014 for every tracked query in the latest sweep." },
     body
   );
 }
@@ -3084,44 +3226,40 @@ function renderCompetitorLandscape(report) {
     `${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 renderAiSourceOrigin(report) {
@@ -3132,24 +3270,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: "Every external website AI engines cited as a source for your tracked queries in the latest sweep, ranked by citation count. Tracked competitors are pulled into their own bucket so you can see how much of the AI\u2019s answer came from rivals; the remaining buckets cover directories, forums, news, and other site types. Your own domains are excluded."
     },
-    `${renderDonut(origin.categories)}${table}`
+    `${headlineFragment}${table}${renderCategoryBars(origin.categories)}`
   );
 }
 function renderLineChart(points, color, title, height = 200) {
@@ -3442,15 +3584,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 rate across every visibility sweep \u2014 the share of tracked queries cited by at least one provider, with a per-provider breakdown beneath. Computed per-query so the headline stays comparable across runs that ran a different mix of providers." },
     `${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>`
@@ -3489,15 +3631,16 @@ function renderOpportunities(report) {
   if (opps.length === 0) return "";
   const canonical = report.meta.project.canonicalDomain;
   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>${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>
     </tr>`;
   }).join("");
@@ -3506,10 +3649,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 you have search demand or competitor citation pressure but aren\u2019t winning AI citations. Each row pairs a suggested action (create / refresh / expand / add-schema) with the signals driving the score, the best matching page on your domain, and the competitor URL the AI most often cites. Top 10 shown."
     },
     `<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>Action</th><th class="numeric">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 multiple competitors are cited by AI engines but you are not \u2014 explicit "they are answering, you are missing" signal. Sorted by recent miss rate, then by number of competitors cited. Top 10 shown.'
+    },
+    `<table class="report-table">
+      <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 +3687,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 horizon (immediate, short-term, medium-term), drawn from open insights and the highest-ranked content opportunities." },
       renderEmpty("No outstanding actions.")
     );
   }
@@ -3529,17 +3698,144 @@ 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 horizon (immediate, short-term, medium-term), drawn from open insights and the highest-ranked content opportunities." },
     `<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) => {
+    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>` : "";
+    return `<article class="action-card">
+        <div class="action-meta">
+          <span class="badge tone-${tone}">${escapeHtml(action.horizon)}</span>
+          <span class="badge tone-neutral">${escapeHtml(action.category)}</span>
+          <span class="badge tone-neutral">${escapeHtml(action.confidence)} confidence</span>
+        </div>
+        <h3>${escapeHtml(action.title)}</h3>
+        <p>${escapeHtml(action.action)}</p>
+        ${why ? `<div><strong>Why</strong>${why}</div>` : ""}
+        ${evidence ? `<div><strong>Evidence</strong>${evidence}</div>` : ""}
+        <div class="success-metric"><strong>Success metric:</strong> ${escapeHtml(action.successMetric)}</div>
+      </article>`;
+  }).join("")}
+  </div>`;
+}
+function renderAudienceActionPlan(report, audience) {
+  const actions = audience === "client" ? report.clientSummary.actionItems : report.agencyDiagnostics.priorities.length > 0 ? report.agencyDiagnostics.priorities : report.actionPlan.filter((a) => actionAudienceMatches(a, audience));
+  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" ? "Polished next steps the client can understand, backed by concise evidence from the report." : "Technical priorities pulled from the canonical action plan, 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>`);
+  }
+  if (report.contentOpportunities.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>${report.contentOpportunities.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;
+  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>
+          ${d.evidence.length > 0 ? `<ul>${d.evidence.map((e) => `<li>${escapeHtml(e)}</li>`).join("")}</ul>` : ""}
+        </div>`).join("")}
+      </div>` : renderEmpty("No agency diagnostics available yet.");
+  return section(
+    {
+      id: "agency-diagnostics",
+      eyebrow: "Agency diagnostics",
+      title: "Technical Diagnostics",
+      intro: "Operator-facing diagnostics for content, provider, source-domain, search-demand, indexing, and location follow-up."
+    },
+    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 +3847,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 +3862,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 +3877,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 +3886,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({
@@ -3631,8 +3928,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 +3938,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();
@@ -4129,27 +4427,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 +4462,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 +4551,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 +4574,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 +4600,328 @@ 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)})`)
+  });
+  if (input.reportLocation) {
+    diagnostics.push({
+      title: "Location caveat",
+      detail: input.reportLocation.otherConfiguredLabels.length > 0 ? "This report is scoped to the latest run location; other configured locations need separate interpretation." : "This report is scoped to one configured location.",
+      severity: input.reportLocation.otherConfiguredLabels.length > 0 ? "caution" : "neutral",
+      evidence: [
+        `Current location: ${input.reportLocation.label}`,
+        ...input.reportLocation.otherConfiguredLabels.length > 0 ? [`Other configured locations: ${compactList(input.reportLocation.otherConfiguredLabels)}`] : []
+      ]
+    });
+  }
+  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 +4931,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 +4963,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 +4974,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 +5002,8 @@ function buildProjectReport(db, projectName) {
   }
   const findings = buildExecutiveFindings(
     citationRate,
+    citedQueryCount,
+    totalQueryCount,
     trend,
     citationsTrend,
     trendBaseline,
@@ -4373,6 +5012,66 @@ 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
+    } : 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 +5083,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 +5101,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 +5124,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 +5985,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 +8211,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 +8225,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." }