@agentimization/core 0.1.0 → 0.1.2

package/README.md

@@ -1,43 +1,6 @@
-<p align="center">
-  <img src="https://img.shields.io/npm/v/agentimization?style=flat-square&color=blue" alt="npm version" />
-  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license" />
-  <img src="https://img.shields.io/badge/checks-35-purple?style=flat-square" alt="checks" />
-</p>
+# agentimization
 
-<h1 align="center">agentimization</h1>
-
-<p align="center">
-  GEO audit for agent-ready websites.<br/>
-  One command to check if AI agents can discover, parse, and cite your content.
-</p>
-
----
-
-## Why
-
-AI agents (Claude, ChatGPT, Perplexity, Gemini) are becoming a major source of traffic and citations. But most websites are invisible to them — no `llms.txt`, no markdown endpoints, no structured data, client-rendered content that crawlers can't read.
-
-**Agentimization** runs checks across 8 categories and gives you a GEO score from 0–100, with specific fixes you can hand off to an AI coding agent.
-
-## Install
-
-```bash
-npx agentimization https://your-site.com
-```
-
-Or install globally:
-
-```bash
-npm install -g agentimization
-```
-
-## Usage
-
-### Audit a live site
-
-```bash
-agentimization https://docs.anthropic.com
-```
+[![npm version](https://img.shields.io/npm/v/agentimization?style=flat-square&color=blue)](https://www.npmjs.com/package/agentimization)
 
 ```text
 ╭───────────────────────────────────────────────╮
@@ -45,149 +8,70 @@ agentimization https://docs.anthropic.com
 │ ░▓▒░▓░░▒▓▒░▓░░▒▓▓░▒░▓▒░░▓▒░▓░▒░░▓▒░░▓░▒       │
 │ ▓░▒▓░░▒▓▒░░▓░▒▓▒░░▓░░▓▒░▓░▒░░▓▒░▓░░▒▓░        │
 │ ░▒▓░▒░▓▒░░▓░▒▓░░▒▓▒░░▓░▒▓░░▒▓░ agentimization │
-│                                               │
-│ https://docs.anthropic.com                    │
-│                                               │
-│ Crawling the site, one sec…                   │
 ╰───────────────────────────────────────────────╯
 ```
 
-### Audit a local directory (great for CI)
+geo audit for agent-ready websites and projects.
 
-```bash
-agentimization .
-agentimization ./docs
-```
+geomaxx your site so ai agents can actually find, parse, and cite it.
 
-### Output formats
+## install
 
 ```bash
-# JSON for CI pipelines
-agentimization https://example.com --json
-
-# Markdown report — paste into Claude, ChatGPT, etc.
-agentimization https://example.com --md
-
-# Filter by category
-agentimization https://example.com --category content-discoverability
+npx agentimization https://your-site.com
 ```
 
-### After the audit
-
-Agentimization shows an interactive menu when the audit finishes:
+## usage
 
-- **Copy fix prompt to clipboard** — structured markdown an AI coding agent can use to fix your GEO issues
-- **Save JSON report** — full audit data written to `agentimization-report.json`
-- **Run another URL or path** — keep the session open and audit the next site
-- **Exit**
+audit a live site:
 
-## Checks
-
-Agentimization runs **36 checks** across **8 categories**:
-
-| Category | What it checks |
-|---|---|
-| **Content Discoverability** | `llms.txt` existence, structure, size, coverage, link resolution. Sitemap presence. `robots.txt` AI agent rules. |
-| **Markdown Availability** | `.md` URL support, `Accept: text/markdown` content negotiation, HTML↔markdown parity. |
-| **Content Structure** | Code fence validity, heading hierarchy, tabbed content serialization. |
-| **Page Size & Rendering** | SSR vs CSR detection, HTML/markdown page size, content start position (boilerplate ratio). |
-| **URL Stability** | HTTP status codes, redirect behavior, cache header hygiene. |
-| **Authentication & Access** | Auth gate detection, alternative access paths for gated content. |
-| **GEO Signals** | Structured data (JSON-LD), citation worthiness, topical authority, content freshness, E-E-A-T signals, FAQ schema, canonical URLs. |
-| **Agent Protocols** | AGENTS.md, MCP server card, API catalog (RFC 9727), content signals (AI usage declarations), Link headers (RFC 8288), agent skills index. |
-
-## Scoring
-
-Each check returns **pass**, **warn**, **fail**, **skip**, or **info**. Checks are weighted by importance, and scores roll up into category scores and an overall grade:
-
-| Grade | Score |
-|---|---|
-| A+ | 95–100 |
-| A | 85–94 |
-| B | 70–84 |
-| C | 55–69 |
-| D | 40–54 |
-| F | 0–39 |
-
-## Example scores
-
-How popular sites score on Agentimization (approximate, scores change as sites update):
-
-| Site | Grade | Score | Notes |
-|---|---|---|---|
-| `docs.anthropic.com` | **A** | 88 | Strong `llms.txt`, good markdown, structured data |
-| `docs.stripe.com` | **A** | 91 | Excellent discoverability, markdown endpoints, great structure |
-| `nextjs.org/docs` | **B** | 76 | Good SSR, missing `llms.txt`, decent GEO signals |
-| `react.dev` | **B** | 72 | Good structure, no `llms.txt`, client-heavy rendering |
-| `en.wikipedia.org` | **A** | 86 | Great content structure, strong citations, no `llms.txt` |
-| `medium.com` | **D** | 45 | Auth gates, weak markdown, no `llms.txt` |
-| `substack.com` | **C** | 58 | Mixed access, some content gated |
-
-> These are illustrative examples. Run `agentimization <url>` to get real-time scores.
-
-## Local mode
-
-When you pass a directory path instead of a URL, Agentimization runs in **local mode**:
+```bash
+agentimization https://docs.your-site.com
+```
 
-- Scans your files on disk (HTML, markdown, `llms.txt`, `robots.txt`, `sitemap.xml`)
-- Skips network-only checks (content negotiation, auth detection, cache headers, etc.)
-- Perfect as a **CI pre-deploy step** — catch GEO regressions before they ship
+audit a local directory:
 
 ```bash
-# In CI
-agentimization . --json
-# Exit code 1 if score < 50
+agentimization .
 ```
 
-## Programmatic API
-
-```typescript
-import { audit, auditLocal } from "@agentimization/core"
+pipe results to a tool or file:
 
-// Remote audit
-const result = await audit("https://docs.anthropic.com")
-console.log(result.grade, result.overall_score)
+```bash
+agentimization https://your-site.com --json > report.json
+agentimization https://your-site.com --md | pbcopy
+```
 
-// Local audit
-const local = await auditLocal("./docs")
-console.log(local.grade, local.overall_score)
+## what it checks
 
-// With options
-const result = await audit("https://example.com", {
-  sampleSize: 20,
-  categories: ["content-discoverability", "geo-signals"],
-  onEvent: (event) => console.log(event),
-})
-```
+36 checks across 8 categories. each one is a thing ai agents need to discover, parse, or cite your content.
 
-## What is GEO?
+- content discoverability: `llms.txt`, sitemap, robots
+- markdown availability: `.md` urls, content negotiation
+- content structure: headings, code fences, hidden tabs
+- page size and rendering: ssr vs csr, boilerplate ratio
+- url stability: status codes, redirects, canonicals
+- authentication and access: gates, alternative paths
+- geo signals: json-ld, citations, freshness, e-e-a-t
+- agent protocols: mcp card, api catalog, agents.md, link headers
 
-**Generative Engine Optimization** is like SEO, but for AI. Instead of optimizing for Google's crawlers and ranking algorithm, GEO optimizes for AI agents that need to:
+## how it works
 
-1. **Discover** your content (via `llms.txt`, sitemaps, `robots.txt`)
-2. **Parse** it efficiently (markdown availability, clean HTML, SSR)
-3. **Cite** it accurately (structured data, canonical URLs, E-E-A-T signals)
+it samples up to 10 pages of your site, runs 36 checks against the html, headers, and well-known files, then weights them into a 0 to 100 score. failed checks come with a suggestion you can paste into your ai coding agent.
 
-Sites that score well on Agentimization are more likely to be surfaced and cited by Claude, ChatGPT, Perplexity, and other generative engines.
+## requirements
 
-## Contributing
+node 18 or newer.
 
-```bash
-git clone https://github.com/antlio/agentimization
-cd agentimization
-bun install
-bun run build
-bun run typecheck
-```
+## programmatic use
 
-The monorepo structure:
+```typescript
+import { audit } from "@agentimization/core"
 
-```
-packages/shared  — Types, schemas, constants
-packages/core    — Audit engine + all 36 checks
-apps/cli         — CLI (Commander.js + Ink)
+const result = await audit("https://your-site.com")
+console.log(result.grade, result.overall_score)
 ```
 
-## License
+## license
 
-MIT
+mit

package/dist/index.js

@@ -769,11 +769,11 @@ var extractMetaTags = (html) => {
   const metaRegex = /<meta[^>]+(?:name|property)=["']([^"']+)["'][^>]+content=["']([^"']+)["']/gi;
   let match;
   while ((match = metaRegex.exec(html)) !== null) {
-    meta[match[1]] = match[2];
+    meta[match[1].toLowerCase()] = match[2];
   }
   const metaRegex2 = /<meta[^>]+content=["']([^"']+)["'][^>]+(?:name|property)=["']([^"']+)["']/gi;
   while ((match = metaRegex2.exec(html)) !== null) {
-    meta[match[2]] = match[1];
+    meta[match[2].toLowerCase()] = match[1];
   }
   return meta;
 };
@@ -789,6 +789,24 @@ var extractJsonLd = (html) => {
   }
   return results;
 };
+var readAttr = (attrs, name) => {
+  const re = new RegExp(`\\b${name}=(?:"([^"]*)"|'([^']*)')`, "i");
+  const m = attrs.match(re);
+  if (!m) return void 0;
+  return m[1] ?? m[2];
+};
+var extractImages = (html) => {
+  const images = [];
+  const imgRegex = /<img\b([^>]*)>/gi;
+  let match;
+  while ((match = imgRegex.exec(html)) !== null) {
+    const attrs = match[1];
+    const src = readAttr(attrs, "src");
+    if (src === void 0) continue;
+    images.push({ src, alt: readAttr(attrs, "alt") });
+  }
+  return images;
+};
 var extractHeadings = (html) => {
   const headings = [];
   const regex = /<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi;
@@ -902,6 +920,53 @@ var renderingStrategy = {
     };
   }
 };
