aeo-ready 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 1.3.1
+
+- Add progress indicator during scan
+- Add `history` command to view past scans
+- Fix silent catch on corrupt history file — now warns instead of silently returning empty
+- Fix error detail missing from `agentic-seo init` and `afdocs` failures
+- Fix User-Agent from old "agent-web/1.0" to "aeo-ready/1.3"
+- Add programmatic API docs to README
+- Add `files` field to package.json — excludes dead dashboard code from npm (~12KB smaller)
+- Add `repository`, `homepage`, `bugs` fields to package.json
+- Add issue templates (bug report, feature request)
+- Add CHANGELOG.md
+- Link best-practices.md from README
+
+## 1.3.0
+
+- Terminal-only output, remove dashboard auto-open
+- Interactive "Fix now?" prompt after scan
+- Fetch site pages for agentic-seo instead of URL-only mode
+- Add .aeo-ready/ to gitignore
+
+## 1.2.0
+
+- Rewrite as pure aggregator — removed proprietary scoring
+- Interactive "Fix now?" prompt after scan runs `agentic-seo init` + `afdocs`
+- Terminal-only output, removed dashboard auto-open
+
+## 1.1.0
+
+- Aggregator benchmarks: agentic-seo + Cloudflare + Fern in one scan
+- Per-check detail with pass/fail and company comparisons
+- `--dir` flag for local agentic-seo scanning (92 vs 23 in URL-only mode)
+- `--json` and `--threshold` flags for CI
+- Score history in `.aeo-ready/history.json`
+- Dashboard generation (HTML)
+
+## 1.0.0
+
+- Initial release
+- Unified AEO CLI with two scorecards, fix mode, dashboard
+- `agent-web` skill for Claude Code

package/README.md

@@ -1,115 +1,118 @@
-# 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/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
-
-  Overall: C 50/100
-
-  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.
-
-  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
+  aeo-ready — yoursite.com
+
+  agentic-seo ·································· 91/100 A
+    ✓ Discovery              25/25
+    ◑ Content Structure      18/25
+    ✓ Token Economics        25/25
+    ✓ Capability Signaling   15/15
+    ✓ UX Bridge               8/10
+    vs Cloudflare 55 · Supabase 52 · Vercel 48 · Stripe 17
+
+  Cloudflare ···································· 4/5 B
+    10 passed  2 failed
+    ✗ robotsTxtAiRules  No rules for AI bots found
+    ✗ contentSignals    No content signals in robots.txt
+    vs Cloudflare 5 · Vercel 4 · Supabase 3 · Stripe 2
+
+  Fern ········································ 83/100 B
+    9 passed  4 failed
+    ✗ llms-txt-links-markdown  Links point to HTML, no markdown
+    ✗ content-start-position   2 pages have content past 50%
+    ✗ llms-txt-coverage        Covers 67% of sitemap
+    ✗ markdown-content-parity  4 pages have content differences
+    vs Stripe 85 · Supabase 78 · Anthropic 72 · Vercel 60
+
+  ──────────────────────────────────────────────────
+  Overall                                     85/100
+
+  Next steps
+    npx agentic-seo init                          scaffold llms.txt, AGENTS.md
+    npx afdocs https://yoursite.com               4 Fern issues
+    npx skills add katrinalaszlo/agent-serve      make your product agent-ready
+
+  Fix now? [y/N]
 ```
 
-## CI Mode
-
-Exit with code 1 if below threshold:
-
-```bash
-npx agent-web scan --json --threshold 60
-```
+Say `y` and it runs `npx agentic-seo init` to scaffold missing files (llms.txt, AGENTS.md, skill.md), then `npx afdocs` for Fern issues. Non-interactive in CI (`--json` or non-TTY).
 
-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
-
-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 saves to `.agent-web/history.json`. Gitignored by default.
+Scores persist in `.aeo-ready/history.json`. Re-scan to track improvement over time.
 
-## Site Type Detection
+```bash
+npx aeo-ready history                          # show last 10 scans
+```
 
-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
+## Programmatic API
 
-Scoring adjusts by type (e.g., OpenAPI is required for SaaS, N/A for personal sites).
+```js
+import { scan, getHistory } from "aeo-ready";
 
