aeorank 3.1.1 → 3.2.1

package/dist/cli.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
+import {
+  isSafeFetchTarget,
+  isSafePublicUrl,
+  normalizeHostname,
+  safeFetch
+} from "./chunk-PYV5JVTC.js";
 
 // src/cli.ts
 import { writeFileSync } from "fs";
@@ -145,19 +151,181 @@ function shingleJaccardSimilarity(a, b) {
   return union === 0 ? 0 : intersection / union;
 }
 
+// src/helpful-content.ts
+function cap(value, max) {
+  return Math.min(max, value);
+}
+function floor(value, min) {
+  return Math.max(min, value);
+}
+function countMatches(text, pattern) {
+  return text.match(pattern)?.length ?? 0;
+}
+function stripScriptsAndStyles(html) {
+  return html.replace(/<script[\s\S]*?<\/script>/gi, " ").replace(/<style[\s\S]*?<\/style>/gi, " ");
+}
+function getTextContent(html) {
+  return stripScriptsAndStyles(html).replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+}
+function getBodyHtml(html) {
+  const bodyMatch = html.match(/<body[^>]*>([\s\S]*?)<\/body>/i);
+  return bodyMatch ? bodyMatch[1] : html;
+}
+function getFirstParagraphText(html) {
+  const firstPara = getBodyHtml(html).match(/<p[^>]*>([\s\S]*?)<\/p>/i);
+  return firstPara ? firstPara[1].replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim() : "";
+}
+function firstNWords(text, count) {
+  return text.split(/\s+/).slice(0, count).join(" ");
+}
+function getH1Text(html) {
+  const match = html.match(/<h1[^>]*>([\s\S]*?)<\/h1>/i);
+  return match ? match[1].replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim() : "";
+}
+function getTitleText(html) {
+  const match = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  return match ? match[1].replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim() : "";
+}
+function wordCount(text) {
+  return text ? text.split(/\s+/).filter(Boolean).length : 0;
+}
+function isContentLikePage(html, url) {
+  const text = getTextContent(html);
+  const wc = wordCount(text);
+  let signals = 0;
+  if (url && /\/(?:blog|article|articles|guide|guides|docs|learn|help|news|insights|resources|how-to|tutorial|case-stud|whitepaper|faq)\b/i.test(url)) {
+    signals += 2;
+  }
+  if (/<article[\s>]/i.test(html)) signals += 1;
+  if ((html.match(/<h[2-3][^>]*>/gi) || []).length >= 2) signals += 1;
+  if (wc >= 500) signals += 1;
+  if (/<time[\s>]/i.test(html) || /datePublished|dateModified/i.test(html)) signals += 1;
+  if (/written\s+by|authored?\s+by|reviewed\s+by|medically\s+reviewed/i.test(text)) signals += 1;
+  return signals >= 2;
+}
+function expectsMethodology(html, url) {
+  const text = getTextContent(html);
+  const title = `${getTitleText(html)} ${getH1Text(html)}`.toLowerCase();
+  const urlText = (url || "").toLowerCase();
+  if (/(?:review|compare|comparison|vs\.?|best|benchmark|study|analysis|survey|report|research|tested|test|methodology)/i.test(title)) {
+    return true;
+  }
+  if (/(?:review|compare|comparison|benchmark|study|analysis|survey|research|report|best)/i.test(urlText)) {
+    return true;
+  }
+  return /\b(methodology|how we tested|how we reviewed|our testing|sample size|dataset|benchmark|editorial policy|review process)\b/i.test(text);
+}
+function titleAndBodyAlign(html) {
+  const h1 = getH1Text(html);
+  const title = getTitleText(html);
+  const text = firstNWords(getTextContent(html), 250).toLowerCase();
+  const topic = `${title} ${h1}`.toLowerCase();
+  const keywords = topic.split(/[\s|:()\-/]+/).filter((w) => w.length >= 5 && !/^(about|guide|complete|ultimate|best|learn|understand|what|when|where|which|their|there|these|those)$/i.test(w));
+  const uniqueKeywords = [...new Set(keywords)];
+  if (uniqueKeywords.length === 0) return false;
+  return uniqueKeywords.filter((w) => text.includes(w)).length >= Math.min(2, uniqueKeywords.length);
+}
+var GENERIC_OPENERS = /^(?:in today'?s|it is important to understand|in this (?:article|guide|post)|whether you are|have you ever|welcome to|if you'?re looking|in the modern|in the digital age)/i;
+var PRACTICAL_LANGUAGE = /\b(?:here'?s what to do|choose\s+\w+\s+if|avoid\s+\w+\s+when|the main risk is|the fastest option is|next step(?:s)?|best option|lowest risk|good fit if|not a good fit if|what to do next)\b/gi;
+var TRADEOFF_LANGUAGE = /\b(?:however|but|trade-?off|caveat|limitation|downside|upside|risk|benefit|pros?\b|cons?\b|watch out|be careful|unless)\b/gi;
+var FLUFF_LANGUAGE = /\b(?:comprehensive guide|ever-evolving|fast-paced world|unlock(?:ing)? the power|in conclusion|delve into|navigate the landscape|journey|seamless|robust solution)\b/gi;
+var EARLY_CTA_PATTERN = /\b(?:sign up|get started|book (?:a )?demo|contact us|schedule (?:a )?call|buy now|start free|request a quote|talk to sales|subscribe)\b/gi;
+var FIRST_HAND_ACTIONS = /\b(?:we|i)\s+(?:tested|used|reviewed|implemented|measured|compared|observed|deployed|migrated|surveyed|analyzed|audited|interviewed)\b/gi;
+var EXPERIENCE_CONTEXT = /\b(?:in our|during our|for our|in practice|in production|in the field|in our clinic|during implementation|over \d+\s+(?:days?|weeks?|months?)|across \d+\s+(?:accounts?|customers?|patients?|sites?|campaigns?)|with \d+\s+(?:participants?|users?|patients?|samples?))\b/gi;
+var EXPERIENCE_ARTIFACTS = /\b(?:screenshot|photo|benchmark|timeline|before\/after|our results|original chart|field note|walkthrough)\b/gi;
+var LIMITATION_LANGUAGE = /\b(?:limitation|limitations|we found that|we learned|one caveat|did not work|failed|issue we hit|edge case|unexpectedly|drawback)\b/gi;
+var AUTHOR_LINK_PATTERN = /<a[^>]*href=["'][^"']*\/(?:author|authors|team|people|staff|reviewers?)\b[^"']*["'][^>]*>/i;
+var BYLINE_PATTERN = /\b(?:written|authored|reviewed|edited|medically reviewed)\s+by\b/i;
+var AUTHOR_BIO_PATTERN = /\b(?:about the author|author bio|reviewed by|medically reviewed by|board-certified|licensed|credentials?|specializes in|specialist in)\b/i;
+var METHODOLOGY_TERMS = /\b(?:methodology|how we tested|how we reviewed|our methodology|testing process|review process|editorial policy|sample size|data collection|timeframe|criteria used|tools used|benchmark method|updated using|last reviewed|ai-assisted|ai assisted)\b/gi;
+var METHODOLOGY_DETAIL = /\b(?:sample size|participants?|dataset|timeframe|criteria|weights?|tool(?:s)? used|measured over|tested over|reviewed on|last updated|last reviewed|scoring method)\b/gi;
+function scoreHelpfulPurposeAlignment(html, url) {
+  const text = getTextContent(html);
+  if (!text) return 0;
+  const contentLike = isContentLikePage(html, url);
+  if (!contentLike && wordCount(text) < 250) return 5;
+  let score = contentLike ? 3 : 5;
+  const firstPara = getFirstParagraphText(html);
+  const earlyText = firstNWords(text, 300);
+  const bodyHtml = getBodyHtml(html);
+  if (firstPara && !GENERIC_OPENERS.test(firstPara)) score += 2;
+  if (countMatches(earlyText, PRACTICAL_LANGUAGE) >= 1) score += 2;
+  else if (countMatches(text, PRACTICAL_LANGUAGE) >= 2) score += 1;
+  const tradeoffCount = countMatches(text, TRADEOFF_LANGUAGE);
+  if (tradeoffCount >= 2) score += 2;
+  else if (tradeoffCount >= 1) score += 1;
+  if (titleAndBodyAlign(html)) score += 1;
+  if (/\b(?:bottom line|key takeaway|here'?s the short answer|next steps?)\b/i.test(text)) score += 1;
+  if (firstPara && GENERIC_OPENERS.test(firstPara)) score -= 2;
+  const earlyBodyHtml = bodyHtml.slice(0, 1800);
+  const earlyCtas = countMatches(earlyBodyHtml, EARLY_CTA_PATTERN);
+  if (earlyCtas >= 3) score -= 2;
+  else if (earlyCtas >= 2) score -= 1;
+  const fluffCount = countMatches(text, FLUFF_LANGUAGE);
+  if (fluffCount >= 3) score -= 2;
+  else if (fluffCount >= 1) score -= 1;
+  return floor(cap(score, 10), 0);
+}
+function scoreFirstHandExperienceSignals(html, url) {
+  const text = getTextContent(html);
+  if (!text) return 0;
+  const contentLike = isContentLikePage(html, url);
+  let score = contentLike ? 2 : 5;
+  const actionCount = countMatches(text, FIRST_HAND_ACTIONS);
+  if (actionCount >= 3) score += 4;
+  else if (actionCount >= 1) score += 2;
+  const contextCount = countMatches(text, EXPERIENCE_CONTEXT);
+  if (contextCount >= 2) score += 2;
+  else if (contextCount >= 1) score += 1;
+  const artifactCount = countMatches(text, EXPERIENCE_ARTIFACTS) + countMatches(html, /<figure|<figcaption/gi);
+  if (artifactCount >= 3) score += 2;
+  else if (artifactCount >= 1) score += 1;
+  const limitationCount = countMatches(text, LIMITATION_LANGUAGE);
+  if (limitationCount >= 2) score += 2;
+  else if (limitationCount >= 1) score += 1;
+  if (/\b(?:manufacturer|vendor)\s+(?:description|specification|copy)\b/i.test(text)) score -= 1;
+  return floor(cap(score, 10), 0);
+}
+function scoreCreatorTransparency(html, url) {
+  const text = getTextContent(html);
+  if (!text) return 0;
+  const contentLike = isContentLikePage(html, url);
+  if (!contentLike) return 5;
+  let score = 0;
+  const hasByline = BYLINE_PATTERN.test(text) || /class=["'][^"']*author[^"']*["']/i.test(html) || /rel=["']author["']/i.test(html);
+  const hasPersonSchema = /"@type"\s*:\s*"Person"/i.test(html);
+  if (hasByline) score += 3;
+  if (AUTHOR_LINK_PATTERN.test(html)) score += 2;
+  if (AUTHOR_BIO_PATTERN.test(text)) score += 2;
+  if (/\b(?:reviewed by|edited by|medically reviewed by)\b/i.test(text)) score += 1;
+  if (hasPersonSchema) score += 2;
+  return floor(cap(score, 10), 0);
+}
+function scoreMethodologyTransparency(html, url) {
+  const text = getTextContent(html);
+  if (!text) return 0;
+  const contentLike = isContentLikePage(html, url);
+  const expected = expectsMethodology(html, url);
+  let score = expected ? 2 : contentLike ? 5 : 5;
+  const methodologyCount = countMatches(text, METHODOLOGY_TERMS);
+  if (methodologyCount >= 2) score += 3;
+  else if (methodologyCount >= 1) score += 2;
+  const detailCount = countMatches(text, METHODOLOGY_DETAIL);
+  if (detailCount >= 3) score += 3;
+  else if (detailCount >= 2) score += 2;
+  else if (detailCount >= 1) score += 1;
+  if (/\b(?:tested|reviewed|analyzed)\s+\d+|\bacross\s+\d+|\bover\s+\d+\s+(?:days?|weeks?|months?)|\busing\s+\d+\s+\w+/i.test(text)) score += 1;
+  if (/<figure|<table/i.test(html) && methodologyCount >= 1) score += 1;
+  if (/\b(?:ai-assisted|ai assisted|reviewed by an editor|human reviewed)\b/i.test(text)) score += 1;
+  return floor(cap(score, 10), 0);
+}
+
 // src/site-crawler.ts
-async function fetchText(url) {
-  try {
-    const res = await fetch(url, {
-      signal: AbortSignal.timeout(15e3),
-      headers: { "User-Agent": "AEO-Visibility-Bot/1.0" },
-      redirect: "follow"
-    });
-    const text = await res.text();
-    return { text: text.slice(0, 5e5), status: res.status, finalUrl: res.url };
-  } catch {
-    return null;
-  }
+async function fetchText(url, expectedDomain) {
+  const res = await safeFetch(url, { timeoutMs: 15e3, expectedDomain });
+  if (!res) return null;
+  const text = await res.text();
+  return { text: text.slice(0, 5e5), status: res.status, finalUrl: res.url };
 }
 function extractDomain(url) {
   return url.replace(/^https?:\/\//, "").replace(/\/.*/, "").replace(/:[0-9]+$/, "").replace(/^www\./, "").toLowerCase();
@@ -198,13 +366,16 @@ function isHtmlResponse(result) {
   return trimmed.startsWith("<!doctype html") || trimmed.startsWith("<html") || /<head[\s>]/i.test(trimmed);
 }
 async function prefetchSiteData(domain) {
+  if (!await isSafeFetchTarget(`https://${domain}`)) {
+    return { domain, protocol: null, homepage: null, llmsTxt: null, robotsTxt: null, faqPage: null, sitemapXml: null, rssFeed: null, aiTxt: null, redirectedTo: null, parkedReason: null, blogSample: [] };
+  }
   let protocol = null;
   let homepage = null;
-  homepage = await fetchText(`https://${domain}`);
+  homepage = await fetchText(`https://${domain}`, domain);
   if (homepage && homepage.status >= 200 && homepage.status < 400) {
     protocol = "https";
   } else {
-    homepage = await fetchText(`http://${domain}`);
+    homepage = await fetchText(`http://${domain}`, domain);
     if (homepage && homepage.status >= 200 && homepage.status < 400) {
       protocol = "http";
     }
@@ -224,38 +395,38 @@ async function prefetchSiteData(domain) {
   }
   const baseUrl = `${protocol}://${domain}`;
   const [llmsTxt, robotsTxt, faqPage, sitemapXml, aiTxt] = await Promise.all([
-    fetchText(`${baseUrl}/llms.txt`),
-    fetchText(`${baseUrl}/robots.txt`),
-    fetchText(`${baseUrl}/faq`).then(async (result) => {
+    fetchText(`${baseUrl}/llms.txt`, domain),
+    fetchText(`${baseUrl}/robots.txt`, domain),
+    fetchText(`${baseUrl}/faq`, domain).then(async (result) => {
       if (result && result.status === 200) return result;
       for (const path of ["/frequently-asked-questions", "/help", "/support", "/help-center"]) {
-        const fallback = await fetchText(`${baseUrl}${path}`);
+        const fallback = await fetchText(`${baseUrl}${path}`, domain);
         if (fallback && fallback.status === 200) return fallback;
       }
       return result;
     }),
-    fetchText(`${baseUrl}/sitemap.xml`),
-    fetchText(`${baseUrl}/ai.txt`)
+    fetchText(`${baseUrl}/sitemap.xml`, domain),
+    fetchText(`${baseUrl}/ai.txt`, domain)
   ]);
   let rssFeed = null;
   if (homepage) {
     const rssLinkMatch = homepage.text.match(/<link[^>]*type="application\/(?:rss|atom)\+xml"[^>]*href="([^"]*)"[^>]*>/i);
     if (rssLinkMatch) {
       const rssUrl = rssLinkMatch[1].startsWith("http") ? rssLinkMatch[1] : `${baseUrl}${rssLinkMatch[1]}`;
-      rssFeed = await fetchText(rssUrl);
+      rssFeed = await fetchText(rssUrl, domain);
     }
     if (!rssFeed || rssFeed.status !== 200) {
       for (const path of ["/feed", "/rss.xml", "/feed.xml"]) {
-        rssFeed = await fetchText(`${baseUrl}${path}`);
+        rssFeed = await fetchText(`${baseUrl}${path}`, domain);
         if (rssFeed && rssFeed.status === 200 && (rssFeed.text.includes("<rss") || rssFeed.text.includes("<feed") || rssFeed.text.includes("<channel"))) break;
         rssFeed = null;
       }
     }
   }
   if (sitemapXml && sitemapXml.status === 200 && sitemapXml.text.includes("<sitemapindex")) {
-    const subUrls = extractAllSubSitemapUrls(sitemapXml.text, 5);
+    const subUrls = extractAllSubSitemapUrls(sitemapXml.text, domain, 5);
     if (subUrls.length > 0) {
-      const subResults = await Promise.all(subUrls.map((u) => fetchText(u)));
+      const subResults = await Promise.all(subUrls.map((u) => fetchText(u, domain)));
       for (const sub of subResults) {
         if (sub && sub.status === 200) {
           sitemapXml.text += "\n" + sub.text;
@@ -268,7 +439,7 @@ async function prefetchSiteData(domain) {
     const sitemapForBlog = sitemapXml.text;
     const blogUrls = extractBlogUrlsFromSitemap(sitemapForBlog, domain, 50);
     if (blogUrls.length > 0) {
-      const fetched = await Promise.all(blogUrls.map((url) => fetchText(url)));
+      const fetched = await Promise.all(blogUrls.map((url) => fetchText(url, domain)));
       blogSample = fetched.filter(
         (r) => r !== null && r.status === 200 && r.text.length > 500
       );
@@ -1050,8 +1221,8 @@ function checkDirectAnswerDensity(data) {
   const paragraphs = html.match(/<p[^>]*>([\s\S]*?)<\/p>/gi) || [];
   const snippetZoneParagraphs = paragraphs.filter((p) => {
     const text2 = p.replace(/<[^>]*>/g, "").trim();
-    const wordCount = text2.split(/\s+/).length;
-    return wordCount >= 40 && wordCount <= 150;
+    const wordCount2 = text2.split(/\s+/).length;
+    return wordCount2 >= 40 && wordCount2 <= 150;
   });
   if (snippetZoneParagraphs.length >= 3) {
     score += 2;
@@ -1319,13 +1490,15 @@ function extractBlogUrlsFromSitemap(sitemapText, domain, limit = 50) {
   });
   return candidates.slice(0, limit).map((c) => c.url);
 }
-function extractAllSubSitemapUrls(sitemapText, limit = 5) {
+function extractAllSubSitemapUrls(sitemapText, domainOrLimit, maybeLimit = 5) {
   if (!sitemapText.includes("<sitemapindex")) return [];
+  const domain = typeof domainOrLimit === "string" ? domainOrLimit : void 0;
+  const limit = typeof domainOrLimit === "number" ? domainOrLimit : maybeLimit;
   const sitemapLocs = sitemapText.match(/<sitemap>[\s\S]*?<loc>([^<]+)<\/loc>[\s\S]*?<\/sitemap>/gi) || [];
   const urls = sitemapLocs.map((block) => {
     const match = block.match(/<loc>([^<]+)<\/loc>/i);
     return match ? match[1].trim() : "";
-  }).filter(Boolean);
+  }).filter((url) => !!url && isSafePublicUrl(url, domain));
   const preferred = urls.filter((u) => /post|blog|article|page/i.test(u));
   const rest = urls.filter((u) => !preferred.includes(u));
   return [...preferred, ...rest].slice(0, limit);
@@ -2199,6 +2372,123 @@ function checkContentDepth(data, topicCoherenceScore) {
   }
   return { criterion: "content_depth", criterion_label: "Content Depth", score: finalScore, status: finalScore >= 7 ? "pass" : finalScore >= 4 ? "partial" : "fail", findings, fix_priority: finalScore >= 7 ? "P3" : "P1" };
 }
+function scoreSampledPages(data, scorer) {
+  const pages = [];
+  if (data.homepage) {
+    const url = data.homepage.finalUrl || (data.protocol ? `${data.protocol}://${data.domain}/` : `https://${data.domain}/`);
+    pages.push({ url, score: scorer(data.homepage.text, url) });
+  }
+  if (data.blogSample) {
+    for (const page of data.blogSample) {
+      const url = page.finalUrl || (data.protocol ? `${data.protocol}://${data.domain}/` : `https://${data.domain}/`);
+      pages.push({ url, score: scorer(page.text, url) });
+    }
+  }
+  return pages;
+}
+function summarizeHelpfulScores(pageScores) {
+  const total = pageScores.length;
+  const average = total > 0 ? Math.round(pageScores.reduce((sum, p) => sum + p.score, 0) / total) : 0;
+  const strong = pageScores.filter((p) => p.score >= 8);
+  const weak = pageScores.filter((p) => p.score <= 4);
+  return { total, average, strong, weak };
+}
+function checkHelpfulPurposeAlignment(data) {
+  const findings = [];
+  if (!data.homepage) {
+    findings.push({ severity: "critical", detail: "Could not fetch homepage" });
+    return { criterion: "helpful_purpose_alignment", criterion_label: "Helpful Purpose Alignment", score: 0, status: "not_found", findings, fix_priority: "P1" };
+  }
+  const pageScores = scoreSampledPages(data, scoreHelpfulPurposeAlignment);
+  const { total, average, strong, weak } = summarizeHelpfulScores(pageScores);
+  if (average >= 8) {
+    findings.push({ severity: "info", detail: `${strong.length}/${total} pages strongly prioritize visitor task completion over filler` });
+  } else if (average >= 5) {
+    findings.push({ severity: "low", detail: `${strong.length}/${total} pages clearly lead with useful guidance`, fix: "Tighten intros, reduce generic filler, and make pages solve the promised user task faster" });
+  } else {
+    findings.push({ severity: "medium", detail: `Average helpful-purpose score is ${average}/10 across ${total} sampled pages`, fix: "Reduce search-first framing, generic intros, and CTA interruptions before the first useful answer" });
+  }
+  if (weak.length > 0) {
+    findings.push({
+      severity: "low",
+      detail: `${weak.length} page(s) read as weakly task-focused`,
+      fix: "Rewrite weak pages to lead with concrete answers, tradeoffs, and next steps instead of broad introductory filler"
+    });
+  }
+  return { criterion: "helpful_purpose_alignment", criterion_label: "Helpful Purpose Alignment", score: average, status: average >= 7 ? "pass" : average >= 4 ? "partial" : "fail", findings, fix_priority: average >= 7 ? "P3" : "P1" };
+}
+function checkFirstHandExperienceSignals(data) {
+  const findings = [];
+  if (!data.homepage) {
+    findings.push({ severity: "critical", detail: "Could not fetch homepage" });
+    return { criterion: "first_hand_experience_signals", criterion_label: "First-Hand Experience Signals", score: 0, status: "not_found", findings, fix_priority: "P2" };
+  }
+  const pageScores = scoreSampledPages(data, scoreFirstHandExperienceSignals);
+  const { total, average, strong, weak } = summarizeHelpfulScores(pageScores);
+  if (average >= 8) {
+    findings.push({ severity: "info", detail: `${strong.length}/${total} pages show strong signs of direct use, testing, or observation` });
+  } else if (average >= 5) {
+    findings.push({ severity: "low", detail: `Moderate experiential depth across ${total} sampled pages`, fix: "Add real implementation details, limitations, screenshots, or direct observations where relevant" });
+  } else {
+    findings.push({ severity: "medium", detail: "Little first-hand experience is visible in sampled content", fix: "Add evidence of real use, testing, implementation, or lived experience instead of generic summaries" });
+  }
+  if (weak.length > 0) {
+    findings.push({
+      severity: "low",
+      detail: `${weak.length} page(s) appear generic or second-hand`,
+      fix: "Strengthen those pages with case details, lessons learned, or original evidence from practice"
+    });
+  }
+  return { criterion: "first_hand_experience_signals", criterion_label: "First-Hand Experience Signals", score: average, status: average >= 7 ? "pass" : average >= 4 ? "partial" : "fail", findings, fix_priority: average >= 7 ? "P3" : "P2" };
+}
+function checkCreatorTransparency(data) {
+  const findings = [];
+  if (!data.homepage) {
+    findings.push({ severity: "critical", detail: "Could not fetch homepage" });
+    return { criterion: "creator_transparency", criterion_label: "Creator Transparency", score: 0, status: "not_found", findings, fix_priority: "P2" };
+  }
+  const pageScores = scoreSampledPages(data, scoreCreatorTransparency);
+  const { total, average, strong, weak } = summarizeHelpfulScores(pageScores);
+  if (average >= 8) {
+    findings.push({ severity: "info", detail: `${strong.length}/${total} sampled pages provide clear visible creator attribution` });
+  } else if (average >= 5) {
+    findings.push({ severity: "low", detail: "Visible authorship is present on some content but inconsistent", fix: "Add bylines, author links, and reviewer details on article-like pages where readers expect them" });
+  } else {
+    findings.push({ severity: "medium", detail: "Creator visibility is weak on content-like pages", fix: "Show clear bylines, author pages, and reviewer context rather than relying on schema alone" });
+  }
+  if (weak.length > 0) {
+    findings.push({
+      severity: "low",
+      detail: `${weak.length} page(s) look article-like but expose little visible author context`,
+      fix: "Add visible bylines, author bios, or reviewer attribution to those pages"
+    });
+  }
+  return { criterion: "creator_transparency", criterion_label: "Creator Transparency", score: average, status: average >= 7 ? "pass" : average >= 4 ? "partial" : "fail", findings, fix_priority: average >= 7 ? "P3" : "P2" };
+}
+function checkMethodologyTransparency(data) {
+  const findings = [];
+  if (!data.homepage) {
+    findings.push({ severity: "critical", detail: "Could not fetch homepage" });
+    return { criterion: "methodology_transparency", criterion_label: "Methodology Transparency", score: 0, status: "not_found", findings, fix_priority: "P2" };
+  }
+  const pageScores = scoreSampledPages(data, scoreMethodologyTransparency);
+  const { total, average, strong, weak } = summarizeHelpfulScores(pageScores);
+  if (average >= 8) {
+    findings.push({ severity: "info", detail: `${strong.length}/${total} pages clearly explain how content was tested, researched, reviewed, or updated` });
+  } else if (average >= 5) {
+    findings.push({ severity: "low", detail: "Some process transparency exists, but it is inconsistent", fix: 'Add "how we tested", methodology, review process, or update disclosures on pages where users would expect them' });
+  } else {
+    findings.push({ severity: "medium", detail: "Little content-production or review transparency is visible", fix: "Explain how pages were researched, tested, or reviewed instead of presenting unsupported comparisons or conclusions" });
+  }
+  if (weak.length > 0) {
+    findings.push({
+      severity: "low",
+      detail: `${weak.length} page(s) lack visible methodology or review context`,
+      fix: "Add process detail such as sample size, criteria, tools used, review process, or update notes"
+    });
+  }
+  return { criterion: "methodology_transparency", criterion_label: "Methodology Transparency", score: average, status: average >= 7 ? "pass" : average >= 4 ? "partial" : "fail", findings, fix_priority: average >= 7 ? "P3" : "P2" };
+}
 function checkCitationReadyWriting(data) {
   const findings = [];
   if (!data.homepage) {
@@ -2294,8 +2584,8 @@ function checkAnswerFirstPlacement(data) {
     const earlyParagraphs = bodyHtml.match(/<p[^>]*>([\s\S]*?)<\/p>/gi)?.slice(0, 5) || [];
     for (const p of earlyParagraphs) {
       const pText = p.replace(/<[^>]*>/g, "").trim();
-      const wordCount = pText.split(/\s+/).length;
-      if (wordCount >= 40 && wordCount <= 80 && first300Words.includes(pText.slice(0, 50))) {
+      const wordCount2 = pText.split(/\s+/).length;
+      if (wordCount2 >= 40 && wordCount2 <= 80 && first300Words.includes(pText.slice(0, 50))) {
         shortAnswerCount++;
         break;
       }
@@ -2837,14 +3127,19 @@ function auditSiteFromData(data) {
     checkVisibleDateSignal(data),
     topicCoherence,
     checkContentDepth(data, topicCoherence.score),
-    // V2 criteria (#29-#34)
+    // Helpful-content criteria (#29-#32)
+    checkHelpfulPurposeAlignment(data),
+    checkFirstHandExperienceSignals(data),
+    checkCreatorTransparency(data),
+    checkMethodologyTransparency(data),
+    // V2 criteria (#33-#38)
     checkCitationReadyWriting(data),
     checkAnswerFirstPlacement(data),
     checkEvidencePackaging(data),
     checkEntityDisambiguation(data),
     checkExtractionFriction(data),
     checkImageContextAI(data),
-    // V3 criteria (#35-#36)
+    // V3 criteria (#39-#40)
     checkDuplicateContent(data),
     checkCrossPageDuplication(data)
   ];
@@ -2870,6 +3165,10 @@ var WEIGHTS = {
   // Relevance to actual AI queries
   faq_section: 0.03,
   // Structured Q&A pairs
+  helpful_purpose_alignment: 0.03,
+  // Visitor-helpful vs search-first framing
+  first_hand_experience_signals: 0.03,
+  // Evidence of real use or observation
   // ─── Content Organization (~30%) ──────────────────────────────────────────
   // HOW easily AI engines can extract and trust your content.
   entity_consistency: 0.05,
@@ -2884,9 +3183,13 @@ var WEIGHTS = {
   // Expert attribution
   table_list_extractability: 0.03,
   // Extractable structured data
-  definition_patterns: 0.02,
+  creator_transparency: 0.02,
+  // Visible author/reviewer clarity
+  methodology_transparency: 0.02,
+  // Process disclosure
+  definition_patterns: 0.015,
   // Clear definitions
-  visible_date_signal: 0.02,
+  visible_date_signal: 0.015,
   // Publication date trust
   semantic_html: 0.02,
   // Clean semantic structure
@@ -2895,15 +3198,15 @@ var WEIGHTS = {
   // ─── Technical Plumbing (~15%) ────────────────────────────────────────────
   // WHETHER AI crawlers can find you. Table stakes with diminishing returns.
   content_cannibalization: 0.02,
-  llms_txt: 0.02,
-  robots_txt: 0.02,
+  llms_txt: 0.01,
+  robots_txt: 0.01,
   content_velocity: 0.02,
-  content_licensing: 0.02,
+  content_licensing: 0.01,
   sitemap_completeness: 0.01,
-  canonical_url: 0.01,
-  rss_feed: 0.01,
-  schema_coverage: 0.01,
-  speakable_schema: 0.01,
+  canonical_url: 5e-3,
+  rss_feed: 5e-3,
+  schema_coverage: 5e-3,
+  speakable_schema: 5e-3,
   // ─── V2 Criteria (~15%) ───────────────────────────────────────────────────
   // Citation quality, evidence packaging, and extraction friction.
   citation_ready_writing: 0.04,
@@ -2916,7 +3219,7 @@ var WEIGHTS = {
   // Clear entity boundaries
   extraction_friction: 0.02,
   // Sentence length, voice, jargon
-  image_context_ai: 0.01,
+  image_context_ai: 5e-3,
   // Figure/figcaption, alt text quality
   // ─── V3 Criteria ────────────────────────────────────────────────────────
   duplicate_content: 0.05,
@@ -2936,8 +3239,8 @@ function calculateOverallScore(criteria) {
   let score = Math.round(weightedSum / totalWeight);
   const coherence = criteria.find((c) => c.criterion === "topic_coherence");
   if (coherence && coherence.score < 6) {
-    const cap2 = 35 + coherence.score * 5;
-    score = Math.min(score, cap2);
+    const cap3 = 35 + coherence.score * 5;
+    score = Math.min(score, cap3);
   }
   return score;
 }
@@ -2965,6 +3268,13 @@ function isSpaShell(html) {
   return SPA_INDICATORS.some((pattern) => pattern.test(html));
 }
 async function fetchWithHeadless(url, options) {
+  let expectedDomain;
+  try {
+    expectedDomain = normalizeHostname(new URL(url).hostname);
+  } catch {
+    return null;
+  }
+  if (!await isSafeFetchTarget(url, expectedDomain)) return null;
   let puppeteer;
   try {
     const mod = "puppeteer";
@@ -2991,12 +3301,28 @@ async function fetchWithHeadless(url, options) {
     const page = await browser.newPage();
     await page.setRequestInterception(true);
     page.on("request", (req) => {
-      const type = req.resourceType();
-      if (["image", "font", "media", "stylesheet"].includes(type)) {
-        req.abort();
-      } else {
-        req.continue();
-      }
+      void (async () => {
+        const alreadyHandled = typeof req.isInterceptResolutionHandled === "function" ? req.isInterceptResolutionHandled() : false;
+        if (alreadyHandled) return;
+        if (!await isSafeFetchTarget(req.url(), expectedDomain)) {
+          try {
+            if (!req.isInterceptResolutionHandled?.()) await req.abort();
+          } catch {
+          }
+          return;
+        }
+        const type = req.resourceType();
+        try {
+          if (!req.isInterceptResolutionHandled?.()) {
+            if (["image", "font", "media", "stylesheet"].includes(type)) {
+              await req.abort();
+            } else {
+              await req.continue();
+            }
+          }
+        } catch {
+        }
+      })();
     });
     await page.setUserAgent("AEO-Visibility-Bot/1.0");
     await page.goto(url, { waitUntil: "networkidle2", timeout });
@@ -3009,6 +3335,7 @@ async function fetchWithHeadless(url, options) {
     }
     const html = await page.content();
     const finalUrl = page.url();
+    if (!await isSafeFetchTarget(finalUrl, expectedDomain)) return null;
     return {
       text: html.slice(0, 5e5),
       status: 200,
@@ -3036,6 +3363,8 @@ var PILLARS = {
     "citation_ready_writing",
     "answer_first_placement",
     "evidence_packaging",
+    "helpful_purpose_alignment",
+    "first_hand_experience_signals",
     "duplicate_content",
     "cross_page_duplication"
   ],
@@ -3053,7 +3382,9 @@ var PILLARS = {
     "internal_linking",
     "content_freshness",
     "author_schema_depth",
-    "schema_markup"
+    "schema_markup",
+    "creator_transparency",
+    "methodology_transparency"
   ],
   "Technical Foundation": [
     "semantic_html",
@@ -3083,6 +3414,8 @@ var CLIENT_NAMES = {
   citation_ready_writing: "Citation-Ready Writing",
   answer_first_placement: "Answer-First Placement",
   evidence_packaging: "Evidence Packaging",
+  helpful_purpose_alignment: "Helpful Purpose Alignment",
+  first_hand_experience_signals: "First-Hand Experience Signals",
   direct_answer_density: "Direct Answer Density",
   qa_content_format: "Q&A Content Format",
   query_answer_alignment: "Query-Answer Alignment",
@@ -3095,6 +3428,8 @@ var CLIENT_NAMES = {
   content_freshness: "Content Freshness",
   author_schema_depth: "Author & Expert Schema",
   schema_markup: "Schema Markup",
+  creator_transparency: "Creator Transparency",
+  methodology_transparency: "Methodology Transparency",
   semantic_html: "Semantic HTML",
   clean_html: "Clean HTML",
   visible_date_signal: "Visible Date Signal",
@@ -3121,6 +3456,8 @@ var PILLAR_WEIGHTS = {
   citation_ready_writing: 0.04,
   answer_first_placement: 0.03,
   evidence_packaging: 0.03,
+  helpful_purpose_alignment: 0.03,
+  first_hand_experience_signals: 0.03,
   duplicate_content: 0.05,
   cross_page_duplication: 0.03,
   direct_answer_density: 0.05,
@@ -3128,28 +3465,30 @@ var PILLAR_WEIGHTS = {
   query_answer_alignment: 0.04,
   faq_section: 0.03,
   table_list_extractability: 0.03,
-  definition_patterns: 0.02,
+  definition_patterns: 0.015,
   entity_disambiguation: 0.02,
   entity_consistency: 0.05,
   internal_linking: 0.04,
   content_freshness: 0.04,
   author_schema_depth: 0.03,
   schema_markup: 0.03,
+  creator_transparency: 0.02,
+  methodology_transparency: 0.02,
   semantic_html: 0.02,
   clean_html: 0.02,
-  visible_date_signal: 0.02,
+  visible_date_signal: 0.015,
   extraction_friction: 0.02,
-  image_context_ai: 0.01,
-  schema_coverage: 0.01,
-  speakable_schema: 0.01,
+  image_context_ai: 5e-3,
+  schema_coverage: 5e-3,
+  speakable_schema: 5e-3,
   content_cannibalization: 0.02,
-  llms_txt: 0.02,
-  robots_txt: 0.02,
+  llms_txt: 0.01,
+  robots_txt: 0.01,
   content_velocity: 0.02,
-  content_licensing: 0.02,
-  canonical_url: 0.01,
+  content_licensing: 0.01,
+  canonical_url: 5e-3,
   sitemap_completeness: 0.01,
-  rss_feed: 0.01
+  rss_feed: 5e-3
 };
 var CRITERION_EFFORT = {
   topic_coherence: "High",
@@ -3159,6 +3498,8 @@ var CRITERION_EFFORT = {
   citation_ready_writing: "Medium",
   answer_first_placement: "Medium",
   evidence_packaging: "Medium",
+  helpful_purpose_alignment: "Medium",
+  first_hand_experience_signals: "Medium",
   duplicate_content: "Medium",
   cross_page_duplication: "Medium",
   direct_answer_density: "Medium",
@@ -3173,6 +3514,8 @@ var CRITERION_EFFORT = {
   content_freshness: "Low",
   author_schema_depth: "Low",
   schema_markup: "Medium",
+  creator_transparency: "Low",
+  methodology_transparency: "Low",
   semantic_html: "Low",
   clean_html: "Medium",
   visible_date_signal: "Low",
@@ -3197,6 +3540,8 @@ var FIX_DESCRIPTIONS = {
   citation_ready_writing: "Write self-contained definition sentences and one-claim statements AI can quote directly.",
   answer_first_placement: "Place a 40-80 word answer block in the first 300 words of each page.",
   evidence_packaging: "Add inline citations, attribution phrases, and a sources section to key pages.",
+  helpful_purpose_alignment: "Lead with useful, task-solving guidance instead of search-first filler.",
+  first_hand_experience_signals: "Add concrete signs of first-hand use, testing, implementation, or observation.",
   direct_answer_density: "Write concise 2-3 sentence answer paragraphs after each question heading.",
   qa_content_format: "Add question-based H2/H3 headings matching common AI queries.",
   query_answer_alignment: "Ensure every question heading is followed by a direct answer paragraph.",
@@ -3209,6 +3554,8 @@ var FIX_DESCRIPTIONS = {
   content_freshness: "Add dateModified schema and visible last-updated dates.",
   author_schema_depth: "Add Person schema for authors with credentials and sameAs links.",
   schema_markup: "Implement JSON-LD structured data on key pages.",
+  creator_transparency: "Show clear visible bylines, author pages, and reviewer details where readers expect them.",
+  methodology_transparency: "Explain how content was tested, researched, reviewed, or updated.",
   semantic_html: "Use semantic HTML5 elements (main, article, nav, header, footer).",
   clean_html: "Fix HTML structure, add meta tags, and ensure HTTPS.",
   visible_date_signal: "Display dates using <time> elements and add datePublished to JSON-LD.",
@@ -3308,6 +3655,10 @@ var CRITERION_LABELS = {
   "Visible Date Signal": "Visible Date Signal",
   "Topic Coherence": "Topic Coherence",
   "Content Depth": "Content Depth",
+  "Helpful Purpose Alignment": "Helpful Purpose Alignment",
+  "First-Hand Experience Signals": "First-Hand Experience Signals",
+  "Creator Transparency": "Creator Transparency",
+  "Methodology Transparency": "Methodology Transparency",
   "Citation-Ready Writing Quality": "Citation-Ready Writing Quality",
   "Answer-First Placement": "Answer-First Placement",
   "Evidence Packaging": "Evidence Packaging",
@@ -3413,6 +3764,8 @@ var CRITERION_WEIGHTS = {
   qa_content_format: 0.04,
   query_answer_alignment: 0.04,
   faq_section: 0.03,
+  helpful_purpose_alignment: 0.03,
+  first_hand_experience_signals: 0.03,
   // Content Organization (~30%)
   entity_consistency: 0.05,
   internal_linking: 0.04,
@@ -3420,28 +3773,30 @@ var CRITERION_WEIGHTS = {
   schema_markup: 0.03,
   author_schema_depth: 0.03,
   table_list_extractability: 0.03,
-  definition_patterns: 0.02,
-  visible_date_signal: 0.02,
+  creator_transparency: 0.02,
+  methodology_transparency: 0.02,
+  definition_patterns: 0.015,
+  visible_date_signal: 0.015,
   semantic_html: 0.02,
   clean_html: 0.02,
   // Technical Plumbing (~15%)
   content_cannibalization: 0.02,
-  llms_txt: 0.02,
-  robots_txt: 0.02,
+  llms_txt: 0.01,
+  robots_txt: 0.01,
   content_velocity: 0.02,
-  content_licensing: 0.02,
+  content_licensing: 0.01,
   sitemap_completeness: 0.01,
-  canonical_url: 0.01,
-  rss_feed: 0.01,
-  schema_coverage: 0.01,
-  speakable_schema: 0.01,
+  canonical_url: 5e-3,
+  rss_feed: 5e-3,
+  schema_coverage: 5e-3,
+  speakable_schema: 5e-3,
   // V2 Criteria (~15%)
   citation_ready_writing: 0.04,
   answer_first_placement: 0.03,
   evidence_packaging: 0.03,
   entity_disambiguation: 0.02,
   extraction_friction: 0.02,
-  image_context_ai: 0.01,
+  image_context_ai: 5e-3,
   // V3 Criteria
   duplicate_content: 0.05,
   cross_page_duplication: 0.03
@@ -3482,6 +3837,16 @@ var OPPORTUNITY_TEMPLATES = {
     effort: "Medium",
     description: "Create a dedicated FAQ page with FAQPage schema markup. Cover common questions about your products, services, and industry to become a direct answer source for AI engines."
   },
+  helpful_purpose_alignment: {
+    name: "Improve Helpful Purpose Alignment",
+    effort: "Medium",
+    description: "Rewrite pages to solve the visitor task quickly and concretely. Reduce generic intros, search-first filler, and CTA interruptions before the first useful answer."
+  },
+  first_hand_experience_signals: {
+    name: "Add First-Hand Experience Signals",
+    effort: "Medium",
+    description: "Show direct use, testing, implementation, or lived experience with concrete observations, examples, screenshots, and lessons learned."
+  },
   original_data: {
     name: "Add Original Data & Case Studies",
     effort: "High",
@@ -3537,6 +3902,16 @@ var OPPORTUNITY_TEMPLATES = {
     effort: "Low",
     description: "Add Person schema for content authors with credentials, expertise, and sameAs links. Expert attribution strengthens E-E-A-T signals that AI engines use to evaluate source credibility."
   },
+  creator_transparency: {
+    name: "Improve Creator Transparency",
+    effort: "Low",
+    description: "Add visible bylines, author pages, and reviewer/editor details so readers can clearly tell who created the content and why they are credible."
+  },
+  methodology_transparency: {
+    name: "Add Methodology Transparency",
+    effort: "Low",
+    description: "Explain how pages were tested, researched, reviewed, or updated. Add methodology, criteria, sample-size, or review-process details where users expect them."
+  },
   fact_density: {
     name: "Increase Fact & Data Density",
     effort: "Medium",
@@ -3796,20 +4171,12 @@ function formatList(items) {
 }
 
 // src/multi-page-fetcher.ts
-async function fetchPage(url, timeoutMs = 1e4) {
-  try {
-    const res = await fetch(url, {
-      signal: AbortSignal.timeout(timeoutMs),
-      headers: { "User-Agent": "AEO-Visibility-Bot/1.0" },
-      redirect: "follow"
-    });
-    if (res.status !== 200) return null;
-    const text = await res.text();
-    if (text.length < 200) return null;
-    return { text: text.slice(0, 5e5), status: res.status, finalUrl: res.url };
-  } catch {
-    return null;
-  }
+async function fetchPage(url, domain, timeoutMs = 1e4) {
+  const res = await safeFetch(url, { timeoutMs, expectedDomain: domain });
+  if (!res || res.status !== 200) return null;
+  const text = await res.text();
+  if (text.length < 200) return null;
+  return { text: text.slice(0, 5e5), status: res.status, finalUrl: res.url };
 }
 var PAGE_VARIANTS = {
   about: ["/about", "/about-us", "/company", "/who-we-are"],
@@ -3965,7 +4332,7 @@ async function fetchMultiPageData(siteData, options) {
   }
   const entries = Array.from(urlsToFetch.entries());
   if (entries.length === 0) return 0;
-  const results = await Promise.all(entries.map(([url]) => fetchPage(url, timeoutMs)));
+  const results = await Promise.all(entries.map(([url]) => fetchPage(url, siteData.domain, timeoutMs)));
   if (!siteData.blogSample) siteData.blogSample = [];
   let added = 0;
   for (let i = 0; i < results.length; i++) {
@@ -3992,19 +4359,23 @@ var PAGE_CRITERIA = {
   content_freshness: { weight: 0.04, label: "Content Freshness Signals" },
   schema_markup: { weight: 0.03, label: "Schema.org Structured Data" },
   table_list_extractability: { weight: 0.03, label: "Table & List Extractability" },
-  definition_patterns: { weight: 0.02, label: "Definition Patterns" },
-  visible_date_signal: { weight: 0.02, label: "Visible Date Signal" },
+  definition_patterns: { weight: 0.015, label: "Definition Patterns" },
+  visible_date_signal: { weight: 0.015, label: "Visible Date Signal" },
   semantic_html: { weight: 0.02, label: "Semantic HTML5 & Accessibility" },
   clean_html: { weight: 0.02, label: "Clean, Crawlable HTML" },
   // Technical Plumbing
-  canonical_url: { weight: 0.01, label: "Canonical URL Strategy" },
+  canonical_url: { weight: 5e-3, label: "Canonical URL Strategy" },
   // V2 Criteria
   citation_ready_writing: { weight: 0.04, label: "Citation-Ready Writing Quality" },
   answer_first_placement: { weight: 0.03, label: "Answer-First Placement" },
   evidence_packaging: { weight: 0.03, label: "Evidence Packaging" },
+  helpful_purpose_alignment: { weight: 0.03, label: "Helpful Purpose Alignment" },
+  first_hand_experience_signals: { weight: 0.03, label: "First-Hand Experience Signals" },
   entity_disambiguation: { weight: 0.02, label: "Entity Disambiguation" },
   extraction_friction: { weight: 0.02, label: "Extraction Friction Score" },
-  image_context_ai: { weight: 0.01, label: "Image Context for AI" },
+  creator_transparency: { weight: 0.02, label: "Creator Transparency" },
+  methodology_transparency: { weight: 0.02, label: "Methodology Transparency" },
+  image_context_ai: { weight: 5e-3, label: "Image Context for AI" },
   duplicate_content: { weight: 0.05, label: "Duplicate Content Blocks" }
 };
 function extractJsonLdBlocks(html) {
@@ -4027,7 +4398,7 @@ function extractTypesFromJsonLd(blocks) {
   }
   return types;
 }
-function getTextContent(html) {
+function getTextContent2(html) {
   return html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
 }
 function extractQuestionHeadings2(html) {
@@ -4055,7 +4426,7 @@ function countAnsweredQuestions(html) {
   }
   return { total: questions.length, answered };
 }
-function cap(value, max) {
+function cap2(value, max) {
   return Math.min(value, max);
 }
 function scoreSchemaMarkup(html) {
@@ -4081,10 +4452,10 @@ function scoreSchemaMarkup(html) {
   for (const t of types) {
     if (knownTypes.includes(t)) knownCount++;
   }
-  score += cap(knownCount * 2, 4);
+  score += cap2(knownCount * 2, 4);
   if (types.has("Organization") || types.has("LocalBusiness")) score += 2;
   if (types.has("FAQPage")) score += 1;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreQAFormat(html) {
   const questions = extractQuestionHeadings2(html);
@@ -4096,7 +4467,7 @@ function scoreQAFormat(html) {
   if (answered >= 1) score += 3;
   const h1Matches = html.match(/<h1[\s>]/gi) || [];
   if (h1Matches.length === 1) score += 2;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreCleanHtml(html) {
   let score = 0;
@@ -4105,15 +4476,15 @@ function scoreCleanHtml(html) {
   for (const tag of semantics) {
     if (html.toLowerCase().includes(tag)) semCount++;
   }
-  score += cap(semCount, 3);
+  score += cap2(semCount, 3);
   const h1Matches = html.match(/<h1[\s>]/gi) || [];
   if (h1Matches.length === 1) score += 2;
-  const text = getTextContent(html);
+  const text = getTextContent2(html);
   if (text.length > 500) score += 3;
   const hasTitle = /<title[^>]*>[^<]+<\/title>/i.test(html);
   const hasDesc = /<meta\s[^>]*name=["']description["'][^>]*content=["'][^"']+["']/i.test(html) || /<meta\s[^>]*content=["'][^"']+["'][^>]*name=["']description["']/i.test(html);
   if (hasTitle && hasDesc) score += 2;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreFaqSection(html) {
   let score = 0;
@@ -4125,11 +4496,11 @@ function scoreFaqSection(html) {
   const questions = extractQuestionHeadings2(html);
   if (questions.length >= 10) score += 1;
   if (/<details[\s>]/i.test(html) || /accordion|collapsible|toggle/i.test(lowerHtml)) score += 1;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreOriginalData(html) {
   let score = 0;
-  const text = getTextContent(html);
+  const text = getTextContent2(html);
   if (/\b(our (study|analysis|research|survey|data|findings))\b/i.test(text)) {
     score += 3;
   } else if (/\d+(\.\d+)?%|\$[\d,.]+|\b\d{1,3}(,\d{3})+\b/.test(text)) {
@@ -4146,7 +4517,7 @@ function scoreOriginalData(html) {
   if (/href=["'][^"']*\/blog\b/i.test(html)) {
     score += 2;
   }
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreQueryAnswerAlignment(html) {
   const { total, answered } = countAnsweredQuestions(html);
@@ -4169,7 +4540,7 @@ function scoreContentFreshness(html) {
   const currentYear = (/* @__PURE__ */ new Date()).getFullYear();
   const yearPattern = new RegExp(`\\b(${currentYear}|${currentYear - 1})\\b`);
   if (yearPattern.test(html)) score += 2;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreTableListExtractability(html) {
   let score = 0;
@@ -4182,7 +4553,7 @@ function scoreTableListExtractability(html) {
   const listItems = html.match(/<li[\s>]/gi) || [];
   if (listItems.length >= 10) score += 1;
   if (/<dl[\s>]/i.test(html)) score += 1;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreDirectAnswerDensity(html) {
   let score = 0;
@@ -4198,9 +4569,9 @@ function scoreDirectAnswerDensity(html) {
   }
   if (snippetCount >= 3) score += 2;
   else if (snippetCount >= 1) score += 1;
-  const directOpeners = getTextContent(html).match(/\b(yes|no|in short|the answer is|simply put|in summary)\b/gi) || [];
+  const directOpeners = getTextContent2(html).match(/\b(yes|no|in short|the answer is|simply put|in summary)\b/gi) || [];
   if (directOpeners.length >= 2) score += 2;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreSemanticHtml(html) {
   let score = 0;
@@ -4210,7 +4581,7 @@ function scoreSemanticHtml(html) {
   for (const el of elements) {
     if (lowerHtml.includes(el)) count++;
   }
-  score += cap(Math.floor(count * 0.7), 4);
+  score += cap2(Math.floor(count * 0.7), 4);
   const imgTags = html.match(/<img\s[^>]*>/gi) || [];
   if (imgTags.length > 0) {
     let withAlt = 0;
@@ -4221,11 +4592,11 @@ function scoreSemanticHtml(html) {
   }
   if (/<html[^>]*\slang=["'][^"']+["']/i.test(html)) score += 2;
   if (/\baria-/i.test(html)) score += 2;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreFactDensity(html) {
   let score = 0;
-  const text = getTextContent(html);
+  const text = getTextContent2(html);
   const numericPatterns = text.match(/\d+(\.\d+)?%|\$[\d,.]+|\b\d{1,3}(,\d{3})+\b|\b\d+\s*(million|billion|thousand|users|customers|employees)\b/gi) || [];
   if (numericPatterns.length >= 6) score += 5;
   else if (numericPatterns.length >= 3) score += 3;
@@ -4238,11 +4609,11 @@ function scoreFactDensity(html) {
   if (/\baccording to\b|\bsource:\s|\bcited\b|\breported by\b/i.test(text)) score += 2;
   const units = text.match(/\b\d+\s*(kg|lb|miles|km|hours|minutes|days|months|years|GB|MB|TB)\b/gi) || [];
   if (units.length >= 2) score += 1;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreDefinitionPatterns(html) {
   let score = 0;
-  const text = getTextContent(html);
+  const text = getTextContent2(html);
   const defPatterns = text.match(/\b(is a|is an|refers to|defined as|means that|also known as|abbreviated as)\b/gi) || [];
   if (defPatterns.length >= 3) score += 5;
   else if (defPatterns.length >= 1) score += 3;
@@ -4250,7 +4621,7 @@ function scoreDefinitionPatterns(html) {
   if (/\b(is a|is an|refers to|defined as)\b/i.test(early)) score += 2;
   if (/<dfn[\s>]/i.test(html) || /<abbr[\s>]/i.test(html)) score += 1;
   if (/<dl[\s>]/i.test(html) || /glossary/i.test(html)) score += 2;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreCanonicalUrl(html, url) {
   let score = 0;
@@ -4271,7 +4642,7 @@ function scoreCanonicalUrl(html, url) {
   if (canonicalHref.startsWith("https://")) score += 2;
   const allCanonicals = html.match(/<link[^>]*rel=["']canonical["'][^>]*>/gi) || [];
   if (allCanonicals.length === 1) score += 1;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreVisibleDateSignal(html) {
   let score = 0;
@@ -4290,11 +4661,11 @@ function scoreVisibleDateSignal(html) {
     } catch {
     }
   }
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreCitationReadyWriting(html) {
   let score = 0;
-  const text = getTextContent(html);
+  const text = getTextContent2(html);
   const defSentences = text.match(/\b\w+\s+(is\s+(?:a|an)\s|refers\s+to|defined\s+as)\b/gi) || [];
   if (defSentences.length >= 3) score += 3;
   else if (defSentences.length >= 1) score += 1;
@@ -4323,7 +4694,7 @@ function scoreCitationReadyWriting(html) {
   );
   if (quotableLines.length >= 2) score += 2;
   else if (quotableLines.length >= 1) score += 1;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreAnswerFirstPlacement(html) {
   let score = 0;
@@ -4334,8 +4705,8 @@ function scoreAnswerFirstPlacement(html) {
   const first300Words = bodyText.split(/\s+/).slice(0, 300).join(" ");
   for (const p of earlyParagraphs) {
     const pText = p.replace(/<[^>]*>/g, "").trim();
-    const wordCount = pText.split(/\s+/).length;
-    if (wordCount >= 40 && wordCount <= 80 && first300Words.includes(pText.slice(0, 50))) {
+    const wordCount2 = pText.split(/\s+/).length;
+    if (wordCount2 >= 40 && wordCount2 <= 80 && first300Words.includes(pText.slice(0, 50))) {
       score += 4;
       break;
     }
@@ -4356,11 +4727,11 @@ function scoreAnswerFirstPlacement(html) {
       score += 3;
     }
   }
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreEvidencePackaging(html) {
   let score = 0;
-  const text = getTextContent(html);
+  const text = getTextContent2(html);
   const paragraphs = html.match(/<p[^>]*>[\s\S]*?<\/p>/gi) || [];
   let inlineCitations = 0;
   for (const p of paragraphs) {
@@ -4378,11 +4749,11 @@ function scoreEvidencePackaging(html) {
   const sourcedStats = text.match(/\d+(\.\d+)?(%|\s*(million|billion|thousand|percent))\b[^.]*\b[A-Z][a-z]+\b/gi) || [];
   if (sourcedStats.length >= 2) score += 2;
   else if (sourcedStats.length >= 1) score += 1;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreEntityDisambiguation(html) {
   let score = 0;
-  const text = getTextContent(html);
+  const text = getTextContent2(html);
   const h1Match = html.match(/<h1[^>]*>([\s\S]*?)<\/h1>/i);
   if (!h1Match) return 3;
   const h1Text = h1Match[1].replace(/<[^>]*>/g, "").trim();
@@ -4400,11 +4771,11 @@ function scoreEntityDisambiguation(html) {
   if (/\bunlike\s+\w/i.test(text) || /\bcompared\s+to\s+\w/i.test(text) || /\bnot\s+to\s+be\s+confused\s+with\b/i.test(text)) {
     score += 3;
   }
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreExtractionFriction(html) {
   let score = 0;
-  const text = getTextContent(html);
+  const text = getTextContent2(html);
   const sentences = text.split(/[.!?]+/).filter((s) => s.trim().length > 5);
   const avgLen = sentences.length > 0 ? sentences.map((s) => s.trim().split(/\s+/).length).reduce((a, b) => a + b, 0) / sentences.length : 0;
   if (avgLen > 0 && avgLen < 20) score += 3;
@@ -4427,7 +4798,7 @@ function scoreExtractionFriction(html) {
   if (/display\s*:\s*none|visibility\s*:\s*hidden/i.test(html) && /<(div|section|p)[^>]*(?:style=["'][^"']*display\s*:\s*none|hidden)[^>]*>/i.test(html)) {
     score = Math.max(0, score - 2);
   }
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreImageContextAI(html) {
   let score = 0;
@@ -4452,7 +4823,7 @@ function scoreImageContextAI(html) {
   else if (goodAltCount > 0) score += 1;
   const contextualImages = html.match(/<(article|section)[^>]*>[\s\S]*?<img[^>]*>[\s\S]*?<\/\1>/gi) || [];
   if (contextualImages.length > 0) score += 3;
-  return cap(score, 10);
+  return cap2(score, 10);
 }
 function scoreDuplicateContent(html) {
   return scoreDuplicateContentDetailed(html).score;
@@ -4514,8 +4885,12 @@ var SCORING_FUNCTIONS = {
   citation_ready_writing: scoreCitationReadyWriting,
   answer_first_placement: scoreAnswerFirstPlacement,
   evidence_packaging: scoreEvidencePackaging,
+  helpful_purpose_alignment: scoreHelpfulPurposeAlignment,
+  first_hand_experience_signals: scoreFirstHandExperienceSignals,
   entity_disambiguation: scoreEntityDisambiguation,
   extraction_friction: scoreExtractionFriction,
+  creator_transparency: scoreCreatorTransparency,
+  methodology_transparency: scoreMethodologyTransparency,
   image_context_ai: scoreImageContextAI,
   duplicate_content: scoreDuplicateContent
 };
@@ -4546,7 +4921,7 @@ function extractTitle(html) {
   const match = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
   return match ? match[1].replace(/\s+/g, " ").trim() : "";
 }
-function getTextContent2(html) {
+function getTextContent3(html) {
   return html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
 }
 function countWords2(text) {
@@ -4606,9 +4981,9 @@ function checkMissingOgTags(html) {
   }
   return null;
 }
-function checkThinContent(wordCount) {
-  if (wordCount < 300) {
-    return { check: "thin-content", label: `Thin content (${wordCount} words)`, severity: "warning" };
+function checkThinContent(wordCount2) {
+  if (wordCount2 < 300) {
+    return { check: "thin-content", label: `Thin content (${wordCount2} words)`, severity: "warning" };
   }
   return null;
 }
@@ -4705,15 +5080,15 @@ function checkNoAnswerBlock(html) {
   const first300Words = bodyText.split(/\s+/).slice(0, 300).join(" ");
   for (const p of earlyParagraphs) {
     const pText = p.replace(/<[^>]*>/g, "").trim();
-    const wordCount = pText.split(/\s+/).length;
-    if (wordCount >= 40 && wordCount <= 80 && first300Words.includes(pText.slice(0, 50))) {
+    const wordCount2 = pText.split(/\s+/).length;
+    if (wordCount2 >= 40 && wordCount2 <= 80 && first300Words.includes(pText.slice(0, 50))) {
       return null;
     }
   }
   return { check: "no-answer-block", label: "No short answer block (40-80 words) in first 300 words", severity: "warning" };
 }
 function checkNoEvidence(html, url) {
-  const text = getTextContent2(html);
+  const text = getTextContent3(html);
   const paragraphs = html.match(/<p[^>]*>[\s\S]*?<\/p>/gi) || [];
   let inlineCitations = 0;
   for (const p of paragraphs) {
@@ -4727,7 +5102,7 @@ function checkNoEvidence(html, url) {
   return null;
 }
 function checkHasCitationReadyContent(html) {
-  const text = getTextContent2(html);
+  const text = getTextContent3(html);
   const sentences = text.split(/[.!?]+/).filter((s) => s.trim().length > 10);
   let quotable = 0;
   for (const s of sentences) {
@@ -4752,8 +5127,8 @@ function checkDuplicateContentBlocks(html) {
 }
 function analyzePage(html, url, category) {
   const title = extractTitle(html);
-  const textContent = getTextContent2(html);
-  const wordCount = countWords2(textContent);
+  const textContent = getTextContent3(html);
+  const wordCount2 = countWords2(textContent);
   const issues = [];
   const strengths = [];
   const issueChecks = [
@@ -4764,7 +5139,7 @@ function analyzePage(html, url, category) {
     checkNoSchema(html),
     checkMissingCanonical(html),
     checkMissingOgTags(html),
-    checkThinContent(wordCount),
+    checkThinContent(wordCount2),
     checkImagesMissingAlt(html),
     checkNoInternalLinks(html, url),
     checkNoAnswerBlock(html),
@@ -4783,7 +5158,7 @@ function analyzePage(html, url, category) {
     if (result) strengths.push(result);
   }
   const { aeoScore, criterionScores } = scorePage(html, url);
-  return { url, title, category, wordCount, issues, strengths, aeoScore, criterionScores };
+  return { url, title, category, wordCount: wordCount2, issues, strengths, aeoScore, criterionScores };
 }
 function analyzeAllPages(siteData) {
   const reviews = [];
@@ -4805,6 +5180,10 @@ function getTextLength(html) {
   return html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim().length;
 }
 async function audit(domain, options) {
+  const normalizedTarget = domain.startsWith("http") ? domain : `https://${domain}`;
+  if (!await isSafeFetchTarget(normalizedTarget)) {
+    throw new Error(`Refusing to audit private or local address: ${domain}`);
+  }
   const startTime = Date.now();
   let renderedWithHeadless = false;
   const siteData = await prefetchSiteData(domain);
@@ -4837,7 +5216,7 @@ async function audit(domain, options) {
     }
   }
   if (options?.fullCrawl) {
-    const { crawlFullSite } = await import("./full-site-crawler-OBECS7AT.js");
+    const { crawlFullSite } = await import("./full-site-crawler-W3WSE6WT.js");
     const crawlResult = await crawlFullSite(siteData, {
       maxPages: options.maxPages ?? 200,
       concurrency: options.concurrency ?? 5
@@ -5266,7 +5645,7 @@ function generateComparisonHtmlReport(result) {
 }
 
 // src/cli.ts
-var VERSION = "3.0.0";
+var VERSION = "3.2.1";
 function printHelp() {
   console.log(`
   aeorank - AI Engine Optimization audit