Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
feat(audit): check that a product description opens with the product type and key attributes (#1424)
Gökhan Geyik0d0718e0621a
diff --git a/docs/guides/site-audit.mdx b/docs/guides/site-audit.mdxindex 3ad81e96f..b1ed2cec8 100644--- a/docs/guides/site-audit.mdx+++ b/docs/guides/site-audit.mdx@@ -1,11 +1,11 @@---title: "Site Audit"-description: "Score any page for AI search readiness across 47 signals, and get page-specific fixes you can paste."+description: "Score any page for AI search readiness across 48 signals, and get page-specific fixes you can paste."---## What it does-The **Site Audit** page (`/dashboard/audit`) checks how ready a page is to be cited by AI answer engines. It fetches the page, runs **47 signals** in five categories, scores the page out of 100, and writes fixes for what failed: an improved H1, a meta description, an opening paragraph that leads with the answer, FAQ markup and more.+The **Site Audit** page (`/dashboard/audit`) checks how ready a page is to be cited by AI answer engines. It fetches the page, runs **48 signals** in five categories, scores the page out of 100, and writes fixes for what failed: an improved H1, a meta description, an opening paragraph that leads with the answer, FAQ markup and more.You find it in the sidebar under **Execution**, after **Content**. It is available on plans that include Content Optimization.@@ -18,7 +18,7 @@ You can audit any URL: your own pages, or a competitor's page to see what it doeThe field at the top is filled in with your brand's primary domain. Replace it with the page you want to check and click **Run Audit**.</Step><Step title="Wait for the report">- The report page opens right away and follows the audit through its stages: **Fetching the page…**, **Analyzing 47 signals…** and **Generating AI recommendations…**. An audit usually takes about 30 seconds. If it is still running after two minutes, the page says **This audit is taking longer than expected.** Click **Check again** to look again.+ The report page opens right away and follows the audit through its stages: **Fetching the page…**, **Analyzing 48 signals…** and **Generating AI recommendations…**. An audit usually takes about 30 seconds. If it is still running after two minutes, the page says **This audit is taking longer than expected.** Click **Check again** to look again.</Step><Step title="Read the report and fix">Start with the **AI Recommendations**, then open the failing signals. When you've made changes, click the re-run icon at the top of the report to audit the page again.@@ -91,7 +91,7 @@ Each audit has its own report at `/dashboard/audit/[id]`. The icons at the top r### Total score-The gauge shows the page's score out of 100 and a grade: **Good** (70 and above), **Needs work** (40–69) or **Poor** (below 40). Beside it are the number of signals that **passed**, raised **warnings** or **failed**, and how many of the 47 signals were evaluated.+The gauge shows the page's score out of 100 and a grade: **Good** (70 and above), **Needs work** (40–69) or **Poor** (below 40). Beside it are the number of signals that **passed**, raised **warnings** or **failed**, and how many of the 48 signals were evaluated.### Categories@@ -107,6 +107,8 @@ The gauge shows the page's score out of 100 and a grade: **Good** (70 and above)A category's score is the average of its signals; the total is the weighted average of the categories. A signal that couldn't be evaluated (**n/a**) is left out, so it never lowers the score.+On a product page (one with Product structured data), **Product description opening** checks that the description's first 40 words, or 250 characters, name the product type and at least two key attributes: a measure such as 268 g, a material, a fit or a use. ChatGPT appears to read only about that much of a description when it matches products to a shopping question. The finding shows where the opening ends. Other pages show this signal as n/a.+Most signals are read straight from the page, its robots.txt and its llms.txt. Thirteen, such as **Direct answer to query** and **Case study evidence**, are judged by an AI model that first works out what the page itself is about, so a page is never judged against a topic it isn't trying to cover. **Brand entity in Wikidata** looks your brand up in Wikidata.### Signalsdiff --git a/server/src/lib/audit/product-description.js b/server/src/lib/audit/product-description.jsnew file mode 100644index 000000000..3c078a9ab--- /dev/null+++ b/server/src/lib/audit/product-description.js@@ -0,0 +1,239 @@+/**+ * Whether a product description's opening is one an AI shopping assistant+ * can match to a question (#1279). ChatGPT appears to read only about the+ * first 50 tokens of a description, about 40 words or 250 characters+ * (public research presented at brightonSEO 2026, from a few test prompts;+ * to be confirmed by our own tests). An opening that tells the brand's story+ * and names the product type later may never be matched.+ *+ * Pure: the Site Audit signal runs it on product pages today, and the+ * catalog and the Content Editor can run it on descriptions later. Every+ * rule is here, so they agree.+ */++/** Where the reader stops: whichever of these ends first. */+export const OPENING = Object.freeze({ words: 40, chars: 250 });++/** Key attributes the opening needs beside the product type. */+export const MIN_ATTRIBUTES = 2;++/**+ * A number with its unit: 268 g, 6 mm, 30 L, 15.6", 5000 mAh, 100%. A bare+ * "in" isn't one ("3 in stock"); inches are written out or as ".+ */+const MEASURE =+ /(?<![\p{L}\p{N}.,])\d+(?:[.,]\d+)?\s?(?:mm|cm|km|m|mg|kg|g|lbs?|oz|ml|cl|l|inch(?:es)?|ft|"|w|kw|v|mah|wh|gb|tb|hz|ghz|mp|%)(?![\p{L}\p{N}])/giu;++/** What a product is made of. */+const MATERIALS = [+ 'organic cotton',+ 'cotton',+ 'merino wool',+ 'wool',+ 'cashmere',+ 'linen',+ 'silk',+ 'full-grain leather',+ 'leather',+ 'suede',+ 'denim',+ 'canvas',+ 'nylon',+ 'polyester',+ 'fleece',+ 'mesh',+ 'gore-tex',+ 'elastane',+ 'spandex',+ 'rubber',+ 'memory foam',+ 'foam',+ 'silicone',+ 'glass',+ 'ceramic',+ 'porcelain',+ 'stainless steel',+ 'steel',+ 'aluminium',+ 'aluminum',+ 'titanium',+ 'carbon fiber',+ 'carbon fibre',+ 'oak',+ 'walnut',+ 'bamboo',+ 'recycled',+];++/** How it fits; ambiguous words only in their fit phrase ("wide fit", not "a wide range"). */+const FITS = [+ 'slim fit',+ 'slim-fit',+ 'slim',+ 'regular fit',+ 'relaxed fit',+ 'loose fit',+ 'oversized',+ 'tapered',+ 'straight leg',+ 'straight-leg',+ 'skinny',+ 'wide fit',+ 'wide-leg',+ 'narrow fit',+ 'fitted',+ 'true to size',+ 'four-way stretch',+ 'stretch',+ 'high-rise',+ 'mid-rise',+ 'low-rise',+];++/** What it's for, or what it does in use. */+const USES = [+ 'running',+ 'trail',+ 'hiking',+ 'walking',+ 'training',+ 'gym',+ 'yoga',+ 'cycling',+ 'swimming',+ 'travel',+ 'outdoor',+ 'everyday',+ 'office',+ 'gaming',+ 'camping',+ 'winter',+ 'summer',+ 'waterproof',+ 'water-resistant',+ 'windproof',+ 'breathable',+ 'lightweight',+ 'cushioned',+ 'insulated',+ 'wireless',+ 'rechargeable',+ 'portable',+ 'dishwasher-safe',+ 'machine-washable',+];++/**+ * Every term, longest first, so "organic cotton" is one attribute, not two.+ * Terms are letters, spaces and hyphens only, so they go into a pattern as+ * they are.+ */+const TERMS = [...MATERIALS, ...FITS, ...USES]+ .sort((a, b) => b.length - a.length)+ .map((term) => ({+ term,+ pattern: new RegExp(`(?<![\\p{L}\\p{N}-])${term}(?![\\p{L}\\p{N}-])`, 'u'),+ }));++/** Words of a product's name that say nothing about what it is. */+const NAME_NOISE = new Set(['the', 'a', 'an', 'and', 'for', 'with', 'of', 'by', 'in', 'new']);++const lower = (text) => String(text ?? '').toLowerCase();++/** A word's form for matching: lowercase, without a possessive or plural "s". */+function stem(word) {+ return lower(word)+ .replace(/[’']s$/, '')+ .replace(/(?<=\p{L}{2}[^s])s$/u, '');+}++/** The words of a text, each with where it ends. */+function wordsOf(text) {+ return [...String(text).matchAll(/\S+/g)].map((m) => ({+ word: m[0],+ end: m.index + m[0].length,+ }));+}++/** The words of a text as stems, punctuation trimmed. */+function stemsOf(text) {+ return wordsOf(text)+ .map(({ word }) => stem(word.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, '')))+ .filter(Boolean);+}++/**+ * The product type from its name: the name's words without the brand's,+ * without model codes and numbers (Speedgoat 5, X-200) and filler.+ * "Acme Men's Trail Running Shoes" by Acme → men, trail, running, shoe.+ */+export function productTypeWords(productName, brand) {+ const brandStems = new Set(stemsOf(brand));+ return [+ ...new Set(+ stemsOf(productName).filter(+ (word) =>+ !brandStems.has(word) && !NAME_NOISE.has(word) && !/\d/.test(word) && word.length > 1,+ ),+ ),+ ];+}++/** Where the opening of `text` ends: at 40 words or 250 characters, whichever comes first. */+export function openingCut(text) {+ const all = String(text);+ const words = wordsOf(all);+ const byWords = words.length > OPENING.words ? words[OPENING.words - 1].end : all.length;+ return Math.min(byWords, OPENING.chars);+}++/**+ * The key attributes an opening names: measures, materials, fits and uses,+ * each once. A word of the product type isn't an attribute too: "running" in+ * a running shoe's opening says what it is, not something more.+ */+export function attributesIn(opening, typeWords = []) {+ const text = lower(opening);+ const typeStems = new Set(typeWords);+ const found = [...text.matchAll(MEASURE)].map((match) => match[0].replace(/\s+/g, ' ').trim());+ for (const { term, pattern } of TERMS) {+ if (term.split(/\s+/).every((word) => typeStems.has(stem(word)))) continue;+ if (found.some((f) => f.includes(term))) continue;+ if (pattern.test(text)) found.push(term);+ }+ return found;+}++/**+ * @param {{ description: string, productName?: string|null, brand?: string|null }} input+ * @returns {{+ * opening: string,+ * cut: number,+ * typeWords: string[],+ * namesType: boolean|null,+ * attributes: string[],+ * passes: boolean,+ * }} `cut` is where the opening ends in the description with its spaces+ * collapsed. `namesType` is null when the name says nothing of the type+ * (only a brand and a model), so only the attributes can be judged.+ */+export function checkDescriptionOpening({ description, productName = '', brand = '' }) {+ const text = String(description ?? '')+ .replace(/\s+/g, ' ')+ .trim();+ const cut = openingCut(text);+ const opening = text.slice(0, cut);+ const typeWords = productTypeWords(productName, brand);+ const openingStems = new Set(stemsOf(opening));+ const named = typeWords.filter((word) => openingStems.has(word)).length;+ const namesType = typeWords.length === 0 ? null : named >= Math.ceil(typeWords.length / 2);+ const attributes = attributesIn(opening, typeWords);+ return {+ opening,+ cut,+ typeWords,+ namesType,+ attributes,+ passes: namesType !== false && attributes.length >= MIN_ATTRIBUTES,+ };+}diff --git a/server/src/lib/audit/product-description.test.js b/server/src/lib/audit/product-description.test.jsnew file mode 100644index 000000000..217cc1f64--- /dev/null+++ b/server/src/lib/audit/product-description.test.js@@ -0,0 +1,170 @@+import { describe, expect, it } from 'vitest';+import {+ OPENING,+ attributesIn,+ checkDescriptionOpening,+ openingCut,+ productTypeWords,+} from './product-description.js';++/**+ * #1279: a product description's first 40 words or 250 characters name the+ * product type and at least two key attributes.+ */++const BRAND_STORY =+ 'Since 1987, our family has crafted every pair by hand in a small workshop at the foot of the Alps. ' ++ 'We believe the mountains belong to everyone, and every step you take carries a little of our story. ' ++ 'This men’s trail running shoe weighs 268 g and has a 6 mm drop.';++/** Real-looking descriptions: [what, input, passes]. */+const FIXTURES = [+ [+ 'type first, two measures',+ {+ description:+ 'Men’s trail running shoe, 268 g, 6 mm drop, with a grippy outsole for wet rock and mud.',+ productName: 'Acme Ridge Men’s Trail Running Shoe',+ brand: 'Acme',+ },+ true,+ ],+ [+ 'brand story first',+ { description: BRAND_STORY, productName: 'Acme Men’s Trail Running Shoe', brand: 'Acme' },+ false,+ ],+ [+ 'type and material and fit',+ {+ description:+ 'Slim fit organic cotton crew neck t-shirt in a midweight jersey that keeps its shape wash after wash.',+ productName: 'Northwind Crew Neck T-Shirt',+ brand: 'Northwind',+ },+ true,+ ],+ [+ 'type named, one attribute',+ {+ description:+ 'A backpack you will love on every adventure, made by people who care about the details.',+ productName: 'Summit Daypack Backpack',+ brand: 'Summit',+ },+ false,+ ],+ [+ 'type with a plural and a use',+ {+ description:+ 'Waterproof hiking boots with a 30 L gaiter loop and full-grain leather uppers for long days on the trail.',+ productName: 'Granite Hiking Boot',+ brand: 'Granite',+ },+ true,+ ],+ [+ 'attributes, but another product type',+ {+ description:+ 'Lightweight, breathable and waterproof: our best-selling jacket for rainy commutes.',+ productName: 'Acme Trail Running Shoe',+ brand: 'Acme',+ },+ false,+ ],+ [+ 'the model named, with two measures and a use',+ {+ description:+ 'The Speedgoat 5 weighs 292 g, has a 4 mm drop and a cushioned midsole for long runs.',+ productName: 'Hoka Speedgoat 5',+ brand: 'Hoka',+ },+ true,+ ],+ [+ 'a kitchen product with a capacity and a material',+ {+ description:+ 'Stainless steel French press coffee maker, 1 L, double-walled to keep coffee hot for an hour.',+ productName: 'Barista French Press Coffee Maker',+ brand: 'Barista',+ },+ true,+ ],+];++describe('checkDescriptionOpening', () => {+ it.each(FIXTURES)('%s', (_, input, passes) => {+ expect(checkDescriptionOpening(input).passes).toBe(passes);+ });++ it('passes "Men’s trail running shoe, 268 g, 6 mm drop…" on its type and two measures', () => {+ const result = checkDescriptionOpening(FIXTURES[0][1]);+ expect(result.namesType).toBe(true);+ expect(result.attributes).toEqual(expect.arrayContaining(['268 g', '6 mm']));+ });++ it('flags a brand-story opening: no product type before the cut', () => {+ const result = checkDescriptionOpening(FIXTURES[1][1]);+ expect(result.namesType).toBe(false);+ expect(result.opening).not.toContain('trail running shoe');+ expect(BRAND_STORY.indexOf('trail running shoe')).toBeGreaterThan(result.cut);+ });++ it('has no type to judge when the name is only the brand and a model number', () => {+ const result = checkDescriptionOpening({+ description: 'Weighs 292 g, with a 4 mm drop and a cushioned midsole for long runs.',+ productName: 'Hoka X-200',+ brand: 'Hoka',+ });+ expect(result.namesType).toBeNull();+ expect(result.passes).toBe(true);+ });+});++describe('openingCut', () => {+ it('stops at 40 words when they end before 250 characters', () => {+ const text = Array.from({ length: 60 }, (_, i) => `w${i}`).join(' ');+ const cut = openingCut(text);+ expect(text.slice(0, cut).split(' ')).toHaveLength(OPENING.words);+ expect(cut).toBeLessThan(OPENING.chars);+ });++ it('stops at 250 characters when they come before the 40th word', () => {+ const text = Array.from({ length: 60 }, () => 'characterful').join(' ');+ expect(openingCut(text)).toBe(OPENING.chars);+ });++ it('keeps a short description whole', () => {+ expect(openingCut('Merino wool beanie, one size.')).toBe(29);+ });+});++describe('productTypeWords', () => {+ it('takes the name without the brand, models and filler', () => {+ expect(productTypeWords('Acme Ridge 2 Men’s Trail Running Shoes', 'Acme')).toEqual([+ 'ridge',+ 'men',+ 'trail',+ 'running',+ 'shoe',+ ]);+ expect(productTypeWords('Hoka Speedgoat 5', 'Hoka')).toEqual(['speedgoat']);+ });+});++describe('attributesIn', () => {+ it('counts a measure, a material, a fit and a use, each once', () => {+ expect(attributesIn('Slim fit organic cotton running tee, 180 g', ['tee']).sort()).toEqual(+ ['180 g', 'organic cotton', 'running', 'slim fit'].sort(),+ );+ });++ it('counts no attribute in the product type, a bare "in" or an everyday "wide"', () => {+ expect(attributesIn('Trail running shoe', ['trail', 'running', 'shoe'])).toEqual([]);+ expect(attributesIn('3 in stock, in a wide range of colors')).toEqual([]);+ });+});diff --git a/server/src/lib/audit/recommendations.js b/server/src/lib/audit/recommendations.jsindex 68bef918c..02b7c92a5 100644--- a/server/src/lib/audit/recommendations.js+++ b/server/src/lib/audit/recommendations.js@@ -59,6 +59,7 @@ export const RECOMMENDABLE_SIGNALS = new Set(['technical-terms','readability','length',+ 'product-description-opening',// e-e-a-t'first-person','case-study-evidence',@@ -108,6 +109,7 @@ When the fix is content the user can paste, put the ready-to-use text in "draft"- outbound-authority-links / citation-density → specific authoritative sources to cite- readability → a simplified rewrite of one representative paragraph (shorter sentences, plainer words)- length → which specific sections to expand or trim (draft can be null)+- product-description-opening → a new opening for the product description, at most 40 words, that starts with the product type and names at least two key attributes from the page (a measure, a material, a fit or a use)Put markup (JSON-LD, HTML) only in "code", never in "draft". Code has no length limit but uses the same placeholders for unknown values, e.g. "price": "[price]".diff --git a/server/src/lib/audit/rubric.js b/server/src/lib/audit/rubric.jsindex 59c759e29..9e284f5f2 100644--- a/server/src/lib/audit/rubric.js+++ b/server/src/lib/audit/rubric.js@@ -19,7 +19,7 @@ export const categories = rubric.categories;/** signalKey -> full signal descriptor ({ key, category, label, what, why, howToFix, source, impactTier }). */export const signalsByKey = Object.fromEntries(rubric.signals.map((s) => [s.key, s]));-/** Total number of signals in the standard (47), regardless of how many we've implemented. */+/** Total number of signals in the standard (48), regardless of how many we've implemented. */export const TOTAL_SIGNALS = rubric.signals.length;/**diff --git a/server/src/lib/audit/rubric.json b/server/src/lib/audit/rubric.jsonindex 470286adf..d3ecf38c8 100644--- a/server/src/lib/audit/rubric.json+++ b/server/src/lib/audit/rubric.json@@ -1,7 +1,7 @@{- "version": "v1",- "description": "47-signal AEO/GEO scoring rubric for measuring whether a page will get cited by AI answer engines.",- "totalSignals": 47,+ "version": "v1.1",+ "description": "48-signal AEO/GEO scoring rubric for measuring whether a page will get cited by AI answer engines.",+ "totalSignals": 48,"categories": [{"key": "structure",@@ -21,8 +21,8 @@"key": "content","label": "Content","weight": 0.25,- "description": "Whether the page actually answers the buyer query — directly, completely, in the right register. BLUF, query coverage, sub-question coverage, readability.",- "signalCount": 11+ "description": "Whether the page actually answers the buyer query — directly, completely, in the right register. BLUF, query coverage, sub-question coverage, readability, and on product pages the description's opening.",+ "signalCount": 12},{"key": "trust",@@ -340,6 +340,16 @@"source": "Ahrefs 2025 study","impactTier": "standard"},+ {+ "key": "product-description-opening",+ "category": "content",+ "label": "Product description opening",+ "what": "On a product page, the description's first 40 words (or 250 characters) name the product type and at least two key attributes: a measure, a material, a fit or a use.",+ "why": "ChatGPT appears to read only about the first 50 tokens of a product description when it matches products to a shopping question. A description that opens with the brand's story may never be matched.",+ "howToFix": "Put the product type and key attributes in the first 40 words.",+ "source": "brightonSEO 2026 research on ChatGPT Shopping (to be confirmed by our own tests)",+ "impactTier": "high"+ },{"key": "sub-query-coverage","category": "content",diff --git a/server/src/lib/audit/signals/content.js b/server/src/lib/audit/signals/content.jsindex 41ff71f3b..cb0e76e79 100644--- a/server/src/lib/audit/signals/content.js+++ b/server/src/lib/audit/signals/content.js@@ -1,6 +1,7 @@/**- * Content-category signal evaluators — Faz 1 ships the 3 deterministic ones- * (readability, length, youtube-embed). The query-dependent / LLM-judged+ * Content-category signal evaluators — Faz 1 ships the deterministic ones+ * (readability, length, youtube-embed) and, on product pages, the+ * description's opening (#1279). The query-dependent / LLM-judged* signals (direct-answer, BLUF, query / sub-query / entity coverage,* info-density, mega-page, definitions) land in a later phase that feeds the* brand's tracked prompts in as the target query.@@ -8,7 +9,8 @@* See structure.js for the evaluator shape.*/-import { fleschReadingEase } from './helpers.js';+import { fleschReadingEase, jsonLd, typesOf } from './helpers.js';+import { OPENING, checkDescriptionOpening } from '../product-description.js';export const readability = {key: 'readability',@@ -63,4 +65,59 @@ export const youtubeEmbed = {},};-export const contentSignals = [readability, length, youtubeEmbed];+/** A JSON-LD value as plain text: a string, or the name of a node. */+const textOf = (value) =>+ typeof value === 'string' ? value : typeof value?.name === 'string' ? value.name : '';++/**+ * A product page's description opening (#1279): on a page with Product+ * structured data, whether the description's first 40 words or 250+ * characters name the product type and two key attributes. The description+ * is the schema's, else the page's microdata one. Other pages don't count.+ */+export const productDescriptionOpening = {+ key: 'product-description-opening',+ evaluate(ctx) {+ const product = jsonLd(ctx).nodes.find((node) =>+ typesOf(node).some((type) => type === 'product' || type === 'productgroup'),+ );+ if (!product) {+ return { status: 'na', score: null, evidence: { reason: 'not a product page' } };+ }+ const description = (+ textOf(product.description) || ctx.$('[itemprop="description"]').first().text()+ )+ .replace(/<[^>]+>/g, ' ')+ .trim();+ if (!description) {+ return { status: 'na', score: null, evidence: { reason: 'no product description' } };+ }++ const result = checkDescriptionOpening({+ description,+ productName: textOf(product.name),+ brand: textOf(product.brand),+ });+ const typeOk = result.namesType !== false;+ const attributesOk = result.attributes.length >= 2;+ const status = typeOk && attributesOk ? 'pass' : typeOk || attributesOk ? 'warn' : 'fail';+ const last = result.opening.split(' ').slice(-6).join(' ');+ const reason =+ `ChatGPT appears to stop reading a product description after about ${OPENING.words} words ` ++ `or ${OPENING.chars} characters, here at "…${last}". ` ++ `Product type named there: ${result.namesType === null ? 'unknown' : result.namesType ? 'yes' : 'no'}. ` ++ `Key attributes there: ${result.attributes.length ? result.attributes.join(', ') : 'none'}.`;+ return {+ status,+ score: status === 'pass' ? 1 : status === 'warn' ? 0.5 : 0,+ evidence: {+ reason,+ cut: result.cut,+ namesType: result.namesType,+ attributes: result.attributes,+ },+ };+ },+};++export const contentSignals = [readability, length, youtubeEmbed, productDescriptionOpening];diff --git a/server/src/lib/audit/signals/content.test.js b/server/src/lib/audit/signals/content.test.jsnew file mode 100644index 000000000..7e2f90ea6--- /dev/null+++ b/server/src/lib/audit/signals/content.test.js@@ -0,0 +1,85 @@+import { describe, expect, it } from 'vitest';+import * as cheerio from 'cheerio';+import { productDescriptionOpening } from './content.js';++/**+ * #1279: on a product page, the description's first 40 words or 250+ * characters name the product type and two key attributes; other pages+ * don't count.+ */++const page = (head, body = '') => ({+ $: cheerio.load(`<html><head>${head}</head><body>${body}</body></html>`),+});++const productLd = (product) =>+ `<script type="application/ld+json">${JSON.stringify({+ '@context': 'https://schema.org',+ '@type': 'Product',+ ...product,+ })}</script>`;++describe('productDescriptionOpening', () => {+ it('passes a product page whose description opens with the type and attributes', () => {+ const result = productDescriptionOpening.evaluate(+ page(+ productLd({+ name: 'Acme Ridge Men’s Trail Running Shoe',+ brand: { '@type': 'Brand', name: 'Acme' },+ description:+ 'Men’s trail running shoe, 268 g, 6 mm drop, with a grippy outsole for wet rock and mud.',+ }),+ ),+ );+ expect(result.status).toBe('pass');+ expect(result.score).toBe(1);+ expect(result.evidence.attributes).toEqual(expect.arrayContaining(['268 g', '6 mm']));+ expect(result.evidence.reason).toContain('Product type named there: yes');+ });++ it('fails a brand-story opening, and says where the opening ends', () => {+ const description =+ 'Since 1987, our family has crafted every pair by hand in a small workshop at the foot of the Alps. ' ++ 'We believe the mountains belong to everyone, and every step you take carries a little of our story. ' ++ 'This men’s trail running shoe weighs 268 g and has a 6 mm drop.';+ const result = productDescriptionOpening.evaluate(+ page(productLd({ name: 'Acme Men’s Trail Running Shoe', brand: 'Acme', description })),+ );+ expect(result.status).toBe('fail');+ expect(result.score).toBe(0);+ expect(result.evidence.cut).toBeLessThan(description.indexOf('trail running shoe'));+ expect(result.evidence.reason).toContain('Product type named there: no');+ expect(result.evidence.reason).toContain('Key attributes there: none');+ });++ it('warns when the opening names the type but only one attribute', () => {+ const result = productDescriptionOpening.evaluate(+ page(+ productLd({+ name: 'Summit Daypack Backpack',+ brand: 'Summit',+ description: 'A lightweight backpack for every adventure, made by people who care.',+ }),+ ),+ );+ expect(result.status).toBe('warn');+ expect(result.score).toBe(0.5);+ });++ it('reads the microdata description when the schema has none', () => {+ const result = productDescriptionOpening.evaluate(+ page(+ productLd({ name: 'Northwind Crew Neck T-Shirt', brand: 'Northwind' }),+ '<div itemprop="description"><p>Slim fit organic cotton crew neck t-shirt.</p></div>',+ ),+ );+ expect(result.status).toBe('pass');+ });++ it('is n/a on a page with no Product structured data, or no description', () => {+ expect(productDescriptionOpening.evaluate(page('<title>Blog</title>')).status).toBe('na');+ expect(+ productDescriptionOpening.evaluate(page(productLd({ name: 'Acme Trail Shoe' }))).status,+ ).toBe('na');+ });+});diff --git a/server/src/lib/audit/signals/index.js b/server/src/lib/audit/signals/index.jsindex 7e75e3133..59cb7bfdd 100644--- a/server/src/lib/audit/signals/index.js+++ b/server/src/lib/audit/signals/index.js@@ -2,8 +2,8 @@* Registry of implemented signal evaluators. Each category file exports its* own array; new signals are added there and surface here automatically.*- * Faz 1 implements the 33 deterministic signals (Structure 13, Trust 7,- * Authority 7, Content 3, E-E-A-T 3) of the 47-signal rubric. The remaining 14+ * Faz 1 implements the 34 deterministic signals (Structure 13, Trust 7,+ * Authority 7, Content 4, E-E-A-T 3) of the 48-signal rubric. The remaining 14* need a target query, an LLM judge, or an external lookup (Wikidata / press)* and land in later phases. The scorer reports coverage (evaluated / total) so* partial implementation never penalizes a page for signals we haven't built.diff --git a/server/src/routes/audits.js b/server/src/routes/audits.jsindex 90be5594c..1b78a94e6 100644--- a/server/src/routes/audits.js+++ b/server/src/routes/audits.js@@ -108,7 +108,7 @@ async function primaryDomainOf(brandId) {);}-// 20 audits × 47 signals stays under PostgREST's 1000-row page.+// 20 audits × 48 signals stays under PostgREST's 1000-row page.const ISSUE_COUNT_CHUNK = 20;/** Every audit of the brand, newest first, read past PostgREST's 1000-row page. */diff --git a/web/messages/en.json b/web/messages/en.jsonindex ea8b20db7..b83b9deae 100644--- a/web/messages/en.json+++ b/web/messages/en.json@@ -2484,7 +2484,7 @@},"audit": {"title": "Site Audit",- "description": "Score any page against the 47-signal AEO/GEO",+ "description": "Score any page against the 48-signal AEO/GEO","runAudit": "Run Audit","running": "Auditing…","pages": {@@ -2735,11 +2735,11 @@"noIssues": "No issues found — every evaluated signal passed.","stages": {"fetch": "Fetching the page…",- "analyze": "Analyzing 47 signals…",+ "analyze": "Analyzing 48 signals…","recommend": "Generating AI recommendations…"},"emptyTitle": "Audit any page for AI search readiness",- "emptyBody": "Enter a URL above to score it against 47 AEO/GEO signals and get AI-written fixes."+ "emptyBody": "Enter a URL above to score it against 48 AEO/GEO signals and get AI-written fixes."},"auth": {"signIn": "Sign in",