ai-search-auditor 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.2.0](https://github.com/a-bibikov/ai-search-audit/compare/v0.2.0...v0.2.0) (2026-11-03)
+
+
+### New checks and features
+
+* checklist by section at the end of the report ([c43423c](https://github.com/a-bibikov/ai-search-audit/commit/c43423c6f1c522de056552980c39db7cb411b082))
+* what to do first, coverage in the summary, weight by scale, llms.txt is optional ([f9e6ffb](https://github.com/a-bibikov/ai-search-audit/commit/f9e6ffb74b51c96b2e9639b4f580dbabe7809512))
+
+
+### Fixes
+
+* checks that cannot run are marked not checked, not passed ([e01eec5](https://github.com/a-bibikov/ai-search-audit/commit/e01eec5674c5f313ffa7b957af6c3520b86e840c))
+* checks that cannot run are marked not checked, not passed ([9281b96](https://github.com/a-bibikov/ai-search-audit/commit/9281b96ad2c6dee10d4a756b11e825fe858fc563))
+* CLI help names the npm package, --version flag ([31887fa](https://github.com/a-bibikov/ai-search-audit/commit/31887fada369eb41024f119b79359e5a98c03126))
+
+
+### Documentation
+
+* what the audit checks, roadmap, release process ([365965a](https://github.com/a-bibikov/ai-search-audit/commit/365965a7f2f0842a4dba13a0d1b8f1dfa8a8404b))
+
+
+### Internal
+
+* release 0.1.4 ([2c8056d](https://github.com/a-bibikov/ai-search-audit/commit/2c8056d386588262362e66c5fce78726df9127d8))
+
+## [0.2.0](https://github.com/a-bibikov/ai-search-audit/compare/v0.1.5...v0.2.0) (2026-11-03)
+
+
+### New checks and features
+
+* what to do first, coverage in the summary, weight by scale, llms.txt is optional ([f9e6ffb](https://github.com/a-bibikov/ai-search-audit/commit/f9e6ffb74b51c96b2e9639b4f580dbabe7809512))
+
 ## [0.1.5](https://github.com/a-bibikov/ai-search-audit/compare/v0.1.4...v0.1.5) (2026-11-03)
 
 

package/README.md

@@ -53,7 +53,7 @@ Most GEO / AI SEO checkers score a checklist: "is there an FAQ?", "are AI bots n
 - **D-2** Articles give the answer in the first two paragraphs
 
 **E. Machine-readable versions**
-- **E-1** `llms.txt` exists and follows the standard
+- **E-1** If there is an `llms.txt`, it follows the standard. It is optional: AI search engines rarely read it today, coding agents and docs tools do
 - **E-2** Every link in `llms.txt` works and is a published page
 - **E-3** Each language has its own `llms.txt`
 - **E-5** `llms-full.txt` carries the full text
@@ -68,9 +68,9 @@ Gaps in the numbering are taken by the checks on the [roadmap](#roadmap).
 
 Levels: `error` — AI search cannot read the page or reads it wrong; `warn` — lowers the chance of a citation; `info` — a recommendation.
 
-The report lists the findings with fixes first, then ends with a checklist of every check by group: ✓ OK, ✖ error, ⚠ warning, ℹ note, – not checked. A check that cannot run on a site — articles on a site without articles, `llms.txt` links when there is no `llms.txt` — is marked «not checked» with the reason, never as passed.
+The report opens with what to do first — the three changes worth the most, in plain words and with how many pages they touch — then lists the findings with fixes, and ends with a checklist of every check by group: ✓ OK, ✖ error, ⚠ warning, ℹ note, – not checked. A check that cannot run on a site — articles on a site without articles, `llms.txt` links when there is no `llms.txt` — is marked «not checked» with the reason, never as passed.
 
-**Score:** 100 minus 15 per rule with an error and 5 per rule with a warning. A rule counts once, not per page, so one template bug does not sink a large site. A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F below.
+**Score:** 100 minus 15 for each check with an error and 5 for each check with a warning; a warning that covers at least half of the audited pages costs 10. A check counts once, not per page, so one template bug does not sink a large site. A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F below. The summary says how many checks could run on the site; if fewer than two thirds did, the grade is capped at B.
 
 ## Usage
 

package/dist/i18n/en.d.ts

@@ -8,11 +8,17 @@ export declare const en: {
         summary: (o: {
             score: number;
             grade: string;
+            checked: number;
+            total: number;
             errors: number;
             warnings: number;
             notes: number;
             pages: number;
         }) => string;
+        capped: (checked: number, total: number) => string;
+        priorities: string;
+        /** Scale of a problem in the priorities: «on 12 of 20 pages». */
+        scale: (n: number, total: number) => string;
         clean: string;
         fix: string;
         /** Label instead of «Fix» when a rule has only notes: nothing is broken, it is advice. */
@@ -43,82 +49,102 @@ export declare const en: {
         "A-1": {
             title: string;
             fix: string;
+            impact: string;
         };
         "A-2": {
             title: string;
             fix: string;
+            impact: string;
         };
         "A-3": {
             title: string;
             fix: string;
+            impact: string;
         };
         "A-4": {
             title: string;
             fix: string;
+            impact: string;
         };
         "A-5": {
             title: string;
             fix: string;
+            impact: string;
         };
         "B-1": {
             title: string;
             fix: string;
+            impact: string;
         };
         "B-2": {
             title: string;
             fix: string;
+            impact: string;
         };
         "B-3": {
             title: string;
             fix: string;
+            impact: string;
         };
         "C-1": {
             title: string;
             fix: string;
+            impact: string;
         };
         "C-2": {
             title: string;
             fix: string;
+            impact: string;
         };
         "C-4": {
             title: string;
             fix: string;
+            impact: string;
         };
         "C-6": {
             title: string;
             fix: string;
+            impact: string;
         };
         "C-7": {
             title: string;
             fix: string;
+            impact: string;
         };
         "D-2": {
             title: string;
             fix: string;
+            impact: string;
         };
         "E-1": {
             title: string;
             fix: string;
+            impact: string;
         };
         "E-2": {
             title: string;
             fix: string;
+            impact: string;
         };
         "E-3": {
             title: string;
             fix: string;
+            impact: string;
         };
         "E-5": {
             title: string;
             fix: string;
+            impact: string;
         };
         "F-1": {
             title: string;
             fix: string;
+            impact: string;
         };
         "G-1": {
             title: string;
             fix: string;
+            impact: string;
         };
     };
     /** Finding messages. Quotes («…»), URLs and code come in already formatted. */
@@ -141,6 +167,7 @@ export declare const en: {
         noId: (type: string, name: string) => string;
         noSameAs: (type: string, name: string) => string;
         noJobTitle: (name: string) => string;
+        entityNotOnHome: (url: string) => string;
         authorNoId: (name: string) => string;
         authorUnknownId: (id: string) => string;
         articleMissing: (type: string, fields: string) => string;
@@ -150,6 +177,7 @@ export declare const en: {
         introFirst: (q: string) => string;
         noLongParagraph: string;
         notFound: (path: string) => string;
+        llmsMissing: string;
         answers: (path: string, status: string) => string;
         skipNoArticles: string;
         skipNoLlms: string;

package/dist/i18n/en.js

@@ -5,7 +5,11 @@
 export const en = {
     report: {
         title: (site) => `AI search audit: ${site}`,
-        summary: (o) => `**${o.score}/100 (${o.grade})** · ${o.errors} errors · ${o.warnings} warnings · ${o.notes} notes · ${o.pages} pages`,
+        summary: (o) => `**${o.score}/100 (${o.grade})** · ${o.checked} of ${o.total} checks run · ${o.errors} errors · ${o.warnings} warnings · ${o.notes} notes · ${o.pages} pages`,
+        capped: (checked, total) => `Grade capped at B: only ${checked} of ${total} checks could run on this site.`,
+        priorities: "What to do first",
+        /** Scale of a problem in the priorities: «on 12 of 20 pages». */
+        scale: (n, total) => `on ${n} of ${total} pages`,
         clean: "Nothing to fix: AI search can read, understand and cite these pages.",
         fix: "Fix",
         /** Label instead of «Fix» when a rule has only notes: nothing is broken, it is advice. */
@@ -38,82 +42,102 @@ export const en = {
         "A-1": {
             title: "robots.txt lets AI search agents in",
             fix: "Remove the Disallow for these agents (or add `Allow: /` in their group). They fetch pages to answer questions and cite them; training crawlers are a separate choice (A-2).",
+            impact: "AI search is not allowed to read the site, so it cannot cite it.",
         },
         "A-2": {
             title: "Training crawlers follow your policy",
             fix: "Decide whether future models may learn from the site and state it in robots.txt with a group per crawler. Blocking them does not remove you from AI search (A-1).",
+            impact: "Whether future models may learn from the site is not decided.",
         },
         "A-3": {
             title: "The server answers AI agents like a browser",
             fix: "Check the CDN, WAF or bot protection: these agents get an error, a challenge or a different page. Allow them by user agent or verified IP ranges.",
+            impact: "AI agents get an error or a check page instead of your content.",
         },
         "A-4": {
             title: "No noindex or noai on public pages",
             fix: 'Remove `noindex`, `none`, `noai` from `<meta name="robots">` and the `X-Robots-Tag` header on pages that should be cited (keep them on previews and staging).',
+            impact: "Pages are marked as closed, so AI search skips them.",
         },
         "A-5": {
             title: "The feed is declared in <head>",
             fix: 'Add `<link rel="alternate" type="application/rss+xml" href="…">` to pages so crawlers find new content without guessing the address.',
+            impact: "New pages are found later than they could be.",
         },
         "B-1": {
             title: "The text is in the HTML, not only in JavaScript",
             fix: "Render the content on the server (SSR or static generation). Most AI crawlers do not run JavaScript: what is not in the HTML does not exist for them.",
+            impact: "ChatGPT, Claude and Perplexity see an empty page: the text appears only after scripts run.",
         },
         "B-2": {
             title: "No invisible characters inside words in machine-readable output",
             fix: "Strip U+2060, U+200B, U+FEFF and U+00AD from <title>, meta, JSON-LD, feeds and llms.txt: «AI-⟨U+2060⟩native» with a hidden character does not match the query «AI-native». On the page itself typography can keep them, use CSS `white-space: nowrap` where you can.",
+            impact: "Hidden characters break words, so the text does not match what people search for.",
         },
         "B-3": {
             title: "Headings do not glue words together",
             fix: 'Put a space between sibling elements inside the heading (in JSX: `{" "}`). Styles show two lines, but a crawler reads the text nodes joined: «NameTagline».',
+            impact: "Headings read as glued words, so AI misreads what the page is about.",
         },
         "C-1": {
             title: "The author or company is a defined entity",
             fix: "Add JSON-LD Person (or Organization) to the home or about page with a stable `@id` (e.g. https://example.com/#person), `name`, `url`, `sameAs` with your profiles, and `jobTitle` for a person.",
+            impact: "AI search cannot tell who stands behind the site, so it trusts it less.",
         },
         "C-2": {
             title: "Articles point at the author entity by @id",
             fix: 'Set `author: { "@id": "https://example.com/#person" }` (plus name and url if you like) — the same @id as the Person on the home page.',
+            impact: "Articles are not tied to their author, so the expertise does not add up to one name.",
         },
         "C-4": {
             title: "Articles have complete Article / BlogPosting markup",
             fix: "Fill in `headline`, `datePublished`, `author` (required), and `dateModified`, `image`, `inLanguage`.",
+            impact: "Articles lack dates or authorship, so AI search treats them as less reliable.",
         },
         "C-6": {
             title: "Every page has a link card: og:title, og:description, og:image",
             fix: "Add og:image (1200×630) and og:title / og:description to each public page. Chat apps, social networks and AI answers build the link card from them.",
+            impact: "Links to the site look bare in chats and AI answers: no title, no picture.",
         },
         "C-7": {
             title: "A visible FAQ is marked up as FAQPage",
             fix: "If the page really is questions and answers, add FAQPage JSON-LD with the same questions and answers as on the page.",
+            impact: "Questions and answers on the page are not marked as such, so they are quoted less often.",
         },
         "D-2": {
             title: "Articles answer in the first two paragraphs",
             fix: "Open with the answer: what it is, for whom, the main conclusion, in 25+ words. Answer engines quote the first paragraphs most often; an intro like «In this article we will…» wastes them.",
+            impact: "The answer is buried below the intro, while AI search quotes the opening.",
         },
         "E-1": {
-            title: "llms.txt exists and follows llmstxt.org",
-            fix: "Serve /llms.txt as Markdown: `# Site name`, a `> one-line summary`, then `## Sections` with `- [Title](url): note` links to the key pages.",
+            title: "llms.txt follows llmstxt.org (optional)",
+            fix: "llms.txt is optional: AI search engines rarely read it, coding agents and docs tools do — worth it for documentation, APIs and developer products. If you publish one, serve Markdown: `# Site name`, a `> one-line summary`, then `## Sections` with `- [Title](url): note` links to the key pages.",
+            impact: "The published llms.txt cannot be read the way the agents that use it expect.",
         },
         "E-2": {
             title: "Links in llms.txt work and match the sitemap",
             fix: "Fix or remove broken links; list only published pages. A link that is in llms.txt but not in sitemap.xml is often a draft or a stale URL.",
+            impact: "Agents that use llms.txt are sent to broken or unpublished pages.",
         },
         "E-3": {
             title: "Each language has its own llms.txt",
             fix: "For a multilingual site, serve llms.txt per language (e.g. /llms.txt and /ru/llms.txt) and link them to each other.",
+            impact: "Language models get the guide to the site in one language only.",
         },
         "E-5": {
             title: "llms-full.txt carries the full text",
             fix: "Serve /llms-full.txt with the full text of key pages and articles, so a model can read the site in one request.",
+            impact: "A model cannot read the site's content in one request.",
         },
         "F-1": {
             title: "Sitemap lastmod matches the page's dateModified",
             fix: "Generate lastmod from the same date as JSON-LD dateModified; a mismatch tells crawlers the page changed when it did not, or hides real updates.",
+            impact: "Search engines get mixed signals about when pages changed.",
         },
         "G-1": {
             title: "No instructions addressed to AI in the content",
             fix: "Remove lines that tell AI systems what to say or do. Answer engines treat them as prompt injection and may drop the page or trust the site less. An easter egg for humans can live in humans.txt or the console.",
+            impact: "Text addressed to AI looks like a manipulation attempt and lowers trust in the site.",
         },
     },
     /** Finding messages. Quotes («…»), URLs and code come in already formatted. */
@@ -136,6 +160,7 @@ export const en = {
         noId: (type, name) => `${type} «${name}» has no @id: articles cannot point at it as one entity`,
         noSameAs: (type, name) => `${type} «${name}» has no sameAs (LinkedIn, GitHub…): models cannot confirm who this is`,
         noJobTitle: (name) => `Person «${name}» has no jobTitle`,
+        entityNotOnHome: (url) => `the home page does not describe the company or author; it is described only on ${url}`,
         authorNoId: (name) => `author ${name} has no @id`,
         authorUnknownId: (id) => `author @id ${id} matches no Person or Organization defined on the site`,
         articleMissing: (type, fields) => `${type} without ${fields}`,
@@ -145,6 +170,7 @@ export const en = {
         introFirst: (q) => `starts with an intro instead of the answer: ${q}`,
         noLongParagraph: "no paragraph of 25+ words among the first two",
         notFound: (path) => `${path} not found`,
+        llmsMissing: "no /llms.txt — optional: AI search engines rarely read it; it helps documentation, APIs and coding agents",
         answers: (path, status) => `${path} answers ${status}, so AI agents cannot read it`,
         skipNoArticles: "no articles among the audited pages",
         skipNoLlms: "no llms.txt",

package/dist/i18n/index.d.ts

@@ -8,11 +8,16 @@ export declare const LANGS: {
             summary: (o: {
                 score: number;
                 grade: string;
+                checked: number;
+                total: number;
                 errors: number;
                 warnings: number;
                 notes: number;
                 pages: number;
             }) => string;
+            capped: (checked: number, total: number) => string;
+            priorities: string;
+            scale: (n: number, total: number) => string;
             clean: string;
             fix: string;
             recommendation: string;
@@ -41,82 +46,102 @@ export declare const LANGS: {
             "A-1": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "A-2": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "A-3": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "A-4": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "A-5": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "B-1": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "B-2": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "B-3": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "C-1": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "C-2": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "C-4": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "C-6": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "C-7": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "D-2": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "E-1": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "E-2": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "E-3": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "E-5": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "F-1": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "G-1": {
                 title: string;
                 fix: string;
+                impact: string;
             };
         };
         m: {
@@ -138,6 +163,7 @@ export declare const LANGS: {
             noId: (type: string, name: string) => string;
             noSameAs: (type: string, name: string) => string;
             noJobTitle: (name: string) => string;
+            entityNotOnHome: (url: string) => string;
             authorNoId: (name: string) => string;
             authorUnknownId: (id: string) => string;
             articleMissing: (type: string, fields: string) => string;
@@ -147,6 +173,7 @@ export declare const LANGS: {
             introFirst: (q: string) => string;
             noLongParagraph: string;
             notFound: (path: string) => string;
+            llmsMissing: string;
             answers: (path: string, status: string) => string;
             skipNoArticles: string;
             skipNoLlms: string;
@@ -173,11 +200,16 @@ export declare const LANGS: {
             summary: (o: {
                 score: number;
                 grade: string;
+                checked: number;
+                total: number;
                 errors: number;
                 warnings: number;
                 notes: number;
                 pages: number;
             }) => string;
+            capped: (checked: number, total: number) => string;
+            priorities: string;
+            scale: (n: number, total: number) => string;
             clean: string;
             fix: string;
             recommendation: string;
@@ -206,82 +238,102 @@ export declare const LANGS: {
             "A-1": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "A-2": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "A-3": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "A-4": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "A-5": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "B-1": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "B-2": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "B-3": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "C-1": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "C-2": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "C-4": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "C-6": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "C-7": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "D-2": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "E-1": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "E-2": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "E-3": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "E-5": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "F-1": {
                 title: string;
                 fix: string;
+                impact: string;
             };
             "G-1": {
                 title: string;
                 fix: string;
+                impact: string;
             };
         };
         m: {
@@ -303,6 +355,7 @@ export declare const LANGS: {
             noId: (type: string, name: string) => string;
             noSameAs: (type: string, name: string) => string;
             noJobTitle: (name: string) => string;
+            entityNotOnHome: (url: string) => string;
             authorNoId: (name: string) => string;
             authorUnknownId: (id: string) => string;
             articleMissing: (type: string, fields: string) => string;
@@ -312,6 +365,7 @@ export declare const LANGS: {
             introFirst: (q: string) => string;
             noLongParagraph: string;
             notFound: (path: string) => string;
+            llmsMissing: string;
             answers: (path: string, status: string) => string;
             skipNoArticles: string;
             skipNoLlms: string;

package/dist/i18n/ru.js

@@ -2,7 +2,10 @@
 export const ru = {
     report: {
         title: (site) => `Проверка для AI-поиска: ${site}`,
-        summary: (o) => `**${o.score}/100 (${o.grade})** · ошибок: ${o.errors} · предупреждений: ${o.warnings} · заметок: ${o.notes} · страниц: ${o.pages}`,
+        summary: (o) => `**${o.score}/100 (${o.grade})** · проверено: ${o.checked} из ${o.total} · ошибок: ${o.errors} · предупреждений: ${o.warnings} · заметок: ${o.notes} · страниц: ${o.pages}`,
+        capped: (checked, total) => `Оценка ограничена B: на этом сайте удалось выполнить только ${checked} проверок из ${total}.`,
+        priorities: "Что сделать в первую очередь",
+        scale: (n, total) => `страниц: ${n} из ${total}`,
         clean: "Исправлять нечего: AI-поиск может прочитать, понять и процитировать эти страницы.",
         fix: "Как исправить",
         recommendation: "Рекомендация",
@@ -27,82 +30,102 @@ export const ru = {
         "A-1": {
             title: "robots.txt пускает поисковых AI-агентов",
             fix: "Уберите Disallow для этих агентов (или добавьте `Allow: /` в их группу). Они загружают страницы, чтобы ответить на вопрос и сослаться на источник; боты обучения — отдельное решение (A-2).",
+            impact: "AI-поиску запрещено читать сайт — он не может на вас ссылаться.",
         },
         "A-2": {
             title: "Боты обучения следуют вашей политике",
             fix: "Решите, могут ли будущие модели учиться на сайте, и укажите это в robots.txt отдельной группой для каждого бота. Запрет для них не убирает сайт из AI-поиска (A-1).",
+            impact: "Не решено, могут ли будущие модели учиться на вашем сайте.",
         },
         "A-3": {
             title: "Сервер отвечает AI-агентам так же, как браузеру",
             fix: "Проверьте CDN, WAF или защиту от ботов: эти агенты получают ошибку, проверку или другую страницу. Разрешите их по User-Agent или по подтверждённым диапазонам IP.",
+            impact: "AI-агенты получают ошибку или проверку вместо вашего контента.",
         },
         "A-4": {
             title: "На публичных страницах нет noindex и noai",
             fix: 'Уберите `noindex`, `none`, `noai` из `<meta name="robots">` и заголовка `X-Robots-Tag` на страницах, которые должны цитироваться (на превью и staging их оставьте).',
+            impact: "Страницы помечены как закрытые — AI-поиск их пропускает.",
         },
         "A-5": {
             title: "Лента объявлена в <head>",
             fix: 'Добавьте на страницы `<link rel="alternate" type="application/rss+xml" href="…">`, чтобы краулеры находили новое без угадывания адреса.',
+            impact: "Новые страницы находят позже, чем могли бы.",
         },
         "B-1": {
             title: "Текст есть в HTML, а не только в JavaScript",
             fix: "Рендерите контент на сервере (SSR или статическая генерация). Большинство AI-краулеров не выполняют JavaScript: чего нет в HTML, того для них не существует.",
+            impact: "ChatGPT, Claude и Perplexity видят пустую страницу: текст появляется только после скриптов.",
         },
         "B-2": {
             title: "В машиночитаемых версиях нет невидимых символов внутри слов",
             fix: "Уберите U+2060, U+200B, U+FEFF и U+00AD из <title>, мета-тегов, JSON-LD, лент и llms.txt: «AI-⟨U+2060⟩native» со скрытым символом не совпадает с запросом «AI-native». На самой странице типограф может их оставлять, но где можно, используйте CSS `white-space: nowrap`.",
+            impact: "Скрытые символы рвут слова — текст не совпадает с тем, что ищут люди.",
         },
         "B-3": {
             title: "Заголовки не склеивают слова",
             fix: 'Поставьте пробел между соседними элементами внутри заголовка (в JSX: `{" "}`). Стили показывают две строки, а краулер читает текстовые узлы подряд: «ИмяСлоган».',
+            impact: "Заголовки читаются слипшимися — AI неверно понимает, о чём страница.",
         },
         "C-1": {
             title: "Автор или компания описаны как сущность",
             fix: "Добавьте на главную или страницу «О себе» JSON-LD Person (или Organization) с постоянным `@id` (например, https://example.com/#person), `name`, `url`, `sameAs` со ссылками на профили и `jobTitle` для человека.",
+            impact: "AI-поиск не может понять, кто стоит за сайтом, и меньше ему доверяет.",
         },
         "C-2": {
             title: "Статьи ссылаются на автора через @id",
             fix: 'Укажите `author: { "@id": "https://example.com/#person" }` (name и url можно оставить) — тот же @id, что у Person на главной.',
+            impact: "Статьи не привязаны к автору — экспертиза не складывается в одно имя.",
         },
         "C-4": {
             title: "У статей полная разметка Article / BlogPosting",
             fix: "Заполните `headline`, `datePublished`, `author` (обязательно), а также `dateModified`, `image`, `inLanguage`.",
+            impact: "У статей нет дат или авторства — AI-поиск считает их менее надёжными.",
         },
         "C-6": {
             title: "У каждой страницы есть карточка ссылки: og:title, og:description, og:image",
             fix: "Добавьте og:image (1200×630) и og:title / og:description на каждую публичную страницу. По ним мессенджеры, соцсети и AI-ответы строят карточку ссылки.",
+            impact: "Ссылки на сайт в мессенджерах и AI-ответах выглядят пустыми: без заголовка и картинки.",
         },
         "C-7": {
             title: "Видимый FAQ размечен как FAQPage",
             fix: "Если страница действительно состоит из вопросов и ответов, добавьте JSON-LD FAQPage с теми же вопросами и ответами, что на странице.",
+            impact: "Вопросы и ответы на странице не размечены — их реже берут в ответы.",
         },
         "D-2": {
             title: "Статьи отвечают в первых двух абзацах",
             fix: "Начинайте с ответа: что это, для кого, главный вывод — от 25 слов. AI-поиск чаще всего цитирует первые абзацы; вступление вроде «В этой статье мы расскажем…» тратит их впустую.",
+            impact: "Ответ спрятан за вступлением, а AI-поиск цитирует начало.",
         },
         "E-1": {
-            title: "llms.txt есть и соответствует llmstxt.org",
-            fix: "Отдавайте /llms.txt в Markdown: `# Название сайта`, строка `> краткое описание`, затем разделы `## …` со ссылками `- [Заголовок](url): пояснение` на ключевые страницы.",
+            title: "llms.txt соответствует llmstxt.org (необязательно)",
+            fix: "llms.txt необязателен: AI-поиск его почти не читает, а агенты для разработки и инструменты документации читают — он нужен сайтам с документацией, API и продуктами для разработчиков. Если публикуете, отдавайте Markdown: `# Название сайта`, строка `> краткое описание`, затем разделы `## …` со ссылками `- [Заголовок](url): пояснение` на ключевые страницы.",
+            impact: "Опубликованный llms.txt не читается так, как ожидают агенты, которые им пользуются.",
         },
         "E-2": {
             title: "Ссылки в llms.txt работают и совпадают с sitemap",
             fix: "Исправьте или уберите битые ссылки; оставляйте только опубликованные страницы. Ссылка, которая есть в llms.txt, но не в sitemap.xml, — часто черновик или устаревший адрес.",
+            impact: "Агентов, которые пользуются llms.txt, отправляют на битые или неопубликованные страницы.",
         },
         "E-3": {
             title: "У каждого языка свой llms.txt",
             fix: "Для многоязычного сайта отдавайте llms.txt на каждом языке (например, /llms.txt и /ru/llms.txt) и связывайте их ссылками друг на друга.",
+            impact: "Модели получают путеводитель по сайту только на одном языке.",
         },
         "E-5": {
             title: "llms-full.txt содержит полный текст",
             fix: "Отдавайте /llms-full.txt с полным текстом ключевых страниц и статей, чтобы модель могла прочитать сайт за один запрос.",
+            impact: "Модель не может прочитать содержимое сайта за один запрос.",
         },
         "F-1": {
             title: "lastmod в sitemap совпадает с dateModified страницы",
             fix: "Берите lastmod из той же даты, что и dateModified в JSON-LD: расхождение сообщает краулерам об изменениях, которых не было, или скрывает настоящие обновления.",
+            impact: "Поисковики получают противоречивые сигналы о свежести страниц.",
         },
         "G-1": {
             title: "В контенте нет указаний, обращённых к AI",
             fix: "Уберите строки, которые говорят AI-системам, что сказать или сделать. AI-поиск считает их prompt injection и может отбросить страницу или меньше доверять сайту. Пасхалка для людей может жить в humans.txt или в консоли.",
+            impact: "Обращения к AI выглядят как попытка манипуляции и снижают доверие к сайту.",
         },
     },
     m: {
@@ -124,6 +147,7 @@ export const ru = {
         noId: (type, name) => `у ${type} «${name}» нет @id: статьи не могут сослаться на него как на одну сущность`,
         noSameAs: (type, name) => `у ${type} «${name}» нет sameAs (LinkedIn, GitHub…): модели не могут подтвердить, кто это`,
         noJobTitle: (name) => `у Person «${name}» нет jobTitle`,
+        entityNotOnHome: (url) => `на главной нет описания компании или автора — оно есть только на ${url}`,
         authorNoId: (name) => `у автора ${name} нет @id`,
         authorUnknownId: (id) => `@id автора ${id} не совпадает ни с одним Person или Organization на сайте`,
         articleMissing: (type, fields) => `в ${type} нет ${fields}`,
@@ -133,6 +157,7 @@ export const ru = {
         introFirst: (q) => `начинается со вступления, а не с ответа: ${q}`,
         noLongParagraph: "среди первых двух абзацев нет абзаца от 25 слов",
         notFound: (path) => `${path} не найден`,
+        llmsMissing: "нет /llms.txt — это необязательно: AI-поиск его почти не читает, он полезен документации, API и агентам для разработки",
         answers: (path, status) => `${path} отвечает ${status}, AI-агенты не могут его прочитать`,
         skipNoArticles: "среди проверенных страниц нет статей",
         skipNoLlms: "нет llms.txt",

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export interface Report extends Score {
         level: Level;
         title: string;
         fix: string;
+        impact: string;
         skipped?: string;
     }[];
 }

package/dist/index.js

@@ -19,7 +19,7 @@ export async function audit(target, opts = {}) {
         lang: config.lang,
         checkedAt: new Date().toISOString(),
         pages: site.pages.map((p) => p.fetched.publicUrl),
-        ...scoreOf(findings),
+        ...scoreOf(findings, { pages: site.pages.length, checked: active.filter((r) => !skipped.get(r.id)).length, total: active.length }),
         findings,
         rules: active.map(({ id, group, level }) => ({ id, group, level, ...t.rules[id], ...(skipped.get(id) ? { skipped: skipped.get(id) } : {}) })),
     };

package/dist/report.js

@@ -1,7 +1,9 @@
 import { messages } from "./i18n/index.js";
+import { pagesOf, penaltyOf } from "./score.js";
 const ICON = { error: "✖", warn: "⚠", info: "ℹ" };
 const ORDER = { error: 0, warn: 1, info: 2 };
 const MAX_PER_RULE = 8;
+const MAX_PRIORITIES = 3;
 /** Markdown report for a terminal, a PR summary or a file, in the report's language. */
 export function toMarkdown(r) {
     const t = messages(r.lang).report;
@@ -9,12 +11,26 @@ export function toMarkdown(r) {
     const lines = [
         `# ${t.title(r.site)}`,
         "",
-        t.summary({ score: r.score, grade: r.grade, errors: r.counts.error, warnings: r.counts.warn, notes: r.counts.info, pages: r.pages.length }),
+        t.summary({ score: r.score, grade: r.grade, checked: r.checked, total: r.total, errors: r.counts.error, warnings: r.counts.warn, notes: r.counts.info, pages: r.pages.length }),
         "",
     ];
+    if (r.capped)
+        lines.push(t.capped(r.checked, r.total), "");
     const byRule = new Map();
     for (const f of r.findings)
         byRule.set(f.rule, [...(byRule.get(f.rule) ?? []), f]);
+    // The few changes worth the most points, in plain words: what it costs the business, then the check.
+    const top = r.rules
+        .map((rule) => ({ rule, found: byRule.get(rule.id) ?? [] }))
+        .map((x) => ({ ...x, cost: penaltyOf(x.found, r.pages.length), pages: pagesOf(x.found) }))
+        .filter((x) => x.cost > 0)
+        .sort((a, b) => b.cost - a.cost || b.pages - a.pages || a.rule.id.localeCompare(b.rule.id, "en", { numeric: true }))
+        .slice(0, MAX_PRIORITIES);
+    if (top.length) {
+        lines.push(`## ${t.priorities}`, "");
+        top.forEach(({ rule, pages }, i) => lines.push(`${i + 1}. **${rule.impact}** ${rule.id}${pages ? `, ${t.scale(pages, r.pages.length)}` : ""}`));
+        lines.push("");
+    }
     const failed = r.rules
         .filter((rule) => byRule.has(rule.id))
         .map((rule) => ({ rule, findings: byRule.get(rule.id), worst: byRule.get(rule.id).reduce((w, f) => (ORDER[f.level] < ORDER[w] ? f.level : w), "info") }))

package/dist/rules/content.js

@@ -43,9 +43,11 @@ export const contentRules = [
         level: "warn",
         run(site, _config, t) {
             const { out, add } = finder(this);
+            // No llms.txt is a note, not a warning: AI search engines rarely read it (2026 crawler logs), coding agents and
+            // docs tools do. A published but broken file is a warning: whoever uses it gets nothing.
             if (!site.llms) {
                 const a = site.llmsAttempt;
-                add("site", a.status === 404 || a.status === 410 ? t.notFound("/llms.txt") : t.answers("/llms.txt", a.error ?? `HTTP ${a.status}`));
+                add("site", a.status === 404 || a.status === 410 ? t.llmsMissing : t.answers("/llms.txt", a.error ?? `HTTP ${a.status}`), "info");
                 return out;
             }
             const body = site.llms.body;
@@ -66,7 +68,7 @@ export const contentRules = [
     {
         id: "E-2",
         group: "E",
-        level: "error",
+        level: "warn",
         applies(site, t) {
             return llmsReadable(site) ? null : t.skipNoLlms;
         },
@@ -77,7 +79,7 @@ export const contentRules = [
                 if (status !== 200)
                     add(href, t.brokenLink(status ? String(status) : t.nothing));
                 else if (site.sitemap && /\/[^./]*$/.test(new URL(href).pathname) && !inSitemap.has(href.replace(/\/$/, "")))
-                    add(href, t.notInSitemap, "warn");
+                    add(href, t.notInSitemap, "info");
             }
             return out;
         },

package/dist/rules/entities.js

@@ -27,6 +27,10 @@ export const entityRules = [
                 add("site", t.noEntity);
                 return out;
             }
+            // The home page is where answer engines look first for who runs the site.
+            const home = site.pages.find((p) => p.fetched.publicUrl.replace(/\/$/, "") === site.base);
+            if (home && !defined.some(({ page }) => page === home))
+                add(home.fetched.publicUrl, t.entityNotOnHome(defined[0].page.fetched.publicUrl), "warn");
             const seen = new Set();
             for (const { n, page } of defined) {
                 const key = str(n["@id"]) || str(n.url) || str(n.name);

package/dist/score.d.ts

@@ -3,9 +3,27 @@ export interface Score {
     score: number;
     grade: "A" | "B" | "C" | "D" | "F";
     counts: Record<Level, number>;
+    /** Checks that ran on this site and all active checks: «14 of 20». */
+    checked: number;
+    total: number;
+    /** The grade was lowered to B because too few checks could run. */
+    capped: boolean;
 }
+export interface ScoreContext {
+    /** Audited pages, to weigh how widespread a problem is. */
+    pages?: number;
+    checked?: number;
+    total?: number;
+}
+/**
+ * Pages a rule's worst findings are about: notes next to a warning do not make the warning wider,
+ * and site-wide findings are not counted as pages.
+ */
+export declare const pagesOf: (findings: Finding[]) => number;
+/** What one rule costs: its worst level, and a warning on most pages costs more than a warning on one. */
+export declare function penaltyOf(findings: Finding[], pages?: number): number;
 /**
- * 100 minus a penalty per rule, not per page: a rule counts once at its worst level, so a large site with one
- * template bug is not punished 500 times.
+ * 100 minus a penalty per rule, not per page: a rule counts once, so a large site with one template bug is not
+ * punished 500 times — but a warning that covers most pages counts double.
  */
-export declare function scoreOf(findings: Finding[]): Score;
+export declare function scoreOf(findings: Finding[], ctx?: ScoreContext): Score;

package/dist/score.js

@@ -1,19 +1,45 @@
 const PENALTY = { error: 15, warn: 5, info: 0 };
+/** A warning on at least half of the audited pages is a site-wide problem: it costs more than a single slip. */
+const WIDE_WARN = 10;
+const WIDE_SHARE = 0.5;
+/** Below this share of checks that could run, the site is not fully audited and cannot get an A. */
+const MIN_COVERAGE = 2 / 3;
+const worstOf = (findings) => findings.reduce((w, f) => (PENALTY[f.level] > PENALTY[w] ? f.level : w), "info");
 /**
- * 100 minus a penalty per rule, not per page: a rule counts once at its worst level, so a large site with one
- * template bug is not punished 500 times.
+ * Pages a rule's worst findings are about: notes next to a warning do not make the warning wider,
+ * and site-wide findings are not counted as pages.
  */
-export function scoreOf(findings) {
-    const worst = new Map();
-    for (const f of findings) {
-        const prev = worst.get(f.rule);
-        if (!prev || PENALTY[f.level] > PENALTY[prev])
-            worst.set(f.rule, f.level);
-    }
-    const score = Math.max(0, 100 - [...worst.values()].reduce((s, l) => s + PENALTY[l], 0));
-    const grade = score >= 90 ? "A" : score >= 80 ? "B" : score >= 70 ? "C" : score >= 60 ? "D" : "F";
+export const pagesOf = (findings) => {
+    const worst = worstOf(findings);
+    return new Set(findings.filter((f) => f.level === worst && f.where !== "site").map((f) => f.where)).size;
+};
+/** What one rule costs: its worst level, and a warning on most pages costs more than a warning on one. */
+export function penaltyOf(findings, pages = 0) {
+    if (!findings.length)
+        return 0;
+    const worst = worstOf(findings);
+    if (worst === "warn" && pages > 0 && pagesOf(findings) / pages >= WIDE_SHARE)
+        return WIDE_WARN;
+    return PENALTY[worst];
+}
+/**
+ * 100 minus a penalty per rule, not per page: a rule counts once, so a large site with one template bug is not
+ * punished 500 times — but a warning that covers most pages counts double.
+ */
+export function scoreOf(findings, ctx = {}) {
+    const byRule = new Map();
+    for (const f of findings)
+        byRule.set(f.rule, [...(byRule.get(f.rule) ?? []), f]);
+    const penalty = [...byRule.values()].reduce((s, list) => s + penaltyOf(list, ctx.pages ?? 0), 0);
+    const score = Math.max(0, 100 - penalty);
+    let grade = score >= 90 ? "A" : score >= 80 ? "B" : score >= 70 ? "C" : score >= 60 ? "D" : "F";
+    const checked = ctx.checked ?? 0;
+    const total = ctx.total ?? 0;
+    const capped = grade === "A" && total > 0 && checked / total < MIN_COVERAGE;
+    if (capped)
+        grade = "B";
     const counts = { error: 0, warn: 0, info: 0 };
     for (const f of findings)
         counts[f.level]++;
-    return { score, grade, counts };
+    return { score, grade, counts, checked, total, capped };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-search-auditor",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Checks whether AI search (ChatGPT, Claude, Perplexity, Google AI Overviews) can read, understand and cite your site: robots.txt for AI agents, text without JavaScript, JSON-LD authorship, llms.txt, freshness.",
   "keywords": [
     "ai search audit",