geo-ai-search-optimization 2.2.1 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {

package/src/cli-site-ops-commands.js

@@ -54,6 +54,11 @@ import { generateAutoFix, renderAutoFixMarkdown, writeAutoFixOutput } from "./au
 import { savePageSnapshot, buildPageTrend, renderPageTrendMarkdown, writePageTrendOutput } from "./page-snapshot.js";
 import { diagnose, renderDiagnoseMarkdown, writeDiagnoseOutput } from "./diagnose.js";
 import { comparePages, renderCompareMarkdown, writeCompareOutput } from "./compare.js";
+import { deepBenchmark, renderDeepBenchmarkMarkdown, writeDeepBenchmarkOutput } from "./deep-benchmark.js";
+import { quickSummary, renderSummaryMarkdown } from "./summary.js";
+import { fullPageAuditToCsv, batchFullPageAuditToCsv, deepBenchmarkToCsv, compareToCsv } from "./csv-export.js";
+import { explain, renderExplainMarkdown, writeExplainOutput } from "./explain.js";
+import { monitorPage, renderMonitorMarkdown, writeMonitorOutput } from "./monitor.js";
 
 export const SITE_OPS_HELP_LINES = [
   "  geo-ai-search-optimization doctor [--json]",
@@ -99,7 +104,11 @@ export const SITE_OPS_HELP_LINES = [
   "  geo-ai-search-optimization auto-fix <url-or-file> [--json] [--out <file>]",
   "  geo-ai-search-optimization page-trend <url-or-file> [--data-dir <dir>] [--last <n>] [--json] [--out <file>]",
   "  geo-ai-search-optimization diagnose <url-or-dir-or-file> [--json] [--out <file>]",
-  "  geo-ai-search-optimization compare <url-or-file-A> <url-or-file-B> [--json] [--out <file>]"
+  "  geo-ai-search-optimization compare <url-or-file-A> <url-or-file-B> [--json] [--csv] [--out <file>]",
+  "  geo-ai-search-optimization deep-benchmark <url> --competitors <url1,url2,...> [--concurrency <n>] [--json] [--csv] [--out <file>]",
+  "  geo-ai-search-optimization summary <url-or-dir-or-file>",
+  "  geo-ai-search-optimization explain <url-or-file> [--dimension <dim>] [--json] [--out <file>]",
+  "  geo-ai-search-optimization monitor <url-or-file> [--threshold <n>] [--data-dir <dir>] [--json] [--out <file>]"
 ];
 
 const passthroughWriteOutput = async (outputPath) => outputPath;
@@ -705,6 +714,68 @@ const handleBatchFullPageAudit = createStructuredOutputCommandHandler({
   getOutputJson: (args) => hasFlag(args, "--json")
 });
 
+const handleExplain = createStructuredOutputCommandHandler({
+  commandLabel: "explain",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("explain requires a URL or file path");
+    return explain(input, { dimension: getFlagValue(args, "--dimension") || undefined });
+  },
+  renderMarkdown: renderExplainMarkdown,
+  writeOutput: writeExplainOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleMonitor = createStructuredOutputCommandHandler({
+  commandLabel: "monitor",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("monitor requires a URL or file path");
+    const thresholdValue = getFlagValue(args, "--threshold");
+    return monitorPage(input, {
+      threshold: thresholdValue ? parsePositiveInteger(thresholdValue, "--threshold") : 5,
+      dataDir: getFlagValue(args, "--data-dir") || undefined
+    });
+  },
+  renderMarkdown: renderMonitorMarkdown,
+  writeOutput: writeMonitorOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleDeepBenchmark = createStructuredOutputCommandHandler({
+  commandLabel: "deep benchmark",
+  execute: async (args) => {
+    const ownUrl = args.find((value) => !value.startsWith("-"));
+    if (!ownUrl) throw new Error("deep-benchmark requires your URL as the first argument");
+    const competitorsRaw = getFlagValue(args, "--competitors");
+    if (!competitorsRaw) throw new Error("deep-benchmark requires --competitors <url1,url2,...>");
+    const competitorUrls = competitorsRaw.split(",").map((u) => u.trim()).filter(Boolean);
+    const concurrencyValue = getFlagValue(args, "--concurrency");
+    return deepBenchmark(ownUrl, competitorUrls, {
+      concurrency: concurrencyValue ? parsePositiveInteger(concurrencyValue, "--concurrency") : 2
+    });
+  },
+  renderMarkdown: (report, args) => {
+    if (args && hasFlag(args, "--csv")) return deepBenchmarkToCsv(report);
+    return renderDeepBenchmarkMarkdown(report);
+  },
+  writeOutput: writeDeepBenchmarkOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleSummary = async (args) => {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) throw new Error("summary requires a URL, file path, or directory");
+  const result = await quickSummary(input);
+
+  if (hasFlag(args, "--json")) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(renderSummaryMarkdown(result));
+};
+
 const handleDiagnose = createStructuredOutputCommandHandler({
   commandLabel: "diagnose",
   execute: async (args) => {
@@ -724,11 +795,34 @@ const handleCompare = createStructuredOutputCommandHandler({
     if (nonFlags.length < 2) throw new Error("compare requires two URLs or file paths: <A> <B>");
     return comparePages(nonFlags[0], nonFlags[1]);
   },
-  renderMarkdown: renderCompareMarkdown,
+  renderMarkdown: (report) => renderCompareMarkdown(report),
   writeOutput: writeCompareOutput,
-  getOutputJson: (args) => hasFlag(args, "--json")
+  getOutputJson: (args) => {
+    if (hasFlag(args, "--csv")) return false; // Let renderMarkdown handle CSV
+    return hasFlag(args, "--json");
+  }
 });
 
+// Override compare to support --csv
+const _originalCompare = handleCompare;
+const handleCompareCsv = async (args) => {
+  if (hasFlag(args, "--csv")) {
+    const nonFlags = args.filter((value) => !value.startsWith("-"));
+    if (nonFlags.length < 2) throw new Error("compare requires two URLs or file paths: <A> <B>");
+    const result = await comparePages(nonFlags[0], nonFlags[1]);
+    const csv = compareToCsv(result);
+    const outputPath = getFlagValue(args, "--out");
+    if (outputPath) {
+      const resolved = await writeCompareOutput(outputPath, csv);
+      process.stdout.write(`已保存 compare CSV：${resolved}\n`);
+    } else {
+      process.stdout.write(csv + "\n");
+    }
+    return;
+  }
+  return _originalCompare(args);
+};
+
 const handleAutoFix = createStructuredOutputCommandHandler({
   commandLabel: "auto-fix",
   execute: async (args) => {
@@ -851,5 +945,9 @@ export const SITE_OPS_COMMAND_HANDLERS = {
   "auto-fix": handleAutoFix,
   "page-trend": handlePageTrend,
   diagnose: handleDiagnose,
-  compare: handleCompare
+  compare: handleCompareCsv,
+  "deep-benchmark": handleDeepBenchmark,
+  summary: handleSummary,
+  explain: handleExplain,
+  monitor: handleMonitor
 };

package/src/csv-export.js

@@ -0,0 +1,112 @@
+/**
+ * CSV export utility for structured audit data.
+ */
+
+function escCsv(value) {
+  if (value === null || value === undefined) return "";
+  const str = String(value);
+  if (str.includes(",") || str.includes('"') || str.includes("\n")) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+
+function toCsvRow(values) {
+  return values.map(escCsv).join(",");
+}
+
+/**
+ * Convert a full-page-audit result to CSV.
+ */
+export function fullPageAuditToCsv(report) {
+  const rows = [toCsvRow(["Dimension", "Score", "Label", "Weight"])];
+
+  const weights = {
+    base: 15, citability: 12, eeat: 12, readability: 8, headingStructure: 6,
+    internalLinks: 5, socialMeta: 5, platformReady: 8, schema: 7,
+    freshness: 8, security: 7, topics: 7
+  };
+
+  for (const [dim, data] of Object.entries(report.dimensions || {})) {
+    rows.push(toCsvRow([dim, data.score, data.label, `${weights[dim] || 0}%`]));
+  }
+
+  rows.push(toCsvRow(["COMPOSITE", report.compositeScore, report.compositeLabel, "100%"]));
+  return rows.join("\n");
+}
+
+/**
+ * Convert a batch-full-page-audit result to CSV.
+ */
+export function batchFullPageAuditToCsv(report) {
+  const dimKeys = Object.keys(report.dimensionAverages || {});
+  const header = ["URL", "Composite", "Label", ...dimKeys];
+  const rows = [toCsvRow(header)];
+
+  for (const result of report.results || []) {
+    const dimScores = dimKeys.map((k) => result.dimensions?.[k]?.score ?? "");
+    rows.push(toCsvRow([result.input, result.compositeScore, result.compositeLabel, ...dimScores]));
+  }
+
+  // Averages row
+  const avgScores = dimKeys.map((k) => report.dimensionAverages[k] ?? "");
+  rows.push(toCsvRow(["AVERAGE", report.avgScore, "", ...avgScores]));
+
+  return rows.join("\n");
+}
+
+/**
+ * Convert a deep-benchmark result to CSV.
+ */
+export function deepBenchmarkToCsv(report) {
+  // Score board
+  const sections = [];
+
+  sections.push("# Score Board");
+  const boardRows = [toCsvRow(["Rank", "URL", "Composite", "Label", "IsOwn"])];
+  report.scoreBoard.forEach((entry, i) => {
+    boardRows.push(toCsvRow([i + 1, entry.url, entry.composite, entry.label, entry.isOwn]));
+  });
+  sections.push(boardRows.join("\n"));
+
+  // Dimension comparison
+  sections.push("\n# Dimension Comparison");
+  const dimHeader = ["Dimension", "You", "CompetitorAvg", "Delta", "Rank"];
+  const dimRows = [toCsvRow(dimHeader)];
+  for (const [dim, data] of Object.entries(report.dimensionComparison || {})) {
+    dimRows.push(toCsvRow([dim, data.own, data.competitorAvg, data.delta, data.rank]));
+  }
+  sections.push(dimRows.join("\n"));
+
+  return sections.join("\n\n");
+}
+
+/**
+ * Convert a compare result to CSV.
+ */
+export function compareToCsv(report) {
+  const rows = [toCsvRow(["Dimension", "Page A", "Page B", "Delta", "Winner"])];
+
+  for (const [dim, data] of Object.entries(report.dimensions || {})) {
+    rows.push(toCsvRow([dim, data.scoreA, data.scoreB, data.delta, data.winner]));
+  }
+
+  rows.push(toCsvRow(["COMPOSITE", report.compositeA, report.compositeB, report.compositeDelta, report.overallWinner]));
+  return rows.join("\n");
+}
+
+/**
+ * Generic object-array to CSV converter.
+ */
+export function arrayToCsv(items, columns) {
+  if (!items || items.length === 0) return "";
+
+  const keys = columns || Object.keys(items[0]);
+  const rows = [toCsvRow(keys)];
+
+  for (const item of items) {
+    rows.push(toCsvRow(keys.map((k) => item[k])));
+  }
+
+  return rows.join("\n");
+}

package/src/deep-benchmark.js

@@ -0,0 +1,231 @@
+import { writeScanOutput } from "./scan.js";
+import { fullPageAudit } from "./full-page-audit.js";
+
+/**
+ * Deep benchmark: full 12-dimension comparison against N competitors.
+ */
+
+async function auditSafe(url, options) {
+  try {
+    const result = await fullPageAudit(url, options);
+    return { ok: true, url, data: result };
+  } catch (err) {
+    return { ok: false, url, error: err.message };
+  }
+}
+
+export async function deepBenchmark(ownUrl, competitorUrls, options = {}) {
+  const concurrency = options.concurrency || 2;
+  const allUrls = [ownUrl, ...competitorUrls];
+
+  // Audit all URLs with concurrency
+  const results = [];
+  const chunks = [];
+  for (let i = 0; i < allUrls.length; i += concurrency) {
+    chunks.push(allUrls.slice(i, i + concurrency));
+  }
+
+  for (const chunk of chunks) {
+    const chunkResults = await Promise.all(chunk.map((url) => auditSafe(url, options)));
+    results.push(...chunkResults);
+  }
+
+  const ownResult = results[0];
+  const competitorResults = results.slice(1);
+  const successful = results.filter((r) => r.ok);
+
+  // Dimension comparison
+  const allDimKeys = new Set();
+  for (const r of successful) {
+    for (const key of Object.keys(r.data.dimensions)) {
+      allDimKeys.add(key);
+    }
+  }
+
+  const dimensionComparison = {};
+  for (const dim of allDimKeys) {
+    const ownScore = ownResult.ok ? (ownResult.data.dimensions[dim]?.score ?? 0) : null;
+    const compScores = competitorResults.map((r) =>
+      r.ok ? (r.data.dimensions[dim]?.score ?? 0) : null
+    );
+    const validCompScores = compScores.filter((s) => s !== null);
+    const avgComp = validCompScores.length > 0
+      ? Math.round(validCompScores.reduce((a, b) => a + b, 0) / validCompScores.length)
+      : null;
+
+    dimensionComparison[dim] = {
+      own: ownScore,
+      competitors: compScores,
+      competitorAvg: avgComp,
+      delta: ownScore !== null && avgComp !== null ? ownScore - avgComp : null,
+      rank: null // Computed below
+    };
+  }
+
+  // Compute ranks per dimension
+  for (const dim of allDimKeys) {
+    const scores = results
+      .filter((r) => r.ok)
+      .map((r) => ({ url: r.url, score: r.data.dimensions[dim]?.score ?? 0 }))
+      .sort((a, b) => b.score - a.score);
+
+    const ownRank = scores.findIndex((s) => s.url === ownUrl) + 1;
+    dimensionComparison[dim].rank = ownRank || null;
+  }
+
+  // Overall scores
+  const scoreBoard = results.map((r) => ({
+    url: r.url,
+    isOwn: r.url === ownUrl,
+    composite: r.ok ? r.data.compositeScore : null,
+    label: r.ok ? r.data.compositeLabel : "Failed",
+    error: r.ok ? null : r.error
+  })).sort((a, b) => (b.composite ?? -1) - (a.composite ?? -1));
+
+  const ownRank = scoreBoard.findIndex((s) => s.isOwn) + 1;
+
+  // Strengths and weaknesses vs competitor average
+  const strengths = [];
+  const weaknesses = [];
+
+  for (const [dim, data] of Object.entries(dimensionComparison)) {
+    if (data.delta === null) continue;
+    if (data.delta >= 10) strengths.push({ dimension: dim, delta: data.delta, rank: data.rank });
+    if (data.delta <= -10) weaknesses.push({ dimension: dim, delta: data.delta, rank: data.rank });
+  }
+
+  strengths.sort((a, b) => b.delta - a.delta);
+  weaknesses.sort((a, b) => a.delta - b.delta);
+
+  // Platform comparison
+  const platformComparison = [];
+  if (ownResult.ok && ownResult.data.platformSummary) {
+    for (const ownPlatform of ownResult.data.platformSummary) {
+      const compPlatformScores = competitorResults
+        .filter((r) => r.ok && r.data.platformSummary)
+        .map((r) => r.data.platformSummary.find((p) => p.platform === ownPlatform.platform)?.score ?? 0);
+      const avgCompPlatform = compPlatformScores.length > 0
+        ? Math.round(compPlatformScores.reduce((a, b) => a + b, 0) / compPlatformScores.length)
+        : 0;
+
+      platformComparison.push({
+        platform: ownPlatform.platform,
+        ownScore: ownPlatform.score,
+        competitorAvg: avgCompPlatform,
+        delta: ownPlatform.score - avgCompPlatform
+      });
+    }
+  }
+
+  // Actionable gaps
+  const gaps = weaknesses.map((w) => ({
+    dimension: w.dimension,
+    gap: Math.abs(w.delta),
+    action: `Improve ${w.dimension} (${Math.abs(w.delta)} points behind competitor average)`
+  }));
+
+  const ownComposite = ownResult.ok ? ownResult.data.compositeScore : 0;
+  const avgCompComposite = successful.length > 1
+    ? Math.round(successful.filter((r) => r.url !== ownUrl).reduce((sum, r) => sum + r.data.compositeScore, 0) / (successful.length - 1))
+    : null;
+
+  return {
+    kind: "geo-deep-benchmark",
+    ownUrl,
+    competitorUrls,
+    ownComposite,
+    competitorAvgComposite: avgCompComposite,
+    compositeDelta: avgCompComposite !== null ? ownComposite - avgCompComposite : null,
+    ownRank,
+    totalCompetitors: competitorUrls.length,
+    scoreBoard,
+    dimensionComparison,
+    strengths,
+    weaknesses,
+    gaps,
+    platformComparison,
+    successful: successful.length,
+    failed: results.length - successful.length,
+    summary: `Deep benchmark: You rank #${ownRank}/${results.length}. Composite: ${ownComposite} vs avg ${avgCompComposite ?? "—"}. ${strengths.length} strength(s), ${weaknesses.length} weakness(es).`
+  };
+}
+
+const DIM_LABELS = {
+  base: "Base", citability: "Citability", eeat: "E-E-A-T", readability: "Readability",
+  headingStructure: "Headings", internalLinks: "Links", socialMeta: "Social",
+  platformReady: "Platforms", schema: "Schema", freshness: "Freshness",
+  security: "Security", topics: "Topics"
+};
+
+export function renderDeepBenchmarkMarkdown(report) {
+  const lines = [
+    "# GEO Deep Benchmark",
+    "",
+    `- Your URL: \`${report.ownUrl}\``,
+    `- Competitors: \`${report.totalCompetitors}\``,
+    `- **Your rank: #${report.ownRank}/${report.scoreBoard.length}**`,
+    `- Your composite: \`${report.ownComposite}/100\` vs competitor avg \`${report.competitorAvgComposite ?? "—"}/100\``,
+    `- Summary: ${report.summary}`,
+    "",
+    "## Score Board",
+    "",
+    "| Rank | URL | Composite | Label |",
+    "|------|-----|-----------|-------|"
+  ];
+
+  report.scoreBoard.forEach((entry, i) => {
+    const marker = entry.isOwn ? " **← You**" : "";
+    lines.push(`| ${i + 1} | ${entry.url.slice(0, 45)} | ${entry.composite ?? "—"} | ${entry.label}${marker} |`);
+  });
+
+  lines.push(
+    "",
+    "## Dimension Comparison (You vs Competitor Avg)",
+    "",
+    "| Dimension | You | Comp Avg | Δ | Rank |",
+    "|-----------|-----|----------|---|------|"
+  );
+
+  const sorted = Object.entries(report.dimensionComparison)
+    .sort((a, b) => (a[1].delta ?? 0) - (b[1].delta ?? 0));
+
+  for (const [dim, data] of sorted) {
+    const icon = (data.delta ?? 0) >= 5 ? "🟢" : (data.delta ?? 0) <= -5 ? "🔴" : "🟡";
+    lines.push(`| ${icon} ${DIM_LABELS[dim] || dim} | ${data.own ?? "—"} | ${data.competitorAvg ?? "—"} | ${data.delta !== null ? (data.delta >= 0 ? "+" : "") + data.delta : "—"} | #${data.rank ?? "—"} |`);
+  }
+
+  if (report.strengths.length > 0) {
+    lines.push("", "## Your Strengths (vs competitor avg)", "");
+    for (const s of report.strengths) {
+      lines.push(`- 🟢 **${DIM_LABELS[s.dimension] || s.dimension}**: +${s.delta} ahead (rank #${s.rank})`);
+    }
+  }
+
+  if (report.weaknesses.length > 0) {
+    lines.push("", "## Your Weaknesses (vs competitor avg)", "");
+    for (const w of report.weaknesses) {
+      lines.push(`- 🔴 **${DIM_LABELS[w.dimension] || w.dimension}**: ${w.delta} behind (rank #${w.rank})`);
+    }
+  }
+
+  if (report.platformComparison.length > 0) {
+    lines.push("", "## Platform Readiness vs Competitors", "", "| Platform | You | Comp Avg | Δ |", "|----------|-----|----------|---|");
+    for (const p of report.platformComparison) {
+      lines.push(`| ${p.platform} | ${p.ownScore} | ${p.competitorAvg} | ${p.delta >= 0 ? "+" : ""}${p.delta} |`);
+    }
+  }
+
+  if (report.gaps.length > 0) {
+    lines.push("", "## Priority Gaps to Close", "");
+    for (const g of report.gaps) {
+      lines.push(`- **${DIM_LABELS[g.dimension] || g.dimension}**: ${g.gap} points behind → ${g.action}`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+export async function writeDeepBenchmarkOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/explain.js

@@ -0,0 +1,268 @@
+import { writeScanOutput } from "./scan.js";
+import { fullPageAudit } from "./full-page-audit.js";
+
+/**
+ * Explain: deep-dive into why a specific dimension scored low.
+ * Shows concrete evidence from the page content.
+ */
+
+const DIMENSION_EXPLAINERS = {
+  base: {
+    label: "Base Audit",
+    explain: (details) => {
+      if (!details) return { factors: [], evidence: [] };
+      const factors = [];
+      const evidence = [];
+      const checks = details.score?.checks || [];
+      for (const check of checks) {
+        if (!check.passed) {
+          factors.push({ factor: check.label, impact: `-${check.maxPoints} points`, status: "missing" });
+        }
+      }
+      if (details.metadata?.title) evidence.push({ type: "title", value: details.metadata.title });
+      if (details.metadata?.metaDescription) evidence.push({ type: "metaDescription", value: details.metadata.metaDescription.slice(0, 160) });
+      if (details.directAnswerCandidate) evidence.push({ type: "firstParagraph", value: details.directAnswerCandidate.slice(0, 200) });
+      return { factors, evidence };
+    }
+  },
+  citability: {
+    label: "Citability",
+    explain: (details) => {
+      if (!details) return { factors: [], evidence: [] };
+      const factors = [];
+      if (details.claims?.claimDensity < 15) factors.push({ factor: `Claim density: ${details.claims.claimDensity}% (target: 15%+)`, impact: "Low factual content", status: "weak" });
+      if (details.claims?.statDensity < 5) factors.push({ factor: `Stat density: ${details.claims.statDensity}% (target: 5%+)`, impact: "Few statistics", status: "weak" });
+      if (details.entities?.entityDensity < 1) factors.push({ factor: `Entity density: ${details.entities.entityDensity}% (target: 1%+)`, impact: "Few named entities", status: "weak" });
+      if ((details.quotableSentences?.length || 0) < 3) factors.push({ factor: `Quotable sentences: ${details.quotableSentences?.length || 0} (target: 3+)`, impact: "Few citable passages", status: "weak" });
+      if (!details.structure?.hasList) factors.push({ factor: "No lists found", impact: "Content hard to scan", status: "missing" });
+      if (!details.structure?.hasTable) factors.push({ factor: "No tables found", impact: "No structured comparisons", status: "missing" });
+      const evidence = (details.quotableSentences || []).slice(0, 3).map((q) => ({ type: "quotable", value: q.sentence, score: q.score }));
+      return { factors, evidence };
+    }
+  },
+  eeat: {
+    label: "E-E-A-T",
+    explain: (details) => {
+      if (!details) return { factors: [], evidence: [] };
+      const factors = [];
+      const dims = details.dimensions || {};
+      for (const [key, data] of Object.entries(dims)) {
+        if (data.score < 30) {
+          factors.push({ factor: `${key}: ${data.score}/100`, impact: `No ${key} signals detected`, status: "critical" });
+        } else if (data.score < 60) {
+          factors.push({ factor: `${key}: ${data.score}/100`, impact: `Weak ${key} signals`, status: "weak" });
+        }
+      }
+      if ((details.authorPresence?.length || 0) === 0) {
+        factors.push({ factor: "No author attribution", impact: "AI can't identify who wrote this", status: "missing" });
+      }
+      const evidence = (details.authorPresence || []).map((s) => ({ type: "authorSignal", value: s }));
+      for (const [key, data] of Object.entries(dims)) {
+        for (const signal of (data.signals || []).slice(0, 2)) {
+          evidence.push({ type: key, value: `${signal.label}: ${signal.count}x — e.g. "${signal.examples[0] || ""}"` });
+        }
+      }
+      return { factors, evidence };
+    }
+  },
+  readability: {
+    label: "Readability",
+    explain: (details) => {
+      if (!details) return { factors: [], evidence: [] };
+      const factors = [];
+      if (details.fleschKincaidGrade > 12) factors.push({ factor: `Grade level: ${details.fleschKincaidGrade} (target: 8-10)`, impact: "Too complex for broad audience", status: "weak" });
+      if (details.sentenceLength?.avg > 25) factors.push({ factor: `Avg sentence: ${details.sentenceLength.avg} words (target: 15-20)`, impact: "Sentences too long", status: "weak" });
+      if (details.passiveVoice?.passiveRatio > 20) factors.push({ factor: `Passive voice: ${details.passiveVoice.passiveRatio}% (target: <15%)`, impact: "Unclear agency", status: "weak" });
+      if (details.sentenceLength?.distribution?.veryLong > 0) factors.push({ factor: `${details.sentenceLength.distribution.veryLong} sentences over 30 words`, impact: "Hard to parse", status: "weak" });
+      return { factors, evidence: [] };
+    }
+  },
+  headingStructure: {
+    label: "Heading Structure",
+    explain: (details) => {
+      if (!details) return { factors: [], evidence: [] };
+      const factors = [];
+      for (const issue of (details.hierarchy?.issues || [])) {
+        factors.push({ factor: issue.message, impact: issue.severity, status: issue.severity === "error" ? "critical" : "weak" });
+      }
+      if (details.questionHeadings?.count === 0) factors.push({ factor: "No question-style headings", impact: "AI can't extract Q&A answers", status: "missing" });
+      if (details.semanticCoverage?.coverageRatio < 30) factors.push({ factor: `Semantic coverage: ${details.semanticCoverage.coverageRatio}%`, impact: "Narrow topic coverage in headings", status: "weak" });
+      const evidence = (details.headings || []).slice(0, 8).map((h) => ({ type: `h${h.level}`, value: h.text }));
+      return { factors, evidence };
+    }
+  },
+  freshness: {
+    label: "Content Freshness",
+    explain: (details) => {
+      if (!details) return { factors: [], evidence: [] };
+      const factors = [];
+      if (details.datesFound === 0) factors.push({ factor: "No dates found anywhere on the page", impact: "AI can't assess content currency", status: "critical" });
+      if (details.age?.isOld) factors.push({ factor: `Content is ${details.age.modifiedAgeLabel} old`, impact: "AI deprioritizes stale content", status: "weak" });
+      if (details.age?.isStale) factors.push({ factor: `Last modified ${details.age.modifiedAgeLabel} ago`, impact: "Consider updating", status: "weak" });
+      const missingSignals = ["datePublished in structured data", "dateModified in structured data", "Visible freshness label"]
+        .filter((s) => !(details.freshnessSignals || []).includes(s));
+      for (const s of missingSignals) factors.push({ factor: `Missing: ${s}`, impact: "Incomplete freshness signals", status: "missing" });
+      const evidence = (details.dates || []).slice(0, 5).map((d) => ({ type: d.source, value: `${d.date} — "${d.raw}"` }));
+      return { factors, evidence };
+    }
+  },
+  security: {
+    label: "Security",
+    explain: (details) => {
+      if (!details) return { factors: [], evidence: [] };
+      const factors = [];
+      for (const check of (details.htmlChecks || [])) {
+        if (!check.passed && check.severity !== "info") {
+          factors.push({ factor: check.label, impact: check.detail || "Missing", status: check.severity === "error" ? "critical" : "weak" });
+        }
+      }
+      for (const header of (details.securityHeaders || [])) {
+        if (!header.present && header.critical) factors.push({ factor: `Missing: ${header.header}`, impact: "Critical security header", status: "critical" });
+      }
+      return { factors, evidence: [] };
+    }
+  },
+  socialMeta: {
+    label: "Social Meta",
+    explain: (details) => {
+      if (!details) return { factors: [], evidence: [] };
+      const factors = [];
+      const allTags = [...(details.openGraph?.tags || []), ...(details.twitter?.tags || [])];
+      for (const tag of allTags) {
+        if (tag.required && !tag.found) factors.push({ factor: `Missing: ${tag.tag}`, impact: "Required for social sharing", status: "missing" });
+      }
+      const evidence = allTags.filter((t) => t.found).map((t) => ({ type: t.tag, value: t.value?.slice(0, 80) || "" }));
+      return { factors, evidence };
+    }
+  },
+  internalLinks: {
+    label: "Internal Links",
+    explain: (details) => {
+      if (!details) return { factors: [], evidence: [] };
+      const factors = [];
+      if (details.internalLinks?.total === 0) factors.push({ factor: "No internal links", impact: "No site structure signals", status: "critical" });
+      if (details.anchorAnalysis?.empty > 0) factors.push({ factor: `${details.anchorAnalysis.empty} empty anchor text(s)`, impact: "Links with no description", status: "weak" });
+      if (details.anchorAnalysis?.generic > 0) factors.push({ factor: `${details.anchorAnalysis.generic} generic anchor text(s)`, impact: '"Click here" style links', status: "weak" });
+      const evidence = (details.internalLinks?.mostLinked || []).slice(0, 5).map((l) => ({ type: "internal", value: `${l.url} (${l.count}x)` }));
+      return { factors, evidence };
+    }
+  },
+  platformReady: {
+    label: "Platform Readiness",
+    explain: (details) => {
+      if (!details) return { factors: [], evidence: [] };
+      const factors = [];
+      for (const p of (details.platforms || [])) {
+        if (p.score < 50) {
+          const failed = (p.checks || []).filter((c) => !c.passed);
+          factors.push({ factor: `${p.platform}: ${p.score}/100`, impact: `Missing: ${failed.map((f) => f.label).join(", ")}`, status: "weak" });
+        }
+      }
+      return { factors, evidence: [] };
+    }
+  },
+  schema: {
+    label: "Schema Validation",
+    explain: (details) => {
+      if (!details) return { factors: [], evidence: [] };
+      const factors = [];
+      if (details.entityCount === 0) factors.push({ factor: "No JSON-LD found", impact: "AI can't understand page entities", status: "critical" });
+      for (const v of (details.validations || [])) {
+        for (const issue of v.issues) factors.push({ factor: `${v.type}: ${issue.message}`, impact: "Schema error", status: "critical" });
+        for (const enh of v.enhancements) factors.push({ factor: `${v.type}: ${enh.message}`, impact: "AI discoverability", status: "enhancement" });
+      }
+      return { factors, evidence: [] };
+    }
+  },
+  topics: {
+    label: "Topic Coverage",
+    explain: (details) => {
+      if (!details) return { factors: [], evidence: [] };
+      const factors = [];
+      if ((details.keywords?.length || 0) < 5) factors.push({ factor: "Few distinct keywords", impact: "Unclear topic focus", status: "weak" });
+      if ((details.topicClusters?.length || 0) < 3) factors.push({ factor: `Only ${details.topicClusters?.length || 0} topic cluster(s)`, impact: "Narrow topic coverage", status: "weak" });
+      const evidence = (details.keywords || []).slice(0, 5).map((k) => ({ type: "keyword", value: `"${k.term}" (${k.count}x, tfidf: ${k.tfidf})` }));
+      return { factors, evidence };
+    }
+  }
+};
+
+export async function explain(input, options = {}) {
+  const audit = await fullPageAudit(input, options);
+  const targetDim = options.dimension || null;
+
+  const explanations = {};
+
+  const dimsToExplain = targetDim
+    ? { [targetDim]: DIMENSION_EXPLAINERS[targetDim] }
+    : DIMENSION_EXPLAINERS;
+
+  for (const [key, explainer] of Object.entries(dimsToExplain)) {
+    if (!explainer) continue;
+    const score = audit.dimensions[key]?.score ?? 0;
+    const detail = audit.details?.[key] || null;
+    const { factors, evidence } = explainer.explain(detail);
+
+    explanations[key] = {
+      label: explainer.label,
+      score,
+      factorCount: factors.length,
+      factors,
+      evidence: evidence.slice(0, 8)
+    };
+  }
+
+  // Sort by score ascending (worst first)
+  const sorted = Object.entries(explanations)
+    .sort((a, b) => a[1].score - b[1].score);
+
+  return {
+    kind: "geo-explain",
+    input,
+    compositeScore: audit.compositeScore,
+    targetDimension: targetDim,
+    explanations: Object.fromEntries(sorted),
+    summary: targetDim
+      ? `${DIMENSION_EXPLAINERS[targetDim]?.label || targetDim}: ${explanations[targetDim]?.score ?? 0}/100. ${explanations[targetDim]?.factorCount || 0} factor(s) identified.`
+      : `Composite: ${audit.compositeScore}/100. ${sorted.filter(([, e]) => e.score < 40).length} critical dimension(s).`
+  };
+}
+
+export function renderExplainMarkdown(report) {
+  const lines = [
+    "# GEO Score Explanation",
+    "",
+    `- Input: \`${report.input}\``,
+    `- Composite Score: \`${report.compositeScore}/100\``,
+    `- Summary: ${report.summary}`,
+    ""
+  ];
+
+  for (const [key, exp] of Object.entries(report.explanations)) {
+    const icon = exp.score >= 70 ? "🟢" : exp.score >= 40 ? "🟡" : "🔴";
+    lines.push(`## ${icon} ${exp.label} — ${exp.score}/100`, "");
+
+    if (exp.factors.length > 0) {
+      lines.push("### Why this score?", "");
+      for (const f of exp.factors) {
+        const badge = f.status === "critical" ? "🔴" : f.status === "missing" ? "❌" : f.status === "enhancement" ? "💡" : "⚠️";
+        lines.push(`- ${badge} **${f.factor}** — ${f.impact}`);
+      }
+      lines.push("");
+    }
+
+    if (exp.evidence.length > 0) {
+      lines.push("### Evidence from page", "");
+      for (const e of exp.evidence) {
+        lines.push(`- [${e.type}] ${e.value}`);
+      }
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export async function writeExplainOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/fetch-utils.js

@@ -0,0 +1,76 @@
+/**
+ * Shared fetch utilities with retry, timeout, and rate limiting.
+ */
+
+const DEFAULT_TIMEOUT = 10_000;
+const DEFAULT_RETRIES = 2;
+const DEFAULT_RETRY_DELAY = 1000;
+const USER_AGENT = "geo-ai-search-optimization/2.2.1";
+
+export async function fetchWithRetry(url, options = {}) {
+  const timeout = options.timeout || DEFAULT_TIMEOUT;
+  const retries = options.retries ?? DEFAULT_RETRIES;
+  const retryDelay = options.retryDelay || DEFAULT_RETRY_DELAY;
+  const headers = { "user-agent": USER_AGENT, ...options.headers };
+
+  let lastError;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const response = await fetch(url, {
+        redirect: "follow",
+        headers,
+        signal: AbortSignal.timeout(timeout)
+      });
+      return response;
+    } catch (err) {
+      lastError = err;
+      if (attempt < retries) {
+        await new Promise((r) => setTimeout(r, retryDelay * (attempt + 1)));
+      }
+    }
+  }
+
+  throw new Error(`Failed to fetch ${url} after ${retries + 1} attempts: ${lastError.message}`);
+}
+
+export async function fetchText(url, options = {}) {
+  const response = await fetchWithRetry(url, options);
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} for ${url}`);
+  }
+  return response.text();
+}
+
+export async function fetchTextSafe(url, options = {}) {
+  try {
+    return { ok: true, text: await fetchText(url, options), url };
+  } catch (err) {
+    return { ok: false, error: err.message, url };
+  }
+}
+
+/**
+ * Run multiple fetches with concurrency control.
+ */
+export async function fetchBatch(urls, fn, options = {}) {
+  const concurrency = options.concurrency || 3;
+  const results = [];
+
+  const chunks = [];
+  for (let i = 0; i < urls.length; i += concurrency) {
+    chunks.push(urls.slice(i, i + concurrency));
+  }
+
+  for (const chunk of chunks) {
+    const chunkResults = await Promise.all(chunk.map((url) => fn(url)));
+    results.push(...chunkResults);
+
+    // Rate limit between chunks
+    if (options.delayBetweenChunks && chunks.indexOf(chunk) < chunks.length - 1) {
+      await new Promise((r) => setTimeout(r, options.delayBetweenChunks));
+    }
+  }
+
+  return results;
+}

package/src/full-audit.js

@@ -5,6 +5,7 @@ import { auditProject } from "./audit.js";
 import { analyzeCrawlers } from "./crawlers.js";
 import { validateLlmsTxt } from "./validate-llms.js";
 import { fullPageAudit } from "./full-page-audit.js";
+import { analyzeSitemap } from "./sitemap.js";
 
 async function runSafe(label, fn) {
   try {
@@ -54,8 +55,23 @@ export async function fullAudit(input, options = {}) {
       : { ok: true, data: { score: 0, found: false, summary: "No llms.txt found in project." } }
   ]);
 
-  // Phase 3: Sample page audits (if URLs or HTML files provided)
-  const sampleUrls = options.sampleUrls || [];
+  // Phase 2.5: Sitemap analysis (if available)
+  let sitemapResult = null;
+  const sitemapPath = await findSpecialFile(root, "sitemap.xml");
+  if (sitemapPath) {
+    sitemapResult = await runSafe("sitemap", () => analyzeSitemap(sitemapPath));
+  }
+
+  // Phase 3: Sample page audits
+  // Auto-discover from sitemap if no explicit URLs provided
+  let sampleUrls = options.sampleUrls || [];
+  if (sampleUrls.length === 0 && options.autoSample !== false && sitemapResult?.ok) {
+    const entries = sitemapResult.data.entries || [];
+    const sitemapUrls = entries.map((e) => e.loc).filter(Boolean);
+    const maxAutoSample = options.maxAutoSample || 5;
+    sampleUrls = sitemapUrls.slice(0, maxAutoSample);
+  }
+
   const samplePages = [];
 
   if (sampleUrls.length > 0) {

package/src/index.js

@@ -85,4 +85,10 @@ export { batchFullPageAudit, renderBatchFullPageAuditMarkdown, writeBatchFullPag
 export { generateAutoFix, renderAutoFixMarkdown, writeAutoFixOutput } from "./auto-fix.js";
 export { diagnose, renderDiagnoseMarkdown, writeDiagnoseOutput } from "./diagnose.js";
 export { comparePages, renderCompareMarkdown, writeCompareOutput } from "./compare.js";
+export { deepBenchmark, renderDeepBenchmarkMarkdown, writeDeepBenchmarkOutput } from "./deep-benchmark.js";
+export { quickSummary, renderSummaryMarkdown } from "./summary.js";
+export { fetchWithRetry, fetchText, fetchTextSafe, fetchBatch } from "./fetch-utils.js";
+export { fullPageAuditToCsv, batchFullPageAuditToCsv, deepBenchmarkToCsv, compareToCsv, arrayToCsv } from "./csv-export.js";
+export { explain, renderExplainMarkdown, writeExplainOutput } from "./explain.js";
+export { monitorPage, renderMonitorMarkdown, writeMonitorOutput } from "./monitor.js";
 export { savePageSnapshot, listPageSnapshots, loadPageSnapshot, buildPageTrend, renderPageTrendMarkdown, writePageTrendOutput } from "./page-snapshot.js";

package/src/monitor.js

@@ -0,0 +1,144 @@
+import { writeScanOutput } from "./scan.js";
+import { fullPageAudit } from "./full-page-audit.js";
+import { savePageSnapshot, buildPageTrend } from "./page-snapshot.js";
+
+/**
+ * Monitor: run full-page-audit, save snapshot, compare with previous,
+ * and alert on score changes.
+ */
+
+export async function monitorPage(input, options = {}) {
+  const threshold = options.threshold ?? 5;
+  const dataDir = options.dataDir;
+
+  // Get previous trend before new audit
+  const previousTrend = await buildPageTrend(input, { dataDir });
+  const previousScore = previousTrend.snapshotCount > 0
+    ? previousTrend.snapshots[previousTrend.snapshots.length - 1].compositeScore
+    : null;
+
+  // Run fresh audit
+  const audit = await fullPageAudit(input, options);
+  const currentScore = audit.compositeScore;
+
+  // Save snapshot
+  const saved = await savePageSnapshot(audit, { dataDir });
+
+  // Compute delta
+  const delta = previousScore !== null ? currentScore - previousScore : null;
+  const dropped = delta !== null && delta < -threshold;
+  const improved = delta !== null && delta > threshold;
+
+  // Build alert
+  let alert = null;
+  if (dropped) {
+    alert = {
+      level: "warning",
+      message: `Score dropped by ${Math.abs(delta)} points (${previousScore} → ${currentScore}). Threshold: ${threshold}.`,
+      dimensions: findDroppedDimensions(audit, previousTrend)
+    };
+  } else if (improved) {
+    alert = {
+      level: "success",
+      message: `Score improved by ${delta} points (${previousScore} → ${currentScore}).`,
+      dimensions: []
+    };
+  }
+
+  // Updated trend (including new snapshot)
+  const updatedTrend = await buildPageTrend(input, { dataDir });
+
+  return {
+    kind: "geo-monitor",
+    input,
+    currentScore,
+    previousScore,
+    delta,
+    dropped,
+    improved,
+    stable: !dropped && !improved,
+    threshold,
+    alert,
+    snapshotPath: saved.path,
+    snapshotCount: updatedTrend.snapshotCount,
+    trend: updatedTrend.trend,
+    compositeLabel: audit.compositeLabel,
+    dimensions: Object.fromEntries(
+      Object.entries(audit.dimensions).map(([k, v]) => [k, v.score])
+    ),
+    summary: alert
+      ? alert.message
+      : previousScore !== null
+        ? `Stable at ${currentScore}/100 (Δ${delta >= 0 ? "+" : ""}${delta}, within ±${threshold} threshold).`
+        : `First scan: ${currentScore}/100. Baseline established.`
+  };
+}
+
+function findDroppedDimensions(audit, previousTrend) {
+  if (!previousTrend.trend?.dimensionTrends) return [];
+
+  const dropped = [];
+  for (const [dim, trend] of Object.entries(previousTrend.trend.dimensionTrends)) {
+    const current = audit.dimensions[dim]?.score ?? 0;
+    if (current < trend.latest - 5) {
+      dropped.push({ dimension: dim, was: trend.latest, now: current, delta: current - trend.latest });
+    }
+  }
+
+  return dropped.sort((a, b) => a.delta - b.delta);
+}
+
+export function renderMonitorMarkdown(report) {
+  const lines = [
+    "# GEO Monitor Report",
+    "",
+    `- Input: \`${report.input}\``,
+    `- Current Score: \`${report.currentScore}/100\` (${report.compositeLabel})`,
+    `- Previous Score: \`${report.previousScore ?? "—"}\``,
+    `- Delta: \`${report.delta !== null ? (report.delta >= 0 ? "+" : "") + report.delta : "—"}\``,
+    `- Status: ${report.dropped ? "🔴 DROPPED" : report.improved ? "🟢 IMPROVED" : "➡️ STABLE"}`,
+    `- Snapshot: \`${report.snapshotPath}\``,
+    `- Total snapshots: \`${report.snapshotCount}\``,
+    `- Summary: ${report.summary}`,
+    ""
+  ];
+
+  if (report.alert) {
+    const icon = report.alert.level === "warning" ? "⚠️" : "✅";
+    lines.push(`## ${icon} Alert`, "", report.alert.message, "");
+
+    if (report.alert.dimensions?.length > 0) {
+      lines.push("### Dimensions that dropped", "");
+      for (const d of report.alert.dimensions) {
+        lines.push(`- 🔴 **${d.dimension}**: ${d.was} → ${d.now} (${d.delta})`);
+      }
+      lines.push("");
+    }
+  }
+
+  if (report.dimensions) {
+    lines.push("## Current Dimensions", "");
+    const sorted = Object.entries(report.dimensions).sort((a, b) => a[1] - b[1]);
+    for (const [dim, score] of sorted) {
+      const icon = score >= 70 ? "🟢" : score >= 40 ? "🟡" : "🔴";
+      lines.push(`- ${icon} ${dim}: ${score}/100`);
+    }
+    lines.push("");
+  }
+
+  if (report.trend) {
+    lines.push(
+      "## Trend",
+      "",
+      `- Direction: **${report.trend.direction}**`,
+      `- First: ${report.trend.firstScore} → Latest: ${report.trend.latestScore}`,
+      ""
+    );
+  }
+
+  return lines.join("\n");
+}
+
+export async function writeMonitorOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/summary.js

@@ -0,0 +1,28 @@
+import { diagnose } from "./diagnose.js";
+
+/**
+ * Quick summary: one-line score output for any input.
+ * Designed for scripting, CI, and quick checks.
+ *
+ * Output format: SCORE/100 LABEL INPUT
+ * Example: 72/100 Moderate https://example.com
+ */
+
+export async function quickSummary(input, options = {}) {
+  const result = await diagnose(input, options);
+
+  return {
+    kind: "geo-summary",
+    input,
+    score: result.score,
+    label: result.scoreLabel,
+    type: result.analysisType,
+    oneLiner: `${result.score}/100 ${result.scoreLabel} ${input}`,
+    topIssue: result.quickWins[0] || null,
+    nextCommand: result.nextCommands[0]?.cmd || null
+  };
+}
+
+export function renderSummaryMarkdown(report) {
+  return `${report.score}/100 (${report.label}) — ${report.input}${report.topIssue ? `\nTop issue: ${report.topIssue}` : ""}\n`;
+}