-## Coming Soon
+const result = await scan({ url: "https://yoursite.com", dir: "./public", json: true });
+// result.averageScore, result.benchmarks.agenticSeo, .cloudflare, .fern
 
-- `--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
+const history = getHistory(process.cwd());
+// history.scans — array of past scan results
+```
 
-## Also available as a Claude Code skill
+## Next step: make your product agent-ready
+
+`aeo-ready` tells you how discoverable your site is to AI agents. To actually serve those agents — structured content, tool definitions, skill endpoints — use [agent-serve](https://github.com/katrinalaszlo/agent-serve):
 
 ```bash
-npx skills add katrinalaszlo/agent-web
+npx skills add katrinalaszlo/agent-serve
 ```
 
-Then use `/agent-web` or `/agent-web https://example.com` inside Claude Code for an interactive audit that also generates missing files.
+## Best practices by site type
+
+See [skills/agent-web/best-practices.md](skills/agent-web/best-practices.md) for an opinionated AEO framework covering SaaS, personal/portfolio, API/developer tools, and content/blog sites.
 
 ## Author
 

package/bin/cli.js

@@ -2,6 +2,7 @@
 
 import { Command } from "commander";
 import { scan } from "../src/scan.js";
+import { getHistory } from "../src/history/index.js";
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
@@ -20,7 +21,13 @@ program
 
 program
   .command("scan [url]")
-  .description("Run all AEO benchmarks against a URL")
+  .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>",
@@ -32,10 +39,15 @@ program
       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);
       }
 
-      const result = await scan({ url, json: opts.json || false });
+      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");
@@ -50,4 +62,29 @@ program
     }
   });
 
+program
+  .command("history")
+  .description("Show past scan scores")
+  .action(() => {
+    const history = getHistory(process.cwd());
+    if (history.scans.length === 0) {
+      console.log("  No scans yet. Run: npx aeo-ready scan <url>");
+      return;
+    }
+    console.log("");
+    const rows = history.scans.slice(-10).map((s) => {
+      const date = new Date(s.timestamp).toLocaleDateString();
+      const parts = [];
+      if (s.agenticSeo != null) parts.push(`seo:${s.agenticSeo}`);
+      if (s.cloudflare != null)
+        parts.push(`cf:${s.cloudflare}/${s.cloudflareMax || "?"}`);
+      if (s.fern != null) parts.push(`fern:${s.fern}`);
+      return `  ${date.padEnd(12)} ${String(s.averageScore).padEnd(6)} ${parts.join("  ")}  ${s.url}`;
+    });
+    console.log(`  ${"Date".padEnd(12)} ${"Avg".padEnd(6)} Scores`);
+    console.log(`  ${"─".repeat(60)}`);
+    for (const row of rows) console.log(row);
+    console.log("");
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aeo-ready",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "AEO benchmark aggregator. One scan, every score. Collects agentic-seo, Cloudflare, and Fern in one report.",
   "type": "module",
   "bin": {
@@ -25,6 +25,25 @@
   ],
   "author": "Kat Laszlo <kat@tansohq.com>",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/katrinalaszlo/aeo-ready.git"
+  },
+  "homepage": "https://github.com/katrinalaszlo/aeo-ready#readme",
+  "bugs": {
+    "url": "https://github.com/katrinalaszlo/aeo-ready/issues"
+  },
+  "files": [
+    "bin/",
+    "src/benchmark/",
+    "src/history/",
+    "src/utils/",
+    "src/index.js",
+    "src/scan.js",
+    "skills/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "engines": {
     "node": ">=18.0.0"
   },

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,13 @@ const REFERENCE_SCORES = {
   },
 };
 
