4e:I[707087,["/_next/static/immutable/chunks/2985g-hklwiee.js","/_next/static/immutable/chunks/0qkc3dps_9x_i.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3thksmxn95rly.js","/_next/static/immutable/chunks/15bpbjna9-vr3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/0agonoz1szsjm.js","/_next/static/immutable/chunks/1ynd3dcge2kn1.js","/_next/static/immutable/chunks/0krdn-21gkgjt.js","/_next/static/immutable/chunks/0n9w9riw96l80.js","/_next/static/immutable/chunks/0w75qangey2ys.js","/_next/static/immutable/chunks/1tge7vcvsb70s.js","/_next/static/immutable/chunks/35ju_ac0ysz07.js"],"RegistryDependencies"] 4f:I[512940,["/_next/static/immutable/chunks/2985g-hklwiee.js","/_next/static/immutable/chunks/0qkc3dps_9x_i.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3thksmxn95rly.js","/_next/static/immutable/chunks/15bpbjna9-vr3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/0agonoz1szsjm.js","/_next/static/immutable/chunks/1ynd3dcge2kn1.js","/_next/static/immutable/chunks/0krdn-21gkgjt.js","/_next/static/immutable/chunks/0n9w9riw96l80.js","/_next/static/immutable/chunks/0w75qangey2ys.js","/_next/static/immutable/chunks/1tge7vcvsb70s.js","/_next/static/immutable/chunks/35ju_ac0ysz07.js"],"Installation"] 50:I[314491,["/_next/static/immutable/chunks/2985g-hklwiee.js","/_next/static/immutable/chunks/0qkc3dps_9x_i.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3thksmxn95rly.js","/_next/static/immutable/chunks/15bpbjna9-vr3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/0agonoz1szsjm.js","/_next/static/immutable/chunks/1ynd3dcge2kn1.js","/_next/static/immutable/chunks/0krdn-21gkgjt.js","/_next/static/immutable/chunks/0n9w9riw96l80.js","/_next/static/immutable/chunks/0w75qangey2ys.js","/_next/static/immutable/chunks/1tge7vcvsb70s.js","/_next/static/immutable/chunks/35ju_ac0ysz07.js"],"FilesView"] 51:T498a,/** Deterministic AI-SEO audit orchestrator (context.dev + rules.ts). */ import { ContextDev } from "context.dev"; import { buildAgentFixPrompts } from "./agent-fix-prompt.ts"; import type { AuditBand, AuditCategory, AuditItem, AuditResult, AuditStatus, } from "./audit-types.ts"; import { CATEGORIES, RULES, countMatches, countWords, type CategoryDef, type DateSignals, type Heading, type JsonObject, type RuleContext, type SchemaSummary, } from "./rules.ts"; import { displayHost } from "./url.ts"; const STATUS_VALUE: Record = { pass: 1, partial: 0.5, fail: 0, na: 0, // N/A rules do not contribute to the score. }; export async function runAudit( normalizedUrl: string, contextDevApiKey: string, ): Promise { const ctx = await buildContext(normalizedUrl, contextDevApiKey); const categories = scoreCategories(ctx); const score = round1(categories.reduce((sum, c) => sum + c.score, 0)); const topPriorities = categories .flatMap((c) => c.items) .filter((item) => item.status === "fail" || item.status === "partial") .sort((a, b) => b.maxScore - a.maxScore) .slice(0, 5) .map((item) => `${item.id}: ${item.recommendation}`); const audit: Omit = { url: normalizedUrl, host: ctx.host, title: ctx.title, description: ctx.description, fetchedAt: new Date().toISOString(), score, band: scoreBand(score), topPriorities, stats: { markdownChars: ctx.markdown.length, rawHtmlChars: ctx.html.length, words: ctx.words, headings: ctx.headings.length, links: ctx.links.length, externalLinks: ctx.externalLinks.length, jsonLdBlocks: ctx.jsonLdBlockCount, }, categories, diagnostics: { contextDevMarkdown: ctx.markdownStatus === "rejected" ? "failed" : ctx.markdown ? "ready" : "empty", contextDevHtml: ctx.htmlStatus === "rejected" ? "failed" : ctx.html ? "ready" : "empty", jsonLdParseFailures: ctx.jsonLdParseFailures, }, }; return { ...audit, agentPrompts: buildAgentFixPrompts(audit) }; } type InternalContext = RuleContext & { markdownStatus: "fulfilled" | "rejected"; htmlStatus: "fulfilled" | "rejected"; }; async function buildContext( normalizedUrl: string, contextDevApiKey: string, ): Promise { const client = new ContextDev({ apiKey: contextDevApiKey }); const url = new URL(normalizedUrl); const host = displayHost(normalizedUrl); const [markdownSettled, htmlSettled] = await Promise.allSettled([ scrapeMarkdown(client, normalizedUrl), scrapeHtml(client, normalizedUrl), ]); const markdown = markdownSettled.status === "fulfilled" ? markdownSettled.value : ""; const html = htmlSettled.status === "fulfilled" ? htmlSettled.value : ""; const htmlText = htmlToText(html); const analysisText = normalizeWhitespace(markdown || htmlText); const title = extractTitle(html) ?? firstMarkdownHeading(markdown); const description = extractMetaContent(html, "description"); const links = extractLinks(html, markdown, normalizedUrl); const externalLinks = links.filter( (link) => new URL(link).origin !== url.origin, ); const sameOriginLinks = links.filter( (link) => new URL(link).origin === url.origin, ); const { schemas: jsonLd, blockCount: jsonLdBlockCount, parseFailures: jsonLdParseFailures, } = extractJsonLd(html); const schema = summarizeSchema(jsonLd); const headings = extractHeadings(html, markdown); const h1Count = Math.max( countMatches(html, / h.level === 1).length, ); const h2Count = Math.max( countMatches(html, / h.level === 2).length, ); const paragraphs = extractParagraphs(markdown || htmlText); const words = countWords(analysisText); const htmlWords = countWords(htmlText); const dataPoints = countDataPoints(analysisText); const grade = fleschKincaidGrade(analysisText); const dateSignals = extractDateSignals(html, analysisText, jsonLd); const canonical = extractCanonical(html); const hasNoIndex = detectNoIndex(html); const faqStatus = computeFaqStatus(analysisText, headings); const hasByline = detectByline(analysisText, schema); return { url, host, title, description, canonical, hasNoIndex, html, htmlText, htmlWords, markdown, analysisText, words, paragraphs, headings, h1Count, h2Count, links, externalLinks, sameOriginLinks, jsonLd, jsonLdBlockCount, jsonLdParseFailures, schema, dataPoints, grade, dateSignals, faqStatus, hasByline, markdownStatus: markdownSettled.status, htmlStatus: htmlSettled.status, }; } function scoreCategories(ctx: RuleContext): AuditCategory[] { return CATEGORIES.map((category) => scoreCategory(category, ctx)); } function scoreCategory(category: CategoryDef, ctx: RuleContext): AuditCategory { const rules = RULES.filter((rule) => rule.categoryId === category.id); const evaluated = rules.map((rule) => ({ rule, result: rule.evaluate(ctx) })); const applicable = evaluated.filter(({ result }) => result.status !== "na"); const denominator = applicable.reduce( (sum, { rule }) => sum + (rule.multiplier ?? 1), 0, ); const items: AuditItem[] = evaluated .map(({ rule, result }) => { if (result.status === "na") { return { id: rule.id, label: rule.label, status: result.status, evidence: result.evidence, recommendation: rule.recommendation, maxScore: 0, score: 0, }; } const participates = denominator > 0; const itemMax = participates ? (category.maxScore * (rule.multiplier ?? 1)) / denominator : 0; return { id: rule.id, label: rule.label, status: result.status, evidence: result.evidence, recommendation: rule.recommendation, maxScore: round1(itemMax), score: round1(itemMax * STATUS_VALUE[result.status]), }; }) .sort((a, b) => b.maxScore - a.maxScore); return { id: category.id, name: category.name, description: category.description, score: round1(items.reduce((sum, item) => sum + item.score, 0)), maxScore: category.maxScore, naExcluded: evaluated.length - applicable.length, items, }; } function scoreBand(score: number): AuditBand { if (score <= 40) { return { label: "Critical", interpretation: "The page is structurally hard for AI engines to fetch, parse, or trust.", }; } if (score <= 55) { return { label: "Below average", interpretation: "Foundations are present in places, but the page is losing extractability and trust signals.", }; } if (score <= 70) { return { label: "Average", interpretation: "The page has reasonable AI SEO hygiene, with gaps in chunking, schema, or authority signals.", }; } if (score <= 85) { return { label: "Strong", interpretation: "The page is structured well enough to compete for AI citations on relevant prompts.", }; } return { label: "Excellent", interpretation: "The page exposes strong crawlability, structure, schema, and trust signals.", }; } async function scrapeMarkdown( client: ContextDev, url: string, ): Promise { const result = await client.web.webScrapeMd({ url, includeLinks: true, includeImages: false, useMainContentOnly: true, }); return result.markdown ?? ""; } async function scrapeHtml(client: ContextDev, url: string): Promise { const result = await client.web.webScrapeHTML({ url, waitForMs: 3000 }); return result.html ?? ""; } function extractTitle(html: string): string | null { const match = html.match(/]*>([\s\S]*?)<\/title>/i); return match ? decodeHtml(normalizeWhitespace(match[1])) : null; } function firstMarkdownHeading(markdown: string): string | null { const match = markdown.match(/^#\s+(.+)$/m); return match ? normalizeWhitespace(match[1]) : null; } function extractMetaContent(html: string, name: string): string | null { const tags = html.match(/]*>/gi) ?? []; for (const tag of tags) { const tagName = getAttr(tag, "name") ?? getAttr(tag, "property"); if (tagName?.toLowerCase() === name.toLowerCase()) { const content = getAttr(tag, "content"); if (content) return decodeHtml(content); } } return null; } function extractCanonical(html: string): string | null { const tags = html.match(/]*>/gi) ?? []; for (const tag of tags) { const rel = getAttr(tag, "rel"); if (rel?.toLowerCase().split(/\s+/).includes("canonical")) { return getAttr(tag, "href"); } } return null; } function detectNoIndex(html: string): boolean { const tags = html.match(/]*>/gi) ?? []; return tags.some((tag) => { const name = getAttr(tag, "name") ?? getAttr(tag, "property"); const content = getAttr(tag, "content") ?? ""; return /robots|googlebot/i.test(name ?? "") && /\bnoindex\b/i.test(content); }); } function getAttr(tag: string, attr: string): string | null { const escaped = attr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); const pattern = new RegExp( `(?:^|\\s)${escaped}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i", ); const match = tag.match(pattern); if (!match) return null; return decodeHtml(match[1] ?? match[2] ?? match[3] ?? ""); } function extractLinks( html: string, markdown: string, baseUrl: string, ): string[] { const raw = new Set(); const anchorTags = html.match(/]*>/gi) ?? []; for (const tag of anchorTags) { const href = getAttr(tag, "href"); if (href) raw.add(href); } for (const match of markdown.matchAll( /\[[^\]]+\]$(https?:\/\/[^)\s]+)$/gi, )) { raw.add(match[1]); } const links = new Set(); for (const href of raw) { try { const url = new URL(href, baseUrl); if (url.protocol === "http:" || url.protocol === "https:") { url.hash = ""; links.add(url.toString()); } } catch { } } return [...links]; } function extractJsonLd(html: string): { schemas: JsonObject[]; blockCount: number; parseFailures: number; } { const pattern = /]*\btype\s*=\s*(?:"\s*application\/ld\+json\s*"|'\s*application\/ld\+json\s*'|application\/ld\+json)[^>]*>([\s\S]*?)<\/script>/gi; const blocks = [...html.matchAll(pattern)]; const schemas: JsonObject[] = []; let parseFailures = 0; for (const block of blocks) { const raw = stripScriptWrappers(block[1]).trim(); if (!raw) continue; const parsed = tryParseJson(raw); if (parsed === undefined) { parseFailures++; continue; } schemas.push(...flattenSchema(parsed)); } return { schemas, blockCount: blocks.length, parseFailures }; } function stripScriptWrappers(body: string): string { let out = body.trim(); out = out.replace(/^$/, ""); out = out.replace(/^\/\/\s*$/, ""); out = out.replace(/^\/\*\s*\s*\*\/$/, ""); return out.trim(); } function tryParseJson(raw: string): unknown { try { return JSON.parse(raw); } catch { try { return JSON.parse(decodeHtml(raw)); } catch { return undefined; } } } function flattenSchema(value: unknown): JsonObject[] { if (Array.isArray(value)) return value.flatMap(flattenSchema); if (!isObject(value)) return []; const objects = [value]; const graph = value["@graph"]; if (Array.isArray(graph)) { objects.push(...graph.filter(isObject)); } return objects; } function summarizeSchema(schemas: JsonObject[]): SchemaSummary { const hasOrganization = schemas.some((s) => hasSchemaType(s, ["Organization", "LocalBusiness", "Corporation"]), ); const organization = schemas.find((s) => hasSchemaType(s, ["Organization", "LocalBusiness", "Corporation"]), ); const sameAsCount = schemas.reduce((sum, s) => { const sameAs = s.sameAs; if (Array.isArray(sameAs)) return sum + sameAs.length; if (typeof sameAs === "string") return sum + 1; return sum; }, 0); const organizationComplete = !!( organization && organization.name && organization.url && organization.logo && sameAsCount >= 1 ); const articles = schemas.filter((s) => hasSchemaType(s, ["Article", "BlogPosting", "NewsArticle"]), ); const articleComplete = articles.some( (s) => s.headline && s.author && s.datePublished && s.dateModified, ); const hasPerson = schemas.some((s) => hasSchemaType(s, ["Person"])); const hasAuthor = schemas.some((s) => !!s.author); const hasFaq = schemas.some((s) => hasSchemaType(s, ["FAQPage"])); return { hasOrganization, organizationComplete, organizationEvidence: hasOrganization ? `Organization-like schema found; complete core fields: ${organizationComplete ? "yes" : "no"}; sameAs links: ${sameAsCount}.` : "No Organization-like schema was found.", hasArticle: articles.length > 0, articleComplete, articleEvidence: articles.length ? `Article-like schema blocks: ${articles.length}; complete authorship/date fields: ${articleComplete ? "yes" : "no"}.` : "No Article or BlogPosting schema was found.", hasPerson, hasAuthor, hasFaq, sameAsCount, }; } function hasSchemaType(schema: JsonObject, types: string[]): boolean { const raw = schema["@type"]; const actual = Array.isArray(raw) ? raw : [raw]; return actual.some( (type) => typeof type === "string" && types.includes(type), ); } function extractHeadings(html: string, markdown: string): Heading[] { const headings: Heading[] = []; for (const match of html.matchAll(/]*>([\s\S]*?)<\/h\1>/gi)) { headings.push({ level: Number(match[1]), text: htmlToText(match[2]) }); } for (const match of markdown.matchAll(/^(#{1,6})\s+(.+)$/gm)) { headings.push({ level: match[1].length, text: normalizeWhitespace(match[2]), }); } const seen = new Set(); return headings.filter((h) => { const key = `${h.level}:${h.text.toLowerCase()}`; if (seen.has(key)) return false; seen.add(key); return h.text.length > 0; }); } function extractParagraphs(text: string): string[] { return text .replace(/```[\s\S]*?```/g, " ") .split(/\n{2,}/) .map((paragraph) => normalizeWhitespace( paragraph .replace(/^#{1,6}\s+/gm, "") .replace(/^[-*]\s+/gm, "") .replace(/\[[^\]]+\]$([^)]+)$/g, "$1"), ), ) .filter((paragraph) => countWords(paragraph) >= 8); } function countDataPoints(text: string): number { const matches = text.match( /\b(?:19|20)\d{2}\b|\b\d+(?:\.\d+)?\s?%|\$\s?\d+(?:[,.]\d+)*|\b\d+(?:\.\d+)?x\b|\b\d+(?:,\d{3})+(?:\.\d+)?\b/g, ); return matches ? matches.length : 0; } function extractDateSignals( html: string, text: string, schemas: JsonObject[], ): DateSignals { const hasSchemaModified = schemas.some((s) => !!s.dateModified); const hasTimeTag = /]*(datetime=|>)/i.test(html); const hasVisibleModified = /\b(updated|last updated|modified|last modified)\b.{0,40}\b(?:19|20)\d{2}\b/i.test( text, ); const hasAnyDate = hasSchemaModified || hasTimeTag || /\b(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\.?\s+\d{1,2},?\s+(?:19|20)\d{2}\b/i.test( text, ) || /\b(?:19|20)\d{2}-\d{2}-\d{2}\b/.test(text); return { hasAnyDate, hasModifiedDate: hasSchemaModified || hasVisibleModified, evidence: `dateModified schema: ${hasSchemaModified ? "yes" : "no"}; visible modified date: ${hasVisibleModified ? "yes" : "no"}; time tag: ${hasTimeTag ? "yes" : "no"}.`, }; } function computeFaqStatus(text: string, headings: Heading[]): AuditStatus { const questionHeadings = headings.filter((h) => h.text.includes("?")); if ( /\b(faq|frequently asked questions|questions and answers)\b/i.test(text) ) { return "pass"; } if (questionHeadings.length >= 2) return "pass"; if (questionHeadings.length === 1 || countMatches(text, /\?/g) >= 2) { return "partial"; } return "fail"; } function detectByline(text: string, schema: SchemaSummary): boolean { if (schema.hasPerson || schema.hasAuthor) return true; return /\b(by|written by|reviewed by|edited by)\s+[A-Z][A-Za-z.'-]+(?:\s+[A-Z][A-Za-z.'-]+){0,3}\b/.test( text, ); } function htmlToText(html: string): string { return normalizeWhitespace( decodeHtml( html .replace(//gi, " ") .replace(//gi, " ") .replace(//gi, " ") .replace(/<[^>]+>/g, " "), ), ); } function normalizeWhitespace(value: string): string { return value.replace(/\s+/g, " ").trim(); } function decodeHtml(value: string): string { return value .replace(/ /g, " ") .replace(/&/g, "&") .replace(/"/g, '"') .replace(/'/g, "'") .replace(/</g, "<") .replace(/>/g, ">"); } function fleschKincaidGrade(text: string): number | null { if (cjkRatio(text) > 0.35) return null; const words = text.match(/[A-Za-z][A-Za-z'-]*/g) ?? []; const sentences = text.match(/[.!?]+(?:\s|$)/g) ?? []; if (words.length < 80 || sentences.length < 3) return null; const syllables = words.reduce((sum, w) => sum + countSyllables(w), 0); return ( 0.39 * (words.length / sentences.length) + 11.8 * (syllables / words.length) - 15.59 ); } function cjkRatio(text: string): number { const cjk = text.match(/[一-鿿㐀-䶿豈-﫿぀-ゟ゠-ヿ가-힯]/g); return Math.min(text.length, 1) ? (cjk?.length ?? 0) / Math.max(text.length, 1) : 0; } function countSyllables(word: string): number { const cleaned = word.toLowerCase().replace(/[^a-z]/g, ""); if (!cleaned) return 1; const withoutSilentE = cleaned.replace(/e$/, ""); const groups = withoutSilentE.match(/[aeiouy]+/g); return Math.max(groups?.length ?? 1, 1); } function round1(value: number): number { return Math.round(value * 10) / 10; } function isObject(value: unknown): value is JsonObject { return !!value && typeof value === "object" && !Array.isArray(value); } export { CATEGORIES, RULES } from "./rules.ts"; export type { Rule, RuleContext, CategoryDef } from "./rules.ts"; 52:T7365,/** AI-SEO audit rules, categories, and scoring helpers. */ import type { AuditStatus } from "./audit-types.ts"; export type RuleDependency = | "url" | "title" | "description" | "html" | "markdown" | "text" | "canonical" | "noindex-meta" | "links" | "json-ld" | "schema-summary" | "headings" | "paragraphs" | "data-points" | "date-signals" | "readability"; export type SchemaSummary = { hasOrganization: boolean; organizationComplete: boolean; organizationEvidence: string; hasArticle: boolean; articleComplete: boolean; articleEvidence: string; hasPerson: boolean; hasAuthor: boolean; hasFaq: boolean; sameAsCount: number; }; export type DateSignals = { hasAnyDate: boolean; hasModifiedDate: boolean; evidence: string; }; export type Heading = { level: number; text: string }; export type JsonObject = Record; export type RuleContext = { url: URL; host: string; title: string | null; description: string | null; canonical: string | null; hasNoIndex: boolean; html: string; htmlText: string; htmlWords: number; markdown: string; analysisText: string; words: number; paragraphs: string[]; headings: Heading[]; h1Count: number; h2Count: number; links: string[]; externalLinks: string[]; sameOriginLinks: string[]; jsonLd: JsonObject[]; jsonLdBlockCount: number; jsonLdParseFailures: number; schema: SchemaSummary; dataPoints: number; grade: number | null; dateSignals: DateSignals; faqStatus: AuditStatus; hasByline: boolean; }; export type RuleEvaluation = { status: AuditStatus; evidence: string; }; export type Rule = { id: string; categoryId: string; label: string; recommendation: string; dependencies: RuleDependency[]; multiplier?: number; evaluate: (ctx: RuleContext) => RuleEvaluation; }; export type CategoryDef = { id: string; name: string; description: string; maxScore: number; }; export const CATEGORIES: CategoryDef[] = [ { id: "A", name: "Technical AI Crawlability", description: "Can AI retrieval crawlers fetch and parse the page without JavaScript?", maxScore: 28.4, }, { id: "B", name: "Content Structure & Chunking", description: "Can answer engines extract self-contained, quotable passages?", maxScore: 25.4, }, { id: "C", name: "Structured Data / Schema", description: "Does the raw HTML expose machine-readable entities and page facts?", maxScore: 13.4, }, { id: "D", name: "E-E-A-T & Entity Authority", description: "Does the page expose trust, authorship, and entity signals?", maxScore: 21.4, }, { id: "E", name: "Off-site / Citation Surface Presence", description: "Does the page connect the brand to surfaces AI engines often cite?", maxScore: 8.4, }, { id: "F", name: "Measurement & Governance", description: "Are monitoring and refresh signals visible or inferable?", maxScore: 3, }, ]; export const RULES: Rule[] = [ { id: "A1", categoryId: "A", label: "HTTPS is used for the audited URL.", recommendation: "Serve the page over HTTPS and redirect HTTP to HTTPS with a single 301.", dependencies: ["url"], evaluate: (ctx) => ({ status: ctx.url.protocol === "https:" ? "pass" : "fail", evidence: ctx.url.protocol === "https:" ? "The submitted URL uses HTTPS." : "The submitted URL is not HTTPS.", }), }, { id: "A8", categoryId: "A", label: "Critical content is present in the raw HTML response.", recommendation: "Render primary copy, headings, FAQs, and schema on the server. AI crawlers often do not execute client-side JavaScript.", dependencies: ["html", "text"], multiplier: 2, evaluate: (ctx) => { const htmlWords = ctx.htmlWords; const extracted = Math.max(ctx.words, 1); const ratio = htmlWords / extracted; const status: AuditStatus = htmlWords >= 250 && ratio >= 0.35 ? "pass" : htmlWords >= 80 ? "partial" : "fail"; return { status, evidence: `${htmlWords} readable words were found in raw HTML; Context.dev extracted ${ctx.words} words from the page.`, }; }, }, { id: "A11", categoryId: "A", label: "Canonical tag is present and points to an indexable URL.", recommendation: "Add a self-referencing canonical tag, or a deliberate canonical target for duplicate variants.", dependencies: ["canonical"], evaluate: (ctx) => ({ status: ctx.canonical ? "pass" : "fail", evidence: ctx.canonical ? `Canonical URL: ${ctx.canonical}.` : "No canonical link tag was found in the raw HTML.", }), }, { id: "A12", categoryId: "A", label: "No noindex directive was found.", recommendation: "Remove noindex from pages that should be eligible for AI search citation.", dependencies: ["noindex-meta"], evaluate: (ctx) => ({ status: ctx.hasNoIndex ? "fail" : "pass", evidence: ctx.hasNoIndex ? "A robots noindex directive appears in the page HTML." : "No robots noindex directive was detected in the raw HTML.", }), }, { id: "B1", categoryId: "B", label: "The page opens with a direct-answer BLUF intro naming the entity.", recommendation: "Start with a 2-3 sentence answer that names the brand, product, or topic and states what the page is about.", dependencies: ["paragraphs", "title", "url"], evaluate: (ctx) => { const first = firstUsefulParagraph(ctx.paragraphs); let status: AuditStatus = "fail"; if (first) { const w = countWords(first); const tokens = [ ctx.host.split(".")[0], ...(ctx.title ?? "") .split(/[\s|:.-]+/) .filter((t) => t.length > 3) .slice(0, 4), ].filter(Boolean); const namesEntity = tokens.some((t) => new RegExp(`\\b${escapeRegExp(t)}\\b`, "i").test(first), ); const answerPattern = /\b(is|are|helps|provides|offers|refers to|means|enables|builds|delivers)\b/i.test( first, ); if (w >= 20 && w <= 90 && namesEntity && answerPattern) status = "pass"; else if (w >= 12 && w <= 130 && (namesEntity || answerPattern)) status = "partial"; } return { status, evidence: first ? `First substantive paragraph: "${clip(first, 180)}"` : "No substantive opening paragraph was extracted.", }; }, }, { id: "B2", categoryId: "B", label: "Heading hierarchy is clear with one H1 and topical H2 sections.", recommendation: "Use one H1, then H2/H3 boundaries for each answerable topic or sub-query.", dependencies: ["headings"], evaluate: (ctx) => { const status: AuditStatus = ctx.h1Count === 1 && ctx.h2Count >= 2 ? "pass" : ctx.h1Count >= 1 && ctx.h2Count >= 1 ? "partial" : "fail"; return { status, evidence: `Detected ${ctx.h1Count} H1 heading(s), ${ctx.h2Count} H2 heading(s), and ${ctx.headings.length} total Markdown/HTML headings.`, }; }, }, { id: "B3", categoryId: "B", label: "Paragraphs are short enough for passage retrieval.", recommendation: "Keep paragraphs to one idea each, usually 1-4 sentences and under roughly 120 words.", dependencies: ["paragraphs"], evaluate: (ctx) => { const paragraphs = ctx.paragraphs; const long = paragraphs.filter((p) => countWords(p) > 120).length; const veryLong = paragraphs.filter((p) => countWords(p) > 180).length; let status: AuditStatus = "fail"; if (paragraphs.length) { if (veryLong === 0 && long / paragraphs.length <= 0.15) status = "pass"; else if (veryLong <= 2 && long / paragraphs.length <= 0.35) status = "partial"; } return { status, evidence: `${paragraphs.length} paragraph(s) found; ${long} exceed 120 words.`, }; }, }, { id: "B4", categoryId: "B", label: "Sections are self-contained semantic chunks.", recommendation: "Break long pages into specific H2/H3 sections that can stand alone when retrieved as chunks.", dependencies: ["headings", "text"], evaluate: (ctx) => { const status: AuditStatus = ctx.h2Count >= 3 && ctx.words / Math.max(ctx.h2Count, 1) <= 450 ? "pass" : ctx.h2Count >= 2 ? "partial" : "fail"; return { status, evidence: `${ctx.words} words across ${Math.max(ctx.h2Count, 1)} H2-level section(s).`, }; }, }, { id: "B5", categoryId: "B", label: "FAQ or Q&A structure appears where appropriate.", recommendation: "Add a concise FAQ section for common prompt-style questions, especially on commercial and informational pages.", dependencies: ["text", "headings"], evaluate: (ctx) => ({ status: ctx.faqStatus, evidence: `${countMatches(ctx.analysisText, /\?/g)} question mark(s) and ${ctx.headings.filter((h) => h.text.includes("?")).length} question-style heading(s) detected.`, }), }, { id: "B6", categoryId: "B", label: "The page contains concrete data points.", recommendation: "Add dated statistics, named sources, percentages, benchmarks, prices, or other extractable facts.", dependencies: ["data-points"], evaluate: (ctx) => ({ status: ctx.dataPoints >= 3 ? "pass" : ctx.dataPoints >= 1 ? "partial" : "fail", evidence: `${ctx.dataPoints} dated specifics, percentages, money values, multipliers, or named-entity-like data points were detected.`, }), }, { id: "B7", categoryId: "B", label: "Quoted source or expert language is present.", recommendation: "Include at least one clearly attributed quote or sourced claim on long-form pages.", dependencies: ["markdown", "text"], evaluate: (ctx) => { const blockquote = /(^|\n)\s*>/.test(ctx.markdown); const accordingTo = /\baccording to\b/i.test(ctx.analysisText); const inlineQuote = /"[^"]{20,}"/.test(ctx.analysisText); const status: AuditStatus = blockquote || accordingTo ? "pass" : inlineQuote ? "partial" : "fail"; return { status, evidence: blockquote ? "Markdown blockquote syntax was found." : accordingTo ? 'The phrase "according to" was found.' : "No obvious quotation or source-attribution pattern was found.", }; }, }, { id: "B8", categoryId: "B", label: "External citations support major claims.", recommendation: "Link major factual claims to authoritative external sources so AI engines can cross-check them.", dependencies: ["links"], evaluate: (ctx) => ({ status: ctx.externalLinks.length >= 3 ? "pass" : ctx.externalLinks.length >= 1 ? "partial" : "fail", evidence: `${ctx.externalLinks.length} external link(s) were detected.`, }), }, { id: "B10", categoryId: "B", label: "Definitional sentence patterns are present.", recommendation: 'Use patterns like "X is defined as..." or "X refers to..." for core concepts.', dependencies: ["text"], evaluate: (ctx) => { const found = /\b(is defined as|are defined as|refers to|means|is a|is an)\b/i.test( ctx.analysisText, ); return { status: found ? "pass" : "fail", evidence: found ? "A definitional sentence pattern was detected." : "No clear definitional sentence pattern was detected.", }; }, }, { id: "B11", categoryId: "B", label: "Internal links create sibling-page fan-out coverage.", recommendation: "Link to at least three related pages that cover adjacent questions, comparisons, use cases, or FAQs.", dependencies: ["links"], evaluate: (ctx) => ({ status: ctx.sameOriginLinks.length >= 3 ? "pass" : ctx.sameOriginLinks.length >= 1 ? "partial" : "fail", evidence: `${ctx.sameOriginLinks.length} same-origin link(s) were detected in the page HTML or Markdown.`, }), }, { id: "B12", categoryId: "B", label: "A visible or structured last-updated date exists.", recommendation: "Show a visible updated date and include dateModified in schema for pages that should be cited.", dependencies: ["date-signals", "url", "text"], evaluate: (ctx) => { if (!isArticleLike(ctx)) { return { status: "na", evidence: "This page does not look like an article or blog post, so a last-updated date is not required.", }; } return { status: ctx.dateSignals.hasModifiedDate ? "pass" : ctx.dateSignals.hasAnyDate ? "partial" : "fail", evidence: ctx.dateSignals.evidence, }; }, }, { id: "B13", categoryId: "B", label: "Readability is in a useful AI citation range.", recommendation: "Aim for clear expert prose: specific enough to be trusted, but not dense academic copy.", dependencies: ["readability"], evaluate: (ctx) => { const g = ctx.grade; const status: AuditStatus = g === null ? "partial" : g >= 10 && g <= 16 ? "pass" : g >= 7 && g <= 20 ? "partial" : "fail"; return { status, evidence: g === null ? "Readability could not be estimated from the extracted text." : `Estimated Flesch-Kincaid grade level is ${g.toFixed(1)}.`, }; }, }, { id: "B14", categoryId: "B", label: "Lists or tables make comparisons machine-extractable.", recommendation: "Use bullets, numbered lists, and tables for steps, comparisons, pros/cons, and factual summaries.", dependencies: ["markdown", "html"], evaluate: (ctx) => { const lists = countMatches(ctx.markdown, /^[-*]\s+/gm) + countMatches(ctx.html, /= 1 || lists >= 6 ? "pass" : lists >= 2 ? "partial" : "fail"; return { status, evidence: `${lists} list item(s) and ${tables} table signal(s) detected.`, }; }, }, { id: "C1", categoryId: "C", label: "JSON-LD structured data is present.", recommendation: "Add server-rendered JSON-LD. Start with WebPage, Organization, Article, Person, and FAQPage as applicable.", dependencies: ["json-ld"], evaluate: (ctx) => { const failureNote = ctx.jsonLdParseFailures > 0 ? ` ${ctx.jsonLdParseFailures} block(s) were present but failed to parse; check for malformed JSON.` : ""; return { status: ctx.jsonLd.length > 0 ? "pass" : "fail", evidence: `${ctx.jsonLd.length} JSON-LD entity(ies) parsed from ${ctx.jsonLdBlockCount} script block(s).${failureNote}`, }; }, }, { id: "C2", categoryId: "C", label: "Organization schema includes name, URL, logo, and sameAs.", recommendation: "Add Organization schema with name, url, logo, and sameAs links to authoritative profiles.", dependencies: ["schema-summary"], evaluate: (ctx) => ({ status: ctx.schema.organizationComplete ? "pass" : ctx.schema.hasOrganization ? "partial" : "fail", evidence: ctx.schema.organizationEvidence, }), }, { id: "C3", categoryId: "C", label: "Article or BlogPosting schema includes authorship and dates.", recommendation: "For editorial pages, include Article or BlogPosting schema with headline, author, datePublished, and dateModified.", dependencies: ["schema-summary", "text", "url"], evaluate: (ctx) => { const status: AuditStatus = ctx.schema.articleComplete ? "pass" : ctx.schema.hasArticle ? "partial" : isArticleLike(ctx) ? "fail" : "na"; return { status, evidence: ctx.schema.articleEvidence }; }, }, { id: "C4", categoryId: "C", label: "Person schema supports visible authors.", recommendation: "Add Person schema for each author, including jobTitle, worksFor, credentials, and sameAs profiles.", dependencies: ["schema-summary", "text", "url"], evaluate: (ctx) => { if (!isArticleLike(ctx)) { return { status: "na", evidence: "This page does not look like an article or blog post, so Person schema is not required.", }; } return { status: ctx.schema.hasPerson ? "pass" : ctx.hasByline ? "partial" : "fail", evidence: ctx.schema.hasPerson ? "Person schema was found." : ctx.hasByline ? "A byline was detected, but no Person schema was found." : "No Person schema or byline signal was found.", }; }, }, { id: "C5", categoryId: "C", label: "FAQPage schema exists when Q&A content exists.", recommendation: "When FAQ content is visible, mirror the questions and answers in FAQPage JSON-LD.", dependencies: ["schema-summary", "text", "headings"], evaluate: (ctx) => ({ status: ctx.faqStatus === "fail" ? "na" : ctx.schema.hasFaq ? "pass" : "fail", evidence: ctx.schema.hasFaq ? "FAQPage schema was found." : "FAQ-like content was found without FAQPage schema.", }), }, { id: "C11", categoryId: "C", label: "Schema appears in the initial HTML response.", recommendation: "Do not rely on client-side JavaScript to inject important schema.", dependencies: ["json-ld"], evaluate: (ctx) => ({ status: ctx.jsonLd.length > 0 ? "pass" : "fail", evidence: ctx.jsonLd.length > 0 ? "JSON-LD was present in the raw HTML response." : "No JSON-LD was present in the raw HTML response.", }), }, { id: "D5", categoryId: "D", label: "About, company, trust, or newsroom pages are linked.", recommendation: "Make About, Company, Trust, or Newsroom pages easy to reach from the audited page.", dependencies: ["links"], evaluate: (ctx) => { const pattern = /(about|company|trust|newsroom|press)/i; return { status: linkPathStatus(ctx.links, pattern), evidence: `${ctx.links.filter((l) => pattern.test(l)).length} about/trust/newsroom-style link(s) detected.`, }; }, }, { id: "D6", categoryId: "D", label: "Privacy, terms, and contact information are linked.", recommendation: "Expose privacy policy, terms, contact, and support paths in the page chrome or footer.", dependencies: ["links"], evaluate: (ctx) => { const privacy = linkPathStatus(ctx.links, /(privacy)/i); const terms = linkPathStatus(ctx.links, /(terms|legal)/i); const contact = linkPathStatus(ctx.links, /(contact|support)/i); const combined = linkPathStatus( ctx.links, /(privacy|terms|legal|contact|support)/i, ); const status: AuditStatus = privacy === "pass" && terms !== "fail" && contact !== "fail" ? "pass" : combined; return { status, evidence: `${ctx.links.filter((l) => /(privacy|terms|legal|contact|support)/i.test(l)).length} privacy/terms/contact-style link(s) detected.`, }; }, }, { id: "D10", categoryId: "D", label: "Original research or proprietary data signals exist.", recommendation: "Publish original data, methodology, benchmarks, or named research that other sites can cite.", dependencies: ["text", "data-points"], multiplier: 1 / 3, evaluate: (ctx) => { const found = /\b(original research|study|survey|benchmark|dataset|methodology|proprietary data|we analyzed|we measured)\b/i.test( ctx.analysisText, ); const status: AuditStatus = found ? "pass" : ctx.dataPoints >= 3 ? "partial" : "fail"; return { status, evidence: found ? "Research or methodology language was detected." : `${ctx.dataPoints} data point(s) were detected without strong original-research language.`, }; }, }, { id: "D12", categoryId: "D", label: "Brand/entity descriptors are consistent.", recommendation: "Use the same brand name, category, and entity descriptors in title, meta description, headings, schema, and body copy.", dependencies: ["title", "description", "text"], evaluate: (ctx) => { const brand = ctx.host.split(".")[0]; const titleHasBrand = !!ctx.title && new RegExp(escapeRegExp(brand), "i").test(ctx.title); const descHasBrand = !!ctx.description && new RegExp(escapeRegExp(brand), "i").test(ctx.description); const bodyMentions = countMatches( ctx.analysisText, new RegExp(`\\b${escapeRegExp(brand)}\\b`, "gi"), ); const status: AuditStatus = titleHasBrand && descHasBrand && bodyMentions >= 2 ? "pass" : titleHasBrand || descHasBrand || bodyMentions >= 1 ? "partial" : "fail"; return { status, evidence: `Brand token "${brand}" appears in title: ${ctx.title ? "yes" : "no"}, meta description: ${ctx.description ? "yes" : "no"}, body mentions: ${bodyMentions}.`, }; }, }, { id: "E1", categoryId: "E", label: "Review or marketplace citation surfaces are linked.", recommendation: "Link to maintained profiles on review or marketplace sites (G2, Capterra, Trustpilot, Gartner, ProductHunt) that match your category.", dependencies: ["links", "text", "json-ld"], multiplier: 0.5, evaluate: (ctx) => { const pattern = /(g2\.com|capterra\.com|trustpilot\.com|gartner\.com|producthunt\.com)/i; const count = ctx.externalLinks.filter((l) => pattern.test(l)).length; if (count > 0) { return { status: "pass", evidence: `${count} review/marketplace link(s) detected.`, }; } if (!isCommercialOfferingLike(ctx)) { return { status: "na", evidence: "This page does not look like a commercial product or SaaS offering, so review/marketplace profiles are not expected.", }; } return { status: "fail", evidence: "Page reads as a commercial product/SaaS offering, but no review or marketplace profile link was detected.", }; }, }, { id: "E7", categoryId: "E", label: "GitHub or developer surface is linked when relevant.", recommendation: "For technical products, link active GitHub repositories, examples, or developer docs.", dependencies: ["links", "text", "json-ld", "url"], evaluate: (ctx) => { const found = /github\.com/i.test(ctx.externalLinks.join(" ")); if (found) { return { status: "pass", evidence: "A GitHub link was detected." }; } if (!isTechnicalProductLike(ctx)) { return { status: "na", evidence: "This page does not look like a technical or developer product, so a GitHub surface is not expected.", }; } return { status: "fail", evidence: "Page reads as a developer/technical product, but no GitHub link was detected.", }; }, }, { id: "E10", categoryId: "E", label: "Entity disambiguation is supported by sameAs links.", recommendation: "Use sameAs links to Wikidata, LinkedIn, Crunchbase, Wikipedia, GitHub, or other authoritative profiles on Organization or Person schema.", dependencies: ["schema-summary"], evaluate: (ctx) => { if (!hasDisambiguableEntity(ctx)) { return { status: "na", evidence: "No Organization, Person, or Article entity was found on this page to attach sameAs links to.", }; } return { status: ctx.schema.sameAsCount >= 3 ? "pass" : ctx.schema.sameAsCount >= 1 ? "partial" : "fail", evidence: `${ctx.schema.sameAsCount} sameAs link(s) were found in JSON-LD.`, }; }, }, { id: "E12", categoryId: "E", label: "Outbound citations place the entity near named category sources.", recommendation: "Cite and co-occur with authoritative category sources, benchmarks, standards, and named experts.", dependencies: ["links", "data-points"], evaluate: (ctx) => ({ status: ctx.externalLinks.length >= 5 && ctx.dataPoints >= 3 ? "pass" : ctx.externalLinks.length >= 2 ? "partial" : "fail", evidence: `${ctx.externalLinks.length} external link(s) and ${ctx.dataPoints} data point(s) were detected.`, }), }, { id: "F6", categoryId: "F", label: "A content refresh signal is visible.", recommendation: "Publish visible updated dates and refresh important pages quarterly.", dependencies: ["date-signals", "url", "text"], evaluate: (ctx) => { if (!isArticleLike(ctx)) { return { status: "na", evidence: "This page does not look like an article or blog post, so a refresh-date signal is not required.", }; } return { status: ctx.dateSignals.hasModifiedDate ? "pass" : ctx.dateSignals.hasAnyDate ? "partial" : "fail", evidence: ctx.dateSignals.evidence, }; }, }, ]; export function countWords(text: string): number { if (typeof Intl !== "undefined" && "Segmenter" in Intl) { try { const segmenter = new Intl.Segmenter(undefined, { granularity: "word" }); let count = 0; for (const segment of segmenter.segment(text)) { if (segment.isWordLike) count++; } return count; } catch { } } const latin = text.match(/[A-Za-z0-9À-ɏ][A-Za-z0-9À-ɏ'-]*/g) ?? []; const cjk = text.match( /[一-鿿㐀-䶿豈-﫿぀-ゟ゠-ヿ가-힯]/g, ); return latin.length + (cjk?.length ?? 0); } export function countMatches(text: string, pattern: RegExp): number { return text.match(pattern)?.length ?? 0; } export function escapeRegExp(value: string): string { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); } function clip(value: string, max: number): string { return value.length <= max ? value : `${value.slice(0, max - 1)}...`; } function firstUsefulParagraph(paragraphs: string[]): string { return paragraphs.find((p) => countWords(p) >= 12) ?? ""; } function isArticleLike(ctx: RuleContext): boolean { return ( /\/(blog|article|articles|guide|guides|news|post|posts|insight|insights|research)\//i.test( ctx.url.pathname, ) || ctx.schema.hasArticle ); } function isCommercialOfferingLike(ctx: RuleContext): boolean { if (isArticleLike(ctx)) return false; if ( hasJsonLdType(ctx, [ "Product", "SoftwareApplication", "WebApplication", "MobileApplication", "Service", "Offer", ]) ) { return true; } return /\b(pricing|free trial|start free|sign up|signup|sign-up|get started|request a demo|schedule a demo|book a demo|buy now|add to cart|subscribe|per (?:month|user|seat)|saas|platform|software)\b/i.test( ctx.analysisText, ); } function isTechnicalProductLike(ctx: RuleContext): boolean { if ( hasJsonLdType(ctx, [ "SoftwareApplication", "SoftwareSourceCode", "APIReference", ]) ) { return true; } if (/\/(docs?|api|sdk|reference|developers?)(\/|$)/i.test(ctx.url.pathname)) { return true; } return /\b(api|sdk|cli|library|framework|open[- ]source|developer (?:portal|docs|guide)|npm install|pip install|brew install|github\.com\/[^\s]+)\b/i.test( ctx.analysisText, ); } function hasDisambiguableEntity(ctx: RuleContext): boolean { return ( ctx.schema.hasOrganization || ctx.schema.hasPerson || ctx.schema.hasArticle ); } function hasJsonLdType(ctx: RuleContext, types: string[]): boolean { return ctx.jsonLd.some((obj) => { const raw = obj["@type"]; const actual = Array.isArray(raw) ? raw : [raw]; return actual.some( (type) => typeof type === "string" && types.includes(type), ); }); } function linkPathStatus(links: string[], pattern: RegExp): AuditStatus { const count = links.filter((l) => pattern.test(l)).length; if (count >= 2) return "pass"; if (count === 1) return "partial"; return "fail"; } export const RULES_BY_ID: Record = Object.fromEntries( RULES.map((rule) => [rule.id, rule]), ); export const CATEGORIES_BY_ID: Record = Object.fromEntries( CATEGORIES.map((c) => [c.id, c]), ); 53:Tbf6,import type { AgentFixPrompts, AuditItem, AuditResult } from "./audit-types.ts"; type PromptAudit = Omit; type PromptIssue = AuditItem & { categoryId: string; categoryName: string; }; const ACTIONABLE_STATUSES = new Set(["fail", "partial"]); export function buildAgentFixPrompts(audit: PromptAudit): AgentFixPrompts { const issues = audit.categories.flatMap((category) => category.items.map((item) => ({ ...item, categoryId: category.id, categoryName: category.name, })), ); const actionable = issues .filter((issue) => ACTIONABLE_STATUSES.has(issue.status)) .sort((a, b) => b.maxScore - a.maxScore || a.id.localeCompare(b.id)); const topIssues = actionable.slice(0, 8).map((issue) => ({ id: issue.id, label: issue.label, prompt: buildIssuePrompt(audit, issue), })); return { full: buildFullPrompt(audit, actionable), topIssues, }; } function buildFullPrompt( audit: PromptAudit, actionable: PromptIssue[], ): string { const issueLines = actionable.length ? actionable.map(formatIssue).join("\n\n") : "No failing or partial automated checks were found."; return `You are an AI SEO implementation agent. Improve the audited page so it is easier for AI answer engines to crawl, parse, trust, and cite. Target URL: ${audit.url} Current score: ${audit.score}/100 (${audit.band.label}) Audit source: guidelines.md in this repository Rules: - Fix the issues below in priority order. - Preserve the page's existing product intent and brand voice. - Do not fabricate off-site authority, reviews, authorship, credentials, dates, or analytics evidence. - Prefer server-rendered HTML for critical copy, headings, FAQs, schema, and metadata. - After changes, run the project's lint, typecheck, and build commands if available. Automated issues to fix: ${issueLines} Expected output from you: 1. A concise summary of what changed. 2. The files changed. 3. The verification commands run and their results.`; } function buildIssuePrompt(audit: PromptAudit, issue: PromptIssue): string { return `You are an AI SEO implementation agent. Fix this single audit finding. Target URL: ${audit.url} Finding: ${issue.id} ${issue.label} Category: ${issue.categoryName} Status: ${issue.status} Score impact: ${issue.maxScore.toFixed(1)} possible points Evidence: ${issue.evidence} Required fix: ${issue.recommendation} Acceptance criteria: - The fix is visible in raw server-rendered HTML when relevant. - The change does not fabricate facts, off-site authority, authors, credentials, or dates. - The page remains useful to human readers. - Lint, typecheck, and build pass if this is a codebase change. Report back with files changed and verification performed.`; } function formatIssue(issue: PromptIssue): string { return `- ${issue.id} ${issue.label} Category: ${issue.categoryName} Status: ${issue.status} Score impact: ${issue.maxScore.toFixed(1)} possible points Evidence: ${issue.evidence} Required fix: ${issue.recommendation}`; } 54:T5e8,export type AuditStatus = "pass" | "partial" | "fail" | "na"; export type AuditItem = { id: string; label: string; status: AuditStatus; evidence: string; recommendation: string; score: number; maxScore: number; }; export type AuditCategory = { id: string; name: string; description: string; score: number; maxScore: number; naExcluded: number; items: AuditItem[]; }; export type AuditBand = { label: "Critical" | "Below average" | "Average" | "Strong" | "Excellent"; interpretation: string; }; export type AgentFixPrompts = { full: string; topIssues: Array<{ id: string; label: string; prompt: string; }>; }; export type AuditResult = { url: string; host: string; title: string | null; description: string | null; fetchedAt: string; score: number; band: AuditBand; topPriorities: string[]; agentPrompts: AgentFixPrompts; stats: { markdownChars: number; rawHtmlChars: number; words: number; headings: number; links: number; externalLinks: number; jsonLdBlocks: number; }; categories: AuditCategory[]; diagnostics: { contextDevMarkdown: "ready" | "empty" | "failed"; contextDevHtml: "ready" | "empty" | "failed"; jsonLdParseFailures: number; }; }; export type AuditApiResponse = | { status: "ready"; audit: AuditResult; cached: boolean; updatedAt?: number; } | { status: "error" | "missing-env"; message: string; missing?: string[]; }; 55:T977,--- name: seo-audit description: How to present the deterministic AI-SEO audit returned by audit_page. Use when reporting a page's readability and citation-readiness for AI answer engines (ChatGPT, Claude, Perplexity). --- ## What this measures How well a page can be **crawled, chunked, understood, and cited by AI answer engines** — not classic blue-link SEO. The `audit_page` tool computes this deterministically: page data flows through context.dev, then a fixed rubric of ~30 checks scores six categories into a 0–100 total. Your job is to **present** that result, not to re-score it. ## The result shape `audit_page` returns JSON with: - `score` (0–100) and `band` (`{ label, interpretation }`). - `stats` — words, headings, links, externalLinks, jsonLdBlocks, char counts. - `categories[]` — each `{ id, name, score, maxScore, naExcluded, items[] }`. - `categories[].items[]` — each check: `{ id, label, status, evidence, recommendation, score, maxScore }`. `status` is `pass | partial | fail | na`. - `topPriorities[]` — the highest-impact failing/partial checks, pre-sorted. - `agentPrompts` — `{ full, topIssues[] }`, ready-to-run fix prompts. - `diagnostics` — context.dev fetch status and JSON-LD parse failures. ## The six categories | ID | Category | Max | | -- | -------- | --- | | A | Technical AI Crawlability | 28.4 | | B | Content Structure & Chunking | 25.4 | | C | Structured Data / Schema | 13.4 | | D | E-E-A-T & Entity Authority | 21.4 | | E | Off-site / Citation Surface Presence | 8.4 | | F | Measurement & Governance | 3 | Scoring (already applied by the tool): `pass` = full weight, `partial` = half, `fail` = 0, `na` = excluded from the denominator. Bands: **Critical** ≤40 · **Below average** ≤55 · **Average** ≤70 · **Strong** ≤85 · **Excellent** >85. ## Output Report, in order: 1. The overall `score`/100, its `band.label`, and the `band.interpretation`. 2. A per-category breakdown: for each category, `score`/`maxScore` and the pass/partial/fail counts. 3. The failing and partial checks, highest-impact first — use `topPriorities` and the matching `items` (cite each check's `id`, `evidence`, and `recommendation`). 4. The **agent-ready fix prompt**: present `agentPrompts.full` verbatim in a copy-paste block. Report only the checks and numbers the tool returned. Never invent or recompute scores, checks, evidence, or content. 4a:["$","div",null,{"className":"flex flex-col gap-12","children":[["$","div",null,{"className":"pt-10 flex flex-col gap-4","children":[["$","ul",null,{"className":"flex gap-2 flex-wrap","children":[["$","li","@flue/runtime",{"children":["$","a",null,{"href":"https://www.npmjs.com/package/%40flue%2Fruntime","target":"_blank","rel":"noopener noreferrer","className":"rounded-md border p-2 text-sm flex items-center gap-1 ","children":[["$","svg",null,{"viewBox":"0 0 24 24","className":"size-3","children":["$","path",null,{"d":"M1.763 0C.786 0 0 .786 0 1.763v20.474C0 23.214.786 24 1.763 24h20.474c.977 0 1.763-.786 1.763-1.763V1.763C24 .786 23.214 0 22.237 0zM5.13 5.323l13.837.019-.009 13.836h-3.464l.01-10.382h-3.456L12.04 19.17H5.113z","fill":"currentColor"}]}],["$","span",null,{"className":"text-xs font-medium","children":"@flue/runtime"}]]}]}],["$","li","context.dev",{"children":["$","a",null,{"href":"https://www.npmjs.com/package/context.dev","target":"_blank","rel":"noopener noreferrer","className":"rounded-md border p-2 text-sm flex items-center gap-1 ","children":[["$","svg",null,{"viewBox":"0 0 24 24","className":"size-3","children":["$","path",null,{"d":"M1.763 0C.786 0 0 .786 0 1.763v20.474C0 23.214.786 24 1.763 24h20.474c.977 0 1.763-.786 1.763-1.763V1.763C24 .786 23.214 0 22.237 0zM5.13 5.323l13.837.019-.009 13.836h-3.464l.01-10.382h-3.456L12.04 19.17H5.113z","fill":"currentColor"}]}],["$","span",null,{"className":"text-xs font-medium","children":"context.dev"}]]}]}]]}],["$","$L4e",null,{"registryDependencies":[]}]]}],["$","$L4f",null,{"sourceUrl":"https://agentcn.vercel.app/r/flue/ai-seo-audit.json","proxyUrl":"https://shadcnregistry.com/r/agentcn/flue-ai-seo-audit","itemId":"@agentcn/flue-ai-seo-audit"}],["$","section",null,{"className":"flex flex-col gap-4","id":"files","children":[["$","h2",null,{"className":"text-lg md:text-2xl font-bold font-mono","children":"Files"}],["$","$L50",null,{"files":[{"path":"agents/ai-seo-audit.ts","content":"import { createAgent } from '@flue/runtime'\nimport type { AgentRouteHandler } from '@flue/runtime'\nimport seoAudit from '../skills/seo-audit/SKILL.md' with { type: 'skill' }\nimport { auditPage } from '../tools/audit-page.ts'\n\nexport const route: AgentRouteHandler = async (_c, next) => next()\n\nexport default createAgent(() => ({\n model: 'anthropic/claude-sonnet-4-6',\n instructions: `\n You audit a web page for how readable it is to AI answer engines\n (ChatGPT, Claude, Perplexity) — not classic search ranking.\n Call audit_page once with the URL. It runs a deterministic rubric through\n context.dev and returns the score, per-category checks, top priorities, and\n agent fix prompts. Present that result faithfully following the seo-audit\n skill — never invent or recompute scores, and only report checks the tool\n returned.\n `,\n skills: [seoAudit],\n tools: [auditPage],\n}))\n","type":"registry:file","target":"agents/ai-seo-audit.ts"},{"path":"tools/audit-page.ts","content":"import { defineTool } from '@flue/runtime'\nimport * as v from 'valibot'\nimport { runAudit } from '../lib/audit.ts'\nimport { normalizeAuditUrl } from '../lib/url.ts'\n\nexport const auditPage = defineTool({\n name: 'audit_page',\n description:\n 'Runs the deterministic AI-SEO audit on a URL through context.dev and returns the full scored result: a 0–100 score and band, per-category check breakdowns (pass/partial/fail/na with evidence), top priorities, and ready-to-run agent fix prompts.',\n parameters: v.object({\n url: v.string(),\n }),\n execute: async ({ url }) => {\n const normalized = normalizeAuditUrl(url)\n if (!normalized) {\n return JSON.stringify({ error: `\"${url}\" is not a valid URL.` })\n }\n const audit = await runAudit(normalized, process.env.CONTEXT_DEV_API_KEY ?? '')\n return JSON.stringify(audit)\n },\n})\n","type":"registry:file","target":"tools/audit-page.ts"},{"path":"lib/audit.ts","content":"$51","type":"registry:file","target":"lib/audit.ts"},{"path":"lib/rules.ts","content":"$52","type":"registry:file","target":"lib/rules.ts"},{"path":"lib/agent-fix-prompt.ts","content":"$53","type":"registry:file","target":"lib/agent-fix-prompt.ts"},{"path":"lib/audit-types.ts","content":"$54","type":"registry:file","target":"lib/audit-types.ts"},{"path":"lib/url.ts","content":"export function normalizeAuditUrl(input: string): string | null {\n const trimmed = input.trim();\n if (!trimmed) return null;\n\n const withProtocol = /^https?:\\/\\//i.test(trimmed)\n ? trimmed\n : `https://${trimmed}`;\n\n try {\n const url = new URL(withProtocol);\n if (![\"http:\", \"https:\"].includes(url.protocol)) return null;\n url.hostname = url.hostname.replace(/^www\\./, \"\").toLowerCase();\n if (!url.hostname.includes(\".\")) return null;\n url.hash = \"\";\n return url.toString();\n } catch {\n return null;\n }\n}\n\nexport function normalizeDomain(input: string): string | null {\n const url = normalizeAuditUrl(input);\n if (!url) return null;\n try {\n return new URL(url).hostname;\n } catch {\n return null;\n }\n}\n\nexport function auditUrlFromDomain(domain: string): string {\n return `https://${domain}/`;\n}\n\nexport function displayHost(url: string): string {\n try {\n return new URL(url).hostname.replace(/^www\\./, \"\");\n } catch {\n return url;\n }\n}\n","type":"registry:file","target":"lib/url.ts"},{"path":"skills/seo-audit/SKILL.md","content":"$55","type":"registry:file","target":"skills/seo-audit/SKILL.md"}]}]]}],"$L56"]}]

AI SEO Audit Agent

Installation

Files

agents

tools

lib

skills

Styles