aeo-ready 1.1.0 → 1.3.0

package/README.md

@@ -1,115 +1,91 @@
-# agent-web
+# aeo-ready
 
-Is your site AI-ready? One scan, two scorecards, one score.
+AEO benchmark aggregator. One scan, every score.
 
 ```bash
-npx agent-web scan --url https://your-site.com
+npx aeo-ready scan yoursite.com
 ```
 
-## What it measures
+## What it does
 
-**Agent Readiness** (0-50) — Can AI agents discover, parse, and act on your site?
-- Discovery: llms.txt, robots.txt AI crawlers, sitemap, meta tags
-- Content Structure: markdown availability, heading hierarchy, token budgets, front-loading
-- Capability Signaling: AGENTS.md, agents.json, OpenAPI, content negotiation
-- Actionable: machine-readable contact, pricing, API endpoints, SDK manifest
+Runs every major AEO (Agentic Engine Optimization) benchmark against your site in one command. Shows per-check pass/fail, company comparisons, and tracks scores over time.
 
-**AI Visibility** (0-50) — Does your content get cited in AI-generated responses?
-- Structured Data: schema.org, FAQ markup, rich schemas, Open Graph
-- Citation Readiness: direct answer formatting, question headings, citable structure
-- Authority: E-E-A-T signals, entity optimization, external validation
-- Freshness: modification dates, publication cadence, content recency
+## Sources
 
-**Overall: X/100** with letter grade (A-F).
+| Benchmark | What it checks | Checks |
+|-----------|---------------|--------|
+| **agentic-seo** (Addy Osmani) | Discovery, content structure, token economics, capability signaling, UX bridge | 10 |
+| **Cloudflare** (isitagentready.com) | Discoverability, content accessibility, bot access, API/auth/MCP/A2A discovery, commerce | 19 |
+| **Fern** (afdocs) | llms.txt quality, markdown availability, page size, content structure, URL stability, auth | 23 |
 
 ## Usage
 
 ```bash
-# Audit a live URL
-npx agent-web scan --url https://example.com
+npx aeo-ready scan yoursite.com                   # scan a URL (remote checks)
+npx aeo-ready scan yoursite.com --dir ./public    # full scan (local + remote)
+npx aeo-ready scan yoursite.com --json            # JSON output for CI
+npx aeo-ready scan yoursite.com --threshold 60    # exit 1 if below
+```
 
-# Audit current directory (repo mode)
-npx agent-web scan
+### Why `--dir`?
 
-# JSON output for CI pipelines
-npx agent-web scan --json --threshold 60
+agentic-seo scores ~23/100 in URL-only mode because most checks (content structure, token economics, capability signaling, UX bridge) need filesystem access. Pass `--dir` to your build output or public directory to get the real score.
 
-# Skip benchmark comparison
-npx agent-web scan --no-benchmark
+```
+URL-only:  agentic-seo 23/100 (F)
+With --dir: agentic-seo 92/100 (A)
 ```
 
 ## Output
 
 ```
-  agent-web — AI readiness audit
-
-  Mode: url | Type: saas
+  aeo-ready — AEO benchmark aggregator
 
-  Overall: C 50/100
+  ─── Benchmarks ────────────────────────────────────
 
-  Agent Readiness: 22/50
-    discovery: 3/12
-      + AI-friendly meta tags [3]
-      - llms.txt [0/4]
-        fix: No llms.txt found.
-      - robots.txt AI crawlers [0/3]
-        fix: robots.txt exists but doesn't mention AI crawlers.
+  ███████████████░ agentic-seo      92/100 (A)
+    ✓ Discovery              25/25
+    ◑ Content Structure      19/25
+    ✓ Token Economics        25/25
+    ✓ Capability Signaling   15/15
+    ✓ UX Bridge              8/10
+    compare: Cloudflare 55 · Supabase 52 · Vercel 48
 
-  AI Visibility: 28/50
-    structured Data: 6/12
-      + FAQ markup [3]
-      + Rich schemas [3]
-      - Schema.org markup [0/4]
-        fix: type doesn't match site category.
-
-  Second opinion: agentic-seo scored you 45/100
-```
+  █████████████░░░ Cloudflare       4/5 (B)
+    + robotsTxt, + sitemap, + linkHeaders, + agentSkills...
+    compare: Cloudflare 5 · Vercel 4 · Supabase 3
 
