geo-ai-search-optimization 2.3.0 → 2.5.0

package/README.md

@@ -193,7 +193,7 @@ Full TypeScript declarations included (`index.d.ts`) — 230+ exports with IDE a
 ## GitHub Action
 
 ```yaml
-- uses: redredchen01/geo-ai-search-optimization@v2.2.0
+- uses: redredchen01/geo-ai-search-optimization@v2.5.0
   with:
     project-path: ./your-project
     min-score: 60

package/action.yml

@@ -51,23 +51,24 @@ runs:
 
     - name: Install geo-ai-search-optimization
       shell: bash
-      run: npm install -g geo-ai-search-optimization
+      run: npm install -g geo-ai-search-optimization@2.5.0
 
     - name: Run GEO Audit
       id: audit
       shell: bash
+      env:
+        PROJ_PATH: ${{ inputs.project-path }}
+        BASELINE: ${{ inputs.baseline }}
+        MIN_SCORE: ${{ inputs.min-score }}
+        FAIL_ON_REGRESSION: ${{ inputs.fail-on-regression }}
       run: |
-        PROJ_PATH="${{ inputs.project-path }}"
-        BASELINE="${{ inputs.baseline }}"
-        MIN_SCORE="${{ inputs.min-score }}"
-
         ARGS=("$PROJ_PATH" "--json")
 
         if [ -n "$BASELINE" ]; then
           ARGS+=("--baseline" "$BASELINE")
         fi
 
-        if [ "${{ inputs.fail-on-regression }}" = "true" ]; then
+        if [ "$FAIL_ON_REGRESSION" = "true" ]; then
           ARGS+=("--fail-on-regression")
         fi
 
@@ -99,14 +100,18 @@ runs:
     - name: Save Snapshot
       if: inputs.save-snapshot == 'true'
       shell: bash
+      env:
+        PROJ_PATH: ${{ inputs.project-path }}
       run: |
-        geo-ai-search-optimization audit "${{ inputs.project-path }}" --save --json > /dev/null 2>&1 || true
+        geo-ai-search-optimization audit "$PROJ_PATH" --save --json > /dev/null 2>&1 || true
 
     - name: Generate Markdown Report
       if: inputs.output-format == 'markdown'
       shell: bash
+      env:
+        PROJ_PATH: ${{ inputs.project-path }}
       run: |
-        geo-ai-search-optimization audit "${{ inputs.project-path }}" --out geo-audit-report.md || true
+        geo-ai-search-optimization audit "$PROJ_PATH" --out geo-audit-report.md || true
 
     - name: Post Summary
       if: always()

package/package.json

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

package/src/auto-fix.js

@@ -1,5 +1,3 @@
-import fs from "node:fs/promises";
-import path from "node:path";
 import { writeScanOutput } from "./scan.js";
 import { auditPage } from "./page-audit.js";
 
@@ -50,10 +48,14 @@ function generateMetaTags(metadata, signals) {
   return tags;
 }
 
+function escapeHtmlAttr(str) {
+  return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
 function generateOgTags(metadata) {
-  const title = metadata.title || "Your Page Title";
-  const description = metadata.metaDescription || "A concise description of your page.";
-  const url = metadata.canonical || "https://yoursite.com/this-page";
+  const title = escapeHtmlAttr(metadata.title || "Your Page Title");
+  const description = escapeHtmlAttr(metadata.metaDescription || "A concise description of your page.");
+  const url = escapeHtmlAttr(metadata.canonical || "https://yoursite.com/this-page");
 
   return [
     { tag: "og:title", html: `<meta property="og:title" content="${title}">` },

package/src/batch-full-page-audit.js

@@ -66,7 +66,7 @@ export async function batchFullPageAudit(urls, options = {}) {
   const commonIssues = Object.entries(issueCounts)
     .sort((a, b) => b[1] - a[1])
     .slice(0, 10)
-    .map(([issue, count]) => ({ issue, count, percentage: Math.round((count / results.length) * 100) }));
+    .map(([issue, count]) => ({ issue, count, percentage: results.length > 0 ? Math.round((count / results.length) * 100) : 0 }));
 
   return {
     kind: "geo-batch-full-page-audit",
@@ -116,7 +116,8 @@ export function renderBatchFullPageAuditMarkdown(report) {
 
   lines.push("", "## Page Results", "", "| Page | Composite | Label |", "|------|-----------|-------|");
   for (const result of report.results) {
-    const short = result.input.length > 50 ? `...${result.input.slice(-47)}` : result.input;
+    const inputStr = result.input || "";
+    const short = inputStr.length > 50 ? `...${inputStr.slice(-47)}` : inputStr;
     const icon = result.compositeScore >= 70 ? "🟢" : result.compositeScore >= 40 ? "🟡" : "🔴";
     lines.push(`| ${short} | ${icon} ${result.compositeScore}/100 | ${result.compositeLabel} |`);
   }

package/src/citability.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { fetchText } from "./fetch-utils.js";
 import { writeScanOutput } from "./scan.js";
 
 function stripHtml(text) {
@@ -198,22 +199,12 @@ function buildRecommendations(claims, entities, quotable, structure, wordCount)
   return recs;
 }
 
-async function fetchContent(url) {
-  const response = await fetch(url, {
-    redirect: "follow",
-    headers: { "user-agent": "geo-ai-search-optimization/2.2.0" },
-    signal: AbortSignal.timeout(10_000)
-  });
-  if (!response.ok) throw new Error(`Failed to fetch: ${url} (status ${response.status})`);
-  return response.text();
-}
-
 export async function analyzeCitability(input, options = {}) {
   let rawContent;
   let source;
 
   if (/^https?:\/\//i.test(input)) {
-    rawContent = await fetchContent(input);
+    rawContent = await fetchText(input);
     source = input;
   } else {
     const filePath = path.resolve(input);

package/src/citation-check.js

@@ -1,3 +1,4 @@
+import { fetchTextSafe } from "./fetch-utils.js";
 import { writeScanOutput } from "./scan.js";
 
 const DEFAULT_ENGINES = ["perplexity", "google"];
@@ -19,23 +20,11 @@ function extractDomain(siteUrl) {
 }
 
 async function fetchWithTimeout(url, timeoutMs = 10000) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const response = await fetch(url, {
-      signal: controller.signal,
-      headers: {
-        "user-agent": "geo-ai-search-optimization/2.2.0"
-      },
-      redirect: "follow"
-    });
-    const text = await response.text();
-    return { ok: response.ok, status: response.status, text };
-  } catch (error) {
-    return { ok: false, status: 0, text: "", error: error.message };
-  } finally {
-    clearTimeout(timer);
+  const result = await fetchTextSafe(url, { timeout: timeoutMs });
+  if (result.ok) {
+    return { ok: true, status: 200, text: result.text };
   }
+  return { ok: false, status: 0, text: "", error: result.error };
 }
 
 function checkTextForCitation(text, domain) {

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

@@ -57,6 +57,12 @@ import { comparePages, renderCompareMarkdown, writeCompareOutput } from "./compa
 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";
+import { analyzeLinkQuality, renderLinkQualityMarkdown, writeLinkQualityOutput } from "./link-quality.js";
+import { analyzeContentFreshness, renderContentFreshnessMarkdown, writeContentFreshnessOutput } from "./content-freshness.js";
+import { trackCompetitors, renderCompetitorTrackingMarkdown, writeCompetitorTrackingOutput } from "./competitor-tracking.js";
+import { generateLlmsTxt, optimizeLlmsTxt, renderGenerateLlmsMarkdown, renderOptimizeLlmsMarkdown, writeGenerateLlmsOutput, writeOptimizeLlmsOutput } from "./optimize-llms.js";
 
 export const SITE_OPS_HELP_LINES = [
   "  geo-ai-search-optimization doctor [--json]",
@@ -104,7 +110,14 @@ export const SITE_OPS_HELP_LINES = [
   "  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] [--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 summary <url-or-dir-or-file> [--json]",
+  "  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>]",
+  "  geo-ai-search-optimization link-quality <url-or-file> [--base-url <url>] [--skip-broken-check] [--json] [--out <file>]",
+  "  geo-ai-search-optimization content-freshness <url-or-file> [--json] [--out <file>]",
+  "  geo-ai-search-optimization track-competitors <url> --competitors <url1,url2,...> [--concurrency <n>] [--data-dir <dir>] [--alert-threshold <n>] [--json] [--out <file>]",
+  "  geo-ai-search-optimization generate-llms <url-or-file> [--site-name <name>] [--site-url <url>] [--site-type <type>] [--json] [--out <file>]",
+  "  geo-ai-search-optimization optimize-llms <url-or-file> [--json] [--out <file>]"
 ];
 
 const passthroughWriteOutput = async (outputPath) => outputPath;
@@ -710,6 +723,34 @@ 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) => {
@@ -766,7 +807,7 @@ const handleCompare = createStructuredOutputCommandHandler({
   renderMarkdown: (report) => renderCompareMarkdown(report),
   writeOutput: writeCompareOutput,
   getOutputJson: (args) => {
-    if (hasFlag(args, "--csv")) return false; // Let renderMarkdown handle CSV
+    if (hasFlag(args, "--csv")) return false; // CSV handled by handleCompareCsv wrapper
     return hasFlag(args, "--json");
   }
 });
@@ -869,6 +910,83 @@ const handleFullAudit = createStructuredOutputCommandHandler({
   getOutputJson: (args) => hasFlag(args, "--json")
 });
 
+const handleLinkQuality = createStructuredOutputCommandHandler({
+  commandLabel: "link quality analysis",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("link-quality requires a URL or file path");
+    return analyzeLinkQuality(input, {
+      baseUrl: getFlagValue(args, "--base-url"),
+      skipBrokenCheck: hasFlag(args, "--skip-broken-check")
+    });
+  },
+  renderMarkdown: renderLinkQualityMarkdown,
+  writeOutput: writeLinkQualityOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleContentFreshness = createStructuredOutputCommandHandler({
+  commandLabel: "content freshness analysis",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("content-freshness requires a URL or file path");
+    return analyzeContentFreshness(input);
+  },
+  renderMarkdown: renderContentFreshnessMarkdown,
+  writeOutput: writeContentFreshnessOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleTrackCompetitors = createStructuredOutputCommandHandler({
+  commandLabel: "competitor tracking",
+  execute: async (args) => {
+    const ownUrl = args.find((value) => !value.startsWith("-"));
+    if (!ownUrl) throw new Error("track-competitors requires your URL as the first argument");
+    const competitorsRaw = getFlagValue(args, "--competitors");
+    if (!competitorsRaw) throw new Error("track-competitors requires --competitors <url1,url2,...>");
+    const competitorUrls = competitorsRaw.split(",").map((u) => u.trim()).filter(Boolean);
+    const concurrencyValue = getFlagValue(args, "--concurrency");
+    const alertThresholdValue = getFlagValue(args, "--alert-threshold");
+    return trackCompetitors(ownUrl, competitorUrls, {
+      concurrency: concurrencyValue ? parsePositiveInteger(concurrencyValue, "--concurrency") : 2,
+      dataDir: getFlagValue(args, "--data-dir"),
+      alertThreshold: alertThresholdValue ? parsePositiveInteger(alertThresholdValue, "--alert-threshold") : 10
+    });
+  },
+  renderMarkdown: renderCompetitorTrackingMarkdown,
+  writeOutput: writeCompetitorTrackingOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleGenerateLlms = createStructuredOutputCommandHandler({
+  commandLabel: "generate-llms",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("generate-llms requires a URL or file path");
+    return generateLlmsTxt(input, {
+      siteName: getFlagValue(args, "--site-name"),
+      siteUrl: getFlagValue(args, "--site-url"),
+      siteType: getFlagValue(args, "--site-type"),
+      outputPath: getFlagValue(args, "--out")
+    });
+  },
+  renderMarkdown: renderGenerateLlmsMarkdown,
+  writeOutput: writeGenerateLlmsOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleOptimizeLlms = createStructuredOutputCommandHandler({
+  commandLabel: "optimize-llms",
+  execute: async (args) => {
+    const input = args.find((value) => !value.startsWith("-"));
+    if (!input) throw new Error("optimize-llms requires a URL or file path");
+    return optimizeLlmsTxt(input);
+  },
+  renderMarkdown: renderOptimizeLlmsMarkdown,
+  writeOutput: writeOptimizeLlmsOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
 export const SITE_OPS_COMMAND_HANDLERS = {
   doctor: handleDoctor,
   "quick-start": handleQuickStart,
@@ -915,5 +1033,12 @@ export const SITE_OPS_COMMAND_HANDLERS = {
   diagnose: handleDiagnose,
   compare: handleCompareCsv,
   "deep-benchmark": handleDeepBenchmark,
-  summary: handleSummary
+  summary: handleSummary,
+  explain: handleExplain,
+  monitor: handleMonitor,
+  "link-quality": handleLinkQuality,
+  "content-freshness": handleContentFreshness,
+  "track-competitors": handleTrackCompetitors,
+  "generate-llms": handleGenerateLlms,
+  "optimize-llms": handleOptimizeLlms
 };

package/src/compare.js

@@ -42,8 +42,8 @@ export async function comparePages(inputA, inputB, options = {}) {
     };
   }
 
-  const compositeA = resultA.compositeScore;
-  const compositeB = resultB.compositeScore;
+  const compositeA = resultA.compositeScore ?? 0;
+  const compositeB = resultB.compositeScore ?? 0;
   const compositeDelta = compositeA - compositeB;
 
   // Identify where each page is stronger
@@ -60,10 +60,10 @@ export async function comparePages(inputA, inputB, options = {}) {
   // Platform comparison
   const platformComparison = [];
   if (resultA.platformSummary && resultB.platformSummary) {
-    for (let i = 0; i < resultA.platformSummary.length; i++) {
-      const pA = resultA.platformSummary[i];
-      const pB = resultB.platformSummary[i];
-      if (pA && pB) {
+    const platformMapB = new Map(resultB.platformSummary.map((p) => [p.platform, p]));
+    for (const pA of resultA.platformSummary) {
+      const pB = platformMapB.get(pA.platform);
+      if (pB) {
         platformComparison.push({
           platform: pA.platform,
           scoreA: pA.score,

package/src/competitor-tracking.js

@@ -0,0 +1,275 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fullPageAudit } from "./full-page-audit.js";
+import { writeScanOutput } from "./scan.js";
+
+const DEFAULT_DATA_DIR = ".geo-data/competitor-tracking";
+
+function sanitizeKey(input) {
+  return input
+    .replace(/^https?:\/\//, "")
+    .replace(/[^a-zA-Z0-9.-]/g, "_")
+    .replace(/_+/g, "_")
+    .slice(0, 120);
+}
+
+function compositeLabel(score) {
+  if (score >= 80) return "Strong";
+  if (score >= 60) return "Moderate";
+  if (score >= 40) return "Weak";
+  return "Very weak";
+}
+
+async function runAuditsWithConcurrency(urls, concurrency, options) {
+  const results = new Map();
+  const queue = [...urls];
+  const running = [];
+
+  async function next() {
+    if (queue.length === 0) return;
+    const url = queue.shift();
+    try {
+      const audit = await fullPageAudit(url, options);
+      results.set(url, { ok: true, audit });
+    } catch (err) {
+      results.set(url, { ok: false, error: err.message });
+    }
+    await next();
+  }
+
+  for (let i = 0; i < Math.min(concurrency, queue.length); i++) {
+    running.push(next());
+  }
+  await Promise.all(running);
+  return results;
+}
+
+async function loadSnapshots(dataDir, ownKey) {
+  const dir = path.join(dataDir, ownKey);
+  let files;
+  try {
+    files = await fs.readdir(dir);
+  } catch {
+    return [];
+  }
+  const jsonFiles = files.filter((f) => f.endsWith(".json")).sort();
+  const snapshots = [];
+  for (const file of jsonFiles) {
+    try {
+      const content = await fs.readFile(path.join(dir, file), "utf8");
+      snapshots.push(JSON.parse(content));
+    } catch {
+      // skip corrupt
+    }
+  }
+  return snapshots;
+}
+
+async function saveSnapshot(dataDir, ownKey, snapshot) {
+  const dir = path.join(dataDir, ownKey);
+  await fs.mkdir(dir, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  const filePath = path.join(dir, `${ts}.json`);
+  await fs.writeFile(filePath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+  return filePath;
+}
+
+export async function trackCompetitors(ownUrl, competitorUrls, options = {}) {
+  const dataDir = path.resolve(options.dataDir || DEFAULT_DATA_DIR);
+  const concurrency = options.concurrency || 2;
+  const alertThreshold = options.alertThreshold || 10;
+
+  const allUrls = [ownUrl, ...competitorUrls];
+  const auditResults = await runAuditsWithConcurrency(allUrls, concurrency, options);
+
+  const timestamp = new Date().toISOString();
+
+  // Own score
+  const ownResult = auditResults.get(ownUrl);
+  const ownScore = ownResult?.ok ? ownResult.audit.compositeScore : 0;
+
+  // Competitor scores
+  const competitorScores = competitorUrls.map((url) => {
+    const res = auditResults.get(url);
+    const score = res?.ok ? res.audit.compositeScore : 0;
+    return { url, score, label: compositeLabel(score) };
+  });
+
+  // Averages and ranking
+  const validCompScores = competitorScores.filter((c) => c.score > 0).map((c) => c.score);
+  const avgCompetitorScore = validCompScores.length > 0
+    ? Math.round(validCompScores.reduce((a, b) => a + b, 0) / validCompScores.length)
+    : 0;
+  const scoreDelta = ownScore - avgCompetitorScore;
+
+  // Rank: 1 = best
+  const allScores = [{ url: ownUrl, score: ownScore }, ...competitorScores];
+  allScores.sort((a, b) => b.score - a.score);
+  const ownRank = allScores.findIndex((s) => s.url === ownUrl) + 1;
+
+  // Load history
+  const ownKey = sanitizeKey(ownUrl);
+  const previousSnapshots = await loadSnapshots(dataDir, ownKey);
+
+  // Build snapshot data to save
+  const snapshotData = {
+    timestamp,
+    ownUrl,
+    ownScore,
+    competitorScores: competitorScores.map((c) => ({ url: c.url, score: c.score }))
+  };
+
+  const snapshotPath = await saveSnapshot(dataDir, ownKey, snapshotData);
+
+  // All snapshots including current
+  const allSnapshots = [...previousSnapshots, snapshotData];
+
+  // History
+  let history;
+  if (allSnapshots.length <= 1) {
+    history = {
+      trackingCount: allSnapshots.length,
+      firstTracked: timestamp,
+      latestTracked: timestamp,
+      ownTrend: [{ date: timestamp, score: ownScore }],
+      competitorTrends: {}
+    };
+  } else {
+    const ownTrend = allSnapshots.map((s) => ({ date: s.timestamp, score: s.ownScore }));
+    const competitorTrends = {};
+    for (const comp of competitorUrls) {
+      competitorTrends[comp] = allSnapshots
+        .map((s) => {
+          const found = s.competitorScores?.find((c) => c.url === comp);
+          return found ? { date: s.timestamp, score: found.score } : null;
+        })
+        .filter(Boolean);
+    }
+    history = {
+      trackingCount: allSnapshots.length,
+      firstTracked: allSnapshots[0].timestamp,
+      latestTracked: timestamp,
+      ownTrend,
+      competitorTrends
+    };
+  }
+
+  // Alerts
+  const alerts = [];
+  if (previousSnapshots.length > 0) {
+    const lastSnapshot = previousSnapshots[previousSnapshots.length - 1];
+    const lastOwnScore = lastSnapshot.ownScore;
+
+    // Own score dropped
+    if (lastOwnScore - ownScore >= alertThreshold) {
+      alerts.push({
+        type: "score-drop",
+        message: `Own score dropped from ${lastOwnScore} to ${ownScore} (delta: ${ownScore - lastOwnScore})`,
+        url: ownUrl,
+        delta: ownScore - lastOwnScore
+      });
+    }
+
+    // Own score improved
+    if (ownScore - lastOwnScore >= alertThreshold) {
+      alerts.push({
+        type: "improvement",
+        message: `Own score improved from ${lastOwnScore} to ${ownScore} (delta: +${ownScore - lastOwnScore})`,
+        url: ownUrl,
+        delta: ownScore - lastOwnScore
+      });
+    }
+  }
+
+  // Competitor overtook own score
+  for (const comp of competitorScores) {
+    if (comp.score > ownScore) {
+      alerts.push({
+        type: "overtaken",
+        message: `${comp.url} (${comp.score}) has overtaken own score (${ownScore})`,
+        url: comp.url,
+        delta: comp.score - ownScore
+      });
+    }
+  }
+
+  const summary = `Own: ${ownScore}/100 (${compositeLabel(ownScore)}), Rank: ${ownRank}/${allScores.length}, vs avg competitor: ${avgCompetitorScore} (delta: ${scoreDelta >= 0 ? "+" : ""}${scoreDelta}). ${alerts.length} alert(s).`;
+
+  return {
+    kind: "geo-competitor-tracking",
+    ownUrl,
+    competitorUrls,
+    timestamp,
+    ownScore,
+    competitorScores,
+    avgCompetitorScore,
+    scoreDelta,
+    ownRank,
+    history,
+    alerts,
+    snapshotPath,
+    summary
+  };
+}
+
+export function renderCompetitorTrackingMarkdown(report) {
+  const lines = [
+    "# GEO Competitor Tracking",
+    "",
+    `- Own URL: \`${report.ownUrl}\``,
+    `- Competitors: ${report.competitorUrls.length}`,
+    `- Timestamp: ${report.timestamp}`,
+    `- **Own Score: ${report.ownScore}/100 (${compositeLabel(report.ownScore)})**`,
+    `- Avg Competitor Score: ${report.avgCompetitorScore}`,
+    `- Score Delta (own - avg): ${report.scoreDelta >= 0 ? "+" : ""}${report.scoreDelta}`,
+    `- Rank: ${report.ownRank} / ${report.competitorScores.length + 1}`,
+    "",
+    "## Competitor Scores",
+    "",
+    "| URL | Score | Label |",
+    "|-----|-------|-------|"
+  ];
+
+  for (const comp of report.competitorScores) {
+    lines.push(`| ${comp.url} | ${comp.score}/100 | ${comp.label} |`);
+  }
+
+  if (report.alerts.length > 0) {
+    lines.push("", "## Alerts", "");
+    for (const alert of report.alerts) {
+      const icon = alert.type === "score-drop" ? "🔴" : alert.type === "improvement" ? "🟢" : "🟡";
+      lines.push(`- ${icon} **${alert.type}**: ${alert.message}`);
+    }
+  }
+
+  if (report.history) {
+    lines.push("", "## History", "");
+    lines.push(`- Tracking count: ${report.history.trackingCount}`);
+    lines.push(`- First tracked: ${report.history.firstTracked}`);
+    lines.push(`- Latest tracked: ${report.history.latestTracked}`);
+
+    if (report.history.ownTrend && report.history.ownTrend.length > 0) {
+      lines.push("", "### Own Score Trend", "");
+      for (const point of report.history.ownTrend) {
+        lines.push(`- \`${point.date.slice(0, 19)}\` — Score: **${point.score}**`);
+      }
+    }
+
+    if (report.history.competitorTrends && Object.keys(report.history.competitorTrends).length > 0) {
+      lines.push("", "### Competitor Trends", "");
+      for (const [url, trend] of Object.entries(report.history.competitorTrends)) {
+        lines.push(`**${url}**:`);
+        for (const point of trend) {
+          lines.push(`- \`${point.date.slice(0, 19)}\` — Score: **${point.score}**`);
+        }
+      }
+    }
+  }
+
+  lines.push("", `---`, "", `Summary: ${report.summary}`, "");
+  return lines.join("\n");
+}
+
+export async function writeCompetitorTrackingOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/config.js

