@operstack/audit 0.9.0 → 0.11.0

package/README.md

@@ -46,6 +46,33 @@ An agent can fill these fields from the JSON: the Claude Code plugin `operstack-
 
 Ten A4 pages: cover, executive summary with a scorecard, site overview with the sampled pages, critical issues, technical and on-page checklist, content and structure, AEO and GEO, off-page and conversion and limitations, roadmap in three phases, closing message. HTML always; PDF with `--pdf` when Chrome or Chromium is installed (`CHROME_PATH` overrides the lookup).
 
+## The agent surface
+
+**In plain words.** Assistants like ChatGPT and Claude are starting to read a couple of small files
+to work out what a site is and what it can do, the way a search engine reads robots.txt. Almost
+nobody has them yet, which is exactly why having them is cheap and noticeable. These checks say
+whether yours exist, and they are honest about it being early days: a missing file is a note, not a
+failure.
+
+**What it checks.** `/.well-known/agent.json` (the agent card: who you are, what you offer, how to
+reach you), `/.well-known/api-catalog` per RFC 9727, and whether a page offers a markdown version,
+either through a `Link` header or as a file beside it. The API catalogue is deliberately never
+offered as work: it belongs to a business that actually exposes an API.
+
+## What an AI does not see: the JavaScript check
+
+**In plain words.** Some sites draw themselves with scripts. A person opens the page and sees the
+full text; a robot that does not run scripts sees an empty frame. The robots that pull a page into
+an AI answer are exactly that kind of robot. So the owner reads his own page, sees plenty of text,
+and cannot understand why nobody quotes it. This check reads the page twice, as a plain request and
+in a real browser, and tells you how much of the text only exists in the second reading.
+
+**What it does.** `collect` runs Chrome or Chromium over the homepage and two sampled pages, strips
+the navigation and footer from both readings, and compares the word counts. Forty percent hidden, or
+a page that is nearly empty without scripts, fails. Ten to forty warns. Under ten passes. With no
+browser installed the check says it was not measured and why. `--no-rendered` skips it,
+`--rendered-pages N` changes how many pages are opened; each page costs roughly half a minute.
+
 ## Writing the report: `draft`
 
 **If you have never done SEO, start here.** An audit tells you what a search engine and an AI see when they open your site. This tool writes that report for you. It does not guess anything about your business: every sentence in it comes from something that was measured on your pages, and where nothing could be measured it says so instead of filling the gap with words. You read it, correct what only you know, and send it.

package/bin/audit.mjs

@@ -40,8 +40,9 @@ const has = (k) => rest.includes(k);
 if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log([
     'Usage:',
-    '  operstack-audit collect <url> [--pages 20] [--out audit.json] [--backlinks links.json] [--lang ru]',
-    '      collect the public signals of a site into audit.json',
+    '  operstack-audit collect <url> [--pages 20] [--out audit.json] [--lang ru] [--no-rendered]',
+    '      collect the public signals of a site into audit.json; a real browser also measures how',
+    '      much of the text is invisible without JavaScript (--no-rendered skips that)',
     '  operstack-audit render <audit.json> [--out report.html] [--pdf]',
     '      render the report; --pdf also prints a PDF with headless Chrome',
     '  operstack-audit draft <audit.json> [--lang ru|en] [--out audit.json]',
@@ -64,7 +65,14 @@ if (cmd === 'collect') {
   if (!/^https?:\/\//.test(target || '')) { console.error('collect needs an absolute URL'); process.exit(2); }
   const backlinksFile = opt('--backlinks', '');
   const backlinks = backlinksFile ? JSON.parse(readFileSync(resolve(backlinksFile), 'utf8')) : null;
-  const audit = await collect(target, { pages: Number(opt('--pages', 20)), backlinks, lang: opt('--lang', 'en'), log: (m) => console.error(`  ${m}`) });
+  // Проверка «виден ли текст без скриптов» требует браузера и добавляет полминуты на страницу.
+  // В платном аудите она нужна всегда: именно здесь мы можем соврать про чужой сайт. Выключается
+  // флагом --no-rendered, например когда браузера нет или прогон идёт по расписанию.
+  const audit = await collect(target, {
+    pages: Number(opt('--pages', 20)), backlinks, lang: opt('--lang', 'en'),
+    rendered: !has('--no-rendered'), renderedPages: Number(opt('--rendered-pages', 3)),
+    log: (m) => console.error(`  ${m}`),
+  });
   const out = resolve(opt('--out', 'audit.json'));
   writeFileSync(out, JSON.stringify(audit, null, 2));
   console.log(`wrote ${out}: ${audit.checks.length} checks, ${audit.sample.length} pages sampled, scores ${Object.entries(audit.scores).map(([k, v]) => `${k} ${v === null ? 'not measured' : v}`).join(', ')}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operstack/audit",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "SEO, AEO and GEO audit generator: collect public signals from a site into audit.json, let an analyst or an agent fill the narrative, render the OperStack report as HTML and PDF.",
   "type": "module",
   "license": "MIT",