+var substantialTextContent = {
+  id: "substantial-text-content",
+  name: "Substantial Text Content",
+  category: "page-size",
+  description: "Checks for at least 100 words of readable body text",
+  weight: 0.8,
+  run: async (ctx) => {
+    const pages = ctx.sampledPages.slice(0, 10);
+    if (pages.length === 0) {
+      return {
+        id: "substantial-text-content",
+        name: "Substantial Text Content",
+        category: "page-size",
+        status: "skip",
+        message: "No pages sampled"
+      };
+    }
+    let withSubstantialContent = 0;
+    let totalWords = 0;
+    for (const page of pages) {
+      const text = stripHtml(page.html);
+      const words = text.split(/\s+/).filter((w) => w.length > 0).length;
+      totalWords += words;
+      if (words >= 100) withSubstantialContent++;
+    }
+    const avgWords = Math.round(totalWords / pages.length);
+    if (withSubstantialContent === pages.length) {
+      return {
+        id: "substantial-text-content",
+        name: "Substantial Text Content",
+        category: "page-size",
+        status: "pass",
+        message: `All ${pages.length} pages have \u2265100 words of body text (avg ${avgWords})`,
+        metadata: { withSubstantialContent, avgWords }
+      };
+    }
+    return {
+      id: "substantial-text-content",
+      name: "Substantial Text Content",
+      category: "page-size",
+      status: withSubstantialContent > 0 ? "warn" : "fail",
+      message: `${withSubstantialContent}/${pages.length} pages have \u2265100 words of body text (avg ${avgWords})`,
+      suggestion: "Generative engines can't cite pages that are mostly images or short copy. Add at least 100 words of substantive text content per page.",
+      metadata: { withSubstantialContent, avgWords }
+    };
+  }
+};
 var pageSizeHtml = {
   id: "page-size-html",
   name: "Page Size (HTML)",
@@ -993,7 +1058,7 @@ var contentStartPosition = {
   id: "content-start-position",
   name: "Content Start Position",
   category: "page-size",
-  description: "Checks if main content starts within the first 10% of the HTML",
+  description: "Checks how soon main content starts relative to total HTML",
   weight: 0.5,
   run: async (ctx) => {
     const pages = ctx.sampledPages.slice(0, 10);
@@ -1010,17 +1075,16 @@ var contentStartPosition = {
       url: p.url,
       position: findContentStartPosition(p.html)
     }));
-    const earlyStart = positions.filter((p) => p.position <= 0.1);
     const medianPct = Math.round(
       positions.map((p) => p.position).sort((a, b) => a - b)[Math.floor(positions.length / 2)] * 100
     );
-    if (earlyStart.length === pages.length) {
+    if (medianPct <= 30) {
       return {
         id: "content-start-position",
         name: "Content Start Position",
         category: "page-size",
         status: "pass",
-        message: `Content starts within first 10% on all ${pages.length} sampled pages (median ${medianPct}%)`,
+        message: `content starts at ${medianPct}% of html (median over ${pages.length} pages)`,
         metadata: { medianPct }
       };
     }
@@ -1028,15 +1092,16 @@ var contentStartPosition = {
       id: "content-start-position",
       name: "Content Start Position",
       category: "page-size",
-      status: "warn",
-      message: `Content starts late on ${pages.length - earlyStart.length}/${pages.length} pages (median ${medianPct}%)`,
-      suggestion: "Move main content higher in the HTML. AI agents may waste context window tokens on navigation, headers, and boilerplate before reaching actual content.",
-      metadata: { medianPct, earlyStart: earlyStart.length }
+      status: medianPct <= 50 ? "warn" : "fail",
+      message: `content starts at ${medianPct}% of html (median over ${pages.length} pages)`,
+      suggestion: "trim head metadata or move main content higher in the html so ai agents do not waste context tokens on boilerplate before reaching real content.",
+      metadata: { medianPct }
     };
   }
 };
 var pageSizeChecks = [
   renderingStrategy,
+  substantialTextContent,
   pageSizeHtml,
   pageSizeMarkdown,
   contentStartPosition
@@ -1210,13 +1275,105 @@ var tabbedContentSerialization = {
     };
   }
 };