@@ -90,15 +90,15 @@ export function mergeConfigWithOptions(config, cliOptions) {
   const merged = { ...cliOptions };
 
   if (config._found) {
-    if (config.site?.url && !merged.siteUrl) merged.siteUrl = config.site.url;
-    if (config.site?.name && !merged.siteName) merged.siteName = config.site.name;
+    if (config.site?.url && merged.siteUrl === undefined) merged.siteUrl = config.site.url;
+    if (config.site?.name && merged.siteName === undefined) merged.siteName = config.site.name;
     if (config.audit?.minScore !== undefined && merged.minScore === undefined) merged.minScore = config.audit.minScore;
     if (config.audit?.maxFileSize !== undefined && merged.maxFileSize === undefined) merged.maxFileSize = config.audit.maxFileSize;
     if (config.audit?.maxExamples !== undefined && merged.maxExamples === undefined) merged.maxExamples = config.audit.maxExamples;
-    if (config.ci?.failOnRegression && merged.failOnRegression === undefined) merged.failOnRegression = config.ci.failOnRegression;
-    if (config.output?.format && !merged.format) merged.format = config.output.format;
-    if (config.output?.dataDir && !merged.dataDir) merged.dataDir = config.output.dataDir;
-    if (config.crawlers?.strategy && !merged.strategy) merged.strategy = config.crawlers.strategy;
+    if (config.ci?.failOnRegression !== undefined && merged.failOnRegression === undefined) merged.failOnRegression = config.ci.failOnRegression;
+    if (config.output?.format && merged.format === undefined) merged.format = config.output.format;
+    if (config.output?.dataDir && merged.dataDir === undefined) merged.dataDir = config.output.dataDir;
+    if (config.crawlers?.strategy && merged.strategy === undefined) merged.strategy = config.crawlers.strategy;
   }
 
   return merged;