-## CI Mode
+  █████████████░░░ Fern             83/100 (B)
+    + llms-txt-exists, + rendering-strategy, - content-negotiation...
+    compare: Stripe 85 · Supabase 78 · Anthropic 72
 
-Exit with code 1 if below threshold:
+  Average across all sources: 85/100
 
-```bash
-npx agent-web scan --json --threshold 60
+  Fix it:
+    npx agentic-seo init          scaffold llms.txt, AGENTS.md
+    Fern: 6 issues — run npx afdocs https://yoursite.com
 ```
 
-Add to GitHub Actions:
+## CI Mode
 
 ```yaml
-- run: npx agent-web scan --threshold 50
+- run: npx aeo-ready scan yoursite.com --dir ./public --threshold 50
 ```
 
-## Benchmark
+## Dashboard
 
-Runs `npx agentic-seo --json` as an independent second opinion. Shows their score alongside yours. If agentic-seo isn't installed, the benchmark line is skipped gracefully.
-
-## History
+Each scan generates a self-contained HTML dashboard at `.aeo-ready/dashboard.html` with:
+- Score cards for each benchmark
+- Per-check detail (expandable)
+- Company comparisons
+- Score trends over time (inline SVG)
+- Scan history with deltas
 
-Each scan saves to `.agent-web/history.json`. Gitignored by default.
+Auto-opens in browser after each scan.
 
-## Site Type Detection
-
-Automatically infers site type from signals:
-- **SaaS** — pricing + auth pages detected
-- **API/Developer Tool** — /docs, /api, SDK references
-- **Content/Blog** — articles, blog posts, publication cadence
-- **Personal/Portfolio** — portfolio, about me, single person
-
-Scoring adjusts by type (e.g., OpenAPI is required for SaaS, N/A for personal sites).
-
-## Coming Soon
-
-- `--fix` mode: generate missing files (robots.txt, meta tags, structured data)
-- HTML dashboard with score trends over time
-- Citation correlation: query AI models and track whether fixes improve citations
-
-## Also available as a Claude Code skill
-
-```bash
-npx skills add katrinalaszlo/agent-web
-```
+## History
 
-Then use `/agent-web` or `/agent-web https://example.com` inside Claude Code for an interactive audit that also generates missing files.
+Scores persist in `.aeo-ready/history.json`. Re-scan to track improvement over time.
 
 ## Author
 

package/bin/cli.js

@@ -2,12 +2,6 @@
 
 import { Command } from "commander";
 import { scan } from "../src/scan.js";
-import { fix } from "../src/fix/index.js";
-import {
-  track,
-  printTrackResults,
-  getAvailableProviders,
-} from "../src/track/index.js";
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
@@ -21,66 +15,44 @@ const program = new Command();
 
 program
   .name("aeo-ready")
-  .description("Is your site AEO ready? Two scorecards, one score.")
+  .description("AEO benchmark aggregator. One scan, every score.")
   .version(pkg.version);
 
 program
   .command("scan [url]")
-  .description("Run a full audit (Agent Readiness + AI Visibility)")
-  .option("--fix", "Fix issues and show before/after")
-  .option("--track", "Query AI models to see what they say about you")
-  .option("--company <name>", "Company name for --track")
-  .option("--category <cat>", "Industry category for --track")
+  .description(
+    "Run all AEO benchmarks against a URL (add --dir for local scanning)",
+  )
+  .option(
+    "-d, --dir <path>",
+    "Local directory to scan (gives agentic-seo full access)",
+  )
   .option("--json", "Output results as JSON")
   .option(
     "--threshold <number>",
-    "Minimum score to pass (exit 1 if below)",
+    "Minimum average score to pass (exit 1 if below)",
     parseInt,
   )
