geo-ai-search-optimization 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "2.3.0",
+  "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

@@ -57,6 +57,8 @@ 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";
 
 export const SITE_OPS_HELP_LINES = [
   "  geo-ai-search-optimization doctor [--json]",
@@ -104,7 +106,9 @@ 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>",
+  "  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;
@@ -710,6 +714,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) => {
@@ -915,5 +947,7 @@ export const SITE_OPS_COMMAND_HANDLERS = {
   diagnose: handleDiagnose,
   compare: handleCompareCsv,
   "deep-benchmark": handleDeepBenchmark,
-  summary: handleSummary
+  summary: handleSummary,
+  explain: handleExplain,
+  monitor: handleMonitor
 };

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/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

@@ -89,4 +89,6 @@ export { deepBenchmark, renderDeepBenchmarkMarkdown, writeDeepBenchmarkOutput }
 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);
+}