@@ -15,7 +15,8 @@
     "./fix": "./src/fix.mjs",
     "./foundation": "./src/foundation.mjs",
     "./narrative": "./src/narrative.mjs",
-    "./prompts": "./src/prompts.mjs"
+    "./prompts": "./src/prompts.mjs",
+    "./rendered": "./src/rendered.mjs"
   },
   "files": [
     "bin",
@@ -26,7 +27,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node src/test-scores.mjs && node src/test-fix.mjs && node src/test-foundation.mjs && node src/test-narrative.mjs && node src/test-prompts.mjs && node bin/audit.mjs check examples/sample-audit.json && node bin/audit.mjs render examples/sample-audit.json --out /tmp/operstack-audit-sample.html",
+    "test": "node src/test-scores.mjs && node src/test-fix.mjs && node src/test-foundation.mjs && node src/test-narrative.mjs && node src/test-prompts.mjs && node src/test-rendered.mjs && node src/test-agent-surface.mjs && node bin/audit.mjs check examples/sample-audit.json && node bin/audit.mjs render examples/sample-audit.json --out /tmp/operstack-audit-sample.html",
     "sample": "node bin/audit.mjs render examples/sample-audit.json --pdf"
   },
   "keywords": [

package/src/collect.mjs

@@ -3,6 +3,7 @@
  * robots.txt, sitemaps, llms.txt, the homepage and a sample of pages from the sitemap.
  * No Search Console, no analytics. The narrative fields are left for the analyst.
  */
+import { renderedDom, compareReadings, jsBlindnessCheck } from './rendered.mjs';
 import { parse } from 'node-html-parser';
 import { localiseChecks } from './i18n.mjs';
 
@@ -15,7 +16,9 @@ async function get(url, { method = 'GET', timeout = 15000 } = {}) {
     const res = await fetch(url, { method, redirect: 'manual', signal: c.signal, headers: { 'user-agent': UA, accept: 'text/html,application/xml,text/plain,*/*' } });
     const ttfb = Date.now() - started;
     const text = method === 'GET' ? await res.text() : '';
-    return { ok: res.ok, status: res.status, location: res.headers.get('location'), type: res.headers.get('content-type') || '', text, ttfb, url };
+    // Заголовок Link нужен проверке «есть ли markdown-версия страницы»: им сайт говорит агенту,
+    // где лежит текстовая копия. Возвращаем его сразу, чтобы не ходить за страницей второй раз.
+    return { ok: res.ok, status: res.status, location: res.headers.get('location'), type: res.headers.get('content-type') || '', link: res.headers.get('link') || '', text, ttfb, url };
   } catch (e) { return { ok: false, status: 0, error: e.name === 'AbortError' ? 'timeout' : e.message, text: '', ttfb: Date.now() - started, url }; }
   finally { clearTimeout(t); }
 }
@@ -162,7 +165,7 @@ async function readSitemap(url, seen = new Set(), depth = 0) {
   return out;
 }
 
-export async function collect(startUrl, { pages = 20, log = () => {}, backlinks = null, lang = 'en' } = {}) {
+export async function collect(startUrl, { pages = 20, log = () => {}, backlinks = null, lang = 'en', rendered = false, renderedPages = 3 } = {}) {
   const opts = { backlinks };
   const origin = new URL(startUrl).origin;
   const host = new URL(startUrl).host;
@@ -226,6 +229,30 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
     !llms.ok ? 'not present' : !llmsIsText ? 'answers with an HTML page, not a text index' : `${llmsLinks.length} link(s), ${llmsForeign.length} to other hosts`,
     !llms.ok ? 'answer engines get nothing to read; a generated index is a one-day job' : llmsForeign.length > 3 ? `links to ${[...new Set(llmsForeign.map((u) => new URL(u).host))].slice(0, 3).join(', ')}: an AI system may misidentify the business` : ''));
 