+var imageAltText = {
+  id: "image-alt-text",
+  name: "Image Alt Text Coverage",
+  category: "content-structure",
+  description: "Checks that at least 50% of images have descriptive alt text",
+  weight: 0.5,
+  run: async (ctx) => {
+    const pages = ctx.sampledPages.slice(0, 10);
+    if (pages.length === 0) {
+      return {
+        id: "image-alt-text",
+        name: "Image Alt Text Coverage",
+        category: "content-structure",
+        status: "skip",
+        message: "No pages sampled"
+      };
+    }
+    const allImages = pages.flatMap((p) => extractImages(p.html));
+    const contentImages = allImages.filter((img) => img.alt === void 0 || img.alt.trim().length > 0);
+    const decorativeImages = allImages.length - contentImages.length;
+    const withAlt = contentImages.filter((img) => img.alt !== void 0 && img.alt.trim().length > 0).length;
+    if (allImages.length === 0) {
+      return {
+        id: "image-alt-text",
+        name: "Image Alt Text Coverage",
+        category: "content-structure",
+        status: "info",
+        message: `No images found across ${pages.length} sampled pages`
+      };
+    }
+    if (contentImages.length === 0) {
+      return {
+        id: "image-alt-text",
+        name: "Image Alt Text Coverage",
+        category: "content-structure",
+        status: "info",
+        message: `All ${allImages.length} sampled images are decorative (alt="")`,
+        metadata: { decorativeImages, totalImages: allImages.length }
+      };
+    }
+    const ratio = withAlt / contentImages.length;
+    const pct = Math.round(ratio * 100);
+    const summary = `${withAlt}/${contentImages.length} content images have descriptive alt text (${pct}%)${decorativeImages > 0 ? `; ${decorativeImages} decorative skipped` : ""}`;
+    if (ratio >= 0.5) {
+      return {
+        id: "image-alt-text",
+        name: "Image Alt Text Coverage",
+        category: "content-structure",
+        status: "pass",
+        message: summary,
+        metadata: { withAlt, contentImages: contentImages.length, decorativeImages, pct }
+      };
+    }
+    return {
+      id: "image-alt-text",
+      name: "Image Alt Text Coverage",
+      category: "content-structure",
+      status: ratio >= 0.25 ? "warn" : "fail",
+      message: summary,
+      suggestion: `Add descriptive alt text to at least 50% of content images. AI agents and screen readers rely on alt text to understand visual content. Mark purely decorative images with alt="" so they don't dilute the ratio.`,
+      metadata: { withAlt, contentImages: contentImages.length, decorativeImages, pct }
+    };
+  }
+};
 var contentStructureChecks = [
   markdownCodeFenceValidity,
   sectionHeaderQuality,
-  tabbedContentSerialization
+  tabbedContentSerialization,
+  imageAltText
 ];
 
 // src/checks/url-stability.ts