-  .option("--no-benchmark", "Skip agentic-seo benchmark")
   .action(async (url, opts) => {
     try {
-      const isUrl = url && url.startsWith("http");
-      const dir = isUrl ? null : process.cwd();
-      const quiet = opts.fix && dir;
-      const result = await scan({
-        url: isUrl ? url : null,
-        dir,
-        json: opts.json || quiet,
-        benchmark: quiet ? false : opts.benchmark !== false,
-      });
-
-      if (opts.track) {
-        const providers = getAvailableProviders();
-        if (providers.length === 0) {
-          console.log("\n  --track needs API keys. Set one or more:");
-          console.log("    ANTHROPIC_API_KEY  (Claude)");
-          console.log("    OPENAI_API_KEY     (ChatGPT)");
-          console.log("    GOOGLE_API_KEY     (Gemini)\n");
-        } else {
-          const trackResults = await track(result, {
-            company: opts.company || null,
-            category: opts.category || null,
-          });
-          printTrackResults(trackResults, opts.company);
-        }
+      if (url && !url.startsWith("http")) url = `https://${url}`;
+      if (!url) {
+        console.error("  Usage: npx aeo-ready scan <url>");
+        console.error("         npx aeo-ready scan <url> --dir ./public");
+        process.exit(1);
       }
 
-      if (opts.fix && dir) {
-        const rescan = () =>
-          scan({ url: null, dir, json: true, benchmark: false });
-        await fix(result, dir, rescan);
-      } else if (opts.fix && !dir) {
-        console.log(
-          "\n  --fix requires repo mode (no --url). Files are written to current directory.\n",
-        );
-      }
+      const result = await scan({
+        url,
+        dir: opts.dir || null,
+        json: opts.json || false,
+      });
 
       if (opts.json) {
         process.stdout.write(JSON.stringify(result, null, 2) + "\n");
       }
 
-      if (opts.threshold && result.score < opts.threshold) {
+      if (opts.threshold && result.averageScore < opts.threshold) {
         process.exit(1);
       }
     } catch (err) {
@@ -89,18 +61,4 @@ program
     }
   });
 
-program
-  .command("init")
-  .description("Create .agent-web/config.yaml for citation tracking")
-  .action(() => {
-    console.log("Coming in v2.0 — citation tracking config");
-  });
-
-program
-  .command("history")
-  .description("List past scan results")
-  .action(() => {
-    console.log("Coming in v1.2 — scan history");
-  });
-
 program.parse();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aeo-ready",
-  "version": "1.1.0",
-  "description": "Is your site AEO ready? Two scorecards: Agent Readiness + AI Visibility. One scan, one score.",
+  "version": "1.3.0",
+  "description": "AEO benchmark aggregator. One scan, every score. Collects agentic-seo, Cloudflare, and Fern in one report.",
   "type": "module",
   "bin": {
     "aeo-ready": "./bin/cli.js"

package/src/benchmark/agentic-seo.js

@@ -1,14 +1,109 @@
 import { execSync } from "child_process";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join, dirname } from "path";
+
+const KNOWN_FILES = [
+  "robots.txt",
+  "llms.txt",
+  "llms-full.txt",
+  "AGENTS.md",
+  "CLAUDE.md",
+  "skill.md",
+  "agent-permissions.json",
+  "agents.json",
+  "sitemap.xml",
+  ".well-known/ai-plugin.json",
+];
+
+async function fetchText(url) {
+  try {
+    const res = await fetch(url, { redirect: "follow" });
+    if (!res.ok) return null;
+    return await res.text();
+  } catch {
+    return null;
+  }
+}
+
+function parseSitemapUrls(xml, baseUrl) {
+  const urls = [];
+  const matches = xml.matchAll(/<loc>([^<]+)<\/loc>/g);
+  for (const m of matches) {
+    const loc = m[1].trim();
+    if (loc.startsWith(baseUrl)) urls.push(loc);
+  }
+  return urls;
+}
+
+function urlToFilePath(url, baseUrl) {
+  let path = new URL(url).pathname;
+  if (path.endsWith("/")) path += "index.html";
+  else if (!path.includes(".")) path += ".html";
+  return path.replace(/^\//, "");
+}
+
+async function fetchSiteToDir(baseUrl) {
+  const tempDir = mkdtempSync(join(tmpdir(), "aeo-"));
+
+  for (const file of KNOWN_FILES) {
+    const content = await fetchText(`${baseUrl}/${file}`);
+    if (content) {
+      const filePath = join(tempDir, file);
+      mkdirSync(dirname(filePath), { recursive: true });
+      writeFileSync(filePath, content);
+    }
+  }
+
+  const sitemap = await fetchText(`${baseUrl}/sitemap.xml`);
+  if (!sitemap) return tempDir;
+
+  const urls = parseSitemapUrls(sitemap, baseUrl);
+
+  await Promise.all(
+    urls.map(async (url) => {
+      const path = urlToFilePath(url, baseUrl);
+      if (KNOWN_FILES.includes(path)) return;
+
+      const html = await fetchText(url);
+      if (html) {
+        const htmlPath = join(tempDir, path);
+        mkdirSync(dirname(htmlPath), { recursive: true });
+        writeFileSync(htmlPath, html);
+      }
+
+      const mdUrl = url
+        .replace(/\.html$/, ".md")
+        .replace(/\/?$/, (m) => (m === "/" ? "/index.md" : ".md"));
+      if (mdUrl !== url) {
+        const md = await fetchText(mdUrl);
+        if (md) {
+          const mdPath = join(tempDir, path.replace(/\.html$/, ".md"));
+          mkdirSync(dirname(mdPath), { recursive: true });
+          writeFileSync(mdPath, md);
+        }
+      }
+    }),
+  );
+
+  return tempDir;
+}
 
 export async function runBenchmark(target) {
+  let tempDir = null;
+
   try {
-    const args =
-      target && target.startsWith("http")
-        ? `--url ${target} --json`
-        : `${target || "."} --json`;
+    let scanDir;
 
-    const output = execSync(`npx agentic-seo ${args}`, {
-      timeout: 30000,
+    if (target && target.startsWith("http")) {
+      tempDir = await fetchSiteToDir(target);
+      scanDir = tempDir;
+    } else {
+      scanDir = target || ".";
+    }
+
+    const output = execSync(`npx agentic-seo ${scanDir} --json`, {
+      timeout: 60000,
       encoding: "utf8",
       stdio: ["pipe", "pipe", "pipe"],
     });
@@ -36,5 +131,11 @@ export async function runBenchmark(target) {
       available: false,
       reason: err.message?.slice(0, 100),
     };
+  } finally {
+    if (tempDir) {
+      try {
+        rmSync(tempDir, { recursive: true, force: true });
+      } catch {}
+    }
   }
 }

package/src/benchmark/index.js

@@ -27,11 +27,11 @@ const REFERENCE_SCORES = {
   },
 };
 
-export async function runAllBenchmarks(target) {
+export async function runAllBenchmarks(target, dir) {
   const isUrl = target && target.startsWith("http");
 
   const results = await Promise.allSettled([
-    runAgenticSeo(target),
+    runAgenticSeo(dir || target),
     isUrl ? runCloudflare(target) : Promise.resolve(null),
     isUrl ? runFern(target) : Promise.resolve(null),
   ]);

package/src/dashboard/generate.js

@@ -2,11 +2,9 @@ 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";
+import { renderBenchmarkDetails } from "./sections/benchmark-details.js";
 
 const DASHBOARD_DIR = ".aeo-ready";
 const DASHBOARD_FILE = "dashboard.html";
@@ -19,12 +17,10 @@ export async function generateDashboard(scanResult, dir, opts = {}) {
   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),
+    "overall-score": renderOverallScore(scanResult),
+    "benchmark-details": renderBenchmarkDetails(scanResult),
     "trend-chart": renderTrendChart(history),
-    recommendations: renderRecommendations(scanResult),
+    "history-table": renderHistoryTable(history),
   };
 
   let html;
@@ -54,13 +50,12 @@ function replaceSection(html, name, content) {
 
 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>
+<title>aeo-ready — AEO Benchmark Dashboard</title>
 <style>
 ${CSS}
 </style>
@@ -69,30 +64,24 @@ ${CSS}
 
 <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="#overall" class="section-head">Scores</a>
+  <a href="#details" class="section-head">Benchmark Details</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>
+<h1>AEO Benchmark Dashboard</h1>
+<p class="subtitle">${scanResult.url} · ${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:benchmark-details -->
+${sections["benchmark-details"]}
+<!-- /SECTION:benchmark-details -->
 
 <!-- SECTION:trend-chart -->
 ${sections["trend-chart"]}
@@ -102,10 +91,6 @@ ${sections["trend-chart"]}
 ${sections["history-table"]}
 <!-- /SECTION:history-table -->
 
-<!-- SECTION:recommendations -->
-${sections["recommendations"]}
-<!-- /SECTION:recommendations -->
-
 </main>
 </body>
 </html>`;
@@ -123,34 +108,23 @@ 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; }
+.scores { display: flex; gap: 16px; flex-wrap: wrap; margin: 16px 0; }
+.score-card { background: #161b22; border: 1px solid #21262d; border-radius: 8px; padding: 20px; flex: 1; min-width: 180px; text-align: center; }
+.score-card .name { font-size: 11px; text-transform: uppercase; letter-spacing: 0.05em; color: #8b949e; margin-bottom: 8px; }
+.score-card .grade { font-size: 36px; font-weight: 700; }
+.score-card .number { font-size: 14px; color: #8b949e; margin-top: 4px; }
+.score-card .bar { margin: 8px auto; width: 100%; height: 4px; background: #21262d; border-radius: 2px; overflow: hidden; }
+.score-card .bar-fill { height: 100%; border-radius: 2px; }
 .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; }
+details { background: #161b22; border: 1px solid #21262d; border-radius: 8px; padding: 16px; margin: 12px 0; cursor: pointer; }
+details summary { font-size: 14px; font-weight: 500; color: #f0f6fc; display: flex; justify-content: space-between; }
 .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; }
+.compare { font-size: 11px; color: #8b949e; margin-top: 8px; padding-top: 8px; border-top: 1px solid #21262d; }
 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/benchmark-details.js

@@ -0,0 +1,79 @@
+const REFERENCE_SCORES = {
+  agenticSeo: {
+    Cloudflare: 55,
+    Supabase: 52,
+    Vercel: 48,
+    Average: 25,
+    Stripe: 17,
+  },
+  cloudflare: { Cloudflare: 5, Vercel: 4, Supabase: 3, Stripe: 2, Average: 2 },
+  fern: { Stripe: 85, Supabase: 78, Anthropic: 72, Vercel: 60, Average: 45 },
+};
+
+export function renderBenchmarkDetails(result) {
+  const { benchmarks } = result;
+
+  let html = `<h2 id="details">Benchmark Details</h2>
+<p style="color:#8b949e;font-size:12px;margin-bottom:12px;">Expand each source to see per-check results and how other companies score.</p>`;
+
+  if (benchmarks.agenticSeo?.available) {
+    html += renderSource("agentic-seo", "agenticSeo", benchmarks.agenticSeo);
+  }
+  if (benchmarks.cloudflare?.available) {
+    html += renderSource("Cloudflare", "cloudflare", benchmarks.cloudflare);
+  }
+  if (benchmarks.fern?.available) {
+    html += renderSource("Fern", "fern", benchmarks.fern);
+  }
+
+  return html;
+}
+
+function renderSource(name, key, data) {
+  const pct =
+    data.maxScore > 0 ? Math.round((data.score / data.maxScore) * 100) : 0;
+
+  let html = `\n<details>
+  <summary>
+    <span>${esc(name)}</span>
+    <span style="color:#8b949e;">${data.score}/${data.maxScore}${data.grade ? ` (${data.grade})` : ""}</span>
+  </summary>
+  <div style="margin-top:12px;">`;
+
+  if (data.checks && data.checks.length > 0) {
+    for (const check of data.checks) {
+      if (check.status === "pass") {
+        html += `\n    <div class="check pass">+ ${esc(check.id)} ${check.message ? `<span style="color:#8b949e;font-size:11px;">${esc(check.message.slice(0, 80))}</span>` : ""}</div>`;
+      } else if (check.status === "fail") {
+        html += `\n    <div class="check fail">- ${esc(check.id)} ${check.message ? `<span style="color:#8b949e;font-size:11px;">${esc(check.message.slice(0, 80))}</span>` : ""}</div>`;
+      }
+    }
+  } else if (data.categories) {
+    for (const [, cat] of Object.entries(data.categories)) {
+      const catPct =
+        cat.maxScore > 0 ? Math.round((cat.score / cat.maxScore) * 100) : 0;
+      const icon = catPct >= 80 ? "+" : catPct >= 40 ? "~" : "-";
+      const cls = catPct >= 80 ? "pass" : "fail";
+      html += `\n    <div class="check ${cls}">${icon} ${esc(cat.name || "")} ${cat.score}/${cat.maxScore}</div>`;
+    }
+  }
+
+  const refs = REFERENCE_SCORES[key];
+  if (refs) {
+    const lines = Object.entries(refs)
+      .sort((a, b) => b[1] - a[1])
+      .map(([n, s]) => `${n}: ${s}`)
+      .join(" · ");
+    html += `\n    <div class="compare">Others: ${lines}</div>`;
+  }
+
+  html += `\n  </div>\n</details>`;
+  return html;
+}
+
+function esc(s) {
+  return (s || "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}