+  // Агентная поверхность: карточки, по которым ИИ-агент понимает, с чем имеет дело и что тут можно
+  // вызвать. Стандарты молодые, поэтому отсутствие это не провал, а предупреждение, и в тексте
+  // прямо сказано, что это раннее и необязательное. Врать про обязательность мы не будем.
+  log('agent surface');
+  const agentCard = await get(`${origin}/.well-known/agent.json`);
+  const agentCardOk = agentCard.ok && /^\s*\{/.test(agentCard.text || '');
+  checks.push(row('agent-card', 'geo', 'Agent card (/.well-known/agent.json)', agentCardOk ? 'ok' : 'warn',
+    agentCardOk ? 'present and valid JSON' : agentCard.ok ? 'present but not JSON' : 'not present',
+    agentCardOk ? '' : 'an early, optional standard: it is the file agent directories read to learn who you are and what you offer'));
+
+  const apiCatalog = await get(`${origin}/.well-known/api-catalog`);
+  checks.push(row('api-catalog', 'geo', 'API catalogue (RFC 9727)', apiCatalog.ok ? 'ok' : 'warn',
+    apiCatalog.ok ? 'present' : 'not present',
+    apiCatalog.ok ? '' : 'optional, and only worth adding when the business actually exposes an API for agents to call'));
+
+  // Markdown-версия страницы: её просят агенты, которым HTML мешает. Признаём оба способа,
+  // заголовок Link и файл рядом со страницей, потому что оба встречаются.
+  const homeMd = await get(`${home.final.replace(/\/$/, '')}/index.md`);
+  const linkHeader = String(home.response.link || '');
+  const mdOk = (homeMd.ok && !/<html/i.test((homeMd.text || '').slice(0, 300))) || /text\/markdown/i.test(linkHeader);
+  checks.push(row('agent-markdown', 'geo', 'Markdown version of the pages', mdOk ? 'ok' : 'warn',
+    mdOk ? (/text\/markdown/i.test(linkHeader) ? 'offered through the Link header' : 'served next to the page') : 'not offered',
+    mdOk ? '' : 'an agent that asks for text/markdown gets HTML and has to strip it: giving it markdown is cheap and removes the guesswork'));
+
   log(`sampling up to ${pages} pages`);
   const norm = (u) => { try { const x = new URL(u); x.hash = ''; x.search = ''; if (!x.pathname.includes('.') && !x.pathname.endsWith('/')) x.pathname += '/'; return x.href.toLowerCase(); } catch { return u; } };
   const seenUrl = new Set([norm(home.final), norm(startUrl)]);
@@ -335,6 +362,25 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
 
   const { scores, scoreBasis } = computeScores(checks);
   // Оценки считаются до перевода: язык на цифры не влияет.
+  // Сколько текста не видно без выполнения скриптов. Меряется настоящим браузером и только по
+  // просьбе: запуск браузера это десятки секунд на страницу, и еженедельному мониторингу это ни к
+  // чему. Для платного аудита включено, потому что именно здесь мы можем соврать про чужой сайт.
+  if (rendered) {
+    const targets = [{ url: home.final, raw: home.response.ok ? home.response.text : '' },
+      ...good.filter((p) => p.url !== home.final).slice(0, Math.max(0, renderedPages - 1)).map((p) => ({ url: p.url, raw: '' }))];
+    const measured = [];
+    for (const t of targets) {
+      if (!t.url) continue;
+      log(`rendering ${t.url} in a real browser`);
+      const dom = renderedDom(t.url);
+      if (!dom) { log('no browser here, the JavaScript check will say it was not measured'); break; }
+      const rawHtml = t.raw || (await get(t.url)).text;
+      if (!rawHtml) continue;
+      measured.push({ url: t.url, ...compareReadings(rawHtml, dom) });
+    }
+    checks.push(jsBlindnessCheck(measured, lang));
+  }
+
   const localised = localiseChecks(checks, lang);
   const critical = checks.filter((c) => c.status === 'bad').map((c) => ({ title: c.label, text: `${c.value}${c.comment ? `. ${c.comment}` : ''}`, level: 'bad' }));
 

package/src/fix.mjs

@@ -66,6 +66,10 @@ export const FIX_ACTIONS = {
   thin: { scope: 'client', why: { ru: 'наполнение тонких страниц это тексты по фактам клиента', en: 'filling thin pages means writing from your facts' } },
   sections: { scope: 'client', why: { ru: 'разбивка на разделы это переписывание текста', en: 'splitting into sections means rewriting the text' } },
   tables: { scope: 'client', why: { ru: 'таблица собирается из данных клиента', en: 'a table is built from your data' } },
+  'agent-card': { scope: 'always', action: { ru: 'Положить в /.well-known/agent.json карточку с названием компании, одной строкой о том, чем она занимается, адресом сайта и способом связи', en: 'Put an agent card at /.well-known/agent.json with the company name, one line on what it does, the site address and a way to get in touch' } },
+  'api-catalog': { scope: 'never', why: { ru: 'нужен только тем, у кого есть API для агентов, выдумывать его ради галочки незачем', en: 'only for a business that actually exposes an API for agents; inventing one for the sake of a tick is pointless' } },
+  'agent-markdown': { scope: 'files', action: { ru: 'Отдавать markdown-версию каждой страницы и объявлять её заголовком Link рядом с HTML', en: 'Serve a markdown version of every page and declare it with a Link header beside the HTML' } },
+  'js-content': { scope: 'files', action: { ru: 'Отдавать текст страницы сразу в HTML, а не дорисовывать его скриптами: предрендер или серверная отрисовка тех страниц, где текст сейчас появляется только в браузере', en: 'Serve the page text in the HTML itself instead of drawing it with scripts: prerender or server-render the pages whose text currently appears only in a browser' } },
   'links-profile': { scope: 'never', why: { ru: 'данные по ссылкам платные и ни в одну оценку не входят', en: 'link data is paid, and it moves no score of ours' } },
 };
 

package/src/i18n.mjs

@@ -105,6 +105,9 @@ const RU = {
   tables: { label: 'Таблицы в тексте', value: (v) => (/no table/.test(v) ? 'на проверенных страницах таблиц нет' : `${nums(v)[0]} из ${pages(nums(v)[1])} выборки используют таблицу`), comment: (c) => (c ? 'таблица это второй по частоте формат цитирования после первого абзаца' : '') },
   sources: { label: 'Названные источники цифр', value: (v) => { const n = nums(v); return `${n[0]} из ${pages(n[1])} выборки называют, откуда взята цифра, словами или ссылкой рядом с ней`; }, comment: (c) => (c ? 'цифра без источника это первое, что система выбрасывает' : '') },
   dates: { label: 'Открытые даты публикации', value: (v) => (/no article dates/.test(v) ? 'дат в выборке нет: ответные системы не поймут, что здесь актуально' : `${nums(v)[0]} из ${pages(nums(v)[1])} выборки показывают дату`) },
+  'agent-card': { label: 'Карточка агента (/.well-known/agent.json)', value: (v) => (/valid JSON/.test(v) ? 'есть, и это правильный JSON' : /not JSON/.test(v) ? 'есть, но это не JSON' : 'нет'), comment: (c) => (c ? 'ранний и необязательный стандарт: этот файл читают каталоги ИИ-агентов, чтобы понять, кто вы и что предлагаете' : '') },
+  'api-catalog': { label: 'Каталог API (RFC 9727)', value: (v) => (/^present/.test(v) ? 'есть' : 'нет'), comment: (c) => (c ? 'необязательно, и нужно только если у бизнеса действительно есть API, который агент мог бы вызвать' : '') },
+  'agent-markdown': { label: 'Markdown-версия страниц', value: (v) => (/Link header/.test(v) ? 'предлагается через заголовок Link' : /next to the page/.test(v) ? 'лежит рядом со страницей' : 'не предлагается'), comment: (c) => (c ? 'агент, который просит text/markdown, получает HTML и вынужден его разбирать: отдать markdown дёшево и снимает догадки' : '') },
   'links-profile': { label: 'Профиль внешних ссылок (необязательное дополнение)', value: (v) => { const n = nums(v); return `${plural(Number(n[0]), 'ссылающийся домен', 'ссылающихся домена', 'ссылающихся доменов')}, ${plural(Number(n[1]), 'ссылка', 'ссылки', 'ссылок')}, ${pct(n[2])} передают вес, показатель авторитета ${n[3]} из 100`; }, comment: (c) => `${c.split('.')[0]}. Платный инструмент, для этого отчёта не обязателен и ни в одну оценку не входит.` },
   'trust-entity': { label: 'Кто это, в машиночитаемом виде', value: (v) => (/no postal address/.test(v) ? 'почтового адреса в разметке нет' : 'почтовый адрес опубликован в разметке'), comment: (c) => (c ? 'рейтинговые системы и ответные движки по нему отличают одну компанию от другой' : '') },
   'trust-contact': {

package/src/prompts.mjs

@@ -94,6 +94,18 @@ const P = {
     ru: { task: 'Пройди по абзацам, где есть цифры, и подпиши к каждой, откуда она: ссылкой на первоисточник или словами («по данным реестра за 2026 год»). Если источника нет ни у тебя, ни у владельца, цифру надо убрать, а не оставлять голой. Не ставь ссылку наугад: неверный источник хуже отсутствующего.', verify: 'В каждом абзаце с цифрой есть либо ссылка на чужой сайт, либо названный словами источник.' },
     en: { task: 'Go through the paragraphs carrying figures and name where each came from: a link to the primary source, or words ("per the 2026 registry"). If neither you nor the owner has a source, the figure comes out rather than standing bare. Do not guess a link: a wrong source is worse than none.', verify: 'Every paragraph with a figure carries either an outbound link or a source named in words.' },
   },
+  'agent-card': {
+    ru: { task: 'Собери файл /.well-known/agent.json: название компании, одна строка о том, чем она занимается, адрес сайта, способ связи и перечень того, что вы предлагаете. Пиши только правду: это читают каталоги агентов, и выдуманная возможность обернётся жалобой. Файл отдавай с типом application/json.', verify: 'Адрес /.well-known/agent.json отвечает 200, тип application/json, и JSON разбирается без ошибок.' },
+    en: { task: 'Build a /.well-known/agent.json: the company name, one line on what it does, the site address, a way to get in touch and a list of what you offer. Put only true things in it: agent directories read this, and an invented capability turns into a complaint. Serve it as application/json.', verify: '/.well-known/agent.json answers 200 with application/json and parses as valid JSON.' },
+  },
+  'agent-markdown': {
+    ru: { task: 'Сделай так, чтобы у каждой страницы была markdown-версия того же текста, и объяви её заголовком Link со ссылкой на неё и типом text/markdown. Markdown должен содержать тот же текст, что и страница: заголовки, абзацы, списки и таблицы. Служебную обвязку, меню и подвал в него не клади.', verify: 'Запрос страницы возвращает заголовок Link с text/markdown, и по этой ссылке отдаётся текст той же страницы, а не HTML.' },
+    en: { task: 'Give every page a markdown version of the same text and declare it with a Link header pointing at it with type text/markdown. The markdown must carry the same text as the page: headings, paragraphs, lists and tables. Leave the navigation and footer out of it.', verify: 'A request for the page returns a Link header with text/markdown, and that URL serves the text of the same page rather than HTML.' },
+  },
+  'js-content': {
+    ru: { task: 'Найди страницы, где основной текст появляется только после выполнения скриптов, и сделай так, чтобы он отдавался сразу в HTML: предрендер при сборке или серверная отрисовка. Проверить просто: открой адрес страницы командой curl и посмотри, есть ли в ответе текст статьи. Не прячь текст в атрибуты и не дублируй его скрытым блоком ради роботов: это считается обманом и наказывается.', verify: 'В ответе на обычный запрос без браузера виден весь основной текст страницы, а не только каркас.' },
+    en: { task: 'Find the pages whose main text appears only after scripts run, and make that text arrive in the HTML itself: prerender at build time or render on the server. Checking is simple: fetch the URL with curl and see whether the article text is in the response. Do not hide the text in attributes and do not duplicate it in a hidden block for robots: that counts as cloaking and is punished.', verify: 'A plain request without a browser returns the whole main text of the page, not just the shell.' },
+  },
   thin: {
     ru: { task: 'Возьми страницы короче трёхсот слов и допиши их фактами, которые знает владелец: условия, цены, сроки, ограничения, частые вопросы покупателей с ответами. Не разбавляй текст водой ради объёма. Если фактов нет, выпиши владельцу список вопросов и оставь страницу как есть.', verify: 'Страница стала длиннее трёхсот слов, и каждый добавленный абзац содержит факт, а не общие слова.' },
     en: { task: 'Take the pages under three hundred words and fill them with facts the owner has: terms, prices, timings, limits, the questions buyers actually ask with the answers. Do not pad for length. Where the facts are missing, write the owner a list of questions and leave the page alone.', verify: 'The page is over three hundred words and every added paragraph carries a fact rather than filler.' },

package/src/rendered.mjs

@@ -0,0 +1,103 @@
+/**
+ * Сколько текста страницы не видит тот, кто не выполняет JavaScript.
+ *
+ * Человеческими словами: если сайт рисует себя скриптами, то поисковый робот и особенно робот,
+ * который достаёт страницу для ответа ИИ, могут увидеть пустую страницу. Владелец при этом видит
+ * полный текст и не понимает, почему его не цитируют. Здесь это измеряется прямо: страница
+ * читается дважды, как обычный запрос без скриптов и как настоящий браузер, и считается, какая
+ * доля текста появляется только во втором случае.
+ *
+ * Браузер берётся тот же, которым печатается PDF отчёта: свой Chrome или Chromium. Если его нет,
+ * проверка не выдумывает результат, а говорит, что не измеряла, и почему.
+ */
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** Тот же поиск браузера, что у печати PDF: одна привычка на весь пакет. */
+export function findChrome() {
+  const candidates = [
+    process.env.CHROME_PATH,
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  ].filter(Boolean);
+  for (const c of candidates) {
+    const r = spawnSync(c, ['--version'], { encoding: 'utf8', timeout: 8000 });
+    if (r.status === 0) return c;
+  }
+  return null;
+}
+
+/** Текст страницы после выполнения скриптов. null, если браузера нет или он не справился. */
+export function renderedDom(url, { chrome = null, timeoutMs = 45000, waitMs = 8000 } = {}) {
+  const bin = chrome || findChrome();
+  if (!bin) return null;
+  const profile = mkdtempSync(join(tmpdir(), 'operstack-render-'));
+  try {
+    const r = spawnSync(bin, [
+      '--headless=new', '--disable-gpu', '--no-first-run', '--no-default-browser-check',
+      '--disable-extensions', '--mute-audio', '--hide-scrollbars',
+      `--user-data-dir=${profile}`, `--virtual-time-budget=${waitMs}`, '--dump-dom', url,
+    ], { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 });
+    if (r.status !== 0 || !r.stdout) return null;
+    return r.stdout;
+  } catch { return null; } finally { rmSync(profile, { recursive: true, force: true }); }
+}
+
+const CHROME_STRIP = /<(nav|footer|aside|script|style|noscript|template)[\s\S]*?<\/\1>/gi;
+const plain = (html) => String(html)
+  .replace(/<!--[\s\S]*?-->/g, ' ')
+  .replace(CHROME_STRIP, ' ')
+  .replace(/<[^>]+>/g, ' ')
+  .replace(/&nbsp;/g, ' ')
+  .replace(/\s+/g, ' ')
+  .trim();
+const countWords = (s) => (s.match(/[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu) || []).length;
+
+/**
+ * Сравнение двух чтений одной страницы.
+ * @returns {{raw:number, rendered:number, hiddenShare:number, verdict:'ok'|'warn'|'bad'}}
+ */
+export function compareReadings(rawHtml, renderedHtml) {
+  const raw = countWords(plain(rawHtml));
+  const rendered = countWords(plain(renderedHtml));
+  // Отрицательной разницы не бывает: если браузер увидел меньше, значит он не досчитал, а не
+  // страница уменьшилась. Такой случай считаем нулевой разницей, а не отрицательной долей.
+  const extra = Math.max(0, rendered - raw);
+  const hiddenShare = rendered > 0 ? Math.round((extra / rendered) * 100) : 0;
+  const verdict = hiddenShare >= 40 || (raw < 50 && rendered >= 200) ? 'bad' : hiddenShare >= 10 ? 'warn' : 'ok';
+  return { raw, rendered, hiddenShare, verdict };
+}
+
+const WORD = { ru: (n) => `${n} ${n % 10 === 1 && n % 100 !== 11 ? 'слово' : n % 10 >= 2 && n % 10 <= 4 && (n % 100 < 10 || n % 100 >= 20) ? 'слова' : 'слов'}` };
+
+/** Строка проверки для аудита. Текст пишется так, чтобы владелец понял, чем ему это грозит. */
+export function jsBlindnessCheck(pages, lang = 'en') {
+  const measured = pages.filter((p) => p && p.rendered > 0);
+  if (!measured.length) {
+    return {
+      id: 'js-content', group: 'technical',
+      label: lang === 'ru' ? 'Виден ли текст без выполнения скриптов' : 'Text visible without running JavaScript',
+      status: 'na',
+      value: lang === 'ru' ? 'не измеряли: на этой машине нет браузера Chrome или Chromium' : 'not measured: no Chrome or Chromium on this machine',
+      comment: lang === 'ru' ? 'проверка сравнивает страницу, прочитанную без скриптов, с ней же в настоящем браузере' : 'the check compares the page read without scripts against the same page in a real browser',
+    };
+  }
+  const worst = measured.slice().sort((a, b) => b.hiddenShare - a.hiddenShare)[0];
+  const median = measured.map((p) => p.hiddenShare).sort((a, b) => a - b)[Math.floor(measured.length / 2)];
+  const status = measured.some((p) => p.verdict === 'bad') ? 'bad' : measured.some((p) => p.verdict === 'warn') ? 'warn' : 'ok';
+  const value = lang === 'ru'
+    ? `без скриптов видно всё, кроме ${median} процентов текста (медиана по ${measured.length} ${measured.length === 1 ? 'странице' : 'страницам'}), хуже всего ${worst.url}: там скрыто ${worst.hiddenShare} процентов, ${WORD.ru(worst.raw)} без скриптов против ${WORD.ru(worst.rendered)} в браузере`
+    : `${median}% of the text is invisible without JavaScript (median over ${measured.length} page${measured.length === 1 ? '' : 's'}); worst is ${worst.url} at ${worst.hiddenShare}%, ${worst.raw} words without scripts against ${worst.rendered} in a browser`;
+  // Слова по размеру беды: на четырнадцати процентах писать «страница почти пустая» это враньё
+  // в ту же сторону, от которого мы уходим.
+  const comment = status === 'ok'
+    ? (lang === 'ru' ? 'страницы читаются целиком и без браузера, это то, что нужно поиску и ИИ' : 'the pages read whole without a browser, which is what search and AI need')
+    : status === 'bad'
+      ? (lang === 'ru' ? 'для простых роботов поиска и для роботов, которые достают страницу в ответ ИИ, эта страница почти пустая: они не выполняют скрипты' : 'to simple search crawlers and to the fetchers that pull a page into an AI answer this page is nearly empty: they do not run scripts')
+      : (lang === 'ru' ? 'эта часть текста не доходит до роботов, которые не выполняют скрипты, а именно они приносят страницу в ответ ИИ' : 'this part of the text does not reach the robots that do not run scripts, and those are the ones that bring a page into an AI answer');
+  return { id: 'js-content', group: 'technical', label: lang === 'ru' ? 'Виден ли текст без выполнения скриптов' : 'Text visible without running JavaScript', status, value, comment };
+}

package/src/test-agent-surface.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/** Агентная поверхность: три проверки, их перевод, работа и задание для агента. */
+import { FIX_ACTIONS } from './fix.mjs';
+import { localiseChecks } from './i18n.mjs';
+import { agentPrompt } from './prompts.mjs';
+import { draftNarrative } from './narrative.mjs';
+
+let bad = 0;
+const is = (n, a, b) => { const ok = JSON.stringify(a) === JSON.stringify(b); if (!ok) { bad++; console.error(`FAIL ${n}\n  ждали ${JSON.stringify(b)}\n  вышло ${JSON.stringify(a)}`); } else console.log(`ok   ${n}`); };
+const ok = (n, c) => is(n, Boolean(c), true);
+
+const ids = ['agent-card', 'api-catalog', 'agent-markdown'];
+
+// У каждой проверки есть решение и перевод
+for (const id of ids) ok(`у проверки ${id} описано, что делать или почему не делаем`, Boolean(FIX_ACTIONS[id] && (FIX_ACTIONS[id].action || FIX_ACTIONS[id].why)));
+const ru = localiseChecks(ids.map((id) => ({ id, group: 'geo', label: 'English label', status: 'warn', value: 'not present', comment: 'an early, optional standard: it is the file agent directories read to learn who you are and what you offer' })), 'ru');
+for (const r of ru) ok(`проверка ${r.id} переведена`, !/English label/.test(r.label) && !/not present/.test(r.value));
+
+// Каталог API мы не обещаем чинить: он нужен не всем
+is('каталог API не обещаем', FIX_ACTIONS['api-catalog'].scope, 'never');
+ok('и объяснено почему', /есть API/.test(FIX_ACTIONS['api-catalog'].why.ru));
+
+// Задания для агента полные и не врут про обязательность
+const card = agentPrompt({ id: 'agent-card', label: 'Карточка агента', status: 'warn', value: 'нет' }, { lang: 'ru' });
+ok('в задании про карточку есть проверка', /Как проверить/.test(card));
+ok('и запрет выдумывать возможности', /только правду|выдуманная возможность/.test(card));
+const md = agentPrompt({ id: 'agent-markdown', label: 'Markdown-версия', status: 'warn', value: 'нет' }, { lang: 'ru' });
+ok('в задании про markdown сказано, что класть, а что нет', /меню и подвал/.test(md));
+
+// В отчёте это не превращается в приговор: стандарт ранний
+const audit = {
+  meta: { host: 'x.ru', lang: 'ru' },
+  scores: { 'GEO, visibility in AI systems': 7 },
+  client: { name: '{{a}}', subject: '{{b}}' },
+  summary: { lead: '{{a}}', verdict: '{{b}}', priorities: ['{{1}}'] },
+  overview: { rows: [], note: '{{n}}' }, content: { strengths: [], weaknesses: [], gaps: [] },
+  aeo: { works: [], blocks: [], recommendation: '{{r}}' }, geo: { rows: [], callout: '{{c}}' },
+  offpage: { listed: [], note: '{{n}}' }, conversion: { rows: [] }, roadmap: [], closing: '{{c}}',
+  sample: [], checks: [{ id: 'agent-card', group: 'geo', label: 'Карточка агента', status: 'warn', value: 'нет' }],
+};
+const d = draftNarrative(audit, { lang: 'ru' });
+ok('в приоритетах появляется работа по карточке', /agent\.json|карточк/i.test(JSON.stringify(d.summary.priorities)));
+ok('и вывод не называет это провалом', !/критичн/i.test(d.summary.verdict) || /нет/.test(d.summary.verdict));
+
+if (bad) { console.error(`\n${bad} тест(ов) упало`); process.exit(1); }
+console.log('\nвсе тесты агентной поверхности прошли');

package/src/test-rendered.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/** Слепота к скриптам: считаем честно, не измерив, так и говорим. */
+import { compareReadings, jsBlindnessCheck } from './rendered.mjs';
+
+let bad = 0;
+const is = (n, a, b) => { const ok = JSON.stringify(a) === JSON.stringify(b); if (!ok) { bad++; console.error(`FAIL ${n}\n  ждали ${JSON.stringify(b)}\n  вышло ${JSON.stringify(a)}`); } else console.log(`ok   ${n}`); };
+const ok = (n, c) => is(n, Boolean(c), true);
+
+const text = (n) => '<p>' + 'слово '.repeat(n) + '</p>';
+const body = (inner) => `<html><body>${inner}</body></html>`;
+
+is('одинаковые чтения дают ноль скрытого', compareReadings(body(text(300)), body(text(300))).hiddenShare, 0);
+is('и вердикт «в порядке»', compareReadings(body(text(300)), body(text(300))).verdict, 'ok');
+
+const empty = compareReadings(body('<div id="root"></div>'), body(text(300)));
+is('пустой каркас против полной страницы это сто процентов', empty.hiddenShare, 100);
+is('и это приговор', empty.verdict, 'bad');
+
+const half = compareReadings(body(text(100)), body(text(200)));
+is('половина текста за скриптами считается верно', half.hiddenShare, 50);
+is('и это тоже приговор', half.verdict, 'bad');
+
+is('пять процентов за скриптами это ещё в порядке', compareReadings(body(text(285)), body(text(300))).verdict, 'ok');
+const tenth = compareReadings(body(text(270)), body(text(300)));
+is('десятая часть текста за скриптами это уже предупреждение', tenth.verdict, 'warn');
+is('и доля посчитана', tenth.hiddenShare, 10);
+
+// Меню и подвал не считаются: их и так никто не цитирует
+const chrome = compareReadings(body('<nav>меню меню меню</nav>' + text(100)), body('<nav>меню меню меню другое</nav>' + text(100)));
+is('разница только в меню не считается скрытым текстом', chrome.hiddenShare, 0);
+
+// Браузер увидел меньше: это его беда, а не отрицательная доля
+is('отрицательной доли не бывает', compareReadings(body(text(300)), body(text(100))).hiddenShare, 0);
+
+// Строка проверки
+const good = jsBlindnessCheck([{ url: 'https://x.ru/', raw: 300, rendered: 300, hiddenShare: 0, verdict: 'ok' }], 'ru');
+is('чистый сайт получает «ok»', good.status, 'ok');
+ok('и понятный текст', /читаются целиком/.test(good.comment));
+
+const worst = jsBlindnessCheck([
+  { url: 'https://x.ru/a', raw: 300, rendered: 300, hiddenShare: 0, verdict: 'ok' },
+  { url: 'https://x.ru/b', raw: 10, rendered: 400, hiddenShare: 98, verdict: 'bad' },
+], 'ru');
+is('одна плохая страница делает проверку проваленной', worst.status, 'bad');
+ok('в тексте названа худшая страница', worst.value.includes('https://x.ru/b'));
+ok('и сказано, сколько слов видно без скриптов', /10 слов без скриптов против 400/.test(worst.value));
+ok('приговор говорит про роботов ИИ', /достают страницу в ответ ИИ/.test(worst.comment));
+
+const mild = jsBlindnessCheck([{ url: 'https://x.ru/', raw: 86, rendered: 100, hiddenShare: 14, verdict: 'warn' }], 'ru');
+ok('на четырнадцати процентах не пишем «страница почти пустая»', !/почти пустая/.test(mild.comment));
+ok('а пишем, что часть текста не доходит', /не доходит/.test(mild.comment));
+
+const none = jsBlindnessCheck([], 'ru');
+is('без браузера статус «не измеряли»', none.status, 'na');
+ok('и сказано почему', /нет браузера/.test(none.value));
+
+const en = jsBlindnessCheck([{ url: 'https://x.com/', raw: 10, rendered: 400, hiddenShare: 98, verdict: 'bad' }], 'en');
+ok('английская версия без кириллицы', !/[А-Яа-яЁё]/.test(JSON.stringify(en)));
+
+if (bad) { console.error(`\n${bad} тест(ов) упало`); process.exit(1); }
+console.log('\nвсе тесты слепоты к скриптам прошли');