-export async function runAllBenchmarks(target) {
+const W = 52;
+
+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),
   ]);
@@ -47,9 +49,7 @@ export function printBenchmarks(benchmarks) {
   const any = Object.values(benchmarks).some((b) => b && b.available);
   if (!any) return;
 
-  console.log(
-    chalk.bold("\n  ─── Benchmarks ────────────────────────────────────\n"),
-  );
+  console.log("");
 
   if (benchmarks.agenticSeo?.available) {
     printBenchmarkBlock("agentic-seo", "agenticSeo", benchmarks.agenticSeo);
@@ -62,30 +62,42 @@ export function printBenchmarks(benchmarks) {
   }
 }
 
+function scoreColor(pct) {
+  return pct >= 80 ? chalk.green : pct >= 50 ? chalk.yellow : chalk.red;
+}
+
 function printBenchmarkBlock(name, key, b) {
   const pct = b.maxScore > 0 ? Math.round((b.score / b.maxScore) * 100) : 0;
-  const color = pct >= 80 ? chalk.green : pct >= 50 ? chalk.yellow : chalk.red;
-  const barW = 16;
-  const filled = Math.round((pct / 100) * barW);
-  const bar = color("█".repeat(filled)) + chalk.dim("░".repeat(barW - filled));
+  const color = scoreColor(pct);
+  const scoreStr = `${b.score}/${b.maxScore}`;
+  const gradeStr = b.grade ? ` ${b.grade}` : "";
+  const right = `${scoreStr}${gradeStr}`;
+  const dots = W - name.length - right.length;
+  const leader = dots > 2 ? " " + chalk.dim("·".repeat(dots - 2)) + " " : " ";
 
-  console.log(
-    `  ${bar} ${chalk.bold(name.padEnd(16))} ${chalk.dim(`${b.score}/${b.maxScore}`)}${b.grade ? chalk.dim(` (${b.grade})`) : ""}`,
-  );
+  console.log(`  ${chalk.bold(name)}${leader}${color(right)}`);
 
   if (b.checks && b.checks.length > 0) {
-    for (const check of b.checks) {
-      if (check.status === "pass") {
-        console.log(
-          chalk.green(`    + ${check.id}`) +
-            chalk.dim(check.message ? ` ${check.message.slice(0, 60)}` : ""),
-        );
-      } else if (check.status === "fail") {
-        console.log(
-          chalk.red(`    - ${check.id}`) +
-            chalk.dim(check.message ? ` ${check.message.slice(0, 60)}` : ""),
-        );
-      }
+    const passed = b.checks.filter((c) => c.status === "pass");
+    const failed = b.checks.filter(
+      (c) => c.status === "fail" || c.status === "warn",
+    );
+
+    if (passed.length > 0 && failed.length > 0) {
+      console.log(
+        chalk.dim(
+          `    ${chalk.green(passed.length + " passed")}  ${chalk.red(failed.length + " failed")}`,
+        ),
+      );
+    } else if (passed.length > 0) {
+      console.log(chalk.dim(`    ${chalk.green(passed.length + " passed")}`));
+    }
+
+    for (const check of failed) {
+      const msg = check.message
+        ? chalk.dim(` ${check.message.slice(0, 50)}`)
+        : "";
+      console.log(`    ${chalk.red("✗")} ${check.id}${msg}`);
     }
   } else if (b.categories) {
     for (const [, cat] of Object.entries(b.categories)) {
@@ -99,20 +111,18 @@ function printBenchmarkBlock(name, key, b) {
             ? chalk.yellow("◑")
             : chalk.red("✗");
       console.log(
-        chalk.dim(
-          `    ${icon} ${(cat.name || "").padEnd(22)} ${cat.score}/${cat.maxScore}`,
-        ),
+        `    ${icon} ${chalk.dim((cat.name || "").padEnd(22))} ${chalk.dim(`${cat.score}/${cat.maxScore}`)}`,
       );
     }
   }
 
   const refs = REFERENCE_SCORES[key];
   if (refs) {
-    const names = Object.entries(refs)
+    const cmp = Object.entries(refs)
       .sort((a, b) => b[1] - a[1])
       .map(([n, s]) => `${n} ${s}`)
-      .join(chalk.dim(" · "));
-    console.log(chalk.dim(`    compare: ${names}`));
+      .join(" · ");
+    console.log(chalk.dim(`    vs ${cmp}`));
   }
 
   console.log("");

package/src/history/index.js

@@ -29,7 +29,11 @@ export function loadHistory(historyPath) {
   if (existsSync(historyPath)) {
     try {
       return JSON.parse(readFileSync(historyPath, "utf8"));
-    } catch {}
+    } catch (err) {
+      console.warn(
+        `Warning: corrupt history file ${historyPath} — ${err.message}`,
+      );
+    }
   }
   return { scans: [] };
 }

package/src/scan.js

@@ -1,20 +1,18 @@
 import chalk from "chalk";
+import { createInterface } from "readline";
+import { execSync } from "child_process";
 import { runAllBenchmarks, printBenchmarks } from "./benchmark/index.js";
 import { saveResult } from "./history/index.js";
-import { generateDashboard } from "./dashboard/generate.js";
-import { exec } from "child_process";
 
 export async function scan(opts) {
-  const { url, json } = opts;
+  const { url, dir, json } = opts;
 
   if (!json) {
-    console.log(
-      chalk.bold("\n  aeo-ready") + chalk.dim(" — AEO benchmark aggregator\n"),
-    );
-    console.log(chalk.dim(`  Scanning ${url}...\n`));
+    console.log(chalk.bold("\n  aeo-ready") + chalk.dim(` — ${url}\n`));
+    console.log(chalk.dim("  Checking agentic-seo · Cloudflare · Fern...\n"));
   }
 
-  const benchmarks = await runAllBenchmarks(url);
+  const benchmarks = await runAllBenchmarks(url, dir);
   const scores = collectScores(benchmarks);
   const averageScore =
     scores.length > 0
@@ -35,10 +33,8 @@ export async function scan(opts) {
   const baseDir = process.cwd();
   await saveResult(result, baseDir);
 
-  if (!json) {
-    const dashPath = await generateDashboard(result, baseDir);
-    console.log(chalk.dim(`  Dashboard: ${dashPath}\n`));
-    openInBrowser(dashPath);
+  if (!json && averageScore < 100 && process.stdin.isTTY) {
+    await promptFix(result, dir);
   }
 
   return result;
@@ -73,50 +69,97 @@ function printReport(result) {
       : averageScore >= 50
         ? chalk.yellow
         : chalk.red;
+
+  console.log(chalk.dim("  " + "─".repeat(50)));
   console.log(
-    chalk.dim("  ─────────────────────────────────────────────────\n"),
-  );
-  console.log(
-    `  Average across all sources: ${gc.bold(`${averageScore}/100`)}\n`,
+    `  ${chalk.bold("Overall")}${" ".repeat(37)}${gc.bold(`${averageScore}/100`)}\n`,
   );
 
+  printNextSteps(result);
+}
+
+function printNextSteps(result) {
+  const { benchmarks, averageScore } = result;
+  const steps = [];
+
   if (averageScore < 80) {
-    console.log(chalk.bold("  Fix it:\n"));
-    console.log(
-      chalk.dim("    npx agentic-seo init") +
-        "          scaffold llms.txt, AGENTS.md, skill.md",
-    );
+    steps.push(["npx agentic-seo init", "scaffold llms.txt, AGENTS.md"]);
+  }
 
-    const cfFails =
-      benchmarks.cloudflare?.checks?.filter((c) => c.status === "fail") || [];
-    for (const fail of cfFails.slice(0, 2)) {
-      console.log(
-        chalk.dim(`    Cloudflare: ${fail.id}`) +
-          chalk.dim(` — see isitagentready.com for fix`),
-      );
-    }
+  const cfFails =
+    benchmarks.cloudflare?.checks?.filter((c) => c.status === "fail") || [];
+  if (cfFails.length > 0) {
+    steps.push([
+      `Cloudflare: ${cfFails.length} failing`,
+      "see isitagentready.com",
+    ]);
+  }
 
-    const fernFails =
-      benchmarks.fern?.checks?.filter(
-        (c) => c.status === "fail" || c.status === "warn",
-      ) || [];
-    if (fernFails.length > 0) {
-      console.log(
-        chalk.dim(`    Fern: ${fernFails.length} issues`) +
-          chalk.dim(` — run npx afdocs ${result.url}`),
-      );
-    }
+  const fernFails =
+    benchmarks.fern?.checks?.filter(
+      (c) => c.status === "fail" || c.status === "warn",
+    ) || [];
+  if (fernFails.length > 0) {
+    steps.push([`npx afdocs ${result.url}`, `${fernFails.length} Fern issues`]);
+  }
 
-    console.log(chalk.dim("\n  Fix, then re-scan to track improvement.\n"));
+  steps.push([
+    "npx skills add katrinalaszlo/agent-serve",
+    "make your product agent-ready",
+  ]);
+
+  if (steps.length > 0) {
+    console.log(chalk.bold("  Next steps\n"));
+    const maxCmd = Math.max(...steps.map(([cmd]) => cmd.length));
+    for (const [cmd, desc] of steps) {
+      console.log(`    ${cmd.padEnd(maxCmd + 4)}${chalk.dim(desc)}`);
+    }
+    console.log("");
   }
 }
 
-function openInBrowser(filePath) {
-  const cmd =
-    process.platform === "darwin"
-      ? "open"
-      : process.platform === "win32"
-        ? "start"
-        : "xdg-open";
-  exec(`${cmd} "${filePath}"`, () => {});
+function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+async function promptFix(result, dir) {
+  const answer = await ask(chalk.bold("  Fix now? ") + chalk.dim("[y/N] "));
+  if (answer !== "y" && answer !== "yes") return;
+
+  console.log("");
+
+  const targetDir = dir || ".";
+
+  console.log(chalk.dim(`  Running: npx agentic-seo init ${targetDir}\n`));
+  try {
+    execSync(`npx agentic-seo init ${targetDir}`, {
+      stdio: "inherit",
+    });
+  } catch (err) {
+    console.log(chalk.red(`\n  agentic-seo init failed: ${err.message}\n`));
+  }
+
+  const fernFails =
+    result.benchmarks.fern?.checks?.filter(
+      (c) => c.status === "fail" || c.status === "warn",
+    ) || [];
+  if (fernFails.length > 0) {
+    console.log(chalk.dim(`\n  Running: npx afdocs ${result.url}\n`));
+    try {
+      execSync(`npx afdocs ${result.url}`, { stdio: "inherit" });
+    } catch (err) {
+      console.log(chalk.red(`\n  afdocs failed: ${err.message}\n`));
+    }
+  }
+
+  console.log(
+    chalk.dim("\n  Re-scan to verify: ") +
+      `npx aeo-ready scan ${result.url}${dir ? ` --dir ${dir}` : ""}\n`,
+  );
 }

package/src/utils/fetch.js

@@ -1,5 +1,5 @@
 const DEFAULT_TIMEOUT = 10000;
-const USER_AGENT = "agent-web/1.0 (AI readiness auditor)";
+const USER_AGENT = "aeo-ready/1.3 (AEO benchmark aggregator)";
 
 export async function fetchUrl(url, opts = {}) {
   const controller = new AbortController();

package/.claude/settings.local.json

@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "WebSearch"
-    ]
-  }
-}

package/src/dashboard/generate.js

@@ -1,130 +0,0 @@
-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 { renderHistoryTable } from "./sections/history-table.js";
-import { renderTrendChart } from "./sections/trend-chart.js";
-import { renderBenchmarkDetails } from "./sections/benchmark-details.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),
-    "benchmark-details": renderBenchmarkDetails(scanResult),
-    "trend-chart": renderTrendChart(history),
-    "history-table": renderHistoryTable(history),
-  };
-
-  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);
-
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<title>aeo-ready — AEO Benchmark Dashboard</title>
-<style>
-${CSS}
-</style>
-</head>
-<body>
-
-<nav>
-  <h2>aeo-ready</h2>
-  <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>
-</nav>
-
-<main>
-
-<h1>AEO Benchmark Dashboard</h1>
-<p class="subtitle">${scanResult.url} · ${timestamp}</p>
-
-<!-- SECTION:overall-score -->
-${sections["overall-score"]}
-<!-- /SECTION:overall-score -->
-
-<!-- SECTION:benchmark-details -->
-${sections["benchmark-details"]}
-<!-- /SECTION:benchmark-details -->
-
-<!-- SECTION:trend-chart -->
-${sections["trend-chart"]}
-<!-- /SECTION:trend-chart -->
-
-<!-- SECTION:history-table -->
-${sections["history-table"]}
-<!-- /SECTION:history-table -->
-
-</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; }
-.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; }
-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; }
-.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; }
-svg { display: block; margin: 16px 0; }`;

package/src/dashboard/sections/benchmark-details.js

@@ -1,79 +0,0 @@
-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;");
-}

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

@@ -1,39 +0,0 @@
-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>agentic-seo</th><th>Cloudflare</th><th>Fern</th><th>Avg</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.averageScore - prev.averageScore : 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 cf =
-      s.cloudflare != null && s.cloudflareMax
-        ? `${s.cloudflare}/${s.cloudflareMax}`
-        : "—";
-
-    html += `\n<tr>
-  <td>${date}</td>
-  <td>${s.agenticSeo ?? "—"}</td>
-  <td>${cf}</td>
-  <td>${s.fern ?? "—"}</td>
-  <td>${s.averageScore ?? "—"}</td>
-  <td>${deltaStr}</td>
-</tr>`;
-  }
-
-  html += `\n</table>`;
-  return html;
-}

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

@@ -1,65 +0,0 @@
-export function renderOverallScore(result) {
-  const { benchmarks, averageScore } = result;
-
-  let html = `<div id="overall" class="scores">`;
-
-  if (benchmarks.agenticSeo?.available) {
-    html += scoreCard(
-      "agentic-seo",
-      benchmarks.agenticSeo.score,
-      100,
-      benchmarks.agenticSeo.grade,
-    );
-  }
-  if (benchmarks.cloudflare?.available) {
-    html += scoreCard(
-      "Cloudflare",
-      benchmarks.cloudflare.score,
-      benchmarks.cloudflare.maxScore,
-      benchmarks.cloudflare.grade,
-    );
-  }
-  if (benchmarks.fern?.available) {
-    html += scoreCard(
-      "Fern",
-      benchmarks.fern.score,
-      100,
-      benchmarks.fern.grade,
-    );
-  }
-
-  html += `</div>`;
-
-  const gc =
-    averageScore >= 80 ? "grade-a" : averageScore >= 50 ? "grade-c" : "grade-f";
-  html += `<div style="text-align:center;margin:16px 0;font-size:14px;color:#8b949e;">Average across sources: <strong class="${gc}">${averageScore}/100</strong></div>`;
-
-  return html;
-}
-
-function scoreCard(name, score, maxScore, grade) {
-  const pct = maxScore > 0 ? Math.round((score / maxScore) * 100) : 0;
-  const gc = grade
-    ? grade.toLowerCase()
-    : pct >= 80
-      ? "a"
-      : pct >= 65
-        ? "b"
-        : pct >= 50
-          ? "c"
-          : pct >= 35
-            ? "d"
-            : "f";
-
-  return `
-  <div class="score-card">
-    <div class="name">${esc(name)}</div>
-    <div class="grade grade-${gc}">${score}/${maxScore}</div>
-    <div class="number">${grade || ""}</div>
-    <div class="bar"><div class="bar-fill bar-${gc}" style="width:${pct}%"></div></div>
-  </div>`;
-}
-
-function esc(s) {
-  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}

package/src/dashboard/sections/trend-chart.js

@@ -1,63 +0,0 @@
-export function renderTrendChart(history) {
-  if (!history.scans || history.scans.length < 2) {
-    return `<h2 id="trends">Score Trends</h2>\n<p style="color:#8b949e;font-size:13px;">Need at least 2 scans for trend data.</p>`;
-  }
-
-  const scans = history.scans.slice(-20);
-  const width = 700;
-  const height = 200;
-  const pad = { top: 20, right: 20, bottom: 30, left: 40 };
-  const chartW = width - pad.left - pad.right;
-  const chartH = height - pad.top - pad.bottom;
-  const xStep = scans.length > 1 ? chartW / (scans.length - 1) : chartW;
-
-  function toY(value) {
-    return pad.top + chartH - (value / 100) * chartH;
-  }
-
-  function polyline(values, color) {
-    const pts = values.map(
-      (v, i) =>
-        `${i === 0 ? "M" : "L"} ${(pad.left + i * xStep).toFixed(1)} ${toY(v ?? 0).toFixed(1)}`,
-    );
-    return `<path d="${pts.join(" ")}" fill="none" stroke="${color}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>`;
-  }
-
-  const agenticSeo = scans.map((s) => s.agenticSeo ?? 0);
-  const cloudflare = scans.map((s) =>
-    s.cloudflare != null && s.cloudflareMax
-      ? Math.round((s.cloudflare / s.cloudflareMax) * 100)
-      : 0,
-  );
-  const fern = scans.map((s) => s.fern ?? 0);
-
-  const grid = [0, 25, 50, 75, 100]
-    .map((v) => {
-      const y = toY(v);
-      return `<line x1="${pad.left}" y1="${y}" x2="${width - pad.right}" y2="${y}" stroke="#21262d"/><text x="${pad.left - 8}" y="${y + 4}" text-anchor="end" fill="#8b949e" font-size="10">${v}</text>`;
-    })
-    .join("\n");
-
-  const labels = scans
-    .map((s, i) => {
-      if (scans.length <= 10 || i % Math.ceil(scans.length / 8) === 0) {
-        const x = pad.left + i * xStep;
-        const label = s.timestamp ? s.timestamp.slice(5, 10) : "";
-        return `<text x="${x}" y="${height - 5}" text-anchor="middle" fill="#8b949e" font-size="10">${label}</text>`;
-      }
-      return "";
-    })
-    .join("\n");
-
-  return `<h2 id="trends">Score Trends</h2>
-<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">
-${grid}
-${labels}
-${polyline(agenticSeo, "#f85149")}
-${polyline(cloudflare, "#3fb950")}
-${polyline(fern, "#79c0ff")}
-<text x="${width - pad.right}" y="${pad.top - 5}" text-anchor="end" fill="#f85149" font-size="10">agentic-seo</text>
-<text x="${width - pad.right - 90}" y="${pad.top - 5}" text-anchor="end" fill="#3fb950" font-size="10">Cloudflare</text>
-<text x="${width - pad.right - 170}" y="${pad.top - 5}" text-anchor="end" fill="#79c0ff" font-size="10">Fern</text>
-</svg>`;
-}