+var httpsEnabled = {
+  id: "https-enabled",
+  name: "HTTPS Enabled",
+  category: "url-stability",
+  description: "Checks if the site is served over HTTPS",
+  weight: 0.7,
+  requiresNetwork: true,
+  run: async (ctx) => {
+    if (ctx.baseUrl.protocol === "https:") {
+      return {
+        id: "https-enabled",
+        name: "HTTPS Enabled",
+        category: "url-stability",
+        status: "pass",
+        message: "Site is served over HTTPS"
+      };
+    }
+    return {
+      id: "https-enabled",
+      name: "HTTPS Enabled",
+      category: "url-stability",
+      status: "fail",
+      message: `Site is served over ${ctx.baseUrl.protocol.replace(":", "")} \u2014 AI crawlers de-prioritize non-HTTPS sources`,
+      suggestion: "Serve your site over HTTPS. AI crawlers like GPTBot, ClaudeBot, and PerplexityBot strongly prefer HTTPS and may skip plain HTTP entirely."
+    };
+  }
+};
 var httpStatusCodes = {
   id: "http-status-codes",
   name: "HTTP Status Codes",
@@ -1328,6 +1485,7 @@ var cacheHeaderHygiene = {
   }
 };
 var urlStabilityChecks = [
+  httpsEnabled,
   httpStatusCodes,
   redirectBehavior,
   cacheHeaderHygiene
@@ -1573,9 +1731,10 @@ var topicalAuthoritySignals = {
     const pages = ctx.sampledPages.slice(0, 10);
     let totalInternalLinks = 0;
     let pagesWithGoodLinking = 0;
+    const resolveBase = ctx.mode === "local" ? ctx.baseUrl.href : ctx.baseUrl.origin;
     for (const page of pages) {
-      const links = extractLinks(page.html, ctx.baseUrl.origin);
-      const internalLinks = ctx.mode === "local" ? links.filter((l) => !l.startsWith("http://") && !l.startsWith("https://")) : links.filter((l) => {
+      const links = extractLinks(page.html, resolveBase);
+      const internalLinks = ctx.mode === "local" ? links.filter((l) => l.startsWith("file:")) : links.filter((l) => {
         try {
           return new URL(l).origin === ctx.baseUrl.origin;
         } catch {
@@ -1671,7 +1830,8 @@ var eeatSignals = {
       const hasAuthorHtml = /class=["'][^"']*author[^"']*["']|rel=["']author["']/i.test(page.html);
       if (hasAuthorMeta || hasAuthorJsonLd || hasAuthorHtml) withAuthor++;
       const hasCredentials = /Ph\.?D|M\.?D|CPA|certified|licensed|expert|specialist/i.test(page.html);
-      const hasAboutPage = extractLinks(page.html, ctx.baseUrl.origin).some((l) => /about|team|author/i.test(l));
+      const linkBase = ctx.mode === "local" ? ctx.baseUrl.href : ctx.baseUrl.origin;
+      const hasAboutPage = extractLinks(page.html, linkBase).some((l) => /about|team|author/i.test(l));
       if (hasCredentials || hasAboutPage) withExpertise++;
     }
     const score = (withAuthor + withExpertise) / (pages.length * 2);
@@ -1735,6 +1895,185 @@ var faqSchema = {
     };
   }
 };
+var metaDescription = {
+  id: "meta-description",
+  name: "Meta Description",
+  category: "geo-signals",
+  description: "Checks for a meta description between 50 and 160 characters",
+  weight: 0.5,
+  run: async (ctx) => {
+    const pages = ctx.sampledPages.slice(0, 10);
+    if (pages.length === 0) {
+      return {
+        id: "meta-description",
+        name: "Meta Description",
+        category: "geo-signals",
+        status: "skip",
+        message: "No pages sampled"
+      };
+    }
+    let withGoodDescription = 0;
+    let missing = 0;
+    let tooShort = 0;
+    let tooLong = 0;
+    for (const page of pages) {
+      const meta = extractMetaTags(page.html);
+      const description = meta["description"]?.trim();
+      if (!description) {
+        missing++;
+        continue;
+      }
+      const len = description.length;
+      if (len >= 50 && len <= 160) withGoodDescription++;
+      else if (len < 50) tooShort++;
+      else tooLong++;
+    }
+    if (withGoodDescription === pages.length) {
+      return {
+        id: "meta-description",
+        name: "Meta Description",
+        category: "geo-signals",
+        status: "pass",
+        message: `All ${pages.length} pages have a meta description between 50\u2013160 characters`,
+        metadata: { withGoodDescription }
+      };
+    }
+    if (missing === pages.length) {
+      return {
+        id: "meta-description",
+        name: "Meta Description",
+        category: "geo-signals",
+        status: "fail",
+        message: "No meta description found on any sampled page",
+        suggestion: 'Add a <meta name="description"> between 50 and 160 characters to every page. Generative engines quote meta descriptions when summarizing your content.'
+      };
+    }
+    const detail = [
+      missing > 0 ? `${missing} missing` : null,
+      tooShort > 0 ? `${tooShort} too short` : null,
+      tooLong > 0 ? `${tooLong} too long` : null
+    ].filter(Boolean).join(" \xB7 ");
+    return {
+      id: "meta-description",
+      name: "Meta Description",
+      category: "geo-signals",
+      status: missing >= pages.length / 2 ? "fail" : "warn",
+      message: `${withGoodDescription}/${pages.length} pages have meta descriptions in the 50\u2013160 char range${detail ? ` \xB7 ${detail}` : ""}`,
+      suggestion: missing > 0 ? 'Add a <meta name="description"> between 50 and 160 characters to every page. Some pages are missing it entirely.' : "Aim for 50\u2013160 characters. Shorter descriptions lack context for AI; longer ones get truncated.",
+      metadata: { withGoodDescription, missing, tooShort, tooLong }
+    };
+  }
+};
+var openGraphTags = {
+  id: "open-graph-tags",
+  name: "Open Graph Tags",
+  category: "geo-signals",
+  description: "Checks for og:title, og:description, og:image, and og:url",
+  weight: 0.5,
+  run: async (ctx) => {
+    const pages = ctx.sampledPages.slice(0, 10);
+    if (pages.length === 0) {
+      return {
+        id: "open-graph-tags",
+        name: "Open Graph Tags",
+        category: "geo-signals",
+        status: "skip",
+        message: "No pages sampled"
+      };
+    }
+    const required = ["og:title", "og:description", "og:image", "og:url"];
+    let fullCoverage = 0;
+    let partialCoverage = 0;
+    const missingCounts = { "og:title": 0, "og:description": 0, "og:image": 0, "og:url": 0 };
+    for (const page of pages) {
+      const meta = extractMetaTags(page.html);
+      const missing = required.filter((tag) => !meta[tag]);
+      for (const tag of missing) missingCounts[tag] = (missingCounts[tag] ?? 0) + 1;
+      if (missing.length === 0) fullCoverage++;
+      else if (missing.length < required.length) partialCoverage++;
+    }
+    if (fullCoverage === pages.length) {
+      return {
+        id: "open-graph-tags",
+        name: "Open Graph Tags",
+        category: "geo-signals",
+        status: "pass",
+        message: `All ${pages.length} pages have complete Open Graph tags`
+      };
+    }
+    const mostMissing = Object.entries(missingCounts).filter(([, n]) => n > 0).sort(([, a], [, b]) => b - a).map(([tag]) => tag);
+    const noneCovered = pages.length - fullCoverage - partialCoverage;
+    return {
+      id: "open-graph-tags",
+      name: "Open Graph Tags",
+      category: "geo-signals",
+      status: fullCoverage + partialCoverage === 0 ? "fail" : "warn",
+      message: `${fullCoverage}/${pages.length} pages have complete Open Graph tags${partialCoverage > 0 ? ` \xB7 ${partialCoverage} partial` : ""}${noneCovered > 0 ? ` \xB7 ${noneCovered} with none` : ""}${mostMissing.length > 0 ? ` \xB7 most often missing: ${mostMissing.slice(0, 2).join(", ")}` : ""}`,
+      suggestion: "Add og:title, og:description, og:image, and og:url to every page. AI engines and link previews use these to render rich citations of your content.",
+      metadata: { fullCoverage, partialCoverage, noneCovered, missingCounts }
+    };
+  }
+};
+var externalCitations = {
+  id: "external-citations",
+  name: "External Citations",
+  category: "geo-signals",
+  description: "Checks for at least 2 outbound links to external sources per page",
+  weight: 0.5,
+  run: async (ctx) => {
+    if (ctx.mode === "local") {
+      return {
+        id: "external-citations",
+        name: "External Citations",
+        category: "geo-signals",
+        status: "info",
+        message: "External link detection requires a live origin to compare against"
+      };
+    }
+    const pages = ctx.sampledPages.slice(0, 10);
+    if (pages.length === 0) {
+      return {
+        id: "external-citations",
+        name: "External Citations",
+        category: "geo-signals",
+        status: "skip",
+        message: "No pages sampled"
+      };
+    }
+    const origin = ctx.baseUrl.origin;
+    let pagesWithCitations = 0;
+    let totalExternal = 0;
+    for (const page of pages) {
+      const links = extractLinks(page.html, origin);
+      const external = links.filter((l) => {
+        const u = new URL(l);
+        return u.protocol.startsWith("http") && u.origin !== origin;
+      });
+      totalExternal += external.length;
+      if (external.length >= 2) pagesWithCitations++;
+    }
+    const avgExternal = Math.round(totalExternal / pages.length);
+    if (pagesWithCitations >= pages.length * 0.7) {
+      return {
+        id: "external-citations",
+        name: "External Citations",
+        category: "geo-signals",
+        status: "pass",
+        message: `${pagesWithCitations}/${pages.length} pages have \u22652 outbound links (avg ${avgExternal}/page)`,
+        metadata: { pagesWithCitations, avgExternal }
+      };
+    }
+    return {
+      id: "external-citations",
+      name: "External Citations",
+      category: "geo-signals",
+      status: pagesWithCitations > 0 ? "warn" : "fail",
+      message: `Only ${pagesWithCitations}/${pages.length} pages have \u22652 outbound links (avg ${avgExternal}/page)`,
+      suggestion: "Add at least 2 outbound links to authoritative external sources per page. Citing sources signals credibility to generative engines, which weigh outbound links when deciding what to cite.",
+      metadata: { pagesWithCitations, avgExternal }
+    };
+  }
+};
 var canonicalUrlConsistency = {
   id: "canonical-url-consistency",
   name: "Canonical URL Consistency",
@@ -1742,6 +2081,15 @@ var canonicalUrlConsistency = {
   description: "Checks if pages have consistent canonical URLs",
   weight: 0.5,
   run: async (ctx) => {
+    if (ctx.mode === "local") {
+      return {
+        id: "canonical-url-consistency",
+        name: "Canonical URL Consistency",
+        category: "geo-signals",
+        status: "info",
+        message: "only meaningful for live urls. re-run against a deployed site to verify"
+      };
+    }
     const pages = ctx.sampledPages.slice(0, 10);
     let withCanonical = 0;
     let selfReferencing = 0;
@@ -1796,6 +2144,9 @@ var geoSignalChecks = [
   contentFreshness,
   eeatSignals,
   faqSchema,
+  metaDescription,
+  openGraphTags,
+  externalCitations,
   canonicalUrlConsistency
 ];
 
@@ -2185,7 +2536,30 @@ var ALL_CHECKS = [
 
 // src/utils/local.ts
 import { readFileSync, readdirSync, existsSync } from "fs";
-import { join, relative, extname } from "path";
+import { dirname, join, relative, extname } from "path";
+var readIfExists = (path) => {
+  try {
+    if (existsSync(path)) {
+      return readFileSync(path, "utf-8");
+    }
+  } catch {
+  }
+  return void 0;
+};
+var findUpward = (start, names, maxDepth = 6) => {
+  let current = start;
+  for (let i = 0; i < maxDepth; i++) {
+    for (const name of names) {
+      const candidate = join(current, name);
+      const value = readIfExists(candidate);
+      if (value !== void 0) return value;
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return void 0;
+};
 var walkDir = (dir, extensions, maxDepth = 10) => {
   if (maxDepth <= 0) return [];
   const results = [];
@@ -2206,15 +2580,6 @@ var walkDir = (dir, extensions, maxDepth = 10) => {
   }
   return results;
 };
-var readIfExists = (path) => {
-  try {
-    if (existsSync(path)) {
-      return readFileSync(path, "utf-8");
-    }
-  } catch {
-  }
-  return void 0;
-};
 var buildLocalContext = (dirPath, config) => {
   const baseUrl = new URL(`file://${dirPath}`);
   const robotsTxt = readIfExists(join(dirPath, "robots.txt"));
@@ -2224,7 +2589,7 @@ var buildLocalContext = (dirPath, config) => {
   const mcpServerCard2 = readIfExists(join(dirPath, ".well-known", "mcp", "server-card.json"));
   const apiCatalog2 = readIfExists(join(dirPath, ".well-known", "api-catalog"));
   const agentSkillsIndex2 = readIfExists(join(dirPath, ".well-known", "agent-skills", "index.json"));
-  const agentsMd2 = readIfExists(join(dirPath, "AGENTS.md")) ?? readIfExists(join(dirPath, "AGENT.md"));
+  const agentsMd2 = findUpward(dirPath, ["AGENTS.md", "AGENT.md"]);
   const sitemapUrls = sitemapXml ? parseSitemapUrls(sitemapXml) : [];
   if (!sitemapXml && robotsTxt) {
     const sitemapMatch = robotsTxt.match(/Sitemap:\s*(.+)/i);
@@ -2241,8 +2606,8 @@ var buildLocalContext = (dirPath, config) => {
   }
   const htmlFiles = walkDir(dirPath, /* @__PURE__ */ new Set([".html", ".htm"]));
   const mdFiles = walkDir(dirPath, /* @__PURE__ */ new Set([".md", ".mdx"]));
-  const allFiles = [...htmlFiles, ...mdFiles];
-  const sampled = allFiles.slice(0, config.sampleSize);
+  const sampleSource = htmlFiles.length > 0 ? htmlFiles : mdFiles;
+  const sampled = sampleSource.slice(0, config.sampleSize);
   const sampledPages = sampled.map((filePath) => {
     const content = readFileSync(filePath, "utf-8");
     const relPath = relative(dirPath, filePath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentimization/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "GEO audit engine. Check if your website is agent-ready and generative-engine optimized.",
   "keywords": [
     "geo",