aeo-ready 1.0.0

package/src/checks/ai-visibility/structured-data.js

@@ -0,0 +1,180 @@
+export async function runStructuredDataChecks(context) {
+  const checks = [
+    checkSchemaOrg(context),
+    checkFaqMarkup(context),
+    checkRichSchemas(context),
+    checkOpenGraph(context),
+  ];
+
+  const score = checks.reduce((sum, c) => sum + (c.passed ? c.points : 0), 0);
+  return { score, maxScore: 12, checks };
+}
+
+function checkSchemaOrg(context) {
+  const allContent = getAllContent(context);
+  const html = context.html || "";
+
+  const jsonLdBlocks = extractJsonLd(html);
+  if (jsonLdBlocks.length === 0 && !allContent.includes("schema.org")) {
+    return fail(
+      "Schema.org markup",
+      4,
+      "No schema.org structured data found. Add JSON-LD with appropriate type (SoftwareApplication, Person, Article, Organization).",
+    );
+  }
+
+  let points = 2;
+  const types = jsonLdBlocks.map((b) => b["@type"]).filter(Boolean);
+  const hasCorrectType = hasAppropriateType(types, context.siteType);
+  if (hasCorrectType) points += 1;
+  const hasRequiredFields = jsonLdBlocks.some((b) => hasMinimumFields(b));
+  if (hasRequiredFields) points += 1;
+
+  if (points === 4) return pass("Schema.org markup", 4);
+  const issues = [];
+  if (!hasCorrectType) issues.push("type doesn't match site category");
+  if (!hasRequiredFields) issues.push("missing required fields");
+  return partial(
+    "Schema.org markup",
+    points,
+    4,
+    `Schema.org present but: ${issues.join(", ")}.`,
+  );
+}
+
+function checkFaqMarkup(context) {
+  const html = context.html || "";
+  const allContent = getAllContent(context);
+
+  const hasFaqSchema =
+    allContent.includes("FAQPage") || allContent.includes("Question");
+  const hasFaqContent = /faq|frequently asked|common questions/i.test(
+    allContent,
+  );
+
+  if (hasFaqSchema) return pass("FAQ markup", 3);
+  if (hasFaqContent) {
+    return partial(
+      "FAQ markup",
+      1,
+      3,
+      "FAQ content exists but not marked up with FAQPage schema. Add JSON-LD FAQPage.",
+    );
+  }
+  return fail(
+    "FAQ markup",
+    3,
+    "No FAQ markup. Add FAQPage schema for common questions — these surface directly in AI answers.",
+  );
+}
+
+function checkRichSchemas(context) {
+  const allContent = getAllContent(context);
+
+  const schemas = [];
+  if (allContent.includes("BreadcrumbList")) schemas.push("Breadcrumb");
+  if (allContent.includes("HowTo")) schemas.push("HowTo");
+  if (
+    allContent.includes("Product") ||
+    allContent.includes("SoftwareApplication")
+  )
+    schemas.push("Product");
+  if (allContent.includes("VideoObject")) schemas.push("Video");
+  if (allContent.includes("Review") || allContent.includes("AggregateRating"))
+    schemas.push("Review");
+
+  if (schemas.length >= 2)
+    return pass("Rich schemas (Breadcrumb/HowTo/Product)", 3);
+  if (schemas.length === 1)
+    return partial(
+      "Rich schemas (Breadcrumb/HowTo/Product)",
+      2,
+      3,
+      `Only ${schemas[0]} schema found. Add more rich schemas for better AI comprehension.`,
+    );
+  return fail(
+    "Rich schemas (Breadcrumb/HowTo/Product)",
+    3,
+    "No rich schemas (BreadcrumbList, HowTo, Product). These help AI understand page context and relationships.",
+  );
+}
+
+function checkOpenGraph(context) {
+  const html = context.html || "";
+
+  const hasOgTitle = /og:title/i.test(html);
+  const hasOgDesc = /og:description/i.test(html);
+  const hasMetaDesc = /name=["']description["']/i.test(html);
+
+  let points = 0;
+  if (hasOgTitle) points += 1;
+  if (hasOgDesc || hasMetaDesc) points += 1;
+
+  if (points === 2) return pass("Open Graph + meta description", 2);
+  if (points === 1)
+    return partial(
+      "Open Graph + meta description",
+      1,
+      2,
+      "Partial OG/meta tags. Need both og:title and description.",
+    );
+  return fail(
+    "Open Graph + meta description",
+    2,
+    "No Open Graph or meta description tags. AI systems use these for page summaries.",
+  );
+}
+
+function extractJsonLd(html) {
+  const blocks = [];
+  const regex =
+    /<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+  let match;
+  while ((match = regex.exec(html)) !== null) {
+    try {
+      const parsed = JSON.parse(match[1]);
+      if (Array.isArray(parsed)) blocks.push(...parsed);
+      else blocks.push(parsed);
+    } catch {
+      /* skip invalid */
+    }
+  }
+  return blocks;
+}
+
+function hasAppropriateType(types, siteType) {
+  const typeMap = {
+    saas: ["SoftwareApplication", "WebApplication", "Product", "Organization"],
+    api: ["SoftwareApplication", "WebAPI", "TechArticle"],
+    content: ["Article", "BlogPosting", "WebSite", "Organization"],
+    personal: ["Person", "ProfilePage", "WebSite"],
+  };
+  const expected = typeMap[siteType] || [];
+  return types.some((t) => expected.includes(t));
+}
+
+function hasMinimumFields(block) {
+  const required = ["name", "@type"];
+  return required.every((f) => block[f]);
+}
+
+function getAllContent(context) {
+  if (context.mode === "url") {
+    return Object.values(context.pages || {})
+      .map((p) => p?.text || "")
+      .join("\n");
+  }
+  return Object.values(context.fileContents || {}).join("\n");
+}
+
+function pass(name, points) {
+  return { name, passed: true, points, maxPoints: points };
+}
+
+function partial(name, points, maxPoints, fix) {
+  return { name, passed: false, points, maxPoints, fix };
+}
+
+function fail(name, maxPoints, fix) {
+  return { name, passed: false, points: 0, maxPoints, fix };
+}

package/src/dashboard/generate.js

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { getHistory } from "../history/index.js";
+import { renderOverallScore } from "./sections/overall-score.js";
+import { renderAgentReadiness } from "./sections/agent-readiness.js";
+import { renderAiVisibility } from "./sections/ai-visibility.js";
+import { renderHistoryTable } from "./sections/history-table.js";
+import { renderTrendChart } from "./sections/trend-chart.js";
+import { renderRecommendations } from "./sections/recommendations.js";
+
+const DASHBOARD_DIR = ".aeo-ready";
+const DASHBOARD_FILE = "dashboard.html";
+
+export async function generateDashboard(scanResult, dir, opts = {}) {
+  const dashDir = join(dir, DASHBOARD_DIR);
+  if (!existsSync(dashDir)) mkdirSync(dashDir, { recursive: true });
+
+  const dashPath = join(dashDir, DASHBOARD_FILE);
+  const history = getHistory(dir);
+
+  const sections = {
+    "overall-score": renderOverallScore(scanResult, opts.beforeResult || null),
+    "agent-readiness-scorecard": renderAgentReadiness(scanResult),
+    "ai-visibility-scorecard": renderAiVisibility(scanResult),
+    "history-table": renderHistoryTable(history),
+    "trend-chart": renderTrendChart(history),
+    recommendations: renderRecommendations(scanResult),
+  };
+
+  let html;
+  if (existsSync(dashPath)) {
+    html = readFileSync(dashPath, "utf8");
+    for (const [name, content] of Object.entries(sections)) {
+      html = replaceSection(html, name, content);
+    }
+  } else {
+    html = buildFullDashboard(sections, scanResult);
+  }
+
+  writeFileSync(dashPath, html);
+  return dashPath;
+}
+
+function replaceSection(html, name, content) {
+  const regex = new RegExp(
+    `(<!-- SECTION:${name} -->)[\\s\\S]*?(<!-- /SECTION:${name} -->)`,
+    "g",
+  );
+  if (regex.test(html)) {
+    return html.replace(regex, `$1\n${content}\n$2`);
+  }
+  return html;
+}
+
+function buildFullDashboard(sections, scanResult) {
+  const timestamp = new Date().toISOString().slice(0, 10);
+  const target = scanResult.target || "Local";
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>aeo-ready — AI Readiness Dashboard</title>
+<style>
+${CSS}
+</style>
+</head>
+<body>
+
+<nav>
+  <h2>aeo-ready</h2>
+  <a href="#overall" class="section-head">Overall Score</a>
+  <a href="#agent-readiness" class="section-head">Agent Readiness</a>
+  <a href="#ai-visibility" class="section-head">AI Visibility</a>
+  <a href="#trends" class="section-head">Trends</a>
+  <a href="#history" class="section-head">History</a>
+  <a href="#recommendations" class="section-head">Recommendations</a>
+</nav>
+
+<main>
+
+<h1>AI Readiness Dashboard</h1>
+<p class="subtitle">${target} · Updated ${timestamp}</p>
+
+<!-- SECTION:overall-score -->
+${sections["overall-score"]}
+<!-- /SECTION:overall-score -->
+
+<!-- SECTION:agent-readiness-scorecard -->
+${sections["agent-readiness-scorecard"]}
+<!-- /SECTION:agent-readiness-scorecard -->
+
+<!-- SECTION:ai-visibility-scorecard -->
+${sections["ai-visibility-scorecard"]}
+<!-- /SECTION:ai-visibility-scorecard -->
+
+<!-- SECTION:trend-chart -->
+${sections["trend-chart"]}
+<!-- /SECTION:trend-chart -->
+
+<!-- SECTION:history-table -->
+${sections["history-table"]}
+<!-- /SECTION:history-table -->
+
+<!-- SECTION:recommendations -->
+${sections["recommendations"]}
+<!-- /SECTION:recommendations -->
+
+</main>
+</body>
+</html>`;
+}
+
+const CSS = `* { box-sizing: border-box; margin: 0; padding: 0; }
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: #0d1117; color: #c9d1d9; display: flex; }
+nav { position: fixed; top: 0; left: 0; width: 200px; height: 100vh; background: #010409; border-right: 1px solid #21262d; padding: 0; overflow-y: auto; z-index: 10; }
+nav h2 { color: #f0f6fc; font-size: 13px; letter-spacing: 0.02em; padding: 20px 16px 14px; border-bottom: 1px solid #21262d; margin: 0 0 8px; }
+nav a { display: block; padding: 6px 16px; font-size: 12px; color: #8b949e; text-decoration: none; transition: color 0.15s; }
+nav a:hover { color: #f0f6fc; }
+nav a.section-head { color: #c9d1d9; font-weight: 600; font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; margin-top: 12px; }
+main { margin-left: 200px; padding: 32px 40px; max-width: 900px; width: 100%; }
+h1 { color: #f0f6fc; font-size: 24px; margin-bottom: 4px; }
+.subtitle { color: #8b949e; font-size: 13px; margin-bottom: 32px; }
+h2 { color: #f0f6fc; font-size: 18px; margin-top: 40px; margin-bottom: 16px; padding-top: 16px; border-top: 1px solid #21262d; }
+h3 { color: #f0f6fc; font-size: 14px; margin-top: 16px; margin-bottom: 8px; }
+.score-hero { text-align: center; padding: 32px 0; }
+.score-hero .grade { font-size: 64px; font-weight: 700; }
+.score-hero .number { font-size: 24px; color: #8b949e; margin-top: 4px; }
+.score-hero .bar { margin: 16px auto; width: 300px; height: 8px; background: #21262d; border-radius: 4px; overflow: hidden; }
+.score-hero .bar-fill { height: 100%; border-radius: 4px; }
+.grade-a { color: #3fb950; } .grade-b { color: #79c0ff; } .grade-c { color: #d29922; } .grade-d { color: #f85149; } .grade-f { color: #f85149; }
+.bar-a { background: #3fb950; } .bar-b { background: #79c0ff; } .bar-c { background: #d29922; } .bar-d { background: #f85149; } .bar-f { background: #f85149; }
+.scorecard { background: #161b22; border: 1px solid #21262d; border-radius: 8px; padding: 20px; margin: 16px 0; }
+.scorecard-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 16px; }
+.scorecard-header h3 { margin: 0; }
+.scorecard-header .pct { font-size: 20px; font-weight: 600; }
+.category { margin: 12px 0; padding: 8px 0; border-bottom: 1px solid #21262d; }
+.category:last-child { border-bottom: none; }
+.cat-header { display: flex; align-items: center; gap: 8px; margin-bottom: 6px; }
+.cat-name { font-size: 13px; font-weight: 500; flex: 1; }
+.cat-score { font-size: 12px; color: #8b949e; }
+.cat-bar { width: 120px; height: 4px; background: #21262d; border-radius: 2px; overflow: hidden; }
+.cat-bar-fill { height: 100%; border-radius: 2px; }
+.check { font-size: 12px; padding: 2px 0 2px 16px; color: #8b949e; }
+.check.pass { color: #3fb950; }
+.check.fail { color: #f85149; }
+.check .fix { display: block; color: #8b949e; font-size: 11px; padding-left: 16px; margin-top: 2px; }
+table { width: 100%; border-collapse: collapse; margin: 12px 0; }
+th, td { text-align: left; padding: 8px 12px; font-size: 12px; border-bottom: 1px solid #21262d; }
+th { color: #8b949e; font-weight: 600; }
+.trend { color: #3fb950; } .regression { color: #f85149; }
+.rec { background: #161b22; border: 1px solid #21262d; border-radius: 6px; padding: 12px 16px; margin: 8px 0; }
+.rec-title { font-size: 13px; font-weight: 500; color: #f0f6fc; }
+.rec-fix { font-size: 12px; color: #8b949e; margin-top: 4px; }
+.rec-impact { font-size: 11px; color: #d29922; margin-top: 4px; }
+svg { display: block; margin: 16px 0; }`;

package/src/dashboard/sections/agent-readiness.js

@@ -0,0 +1,71 @@
+export function renderAgentReadiness(result) {
+  return renderScorecard(
+    "Agent Readiness",
+    result.agentReadiness,
+    "agent-readiness",
+  );
+}
+
+function renderScorecard(title, scorecard, id) {
+  const pct = Math.round((scorecard.score / scorecard.maxScore) * 100);
+  const gradeClass =
+    pct >= 80
+      ? "grade-a"
+      : pct >= 60
+        ? "grade-b"
+        : pct >= 40
+          ? "grade-c"
+          : "grade-d";
+
+  let html = `<div class="scorecard" id="${id}">
+  <div class="scorecard-header">
+    <h3>${title}</h3>
+    <span class="pct ${gradeClass}">${scorecard.score}/${scorecard.maxScore} (${pct}%)</span>
+  </div>`;
+
+  for (const [catName, cat] of Object.entries(scorecard.categories)) {
+    const label = formatName(catName);
+    const catPct = Math.round((cat.score / cat.maxScore) * 100);
+    const barColor =
+      catPct >= 80 ? "#3fb950" : catPct >= 50 ? "#d29922" : "#f85149";
+
+    html += `\n  <div class="category">
+    <div class="cat-header">
+      <span class="cat-name">${label}</span>
+      <span class="cat-score">${cat.score}/${cat.maxScore}</span>
+      <div class="cat-bar"><div class="cat-bar-fill" style="width:${catPct}%;background:${barColor}"></div></div>
+    </div>`;
+
+    for (const check of cat.checks) {
+      if (check.passed) {
+        html += `\n    <div class="check pass">+ ${check.name} [${check.points}]</div>`;
+      } else {
+        html += `\n    <div class="check fail">- ${check.name} [${check.points || 0}/${check.maxPoints}]`;
+        if (check.fix) {
+          html += `<span class="fix">${escapeHtml(check.fix)}</span>`;
+        }
+        html += `</div>`;
+      }
+    }
+
+    html += `\n  </div>`;
+  }
+
+  html += `\n</div>`;
+  return html;
+}
+
+function formatName(camelCase) {
+  return camelCase
+    .replace(/([A-Z])/g, " $1")
+    .replace(/^./, (c) => c.toUpperCase())
+    .trim();
+}
+
+function escapeHtml(str) {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/src/dashboard/sections/ai-visibility.js

@@ -0,0 +1,67 @@
+export function renderAiVisibility(result) {
+  return renderScorecard("AI Visibility", result.aiVisibility, "ai-visibility");
+}
+
+function renderScorecard(title, scorecard, id) {
+  const pct = Math.round((scorecard.score / scorecard.maxScore) * 100);
+  const gradeClass =
+    pct >= 80
+      ? "grade-a"
+      : pct >= 60
+        ? "grade-b"
+        : pct >= 40
+          ? "grade-c"
+          : "grade-d";
+
+  let html = `<div class="scorecard" id="${id}">
+  <div class="scorecard-header">
+    <h3>${title}</h3>
+    <span class="pct ${gradeClass}">${scorecard.score}/${scorecard.maxScore} (${pct}%)</span>
+  </div>`;
+
+  for (const [catName, cat] of Object.entries(scorecard.categories)) {
+    const label = formatName(catName);
+    const catPct = Math.round((cat.score / cat.maxScore) * 100);
+    const barColor =
+      catPct >= 80 ? "#3fb950" : catPct >= 50 ? "#d29922" : "#f85149";
+
+    html += `\n  <div class="category">
+    <div class="cat-header">
+      <span class="cat-name">${label}</span>
+      <span class="cat-score">${cat.score}/${cat.maxScore}</span>
+      <div class="cat-bar"><div class="cat-bar-fill" style="width:${catPct}%;background:${barColor}"></div></div>
+    </div>`;
+
+    for (const check of cat.checks) {
+      if (check.passed) {
+        html += `\n    <div class="check pass">+ ${check.name} [${check.points}]</div>`;
+      } else {
+        html += `\n    <div class="check fail">- ${check.name} [${check.points || 0}/${check.maxPoints}]`;
+        if (check.fix) {
+          html += `<span class="fix">${escapeHtml(check.fix)}</span>`;
+        }
+        html += `</div>`;
+      }
+    }
+
+    html += `\n  </div>`;
+  }
+
+  html += `\n</div>`;
+  return html;
+}
+
+function formatName(camelCase) {
+  return camelCase
+    .replace(/([A-Z])/g, " $1")
+    .replace(/^./, (c) => c.toUpperCase())
+    .trim();
+}
+
+function escapeHtml(str) {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/src/dashboard/sections/history-table.js

@@ -0,0 +1,36 @@
+export function renderHistoryTable(history) {
+  if (!history.scans || history.scans.length === 0) {
+    return `<h2 id="history">Scan History</h2>\n<p style="color:#8b949e;font-size:13px;">No scan history yet.</p>`;
+  }
+
+  const scans = [...history.scans].reverse().slice(0, 20);
+
+  let html = `<h2 id="history">Scan History</h2>\n<table>\n<tr><th>Date</th><th>Score</th><th>Grade</th><th>Agent</th><th>Visibility</th><th>Delta</th></tr>`;
+
+  for (let i = 0; i < scans.length; i++) {
+    const s = scans[i];
+    const prev = scans[i + 1];
+    const delta = prev ? s.score - prev.score : 0;
+    const deltaStr =
+      delta > 0
+        ? `<span class="trend">+${delta}</span>`
+        : delta < 0
+          ? `<span class="regression">${delta}</span>`
+          : `<span style="color:#8b949e">—</span>`;
+
+    const date = s.timestamp ? s.timestamp.slice(0, 10) : "—";
+    const gradeClass = `grade-${(s.grade || "f").toLowerCase()}`;
+
+    html += `\n<tr>
+  <td>${date}</td>
+  <td>${s.score}/100</td>
+  <td class="${gradeClass}">${s.grade || "?"}</td>
+  <td>${s.agentReadiness ?? "—"}/50</td>
+  <td>${s.aiVisibility ?? "—"}/50</td>
+  <td>${deltaStr}</td>
+</tr>`;
+  }
+
+  html += `\n</table>`;
+  return html;
+}

package/src/dashboard/sections/overall-score.js

@@ -0,0 +1,128 @@
+export function renderOverallScore(result, beforeResult) {
+  if (beforeResult) {
+    return renderBeforeAfter(beforeResult, result);
+  }
+  return renderSingle(result);
+}
+
+function renderSingle(result) {
+  const { score, grade } = result;
+  const gradeClass = `grade-${grade.toLowerCase()}`;
+  const barClass = `bar-${grade.toLowerCase()}`;
+
+  return `<div class="score-hero" id="overall">
+  <div class="grade ${gradeClass}">${grade}</div>
+  <div class="number">${score} / 100</div>
+  <div class="bar"><div class="bar-fill ${barClass}" style="width:${score}%"></div></div>
+  <div style="display:flex;justify-content:center;gap:40px;margin-top:16px;font-size:13px;">
+    <span>Agent Readiness: <strong>${result.agentReadiness.score}/50</strong></span>
+    <span>AI Visibility: <strong>${result.aiVisibility.score}/50</strong></span>
+  </div>
+</div>
+${renderInsight(result)}
+${renderBenchmarkComparison(score)}`;
+}
+
+function renderBeforeAfter(before, after) {
+  const delta = after.score - before.score;
+  const deltaClass = delta > 0 ? "trend" : delta < 0 ? "regression" : "";
+  const deltaStr = delta > 0 ? `+${delta}` : `${delta}`;
+
+  return `<div id="overall" style="display:flex;align-items:center;justify-content:center;gap:24px;padding:32px 0;">
+
+  <div style="text-align:center;flex:1;">
+    <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.05em;color:#8b949e;margin-bottom:8px;">Before</div>
+    <div class="grade-${before.grade.toLowerCase()}" style="font-size:48px;font-weight:700;">${before.grade}</div>
+    <div style="font-size:20px;color:#8b949e;margin-top:4px;">${before.score} / 100</div>
+    <div class="bar" style="margin:12px auto;width:200px;height:6px;background:#21262d;border-radius:3px;overflow:hidden;">
+      <div class="bar-fill bar-${before.grade.toLowerCase()}" style="width:${before.score}%;height:100%;border-radius:3px;"></div>
+    </div>
+    <div style="font-size:12px;color:#8b949e;">
+      Agent: ${before.agentReadiness.score}/50 · Visibility: ${before.aiVisibility.score}/50
+    </div>
+  </div>
+
+  <div style="font-size:32px;color:#8b949e;padding:0 8px;">→</div>
+
+  <div style="text-align:center;flex:1;">
+    <div style="font-size:11px;text-transform:uppercase;letter-spacing:0.05em;color:#8b949e;margin-bottom:8px;">After</div>
+    <div class="grade-${after.grade.toLowerCase()}" style="font-size:48px;font-weight:700;">${after.grade}</div>
+    <div style="font-size:20px;color:#8b949e;margin-top:4px;">${after.score} / 100</div>
+    <div class="bar" style="margin:12px auto;width:200px;height:6px;background:#21262d;border-radius:3px;overflow:hidden;">
+      <div class="bar-fill bar-${after.grade.toLowerCase()}" style="width:${after.score}%;height:100%;border-radius:3px;"></div>
+    </div>
+    <div style="font-size:12px;color:#8b949e;">
+      Agent: ${after.agentReadiness.score}/50 · Visibility: ${after.aiVisibility.score}/50
+    </div>
+  </div>
+
+</div>
+${delta !== 0 ? `<div style="text-align:center;margin-top:-16px;margin-bottom:16px;"><span class="${deltaClass}" style="font-size:16px;font-weight:600;">${deltaStr} points</span></div>` : ""}
+${renderInsight(after)}
+${renderBenchmarkComparison(after.score)}`;
+}
+
+function renderInsight(result) {
+  const agent = result.agentReadiness.score;
+  const vis = result.aiVisibility.score;
+
+  if (agent < 25) {
+    return `<div style="text-align:center;padding:12px 24px;margin:16px auto;max-width:500px;background:#d2992210;border:1px solid #d2992233;border-radius:6px;font-size:13px;color:#d29922;">
+  <strong>Agent Readiness is low.</strong> AI engines can't cite what they can't read.<br>
+  <span style="color:#8b949e;">Fix the agent side first. Visibility follows.</span>
+</div>`;
+  }
+
+  if (agent >= 40 && vis < 25) {
+    return `<div style="text-align:center;padding:12px 24px;margin:16px auto;max-width:500px;background:#79c0ff10;border:1px solid #79c0ff33;border-radius:6px;font-size:13px;color:#79c0ff;">
+  <strong>Agents can read your site — now make it citable.</strong><br>
+  <span style="color:#8b949e;">Add direct answer summaries, question headings, and structured claims.</span>
+</div>`;
+  }
+
+  if (agent >= 40 && vis >= 40) {
+    return `<div style="text-align:center;padding:12px 24px;margin:16px auto;max-width:500px;background:#3fb95010;border:1px solid #3fb95033;border-radius:6px;font-size:13px;color:#3fb950;">
+  <strong>Strong on both sides.</strong> Agents can find you and AI engines can cite you.
+</div>`;
+  }
+
+  return "";
+}
+
+const REFERENCE_SCORES = [
+  { name: "Stripe", score: 33, type: "SaaS" },
+  { name: "Anthropic Docs", score: 43, type: "API" },
+  { name: "Vercel", score: 48, type: "SaaS" },
+  { name: "Supabase", score: 52, type: "API" },
+  { name: "Cloudflare", score: 55, type: "SaaS" },
+  { name: "Average site", score: 25, type: "" },
+];
+
+function renderBenchmarkComparison(yourScore) {
+  const sorted = [
+    ...REFERENCE_SCORES,
+    { name: "You", score: yourScore, type: "", you: true },
+  ].sort((a, b) => b.score - a.score);
+
+  let html = `<div style="margin-top:24px;padding:20px;background:#161b22;border:1px solid #21262d;border-radius:8px;">
+  <div style="font-size:13px;font-weight:600;color:#f0f6fc;margin-bottom:12px;">How you compare</div>`;
+
+  for (const entry of sorted) {
+    const isYou = entry.you;
+    const color = isYou ? "#d29922" : "#30363d";
+    const nameColor = isYou ? "#f0f6fc" : "#8b949e";
+    const weight = isYou ? "font-weight:600;" : "";
+
+    html += `
+  <div style="display:flex;align-items:center;gap:8px;margin:6px 0;">
+    <span style="width:120px;font-size:12px;color:${nameColor};${weight}">${entry.name}</span>
+    <div style="flex:1;height:4px;background:#21262d;border-radius:2px;overflow:hidden;">
+      <div style="width:${entry.score}%;height:100%;background:${color};border-radius:2px;"></div>
+    </div>
+    <span style="font-size:11px;color:${nameColor};width:32px;text-align:right;${weight}">${entry.score}</span>
+  </div>`;
+  }
+
+  html += `\n</div>`;
+  return html;
+}