@operstack/audit 0.31.0 → 0.32.1

package/README.md

@@ -1,3 +1,5 @@
+<img src="https://raw.githubusercontent.com/oper-stack/brand/main/og-audit.png" alt="OperStack audit-generator" width="100%">
+
 # @operstack/audit
 
 The SEO, AEO and GEO audit generator behind the OperStack audit service. It collects the public signals of a site into one JSON file, leaves the narrative to an analyst or an agent, and renders a print-ready report.
@@ -90,10 +92,10 @@ Technically: `draft` fills the narrative fields (`summary`, `client.subject`, `o
 **If you do not edit the site yourself.** Most people who read an audit now fix their site by telling an AI assistant what to do. This turns every finding into a task written for that assistant: copy it, paste it into Cursor or Claude Code, and it does the work. Each task says what the state is today, what to change, and how you will know it is finished, so the assistant cannot wander off and cannot quietly invent facts about your business.
 
 ```
-npx @operstack/audit prompts audit.json --lang en --limit 3
+npx @operstack/audit prompts audit.json --lang en
 ```
 
-Technically: every open check is rendered as a Markdown block with `Now` (the measured value), `Task` (the action and its boundaries) and `How to check` (the acceptance test), plus a standing rule against inventing business facts. Twenty checks carry text written for that specific finding; the rest fall back to the Fix action with a generic acceptance test. `--limit 3` is what the free tier hands out; the full list ships with the paid audit. `renderFixChecklist(plan, { withPrompts: true })` embeds the same tasks in the executor checklist.
+Technically: every open check is rendered as a Markdown block with `Now` (the measured value), `Task` (the action and its boundaries) and `How to check` (the acceptance test), plus a standing rule against inventing business facts. Twenty checks carry text written for that specific finding; the rest fall back to the Fix action with a generic acceptance test. Every open finding becomes a task, and that is the free behaviour: no account, no key, no trimmed preview. `--limit 3` is there when you want only the three tasks that move the score most. The paid audit sells the reading and the work, not the list. `renderFixChecklist(plan, { withPrompts: true })` embeds the same tasks in the executor checklist.
 
 ## The Fix package: turning findings into agreed work
 

package/bin/audit.mjs

@@ -24,7 +24,8 @@
  * Scores are never typed by hand: the report always prints what the collected checks give,
  * and an area with no checks is printed as "not measured" rather than scored low.
  */
-import { collect, verifyScores } from '../src/collect.mjs';
+import { collect, verifyScores, compareRivals } from '../src/collect.mjs';
+import { buildLlmsTxt, buildOrganisationSchema, fixTitlesAndDescriptions } from '../src/handover.mjs';
 import { buildFixPlan, renderFixPlan, renderFixChecklist, buildFixReport, renderFixReport } from '../src/fix.mjs';
 import { buildFoundationScope, renderFoundationScope, renderFoundationChecklist } from '../src/foundation.mjs';
 import { draftNarrative, stillEmpty } from '../src/narrative.mjs';
@@ -33,17 +34,26 @@ import { render, checkNarrative } from '../src/render.mjs';
 import { buildDemandMap, renderDemandMarkdown, demandCsv } from '../src/demand.mjs';
 import { resolveBranding } from '../src/agency.mjs';
 import { rank, readList, runBatch, runProspect, split, summarise, toCsv, toMarkdown } from '../src/batch.mjs';
-import { writeFileSync, readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { writeFileSync, readFileSync, mkdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
 
 const [cmd, target, ...rest] = process.argv.slice(2);
+/*
+ * Сколько страниц читает каждый платный тариф. Аудит за 149 обещает сто, и набирать это число
+ * руками каждый раз означает рано или поздно его забыть и отдать двадцать вместо ста.
+ * Автоматические ступени за 9 и 29 живут в ops-notify и сюда не приходят.
+ */
+const PAGES_BY_TIER = { audit: 100 };
+
 const opt = (k, d) => { const i = rest.indexOf(k); return i === -1 ? d : rest[i + 1]; };
 const has = (k) => rest.includes(k);
 
 if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log([
     'Usage:',
-    '  operstack-audit collect <url> [--pages 20] [--out audit.json] [--lang ru] [--no-rendered]',
+    '  operstack-audit collect <url> [--pages 20 | --tier audit] [--rivals "a.com,b.com"] [--out audit.json] [--lang ru] [--no-rendered]',
+    '      --tier audit reads 100 pages: that is what the 149 audit promises, and typing it by hand is how it gets forgotten',
+    '      --rivals reads up to five competitors with the same code and prints them beside you',
     '      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]',
@@ -57,6 +67,8 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
     '      autocomplete, volumes from Topvisor (TOPVISOR_USER_ID and TOPVISOR_KEY in env, --dry only prices it),',
     '      --attach writes the map into audit.json so render prints it as an appendix',
     '  operstack-audit check <audit.json>',
+    '  operstack-audit handover <audit.json> [--out dir] [--lang ru|en]',
+    '      the files the buyer pastes: llms.txt, the Organization markup and the title fixes',
     '      list narrative fields still holding placeholders and any score the checks do not support',
     '',
     '  operstack-audit fix-plan <audit.json> [--platform files|cms] [--lang ru|en] [--price 249] [--out base]',
@@ -93,11 +105,16 @@ if (cmd === 'collect') {
   // В платном аудите она нужна всегда: именно здесь мы можем соврать про чужой сайт. Выключается
   // флагом --no-rendered, например когда браузера нет или прогон идёт по расписанию.
   const audit = await collect(target, {
-    pages: Number(opt('--pages', 20)), backlinks, lang: opt('--lang', 'en'),
+    pages: Number(opt('--pages', PAGES_BY_TIER[opt('--tier', '')] ?? 20)), tier: opt('--tier', ''), backlinks, lang: opt('--lang', 'en'),
     rendered: !has('--no-rendered'), renderedPages: Number(opt('--rendered-pages', 3)),
     preparedBy: opt('--by', ''),
     log: (m) => console.error(`  ${m}`),
   });
+  /* Конкуренты читаются тем же кодом и кладутся в тот же файл: отчёту больше ничего не нужно. */
+  const rivalList = String(opt('--rivals', '')).split(',').map((x) => x.trim()).filter(Boolean);
+  if (rivalList.length) {
+    audit.rivals = await compareRivals(rivalList, { lang: opt('--lang', 'en'), 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(', ')}`);
@@ -141,6 +158,31 @@ if (cmd === 'collect') {
   console.log(`wrote ${out} (${html.length} bytes)${pdf ? `\nwrote ${pdf}` : ''}`);
   const missing = checkNarrative(audit);
   if (missing.length) console.log(`note: ${missing.length} narrative field(s) still carry placeholders: ${missing.slice(0, 6).join(', ')}${missing.length > 6 ? ', ...' : ''}`);
+} else if (cmd === 'handover') {
+  /*
+   * Файлы, которые покупатель кладёт к себе. Они же печатаются в отчёте, но в отчёте их надо
+   * перенабирать, а тут они лежат готовыми: llms.txt, разметка и правки заголовков.
+   */
+  const audit = JSON.parse(readFileSync(resolve(target), 'utf8'));
+  const lang = opt('--lang', audit?.meta?.lang === 'ru' ? 'ru' : 'en');
+  const dir = resolve(opt('--out', 'handover'));
+  mkdirSync(dir, { recursive: true });
+  const org = buildOrganisationSchema(audit, { lang });
+  const fixes = fixTitlesAndDescriptions(audit, { lang, limit: 40 });
+  writeFileSync(join(dir, 'llms.txt'), buildLlmsTxt(audit, { lang }), 'utf8');
+  writeFileSync(join(dir, 'organization.jsonld'), `${org.text}\n`, 'utf8');
+  const head = lang === 'ru' ? ['# Заголовки и описания', '', 'Чинится длина и структура, а не смысл.', ''] : ['# Titles and descriptions', '', 'Length and structure only, not new wording.', ''];
+  const body = fixes.flatMap((f) => [
+    `## ${f.path}`, '',
+    ...(f.title ? [`**title** — ${f.title.problem}`, '', `Сейчас: ${f.title.now || '—'}`.replace('Сейчас:', lang === 'ru' ? 'Сейчас:' : 'Now:'), '', `${lang === 'ru' ? 'Поставить' : 'Put'}: ${f.title.suggestion}`, ''] : []),
+    ...(f.description ? [`**description** — ${f.description.problem}`, '', `${lang === 'ru' ? 'Сейчас' : 'Now'}: ${f.description.now || '—'}`, '', `${lang === 'ru' ? 'Поставить' : 'Put'}: ${f.description.suggestion}`, ''] : []),
+  ]);
+  writeFileSync(join(dir, 'titles.md'), `${[...head, ...body].join('\n').trimEnd()}\n`, 'utf8');
+  console.log(`wrote ${dir}: llms.txt, organization.jsonld, titles.md (${fixes.length} page(s) to fix)`);
+  if (org.missing.length) {
+    console.log(lang === 'ru' ? 'в разметке осталось вписать руками:' : 'the markup still needs, by hand:');
+    for (const m of org.missing) console.log(`  ${m.field}: ${m.what}`);
+  }
 } else if (cmd === 'check') {
   const audit = JSON.parse(readFileSync(resolve(target), 'utf8'));
   const missing = checkNarrative(audit);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operstack/audit",
-  "version": "0.31.0",
+  "version": "0.32.1",
   "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",
@@ -29,7 +29,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 src/test-sitemap.mjs && node src/test-overall.mjs && node src/test-blocked.mjs && node src/test-unmeasured.mjs && node src/test-rendered.mjs && node src/test-sample.mjs && node src/test-demand.mjs && node src/test-agent-surface.mjs && node src/test-agency.mjs && node src/test-i18n.mjs examples/sample-audit.json && node bin/audit.mjs check examples/sample-audit.json && node bin/audit.mjs render examples/sample-audit.json --out /tmp/operstack-audit-sample.html && node src/test-ru-sources.mjs && node src/test-sample-fairness.mjs && node test-engines.mjs && node test-seo-basics.mjs",
+    "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-sitemap.mjs && node src/test-overall.mjs && node src/test-blocked.mjs && node src/test-unmeasured.mjs && node src/test-rendered.mjs && node src/test-sample.mjs && node src/test-demand.mjs && node src/test-agent-surface.mjs && node src/test-agency.mjs && node src/test-i18n.mjs examples/sample-audit.json && node bin/audit.mjs check examples/sample-audit.json && node bin/audit.mjs render examples/sample-audit.json --out /tmp/operstack-audit-sample.html && node src/test-ru-sources.mjs && node src/test-sample-fairness.mjs && node test-engines.mjs && node test-seo-basics.mjs && node test-polite.mjs && node src/test-handover.mjs && node src/test-prospect-count.mjs",
     "sample": "node bin/audit.mjs render examples/sample-audit.json --pdf",
     "verify:live": "node src/verify-live.mjs"
   },

package/src/collect.mjs

@@ -38,6 +38,72 @@ async function get(url, { method = 'GET', timeout = REQUEST_TIMEOUT } = {}) {
   finally { clearTimeout(t); }
 }
 
+/**
+ * Вы и ваши конкуренты: тот же замер по чужим сайтам, чтобы число стало относительным.
+ *
+ * Простым языком. «88 из 100» само по себе ничего не говорит: много это или мало, видно только
+ * рядом с теми, у кого покупатель выбирает. Поэтому конкуренты читаются ТЕМ ЖЕ кодом.
+ *
+ * Конкуренты читаются по десять страниц, а свой сайт по сто: доли в проверках считаются от
+ * разного, и об этом сказано в отчёте прямо. Балл видимости у всех читается по десяти страницам
+ * одинаково, вот его сравнивать можно, и он стоит в таблице первым.
+ *
+ * Пятеро это потолок: шестой столбец в лист A4 уже не помещается, а таблица, которая не
+ * помещается, это таблица, которую не читают.
+ */
+export const RIVALS_MAX = 5;
+
+export async function compareRivals(rivals, { pages = 10, lang = 'en', pageDelayMs = 400, log = () => {} } = {}) {
+  const hosts = [...new Set((rivals || []).map((x) => String(x || '').trim()).filter(Boolean))].slice(0, RIVALS_MAX);
+  const out = [];
+  for (const raw of hosts) {
+    const url = /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+    log(`конкурент ${raw}`);
+    try {
+      const a = await collect(url, { pages, lang, rendered: false, pageDelayMs, log: () => {} });
+      out.push({
+        host: a.meta.host,
+        reachable: a.meta.reachable !== false,
+        score: a.overall?.score ?? null,
+        grade: a.overall?.grade ?? null,
+        areas: (a.overall?.areas || []).map((x) => ({ id: x.id, label: x.label, score: x.score, max: x.max })),
+        seo: a.overall?.seo?.score ?? null,
+        reportScores: a.scores || {},
+        pagesRead: a.reading?.read ?? null,
+        status: a.meta.homeStatus ?? null,
+      });
+    } catch (e) {
+      // Сайт не ответил, значит в таблице стоит прочерк и причина, а не выдуманный ноль.
+      out.push({ host: raw, reachable: false, score: null, grade: null, areas: [], seo: null, reportScores: {}, pagesRead: 0, error: e.message });
+    }
+  }
+  return out;
+}
+
+/*
+ * Вежливое чтение чужого сайта.
+ *
+ * Страницы читаются по одной, но без паузы это примерно семь запросов в секунду, и защита сайта
+ * видит в этом не аудит, а обход. Мы на этом уже горели: собственный Vercel начинал отдавать 403
+ * на наши же прогоны. На двадцати страницах это сходило с рук, на ста не сойдёт.
+ *
+ * Поэтому три вещи. Пауза между страницами опускает темп до двух запросов в секунду. Crawl-delay
+ * из robots.txt слушается, если сайт его назвал: это его правило, и оно старше нашего удобства.
+ * И отказ не игнорируется: на 429 или 403 пауза удваивается, а после трёх отказов подряд чтение
+ * останавливается, и в отчёт идёт «прочитано столько из стольких», а не тишина.
+ */
+const sleep = (ms) => (ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve());
+
+/** Crawl-delay из robots.txt в миллисекундах, с потолком: 30 секунд на страницу это не аудит. */
+export function crawlDelayFrom(robotsText, capMs = 3000) {
+  const found = [...String(robotsText || '').matchAll(/^crawl-delay:\s*([\d.]+)/gim)]
+    .map((m) => Number(m[1]))
+    .filter((n) => Number.isFinite(n) && n > 0);
+  if (!found.length) return { ms: 0, asked: 0, capped: false };
+  const asked = Math.max(...found) * 1000;
+  return { ms: Math.min(asked, capMs), asked, capped: asked > capMs };
+}
+
 async function follow(url, max = 5) {
   const hops = [];
   let cur = url;
@@ -141,6 +207,7 @@ function analysePage(url, html) {
     telephone: /"telephone"\s*:/.test(ld) || telLinks > 0,
     email: /"email"\s*:/.test(ld) || mailLinks > 0,
     sameAs: [...new Set(sameAs.map((u) => { try { return new URL(u).host.replace(/^www\./, ''); } catch { return ''; } }).filter(Boolean))],
+    sameAsUrls: [...new Set(sameAs)],
     aboutPage: hrefsLower.some((h) => /\/(about|about-us|our-story|team|company|o-nas)\/?($|[?#])/.test(h)),
     policyPages: [...new Set(hrefsLower.filter((h) => /\/(privacy|privacy-policy|terms|terms-of-use|legal|cookie|cookies|disclaimer)/.test(h)).map((h) => (h.match(/\/(privacy|terms|legal|cookie|disclaimer)/) || [])[1]).filter(Boolean))],
     author: /"author"\s*:/.test(ld),
@@ -220,7 +287,7 @@ async function readSitemap(startUrl, { maxFiles = 6, budgetMs = 45000, maxUrls =
 
 export const __readSitemap = readSitemap;
 
-export async function collect(startUrl, { pages = 20, log = () => {}, backlinks = null, lang = 'en', rendered = false, renderedPages = 3, preparedBy = '', visibility: givenVisibility = null, requestTimeout = 15000, sitemapBudgetMs = 45000, sitemapMaxFiles = 6 } = {}) {
+export async function collect(startUrl, { pages = 20, pageDelayMs = 400, log = () => {}, backlinks = null, lang = 'en', rendered = false, renderedPages = 3, preparedBy = '', visibility: givenVisibility = null, requestTimeout = 15000, sitemapBudgetMs = 45000, sitemapMaxFiles = 6, tier = '' } = {}) {
   REQUEST_TIMEOUT = requestTimeout;
   const opts = { backlinks };
   const origin = new URL(startUrl).origin;
@@ -411,13 +478,30 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
   const TRUST_PAGE = /\/(contact|contacts|contact-us|kontakt|kontakty|about|about-us|o-nas|team|company|privacy|privacy-policy|politika[a-z-]*|terms|terms-of-use|usloviya|oferta|legal|impressum)\/?$/i;
   const trustFirst = rest.filter((u) => { try { return TRUST_PAGE.test(new URL(u).pathname); } catch { return false; } });
   const pool = [home.final, ...trustFirst, ...rest.filter((u) => !trustFirst.includes(u))];
+  const wanted = pool.slice(0, pages);
+  const politeness = crawlDelayFrom(robots.ok ? robots.text : '');
+  let gap = Math.max(pageDelayMs, politeness.ms);
   const sample = [];
-  for (const u of pool.slice(0, pages)) {
+  let refusedInARow = 0;
+  let stoppedAt = null;
+  for (let i = 0; i < wanted.length; i += 1) {
+    const u = wanted[i];
+    if (i > 0) await sleep(gap);
     const r = await get(u);
+    // 429 и 403 это «притормози», а не «страницы нет». Удваиваем паузу и считаем отказы подряд:
+    // три подряд означают, что сайт нас закрыл, и дальше мы только злим его защиту.
+    if (r.status === 429 || r.status === 403) {
+      refusedInARow += 1;
+      gap = Math.min(gap * 2 || 1000, 8000);
+      if (refusedInARow >= 3) { stoppedAt = i; break; }
+    } else if (r.ok) {
+      refusedInARow = 0;
+    }
     if (r.ok && /html/i.test(r.type)) sample.push(analysePage(u, r.text));
     else if (r.status >= 300 && r.status < 400) sample.push({ url: u, redirect: r.location, status: r.status });
     else sample.push({ url: u, status: r.status, error: r.error });
   }
+  const reading = { wanted: wanted.length, read: sample.filter((x) => x.title !== undefined).length, stoppedAt, gapMs: gap, crawlDelay: politeness };
   const good = sample.filter((p) => p.title !== undefined);
   const hp = homePage || good[0];
 
@@ -561,6 +645,16 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
   checks.push(row('trust-contact', 'offpage', 'Direct contact details', channels.length >= 2 ? 'ok' : channels.length ? 'warn' : 'bad', channels.length ? channels.join(' and ') : 'no phone, email or messenger is published'));
   const ownHost = host.replace(/^www\./, '');
   const profiles = [...new Set(pagesForTrust.flatMap((p) => p.trust?.sameAs || []))].filter((h) => h !== ownHost && !h.endsWith(`.${ownHost}`));
+  /*
+   * Для готовой разметки нужен адрес профиля, а не домен: «https://x.com» это не страница компании,
+   * а сам сайт. И список сужается до площадок, где профиль вообще бывает: сайт нередко перечисляет
+   * в своём sameAs партнёров и застройщиков, а вставить их в свою разметку значит сказать
+   * поисковику, что это одна и та же организация. Поэтому берём только профили и только с путём.
+   */
+  const PROFILE_HOST = /^(instagram\.com|facebook\.com|fb\.com|x\.com|twitter\.com|linkedin\.com|youtube\.com|threads\.net|tiktok\.com|t\.me|telegram\.me|vk\.com|ok\.ru|dzen\.ru|pinterest\.[a-z.]+|wikidata\.org|crunchbase\.com|yelp\.com|trustpilot\.com|github\.com|behance\.net|maps\.google\.[a-z.]+|g\.page)$/i;
+  const profileUrls = [...new Set(pagesForTrust.flatMap((p) => p.trust?.sameAsUrls || []))].filter((u) => {
+    try { const x = new URL(u); return PROFILE_HOST.test(x.host.replace(/^www\./, '')) && x.pathname.replace(/\/+$/, '').length > 1; } catch { return false; }
+  });
   checks.push(row('trust-profiles', 'offpage', 'Profiles the site claims elsewhere', profiles.length >= 2 ? 'ok' : profiles.length ? 'warn' : 'bad', profiles.length ? `${profiles.length}: ${profiles.slice(0, 5).join(', ')}` : 'no sameAs links: the site claims no profile anywhere else', profiles.length ? '' : 'the cheapest off-site signal there is, and it is free'));
   const about = anyTrust((p) => p.trust?.aboutPage);
   checks.push(row('trust-about', 'offpage', 'A page that says who is behind the site', about ? 'ok' : 'warn', about ? 'linked from the sampled pages' : 'no about or team page is linked'));
@@ -656,7 +750,7 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
   const critical = checks.filter((c) => c.status === 'bad').map((c) => ({ title: c.label, text: `${c.value}${c.comment ? `. ${c.comment}` : ''}`, level: 'bad' }));
 
   return {
-    meta: { site: home.final, host, reachable: homeAnswered, collectedAt: new Date().toISOString(), tool: `@operstack/audit ${VERSION}`, auditType: lang === 'ru' ? 'Аудит по публичным сигналам' : 'External audit (no Search Console or analytics access)', lang, language: hp ? (hp.og?.locale || '') : '' },
+    meta: { site: home.final, host, reachable: homeAnswered, homeStatus: home.response.status || 0, collectedAt: new Date().toISOString(), tool: `@operstack/audit ${VERSION}`, tier, auditType: lang === 'ru' ? 'Аудит по публичным сигналам' : 'External audit (no Search Console or analytics access)', lang, language: hp ? (hp.og?.locale || '') : '' },
     client: { name: '{{CLIENT NAME}}', subject: '{{What the site sells and where}}', reportDate: new Date().toISOString().slice(0, 10), preparedBy: preparedBy || process.env.OPERSTACK_PREPARED_BY || 'OperStack' },
     overall,
     reportScore,
@@ -684,7 +778,10 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
     closing: '{{Key message for the client in three sentences.}}',
     // В выборке остаётся и то, из чего считается работа с текстами: без этих полей пакет
     // Foundation пришлось бы оценивать на глаз, как раньше оценивался Fix.
-    sample: sample.map((p) => p.title !== undefined ? { url: p.url, title: p.title, words: p.words, h1Count: p.h1Count, linkCount: Array.isArray(p.links) ? p.links.length : null, images: p.images, imagesNoAlt: p.imagesNoAlt, schemaTypes: p.schemaTypes, answerFirst: p.answerFirst, sourcePhrases: p.sourcePhrases, citedParagraphs: p.citedParagraphs, figureParagraphs: p.figureParagraphs, h2Count: p.h2Count, tables: p.tables, firstParaWords: p.firstParaWords, dates: p.dates } : p),
+    reading,
+    /* Сырьё для готовых файлов: профили, которые сайт сам про себя заявляет, и есть ли контакты. */
+    entity: { profiles: profileUrls, hosts: profiles, telephone: Boolean(hp?.trust?.telephone), email: Boolean(hp?.trust?.email) },
+    sample: sample.map((p) => p.title !== undefined ? { url: p.url, title: p.title, description: p.description, h1: p.h1, firstPara: p.firstPara, words: p.words, h1Count: p.h1Count, linkCount: Array.isArray(p.links) ? p.links.length : null, images: p.images, imagesNoAlt: p.imagesNoAlt, schemaTypes: p.schemaTypes, answerFirst: p.answerFirst, sourcePhrases: p.sourcePhrases, citedParagraphs: p.citedParagraphs, figureParagraphs: p.figureParagraphs, h2Count: p.h2Count, tables: p.tables, firstParaWords: p.firstParaWords, dates: p.dates } : p),
     notes,
   };
 }

package/src/handover.mjs

@@ -0,0 +1,234 @@
+/**
+ * Готовые файлы, а не советы.
+ *
+ * Простым языком. Аудит находит, что нет карты для агентов, что разметка неполная, что заголовок
+ * обрезается в выдаче. Написать «сделайте llms.txt» легко, и это ровно то, за что покупатель
+ * платить не должен. Здесь из уже прочитанных данных собираются файлы, которые человек кладёт к
+ * себе: карта для агентов, разметка организации и починенные заголовки.
+ *
+ * Главное правило: **ничего не выдумывать про чужой бизнес**. Всё, что здесь появляется, взято
+ * с его же страниц. Чего в данных нет, то остаётся помеченным пропуском с подписью, что туда
+ * вписать, а не догадкой. Придуманный ИНН или придуманный год основания в разметке это ложь,
+ * которую потом прочитают и поисковик, и ИИ.
+ */
+
+const trim = (s, n) => {
+  const t = String(s || '').replace(/\s+/g, ' ').trim();
+  if (t.length <= n) return t;
+  const cut = t.slice(0, n);
+  const space = cut.lastIndexOf(' ');
+  return `${(space > n * 0.6 ? cut.slice(0, space) : cut).replace(/[\s.,;:·|–—-]+$/, '')}…`;
+};
+
+/**
+ * Описание, которое обрывается на многоточии, выглядит как недоделка, а не как готовое поле.
+ * Поэтому режем по концу предложения, если оно есть во второй половине лимита, иначе по слову,
+ * и никакого хвоста с точками.
+ */
+const sentenceTrim = (s, n) => {
+  const t = String(s || '').replace(/\s+/g, ' ').trim();
+  if (t.length <= n) return t;
+  // Набираем целые предложения, пока влезают. Так поле кончается точкой, а не на полуслове.
+  let out = '';
+  for (const part of t.split(/(?<=[.!?])\s+/)) {
+    const next = out ? `${out} ${part}` : part;
+    if (next.length > n) break;
+    out = next;
+  }
+  if (out) return out;
+  const cut = t.slice(0, n);
+  const space = cut.lastIndexOf(' ');
+  return `${(space > n * 0.6 ? cut.slice(0, space) : cut).replace(/[\s,;:–—-]+$/, '')}…`;
+};
+
+/** Служебные страницы заголовком клики не зарабатывают, и чинить их длину незачем. */
+const SERVICE_PATH = /\/(privacy|privacy-policy|terms|terms-of-use|legal|cookie|cookies|disclaimer|sitemap|404|thank-you|thanks|spasibo|politika|oferta|soglashenie)/i;
+
+const pathOf = (u) => { try { return new URL(u).pathname; } catch { return String(u || ''); } };
+
+/** Первый сегмент адреса: по нему страницы группируются в разделы карты. */
+const sectionOf = (u) => {
+  const p = pathOf(u).replace(/^\/+|\/+$/g, '');
+  if (!p) return '';
+  return p.split('/')[0];
+};
+
+/**
+ * Как называется компания.
+ *
+ * Заголовок главной почти всегда собран из двух частей, но бренд стоит то в конце («Станки · ШопРу»),
+ * то в начале («MORE Group: агентство на Пхукете»). Отличает их длина: название это одно-три слова,
+ * а не фраза. Поэтому берём хвост, если он короткий, иначе начало, если короткое оно. Если коротким
+ * не оказалось ничего, названия мы не знаем: ставим домен и просим проверить, а не выдаём фразу со
+ * страницы за имя организации.
+ */
+const WORDS_IN_NAME = 3;
+function brandOf(audit) {
+  const host = audit?.meta?.host || '';
+  const pages = (audit?.sample || []).filter((p) => p.title !== undefined);
+  const raw = String(pages[0]?.title || '').replace(/\s+/g, ' ').trim();
+  const parts = raw.split(/\s*[·|—–:]\s*|\s+-\s+/).map((x) => x.trim()).filter(Boolean);
+  if (parts.length > 1) {
+    const words = (x) => x.split(/\s+/).length;
+    const last = parts[parts.length - 1];
+    const first = parts[0];
+    if (words(last) <= WORDS_IN_NAME) return { name: trim(last, 60), sure: true };
+    if (words(first) <= WORDS_IN_NAME) return { name: trim(first, 60), sure: true };
+  }
+  return { name: host, sure: false };
+}
+
+const WORDS = {
+  en: {
+    other: 'Other pages',
+    home: 'Start here',
+    placeholder: (what) => `TODO: ${what}`,
+    titlePattern: 'Assembled from the page H1 and the site name so it fits the limit.',
+    descPattern: 'Assembled from the first paragraph of the page so it fits the limit.',
+    noDesc: 'the page has no meta description at all',
+    tooLong: (n) => `${n} characters: cut in results`,
+    tooShort: (n) => `${n} characters: the words that earn the click are missing`,
+  },
+  ru: {
+    other: 'Другие страницы',
+    home: 'Начните отсюда',
+    placeholder: (what) => `ВПИСАТЬ: ${what}`,
+    titlePattern: 'Собран из H1 страницы и названия сайта так, чтобы уложиться в лимит.',
+    descPattern: 'Собрано из первого абзаца страницы так, чтобы уложиться в лимит.',
+    noDesc: 'описания у страницы нет вовсе',
+    tooLong: (n) => `${n} знаков: в выдаче обрежется`,
+    tooShort: (n) => `${n} знаков: не хватает слов, ради которых кликают`,
+  },
+};
+
+/**
+ * Карта для агентов. Формат llms.txt: заголовок с названием сайта, абзац о нём, затем разделы
+ * списками ссылок с однострочным пояснением у каждой.
+ *
+ * Пояснение берётся из описания страницы, а если его нет, из её первого абзаца. Выдумывать
+ * пояснение нечем и незачем: пустая строка честнее придуманной.
+ */
+export function buildLlmsTxt(audit, { lang = 'en', maxLinks = 60 } = {}) {
+  const w = WORDS[lang === 'ru' ? 'ru' : 'en'];
+  const host = audit?.meta?.host || '';
+  const pages = (audit?.sample || []).filter((p) => p.title !== undefined && p.url);
+  const home = pages[0] || {};
+  const name = brandOf(audit).name || host;
+  const about = sentenceTrim(home.description || home.firstPara || '', 200);
+
+  const bySection = new Map();
+  for (const p of pages.slice(0, maxLinks)) {
+    const key = sectionOf(p.url);
+    if (!bySection.has(key)) bySection.set(key, []);
+    bySection.get(key).push(p);
+  }
+
+  const lines = [`# ${name}`, ''];
+  lines.push(about ? `> ${about}` : `> ${w.placeholder(lang === 'ru' ? 'одно предложение о том, чем занимается сайт' : 'one sentence on what this site is')}`);
+  lines.push('');
+
+  const sections = [...bySection.entries()].sort((a, b) => (a[0] === '' ? -1 : b[0] === '' ? 1 : a[0].localeCompare(b[0])));
+  for (const [key, list] of sections) {
+    lines.push(`## ${key === '' ? w.home : key}`);
+    lines.push('');
+    for (const p of list) {
+      const note = sentenceTrim(p.description || p.firstPara || '', 140);
+      lines.push(`- [${trim(p.title, 95)}](${p.url})${note ? `: ${note}` : ''}`);
+    }
+    lines.push('');
+  }
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+/**
+ * Разметка организации из того, что сайт уже сам про себя говорит.
+ *
+ * Возвращает и сам блок, и список того, чего в данных не нашлось: телефон, почта, адрес. Эти поля
+ * в блок не попадают, а уезжают отдельным списком «впишите сами». Так покупатель видит, что
+ * пропуск это пропуск, а не наша забывчивость.
+ */
+export function buildOrganisationSchema(audit, { lang = 'en' } = {}) {
+  const host = audit?.meta?.host || '';
+  const site = audit?.meta?.site || (host ? `https://${host}/` : '');
+  const pages = (audit?.sample || []).filter((p) => p.title !== undefined);
+  const home = pages[0] || {};
+  const brand = brandOf(audit);
+  const name = brand.name || host;
+  const description = sentenceTrim(home.description || home.firstPara || '', 200);
+  const profiles = (audit?.entity?.profiles || []).map((h) => (/^https?:\/\//i.test(h) ? h : `https://${h}`));
+
+  const json = { '@context': 'https://schema.org', '@type': 'Organization', name, url: site };
+  if (description) json.description = description;
+  if (profiles.length) json.sameAs = profiles;
+
+  const missing = [];
+  const need = lang === 'ru'
+    ? { telephone: 'телефон', email: 'почта', address: 'адрес', logo: 'адрес картинки с логотипом' }
+    : { telephone: 'a telephone', email: 'an email', address: 'a postal address', logo: 'the URL of your logo image' };
+  if (!profiles.length) missing.push({ field: 'sameAs', what: lang === 'ru' ? 'адреса ваших профилей: инстаграм, ютуб, линкедин, карточка на картах' : 'the URLs of your own profiles: Instagram, YouTube, LinkedIn, your maps listing' });
+  if (!audit?.entity?.telephone) missing.push({ field: 'telephone', what: need.telephone });
+  if (!audit?.entity?.email) missing.push({ field: 'email', what: need.email });
+  missing.push({ field: 'address', what: need.address });
+  missing.push({ field: 'logo', what: need.logo });
+  if (!description) missing.push({ field: 'description', what: lang === 'ru' ? 'одно предложение о компании' : 'one sentence about the company' });
+  // Названия в заголовке главной не было, поэтому в разметке стоит домен: это надо проверить глазами.
+  if (!brand.sure) missing.push({ field: 'name', what: lang === 'ru' ? `проверьте название: в разметке стоит «${name}», взято из домена` : `check the name: the markup says “${name}”, taken from the domain` });
+
+  return { json, missing, text: JSON.stringify(json, null, 2) };
+}
+
+/**
+ * Починенные заголовки и описания.
+ *
+ * Это не копирайтинг, и называть его так нельзя. Настоящий заголовок требует знать, чем человек
+ * торгует и как это ищут, а мы этого не знаем. Что здесь делается: заголовок собирается из
+ * СОБСТВЕННОГО H1 страницы и названия сайта так, чтобы уложиться в лимит и не обрезаться в
+ * выдаче, описание из первого абзаца той же страницы. Рядом всегда написано, что там сейчас и
+ * почему это плохо, чтобы покупатель видел, что чинится длина и структура, а не смысл.
+ */
+export function fixTitlesAndDescriptions(audit, { lang = 'en', limit = 6 } = {}) {
+  const w = WORDS[lang === 'ru' ? 'ru' : 'en'];
+  const pages = (audit?.sample || []).filter((p) => p.title !== undefined && p.url);
+  const brand = trim(brandOf(audit).name, 24);
+
+  const broken = [];
+  for (const p of pages) {
+    if (SERVICE_PATH.test(pathOf(p.url))) continue;
+    const title = String(p.title || '');
+    const desc = String(p.description || '');
+    /*
+     * Пороги те же, что у проверок аудита: заголовок 40-60 знаков, описание 70-160. Свои числа
+     * здесь означали бы, что отчёт называет страницу нормальной, а список правок её же чинит.
+     */
+    const titleBad = !title.length ? (lang === 'ru' ? 'заголовка нет' : 'no title')
+      : title.length > 60 ? w.tooLong(title.length)
+      : title.length < 40 ? w.tooShort(title.length) : '';
+    const descBad = !desc.length ? w.noDesc : desc.length > 160 ? w.tooLong(desc.length) : desc.length < 70 ? w.tooShort(desc.length) : '';
+    if (!titleBad && !descBad) continue;
+
+    const item = { url: p.url, path: pathOf(p.url) };
+    if (titleBad) {
+      /*
+       * Заголовок собирается только из того, что на странице уже есть, и проверяется тем же
+       * порогом, что и в самом аудите: 40-60 знаков. Три попытки по очереди. H1 плюс бренд.
+       * Нынешний заголовок без бренда, если он просто длинный. H1 сам по себе. Что не уложилось
+       * целиком, то не предлагается: заголовок с многоточием в выдаче это не починка.
+       */
+      const h1 = String(p.h1 || '').replace(/\s+/g, ' ').trim();
+      const withoutBrand = brand ? title.split(/\s*[·|—–]\s*/).filter((x) => x.trim() && x.trim() !== brand).join(' · ').trim() : '';
+      const fits = (x) => x && !x.includes('\u2026') && x.length >= 40 && x.length <= 60;
+      const suggestion = [h1 && brand ? `${h1} · ${brand}` : '', withoutBrand, h1].find(fits) || '';
+      if (suggestion && suggestion !== title) item.title = { now: title, problem: titleBad, suggestion, how: w.titlePattern };
+    }
+    if (descBad) {
+      const source = p.firstPara || desc;
+      const suggestion = source ? sentenceTrim(source, 155) : '';
+      const better = suggestion.length >= 70 && suggestion.length <= 160 && suggestion !== desc;
+      if (better) item.description = { now: desc, problem: descBad, suggestion, how: w.descPattern };
+    }
+    if (!item.title && !item.description) continue;
+    broken.push(item);
+    if (broken.length >= limit) break;
+  }
+  return broken;
+}

package/src/index.mjs

@@ -8,3 +8,4 @@ export { buildFoundationScope, renderFoundationScope, renderFoundationChecklist
 export { draftNarrative, stillEmpty } from './narrative.mjs';
 export { agentPrompt, agentPrompts, renderAgentPrompts, firstFixParts, FIRST_FIX_IDS } from './prompts.mjs';
 export { buildDemandMap, expandQueries, coverage, seedsFromPages, volumesViaTopvisor, topvisorClient, renderDemandHtml, renderDemandMarkdown, demandSourceRow, demandCsv, demandTotals, REGIONS as DEMAND_REGIONS, DEMAND_DEFAULTS } from './demand.mjs';
+export { buildLlmsTxt, buildOrganisationSchema, fixTitlesAndDescriptions } from './handover.mjs';

package/src/narrative.mjs

@@ -113,8 +113,9 @@ function plural(n, one, few, many) {
   const d = n % 10; const dd = n % 100;
   return d === 1 && dd !== 11 ? one : d >= 2 && d <= 4 && (dd < 10 || dd >= 20) ? few : many;
 }
-const listRu = (a) => a.length > 1 ? `${a.slice(0, -1).join(', ')} и ${a[a.length - 1]}` : a[0] || '';
-const listEn = (a) => a.length > 1 ? `${a.slice(0, -1).join(', ')} and ${a[a.length - 1]}` : a[0] || '';
+const sep = (a) => (a.some((x) => String(x).includes(',')) ? '; ' : ', ');
+const listRu = (a) => (a.length < 2 ? a[0] || '' : sep(a) === '; ' ? a.join('; ') : `${a.slice(0, -1).join(', ')} и ${a[a.length - 1]}`);
+const listEn = (a) => (a.length < 2 ? a[0] || '' : sep(a) === '; ' ? a.join('; ') : `${a.slice(0, -1).join(', ')} and ${a[a.length - 1]}`);
 
 /** Проверки, которые Fix закрывает технически: ими меряется «сколько чинится быстро». */
 const MECHANICAL = new Set(['robots', 'robots-block', 'ai-search-access', 'sitemap', 'sitemap-foreign', 'sitemap-health', 'llms', 'title', 'description', 'h1', 'canonical', 'viewport', 'og', 'schema', 'faq-schema', 'org-schema', 'hreflang', 'xmlrpc', 'alt', 'h1-sample', 'dup-titles', 'utility', 'dates', 'trust-entity', 'trust-contact', 'trust-profiles', 'trust-about', 'trust-policies', 'conv-contact-path', 'conv-cta', 'conv-messenger', 'www', 'resources', 'conv-form-depth', 'conv-form-fields']);
@@ -163,7 +164,7 @@ export function draftNarrative(audit, opts = {}) {
   const weakest = areaName(scores.slice().sort((x, y) => x[1] - y[1])[0]?.[0] || '');
 
   // Кто клиент. Имя это адрес сайта, предмет прочитан с главной и помечен как прочитанный.
-  const desc = String(home.description || '').trim().slice(0, 180);
+  const desc = String(home.description || '').trim().slice(0, 180).replace(/[\s.]+$/, '');
   a.client.name = a.client.name?.includes('{{') ? host : a.client.name;
   if (String(a.client.subject).includes('{{')) a.client.subject = desc ? t.subjectFrom(desc) : t.subjectNone;
 

package/src/prospect.mjs

@@ -85,9 +85,24 @@ export const OWNER_LINES = {
     en: 'On a phone your page cannot be pinched to zoom: the code forbids it.',
     ru: 'С телефона страницу нельзя увеличить пальцами, масштабирование запрещено в коде.',
   },
+  /*
+   * Фраза от числа (задание Максима 26.09.2026): «Not one page…» стояло и при «5 of 8», то есть
+   * письмо говорило неправду про сайт, где половина страниц в порядке. Число берётся из самой
+   * проверки («5 of 8 sampled page(s) open…»).
+   */
   'answer-first': {
-    en: 'Not one page opens with a short direct answer, and that opening is exactly what gets quoted.',
-    ru: 'Ни на одной странице нет короткого прямого ответа в первом абзаце, а цитируют именно его.',
+    en: (c) => {
+      const [have, of] = countOf(c);
+      return have > 0 && of > have
+        ? `Only ${have} of your ${of} checked pages open with a short direct answer, and that opening is exactly what gets quoted.`
+        : 'Not one page opens with a short direct answer, and that opening is exactly what gets quoted.';
+    },
+    ru: (c) => {
+      const [have, of] = countOf(c);
+      return have > 0 && of > have
+        ? `Короткий прямой ответ в первом абзаце есть только на ${have} из ${of} проверенных страниц, а цитируют именно его.`
+        : 'Ни на одной странице нет короткого прямого ответа в первом абзаце, а цитируют именно его.';
+    },
   },
   'tables': {
     en: 'Your pages have no tables, and a table is the easiest thing for an assistant to lift and quote.',
@@ -164,8 +179,17 @@ const LEAD_ORDER = [
   'conv-form-fields', 'conv-contact-path', 'agent-markdown', 'h1', 'dates', 'utility',
 ];
 
+/** «5 of 8 sampled page(s)…» в находке: сколько страниц в порядке и сколько проверено. */
+function countOf(check) {
+  const m = String(check?.value || '').match(/(\d+)\s+(?:of|из)\s+(\d+)/);
+  return m ? [Number(m[1]), Number(m[2])] : [0, 0];
+}
+
 /** Фраза владельцу на нужном языке. Нет перевода, значит нет фразы, и печатается сама находка. */
-const line = (id, lang = 'en') => (OWNER_LINES[id] || {})[lang === 'ru' ? 'ru' : 'en'] || '';
+const line = (id, lang = 'en', check = null) => {
+  const say = (OWNER_LINES[id] || {})[lang === 'ru' ? 'ru' : 'en'];
+  return (typeof say === 'function' ? say(check) : say) || '';
+};
 
 /** Вес области при подсчёте одной общей оценки. Считаем только то, что правда измерено. */
 const WEIGHT = {
@@ -207,15 +231,15 @@ export function worstFindings(audit, limit = 3, lang = 'en') {
       const s = (SEVERITY[a.status] ?? 2) - (SEVERITY[b.status] ?? 2);
       if (s) return s;
       // При равной тяжести вперёд идёт то, для чего есть фраза владельцу: она и попадёт в письмо.
-      return (line(b.id, lang) ? 1 : 0) - (line(a.id, lang) ? 1 : 0);
+      return (line(b.id, lang, b) ? 1 : 0) - (line(a.id, lang, a) ? 1 : 0);
     });
   return open.slice(0, limit).map((c) => ({
     id: c.id,
     status: c.status,
     label: c.label,
     value: c.value,
-    say: line(c.id, lang) || `${c.label}: ${c.value}`,
-    translated: Boolean(line(c.id, lang)),
+    say: line(c.id, lang, c) || `${c.label}: ${c.value}`,
+    translated: Boolean(line(c.id, lang, c)),
   }));
 }
 

package/src/render.mjs

@@ -12,6 +12,7 @@ import { localiseBasisNote, AREAS_RU } from './i18n.mjs';
 import { MESSAGES as VISIBILITY_MESSAGES } from './visibility.mjs';
 import { softenHex } from './agency.mjs';
 import { renderDemandHtml, demandSourceRow } from './demand.mjs';
+import { buildLlmsTxt, buildOrganisationSchema, fixTitlesAndDescriptions } from './handover.mjs';
 
 const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 const isPlaceholder = (s) => typeof s === 'string' && /\{\{[^}]*\}\}/.test(s);
@@ -48,6 +49,12 @@ const LABELS = {
     secondMeasure: 'A second, separate measurement: how this report scores its own checks',
     ofHundred: 'of 100', ofHundredShort: 'OF 100', aiVisibility: 'AI visibility', seoBasics: 'SEO basics',
     enginesHead: 'Readiness by engine', madeOf: 'What the score is made of', worth: 'worth', blockedIn: 'Blocked', colTables: 'Tables', colLinks: 'Links',
+    secHandover: 'Files to paste', handoverEyebrow: 'Ready to paste', handoverTitle: 'What to paste', handoverLead: 'Not advice: files. Everything below was assembled from your own pages, so nothing here was invented about your business.', llmsHead: 'llms.txt, the map for AI agents', llmsNote: 'Save this as llms.txt in the root of your site. An answer engine reads it instead of crawling every page.', andMoreInFile: '… the full file is attached to the email', orgHead: 'Organization markup', orgNote: 'Paste this into a script tag of type application/ld+json in the head of your homepage. Every value here was read from your site.', orgMissingHead: 'Fill in yourself', orgMissingNote: 'These fields are not on your site, so we did not invent them. Add them and the markup gets stronger.', metaHead: 'Titles and descriptions', metaMore: (n) => `${n} more page${n === 1 ? '' : 's'} need the same treatment; all of them are in the titles file attached to the email.`, metaNote: 'Length and structure only, not new wording: the suggestion is assembled from the page\u2019s own H1 and first paragraph so it fits the limit. Grey is what is there now, then why it is a problem, then what to put.',
+    secRivals: 'Rivals', rivalsEyebrow: 'Rivals', rivalsTitle: 'You and your rivals', pagesReadLabel: 'Pages it let us read', rivalsThin: 'An asterisk marks a score taken from fewer than three pages: it is what the site let us see, not everything it has.', rivalsWithheld: (list) => `${list.join(', ')} answered, but not on every page we asked for, so there is no score: a score that goes up because we read less is not one we will print.`, rivalsRefused: (list) => `Turned a robot away: ${list.join(', ')}. Bot protection answers the same way to an answer engine, so a site that refuses us is also a site an AI cannot read.`,
+    rivalsLead: 'The same code read your rivals, asking each for up to ten pages. The row under the score says how many pages each one actually handed over.',
+    rivalsFoot: 'A dash means the site did not answer at all, and that is a fact about the site, not a zero we invented.',
+    appendixEyebrow: 'Appendix', appendixPages: 'Every page we read', fullListInAppendix: 'The first pages are shown here; every page we read is listed in the appendix at the end.',
+    readNote: (read, wanted) => (read === wanted ? `All ${wanted} pages answered and were read.` : `${read} of ${wanted} pages answered and were read; the rest did not answer or the site stopped us.`),
     secOverview: 'Site overview', overviewEyebrow: '02 · Overview', whatSiteIs: 'What the site is', parameter: 'Parameter', value: 'Value', pagesSampled: 'Pages sampled', colUrl: 'URL', colTitle: 'Title', colWords: 'Words',
     secCritical: 'Critical issues', criticalEyebrow: '03 · P0', criticalTitle: 'Critical issues, fix first', whatItCosts: 'What it costs', theFix: 'Fix', noBody: 'This issue has no description in the audit file.', noCritical: 'No critical defects were found in the public signals.',
     secTechnical: 'Technical SEO', technicalEyebrow: '04 · Technical', technicalTitle: 'Technical and on-page checklist', colCheck: 'Check', colStatus: 'Status', colFinding: 'Finding',
@@ -90,6 +97,12 @@ const LABELS = {
     secondMeasure: 'Второе, отдельное измерение: как этот отчёт оценивает собственные проверки',
     ofHundred: 'из 100', ofHundredShort: 'ИЗ 100', aiVisibility: 'ИИ-видимость', seoBasics: 'Основы SEO',
     enginesHead: 'Готовность по движкам', madeOf: 'Из чего сложился балл', worth: 'вес', blockedIn: 'Закрыты', colTables: 'Таблиц', colLinks: 'Ссылок',
+    secHandover: 'Что вставить', handoverEyebrow: 'Готово к вставке', handoverTitle: 'Что вставить', handoverLead: 'Не советы, а файлы. Всё ниже собрано с ваших же страниц, поэтому ничего про ваш бизнес здесь не выдумано.', llmsHead: 'llms.txt, карта для агентов ИИ', llmsNote: 'Сохраните это файлом llms.txt в корне сайта. Ответная система читает его вместо того, чтобы обходить все страницы.', andMoreInFile: '… файл целиком приложен к письму', orgHead: 'Разметка организации', orgNote: 'Вставьте это в тег script с типом application/ld+json в head главной страницы. Каждое значение здесь прочитано с вашего сайта.', orgMissingHead: 'Впишите сами', orgMissingNote: 'Этих полей на сайте нет, и мы их не выдумывали. Впишите, и разметка станет сильнее.', metaHead: 'Заголовки и описания', metaMore: (n) => `Ещё ${n} странице${n === 1 ? '' : 'й'} нужна такая же правка, все они есть в файле с заголовками, приложенном к письму.`, metaNote: 'Чинится длина и структура, а не смысл: предложенный вариант собран из собственного H1 страницы и её первого абзаца так, чтобы уложиться в лимит. Серым то, что стоит сейчас, ниже чем это плохо, ниже что поставить.',
+    secRivals: 'Конкуренты', rivalsEyebrow: 'Конкуренты', rivalsTitle: 'Вы и ваши конкуренты', pagesReadLabel: 'Сколько страниц дал прочитать', rivalsThin: 'Звёздочкой помечен балл, посчитанный меньше чем по трём страницам: это то, что сайт дал посмотреть, а не всё, что у него есть.', rivalsWithheld: (list) => `${list.join(', ')} ответил, но не на все запрошенные страницы, поэтому балла нет: балл, который растёт оттого, что мы прочитали меньше, мы не печатаем.`, rivalsRefused: (list) => `Развернули робота: ${list.join(', ')}. Защита от ботов так же отвечает и ответной системе, поэтому сайт, который не пустил нас, не пустит и ИИ.`,
+    rivalsLead: 'Конкурентов читал тот же код и просил у каждого до десяти страниц. Строка под баллом говорит, сколько страниц каждый сайт отдал на самом деле.',
+    rivalsFoot: 'Прочерк значит, что сайт не ответил вовсе, и это факт про сайт, а не выдуманный нами ноль.',
+    appendixEyebrow: 'Приложение', appendixPages: 'Все прочитанные страницы', fullListInAppendix: 'Здесь первые строки, весь список прочитанных страниц лежит приложением в конце отчёта.',
+    readNote: (read, wanted) => (read === wanted ? `Ответили и прочитаны все ${wanted} страниц.` : `Из ${wanted} страниц ответили и прочитаны ${read}; остальные не ответили или сайт нас остановил.`),
     secOverview: 'О сайте', overviewEyebrow: '02 · Обзор', whatSiteIs: 'Что это за сайт', parameter: 'Параметр', value: 'Значение', pagesSampled: 'Проверенные страницы', colUrl: 'Адрес', colTitle: 'Заголовок', colWords: 'Слов',
     secCritical: 'Критичное', criticalEyebrow: '03 · Срочно', criticalTitle: 'Что чинить первым', whatItCosts: 'Чем это грозит', theFix: 'Как чинится', noBody: 'У этой проблемы нет описания в файле аудита.', noCritical: 'Критичных дефектов в публичных сигналах не найдено.',
     secTechnical: 'Техническое SEO', technicalEyebrow: '04 · Техника', technicalTitle: 'Техническая проверка и страницы', colCheck: 'Проверка', colStatus: 'Статус', colFinding: 'Что нашли',
@@ -195,6 +208,29 @@ function css() {
   .mast-meta { display: grid; grid-template-columns: repeat(4, auto); gap: 0 9mm; justify-content: start; border-top: 1px solid var(--rule); padding-top: 2.5mm; }
   .mast-meta dt { font-size: 6.8pt; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); margin: 0 0 .6mm; }
   .mast-meta dd { font-size: 8.5pt; font-weight: 600; margin: 0; }
+
+  /* Таблица конкурентов: свой сайт выделен, лучшее в строке подсвечено. */
+  table.rivals-table { table-layout: fixed; font-size: 8.8pt; }
+  table.rivals-table th, table.rivals-table td { padding-left: 1.4mm; padding-right: 1.4mm; }
+  table.rivals-table th:first-child, table.rivals-table td:first-child { width: 23%; }
+  table.rivals-table th.n, table.rivals-table td.n { text-align: center; font-variant-numeric: tabular-nums; }
+  table.rivals-table th.n { font-size: 6.8pt; letter-spacing: 0; text-transform: none; overflow-wrap: normal; word-break: normal; }
+  table.rivals-table th.mine { color: var(--accent); }
+  table.rivals-table td.beat { color: var(--ok); font-weight: 600; }
+  table.rivals-table td .na { color: var(--muted); }
+  table.rivals-table tr.lead-row td { font-family: "Fraunces", Georgia, serif; font-size: 13pt; }
+  table.rivals-table tr.foot-row td { color: var(--muted); font-size: 8pt; }
+  table.rivals-table td span { font-size: 8pt; color: var(--muted); }
+
+  /* Раздел «что вставить»: код мелко и моноширинно, чтобы копировался без потерь. */
+  .handover-page .hand-note { font-size: 8.5pt; color: var(--muted); line-height: 1.45; margin: 0 0 3mm; }
+  pre.code { font-family: "JetBrains Mono", ui-monospace, monospace; font-size: 7.5pt; line-height: 1.5; background: #fafbfb; border: 1px solid var(--rule); border-radius: 4px; padding: 3mm 4mm; white-space: pre-wrap; word-break: break-word; margin: 0 0 4mm; }
+  ul.hand-missing { margin: 0; padding-left: 5mm; font-size: 9pt; }
+  ul.hand-missing code { font-family: "JetBrains Mono", ui-monospace, monospace; font-size: 8pt; color: var(--accent); }
+  table.meta-fixes td { vertical-align: top; font-size: 8.5pt; }
+  table.meta-fixes .was { color: var(--muted); }
+  table.meta-fixes .why { color: var(--warn); font-size: 7.5pt; }
+  table.meta-fixes .now { color: var(--ink); font-weight: 600; }
   .tool-line { font-size: 7.5pt; color: var(--muted); line-height: 1.4; margin: 4mm 0 0; }
   .cover-meta { display: grid; grid-template-columns: 1fr 1fr; gap: 6mm; margin-top: 14mm; padding-top: 6mm; border-top: 1px solid var(--rule); }
   .cover-meta dt { font-size: 7.5pt; text-transform: uppercase; letter-spacing: .08em; color: var(--muted); margin-bottom: 1mm; }
@@ -227,7 +263,7 @@ function css() {
   .overall-grade { font-family: "Fraunces", Georgia, serif; font-size: 14pt; font-weight: 600; margin: 0 0 1.5mm; }
   .overall-note { font-size: 8.5pt; color: var(--muted); line-height: 1.45; margin: 0; }
 
-  h3.engines-head, h3.areas-head { font-size: 11pt; margin: 4.5mm 0 2.2mm; }
+  h3.engines-head, h3.areas-head { font-size: 11pt; margin: 4mm 0 2mm; }
   .engines { display: grid; grid-template-columns: repeat(5, 1fr); gap: 2.2mm; }
   .eng { border: 1px solid var(--rule); border-radius: 4px; padding: 2.4mm 2.6mm; background: #fafbfb; }
   .eng p { margin: 0; }
@@ -244,7 +280,7 @@ function css() {
   .eng-na .pbar i, .ar-na .pbar i { background: var(--muted); }
 
   .areas-bars { margin-bottom: 2mm; }
-  .ar { padding: 2mm 0; border-top: 1px solid var(--rule); }
+  .ar { padding: 1.6mm 0; border-top: 1px solid var(--rule); }
   .ar:first-child { border-top: 0; padding-top: 0.5mm; }
   .ar-h { display: grid; grid-template-columns: 1fr auto auto; gap: 3mm; align-items: baseline; margin-bottom: 1.4mm; }
   .ar-n { font-size: 9pt; font-weight: 600; }
@@ -273,6 +309,11 @@ function css() {
   .kpi { flex: 1; background: var(--panel); border-radius: 4px; padding: 3mm 4mm; }
   .kpi-value { font-family: "Fraunces", "Iowan Old Style", Georgia, serif; font-size: 17pt; font-weight: 600; color: var(--ink); line-height: 1.1; }
   .kpi-label { font-size: 8.5pt; color: var(--muted); margin-top: 1mm; }
+  table.pages.appendix { table-layout: fixed; }
+  table.pages.appendix td, table.pages.appendix th { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  table.pages.appendix td:nth-child(1), table.pages.appendix th:nth-child(1) { width: 33%; }
+  table.pages.appendix td:nth-child(2), table.pages.appendix th:nth-child(2) { width: 35%; }
+  table.pages.appendix td:nth-child(n+3), table.pages.appendix th:nth-child(n+3) { width: 8%; text-align: right; font-variant-numeric: tabular-nums; }
   td.num, th.num { text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; } .status-na { color: var(--muted); }
   .cards { display: grid; gap: 3mm; margin: 4mm 0; }
   .card { border-left: 3px solid var(--danger); background: #fbf1f0; padding: 3.5mm 4mm; border-radius: 0 4px 4px 0; }
@@ -377,7 +418,13 @@ export function toHtml(audit, brand = null) {
    * следующую страницу, и мы вернёмся к тому, от чего уходили.
    */
   const subjectText = t(a.client.subject);
-  const subjectShort = subjectText.length > 190 ? `${subjectText.slice(0, 187).trimEnd()}\u2026` : subjectText;
+  /* Обрыв на полуслове в первой строке отчёта за 149 выглядит как недоделка, поэтому режем по точке. */
+  const subjectShort = (() => {
+    if (subjectText.length <= 190) return subjectText;
+    const cut = subjectText.slice(0, 190);
+    const stop = cut.lastIndexOf('. ');
+    return stop > 60 ? cut.slice(0, stop + 1) : `${cut.slice(0, 187).trimEnd()}\u2026`;
+  })();
   const masthead = `<div class="masthead">${logo}<p class="mast-eyebrow">${L.eyebrowAudit}</p><h1 class="mast-title">${L.coverTitle.replace(/<br>/g, ' ')}</h1><p class="mast-sub">${subjectShort}</p><dl class="mast-meta"><div><dt>${L.auditSubject}</dt><dd>${t(a.client.name)}</dd></div><div><dt>${L.reportDate}</dt><dd>${esc(a.client.reportDate)}</dd></div><div><dt>${L.auditType}</dt><dd>${esc(a.meta.auditType)}</dd></div><div><dt>${L.preparedBy}</dt><dd>${esc(preparedBy)}</dd></div></dl></div>`;
   /*
    * Сводка занимает ДВА листа намеренно, а не один с переливом.
@@ -394,14 +441,36 @@ export function toHtml(audit, brand = null) {
    * строк, как техническую. Первый лист несёт параметры сайта и первые строки, дальше только
    * продолжение таблицы со своей шапкой.
    */
-  const sampleRows = (a.sample || []).filter((x) => x.title !== undefined).slice(0, 20);
+  /*
+   * Список прочитанных страниц. На двадцати строках это два листа, на ста это семь листов
+   * подряд одной таблицей посреди разбора. Поэтому в основной части печатаются первые строки,
+   * а весь список уезжает приложением в конец: покупатель за сто страниц имеет право видеть все
+   * сто адресов, но не вместо чтения.
+   */
+  const readStat = a.reading && typeof a.reading.read === 'number' ? a.reading : null;
+  const readNote = readStat && L.readNote ? `<p class="scorecard-foot">${esc(L.readNote(readStat.read, readStat.wanted))}</p>` : '';
+  const allSampleRows = (a.sample || []).filter((x) => x.title !== undefined);
+  const APPENDIX_FROM = 20;
+  /*
+   * В приложении заголовок обрезается: длинный переносится на вторую строку, и лист, рассчитанный
+   * по числу строк, переливается. Замерено: на восьмидесяти страницах так переливали три листа.
+   * Это справочник прочитанного, ключ в нём адрес, а не заголовок.
+   */
+  const appendixRow = (x) => {
+    const title = String(x.title || '');
+    const short = title.length > 52 ? `${title.slice(0, 50).trimEnd()}\u2026` : title;
+    return `<tr><td><code>${esc(new URL(x.url).pathname)}</code></td><td>${esc(short)}</td><td>${x.words}</td><td>${x.h2Count ?? '\u00b7'}</td><td>${x.tables ?? '\u00b7'}</td><td>${x.linkCount ?? '\u00b7'}</td><td>${x.images ? `${x.images - x.imagesNoAlt}/${x.images}` : '\u00b7'}</td></tr>`;
+  };
+
+  const asAppendix = allSampleRows.length > APPENDIX_FROM;
+  const sampleRows = asAppendix ? allSampleRows.slice(0, 7) : allSampleRows;
   const pagesHead = `<tr><th>${L.colUrl}</th><th>${L.colTitle}</th><th>${L.colWords}</th><th>H2</th><th>${L.colTables || 'Tables'}</th><th>${L.colLinks || 'Links'}</th><th>Alt</th></tr>`;
   const pageRow = (x) => `<tr><td><code>${esc(new URL(x.url).pathname)}</code></td><td>${esc(x.title)}</td><td>${x.words}</td><td>${x.h2Count ?? '\u00b7'}</td><td>${x.tables ?? '\u00b7'}</td><td>${x.linkCount ?? '\u00b7'}</td><td>${x.images ? `${x.images - x.imagesNoAlt}/${x.images}` : '\u00b7'}</td></tr>`;
   const FIRST_PAGE_ROWS = 7;
   const NEXT_PAGE_ROWS = 16;
   const firstRows = sampleRows.slice(0, FIRST_PAGE_ROWS);
   const restRows = sampleRows.slice(FIRST_PAGE_ROWS);
-  pages.push(`<div class="page">${header(a, L.secOverview, L)}<div class="eyebrow">${L.overviewEyebrow}</div><h2>${L.whatSiteIs}</h2><table><tr><th>${L.parameter}</th><th>${L.value}</th></tr>${(a.overview.rows || []).map(([k, v]) => `<tr><td>${t(k)}</td><td>${t(v)}</td></tr>`).join('')}</table><p>${t(a.overview.note)}</p><h3>${L.pagesSampled}</h3><table class="pages">${pagesHead}${firstRows.map(pageRow).join('')}</table>${footer(a, n++, preparedBy)}</div>`);
+  pages.push(`<div class="page">${header(a, L.secOverview, L)}<div class="eyebrow">${L.overviewEyebrow}</div><h2>${L.whatSiteIs}</h2><table><tr><th>${L.parameter}</th><th>${L.value}</th></tr>${(a.overview.rows || []).map(([k, v]) => `<tr><td>${t(k)}</td><td>${t(v)}</td></tr>`).join('')}</table><p>${t(a.overview.note)}</p><h3>${L.pagesSampled}</h3>${readNote}<table class="pages">${pagesHead}${firstRows.map(pageRow).join('')}</table>${asAppendix ? `<p class="scorecard-foot">${esc(L.fullListInAppendix || '')}</p>` : ''}${footer(a, n++, preparedBy)}</div>`);
   for (let i = 0; i < restRows.length; i += NEXT_PAGE_ROWS) {
     const chunk = restRows.slice(i, i + NEXT_PAGE_ROWS);
     pages.push(`<div class="page">${header(a, L.secOverview, L)}<div class="eyebrow">${L.overviewEyebrow}</div><h2>${L.pagesSampled}</h2><table class="pages">${pagesHead}${chunk.map(pageRow).join('')}</table>${footer(a, n++, preparedBy)}</div>`);
@@ -471,6 +540,95 @@ export function toHtml(audit, brand = null) {
   pages.push(`<div class="page">${header(a, L.secOffpage, L)}<div class="eyebrow">${L.offpageEyebrow}</div><h2>${L.offpageTitle}</h2>${checkTable('offpage')}${list(a.offpage.listed)}<p>${t(a.offpage.note)}</p>${footer(a, n++, preparedBy)}</div>`);
   pages.push(`<div class="page">${header(a, L.secOffpage, L)}<div class="eyebrow">${L.conversionEyebrow}</div><h2>${L.conversionTitle}</h2>${checkTable('conversion')}<table><tr><th>${L.colElement}</th><th>${L.colStatus}</th></tr>${(a.conversion.rows || []).map(([k, v]) => `<tr><td>${t(k)}</td><td>${t(v)}</td></tr>`).join('')}</table>${footer(a, n++, preparedBy)}</div>`);
 
+  /*
+   * Вы и ваши конкуренты. Балл видимости стоит первым, потому что он у всех посчитан по десяти
+   * страницам и сравним напрямую. Шесть оценок аудита идут ниже с подписью, что свой сайт читался
+   * глубже: без этой подписи «2 из 100» рядом с «1 из 10» читается как сравнение, которым не
+   * является. Сайт, который не ответил, получает прочерк, а не выдуманный ноль.
+   */
+  const rivals = Array.isArray(a.rivals) ? a.rivals.slice(0, 5) : [];
+  if (rivals.length) {
+    const mine = { host: a.meta.host, score: a.overall?.score ?? null, grade: a.overall?.grade ?? null, areas: a.overall?.areas || [], seo: a.overall?.seo?.score ?? null, reportScores: a.scores || {}, pagesRead: a.reading?.read ?? null };
+    const all = [mine, ...rivals];
+    const cell = (v, max) => (v === null || v === undefined ? `<span class="na">\u00b7</span>` : max ? `${v}<span>/${max}</span>` : String(v));
+    const best = (vals) => { const nums = vals.filter((x) => typeof x === 'number'); return nums.length ? Math.max(...nums) : null; };
+    const hostLabel = (h) => esc(String(h || '')).replace(/\.(?=[^.]+$)/, '<wbr>.');
+    const headRow = `<tr><th>${esc(L.colSignal || 'Signal')}</th>${all.map((x, i) => `<th class="n${i === 0 ? ' mine' : ''}">${hostLabel(x.host)}</th>`).join('')}</tr>`;
+    const scoreVals = all.map((x) => x.score);
+    const topScore = best(scoreVals);
+    /*
+     * Крупный сайт часто пускает робота только на главную. Балл, посчитанный по одной странице,
+     * это не то же самое, что балл по десяти, поэтому такой столбец помечается звёздочкой, а
+     * строка «сколько страниц дал прочитать» стоит сразу под баллом, где её видно вместе с ним.
+     */
+    const THIN = 3;
+    const thin = (x) => typeof x.pagesRead === 'number' && x.pagesRead > 0 && x.pagesRead < THIN;
+    const anyThin = rivals.some(thin);
+    const refused = rivals.filter((x) => x.reachable === false);
+    const withheld = rivals.filter((x) => x.reachable !== false && x.score === null);
+    const rows = [
+      `<tr class="lead-row"><td>${esc(L.aiVisibility || 'AI visibility')}</td>${all.map((x) => `<td class="n${x.score !== null && x.score === topScore ? ' beat' : ''}">${cell(x.score, 100)}${thin(x) ? '*' : ''}</td>`).join('')}</tr>`,
+      `<tr class="foot-row"><td>${esc(L.pagesReadLabel || 'Pages read')}</td>${all.map((x) => `<td class="n">${x.pagesRead ?? '\u00b7'}</td>`).join('')}</tr>`,
+      `<tr><td>${esc(L.seoBasics || 'SEO basics')}</td>${all.map((x) => `<td class="n">${cell(x.seo, 100)}</td>`).join('')}</tr>`,
+      ...(mine.areas || []).map((area, k) => {
+        const vals = all.map((x) => (x.areas && x.areas[k] ? x.areas[k].score : null));
+        const top = best(vals);
+        return `<tr><td>${esc(area.label)}</td>${vals.map((v) => `<td class="n${v !== null && v === top ? ' beat' : ''}">${cell(v, area.max)}</td>`).join('')}</tr>`;
+      }),
+    ].join('');
+    pages.push(`<div class="page">${header(a, L.secRivals || 'Rivals', L)}<div class="eyebrow">${esc(L.rivalsEyebrow || 'Rivals')}</div><h2>${esc(L.rivalsTitle || 'You and your rivals')}</h2><p class="lead">${esc(L.rivalsLead || '')}</p><table class="rivals-table">${headRow}${rows}</table><p class="scorecard-foot">${refused.length ? esc(L.rivalsFoot || '') : ''}${anyThin ? `${refused.length ? ' ' : ''}${esc(L.rivalsThin || '')}` : ''}${refused.length ? ` ${esc(L.rivalsRefused ? L.rivalsRefused(refused.map((x) => `${x.host}${x.status ? ` (${x.status})` : ''}`)) : '')}` : ''}${withheld.length ? ` ${esc(L.rivalsWithheld ? L.rivalsWithheld(withheld.map((x) => x.host)) : '')}` : ''}</p>${footer(a, n++, preparedBy)}</div>`);
+  }
+
+  /*
+   * «Что вставить»: готовые файлы прямо в отчёте. Покупатель за 149 получает не список
+   * пожеланий, а карту для агентов, разметку организации и починенные заголовки, которые можно
+   * скопировать отсюда или взять файлами из письма.
+   *
+   * Пропуски в разметке названы отдельно и намеренно: поле, которого нет в данных, мы не
+   * придумываем, а говорим, что туда вписать.
+   */
+  /*
+   * Готовые файлы входят только в аудит за 149. На ступенях дешевле они не печатаются: иначе
+   * то, чем дорогой товар отличается от дешёвого, уезжает в дешёвый бесплатно.
+   */
+  if (a.meta?.tier === 'audit') {
+    const hl = a.meta?.lang === 'ru' ? 'ru' : 'en';
+    const llms = buildLlmsTxt(a, { lang: hl });
+    const org = buildOrganisationSchema(a, { lang: hl });
+    const allFixes = fixTitlesAndDescriptions(a, { lang: hl, limit: 40 });
+    const metaFixes = allFixes.slice(0, 6);
+    const llmsShort = llms.split('\n').slice(0, 16).join('\n');
+    const cut = llms.split('\n').length > 16;
+    pages.push(`<div class="page handover-page">${header(a, L.secHandover || 'Files', L)}<div class="eyebrow">${esc(L.handoverEyebrow || 'Files')}</div><h2>${esc(L.handoverTitle || 'What to paste')}</h2><p class="lead">${esc(L.handoverLead || '')}</p>
+      <h3>${esc(L.llmsHead || 'llms.txt')}</h3><p class="hand-note">${esc(L.llmsNote || '')}</p><pre class="code">${esc(llmsShort)}${cut ? `\n${esc(L.andMoreInFile || '')}` : ''}</pre>
+      ${footer(a, n++, preparedBy)}</div>`);
+    pages.push(`<div class="page handover-page">${header(a, L.secHandover || 'Files', L)}<div class="eyebrow">${esc(L.handoverEyebrow || 'Files')}</div><h2>${esc(L.orgHead || 'Organization markup')}</h2><p class="hand-note">${esc(L.orgNote || '')}</p><pre class="code">${esc(org.text)}</pre>
+      ${org.missing.length ? `<h3>${esc(L.orgMissingHead || 'Fill in yourself')}</h3><p class="hand-note">${esc(L.orgMissingNote || '')}</p><ul class="hand-missing">${org.missing.map((m) => `<li><code>${esc(m.field)}</code> ${esc(m.what)}</li>`).join('')}</ul>` : ''}
+      ${footer(a, n++, preparedBy)}</div>`);
+    if (metaFixes.length) {
+      /*
+       * Три строки на лист, а не шесть. Замерено на отрисованном листе: самая высокая строка
+       * это 250 пикселей (два блока по четыре строки, каждая длинная часть в две строки), от
+       * листа под таблицу остаётся около 790. Длина того, что стоит сейчас, ограничена здесь же,
+       * иначе одна страница с описанием в триста знаков ломает расчёт.
+       */
+      const METAFIX_ROWS = 3;
+      const short = (x) => { const t = String(x || ''); return t.length > 150 ? `${t.slice(0, 148).trimEnd()}\u2026` : t; };
+      const rowOf = (f) => `<tr><td><code>${esc(f.path)}</code></td><td>${[
+        f.title ? `<b>title</b><br><span class="was">${esc(short(f.title.now) || '—')}</span><br><span class="why">${esc(f.title.problem)}</span><br><span class="now">${esc(f.title.suggestion)}</span>` : '',
+        f.description ? `<b>description</b><br><span class="was">${esc(short(f.description.now) || '—')}</span><br><span class="why">${esc(f.description.problem)}</span><br><span class="now">${esc(f.description.suggestion)}</span>` : '',
+      ].filter(Boolean).join('<br><br>')}</td></tr>`;
+      const parts = Math.ceil(metaFixes.length / METAFIX_ROWS);
+      for (let i = 0; i < metaFixes.length; i += METAFIX_ROWS) {
+        const chunk = metaFixes.slice(i, i + METAFIX_ROWS);
+        const part = Math.floor(i / METAFIX_ROWS) + 1;
+        const title = parts > 1 ? `${L.metaHead || 'Titles and descriptions'} (${part}/${parts})` : (L.metaHead || 'Titles and descriptions');
+        const last = part === parts;
+        pages.push(`<div class="page handover-page">${header(a, L.secHandover || 'Files', L)}<div class="eyebrow">${esc(L.handoverEyebrow || 'Files')}</div><h2>${esc(title)}</h2><p class="hand-note">${esc(L.metaNote || '')}</p><table class="meta-fixes"><tr><th>${esc(L.colUrl)}</th><th>${esc(L.colFinding)}</th></tr>${chunk.map(rowOf).join('')}</table>${last && allFixes.length > metaFixes.length ? `<p class="scorecard-foot">${esc(L.metaMore ? L.metaMore(allFixes.length - metaFixes.length) : '')}</p>` : ''}${footer(a, n++, preparedBy)}</div>`);
+      }
+    }
+  }
+
   const phases = (a.roadmap || []).map((x) => `<div class="phase"><div class="phase-head"><span class="badge">${esc(x.badge)}</span><span class="phase-title">${t(x.title)}</span></div>${olist(x.items)}</div>`).join('');
   /*
    * Последний лист несёт и дорожную карту, и источники с границами замера. Оба раздела короткие,
@@ -480,6 +638,23 @@ export function toHtml(audit, brand = null) {
   pages.push(`<div class="page">${header(a, L.secRoadmap, L)}<div class="eyebrow">${L.roadmapEyebrow}</div><h2>${L.roadmapTitle}</h2>${phases}<div class="verdict"><p><strong>${L.keyMessage}</strong> ${t(a.closing)}</p></div><div class="eyebrow" style="margin-top:7mm">${L.limitationsEyebrow}</div><h2>${L.sourcesTitle}</h2>${sources.length ? `<table><tr><th>${L.colSource}</th><th>${L.colAccess}</th><th>${L.colWhatRead}</th></tr>${sources.map((x) => `<tr><td>${t(x.name)}</td><td>${t(x.access)}</td><td>${t(x.detail)}</td></tr>`).join('')}</table><p class="scorecard-foot">${L.sourcesFoot}</p>` : ''}<h3>${L.limitations}</h3>${list(a.limitations)}<p class="tool-line">${esc(brand && brand.showToolLine === false ? L.reproducible : L.collectedBy(a.meta.tool, (a.meta.collectedAt || '').slice(0, 10)))}</p>${footer(a, n++, preparedBy)}</div>`);
   // Карта спроса идёт приложением после дорожной карты: она не входит в баллы, и об этом
   // сказано в ней самой и в таблице источников выше.
+  /* Приложение со всеми прочитанными страницами: только когда их больше двадцати. */
+  if (asAppendix) {
+    /*
+     * Четырнадцать строк, а не на глаз. Замерено на отрисованном листе: строка таблицы это
+     * 54 пикселя, от верха листа до таблицы уходит 189, снизу отступ и подвал ещё 106.
+     * Остаётся около 790 пикселей, это четырнадцать строк вместе с шапкой таблицы.
+     */
+    const APPENDIX_ROWS = 14;
+    for (let i = 0; i < allSampleRows.length; i += APPENDIX_ROWS) {
+      const chunk = allSampleRows.slice(i, i + APPENDIX_ROWS);
+      const part = Math.floor(i / APPENDIX_ROWS) + 1;
+      const parts = Math.ceil(allSampleRows.length / APPENDIX_ROWS);
+      const title = parts > 1 ? `${L.appendixPages || L.pagesSampled} (${part}/${parts})` : (L.appendixPages || L.pagesSampled);
+      pages.push(`<div class="page">${header(a, L.secOverview, L)}<div class="eyebrow">${esc(L.appendixEyebrow || 'Appendix')}</div><h2>${esc(title)}</h2><table class="pages appendix">${pagesHead}${chunk.map(appendixRow).join('')}</table>${footer(a, n++, preparedBy)}</div>`);
+    }
+  }
+
   if (a.demand && Array.isArray(a.demand.queries)) {
     pages.push(`<div class="page">${header(a, L.secDemand, L)}<div class="eyebrow">${L.demandEyebrow}</div><h2>${L.demandTitle}</h2>${renderDemandHtml(a.demand, { lang: a.meta?.lang === 'ru' ? 'ru' : 'en' })}${footer(a, n++, preparedBy)}</div>`);
   }

package/src/test-handover.mjs

@@ -0,0 +1,148 @@
+/**
+ * Готовые файлы: проверяем не «собралось ли», а что ничего не выдумано.
+ *
+ * Главный сторож здесь последний: поле, которого нет в данных, обязано остаться пропуском со
+ * словами «впишите», а не догадкой. Придуманный адрес в разметке это ложь, которую потом
+ * прочитают и поисковик, и ИИ.
+ */
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { buildLlmsTxt, buildOrganisationSchema, fixTitlesAndDescriptions } from './handover.mjs';
+
+const ok = (name, cond) => { assert.ok(cond, name); console.log('ok  ', name); };
+
+const audit = {
+  meta: { host: 'shop.ru', site: 'https://shop.ru/', lang: 'ru' },
+  entity: { profiles: ['vk.com/shop', 't.me/shop'], telephone: true, email: false },
+  sample: [
+    { url: 'https://shop.ru/', title: 'Станки для деревообработки с гарантией и сервисом · ШопРу', description: 'Продаём и обслуживаем станки для деревообработки по всей России: сто двадцать моделей в наличии, доставка за три дня.', h1: 'Станки для дерева', firstPara: 'Мы продаём станки с 2011 года.', words: 900 },
+    { url: 'https://shop.ru/catalog/', title: 'Каталог', description: '', h1: 'Каталог станков', firstPara: 'Сто двадцать моделей в наличии на складе в Москве, доставка по России за три дня.', words: 700 },
+    { url: 'https://shop.ru/catalog/cnc/', title: 'Станки с ЧПУ для серийного производства мебели на заказ · ШопРу', description: 'Коротко', h1: 'Станки с ЧПУ для серийного производства мебели', firstPara: 'Станки с числовым управлением для серийного производства мебели.', words: 800 },
+    { url: 'https://shop.ru/catalog/rare/', title: 'Очень длинный заголовок страницы, который точно не помещается в выдачу поисковика и будет обрезан', description: 'Сто двадцать моделей в наличии на складе в Москве, доставка по России за три дня и пусконаладка в цене.', h1: 'Станки', words: 800 },
+  ],
+};
+
+// Карта для агентов
+{
+  const txt = buildLlmsTxt(audit, { lang: 'ru' });
+  ok('карта начинается с названия компании, а не с фразы о странице', txt.startsWith('# ШопРу\n'));
+  ok('в карте есть абзац о сайте', /^> Продаём и обслуживаем/m.test(txt));
+  ok('страницы сгруппированы в разделы', /^## catalog$/m.test(txt) && /^## Начните отсюда$/m.test(txt));
+  ok('у ссылки есть пояснение', /- \[Каталог\]\(https:\/\/shop\.ru\/catalog\/\): Сто двадцать моделей/.test(txt));
+  ok('все страницы попали в карту', (txt.match(/^- \[/gm) || []).length === 4);
+  ok('файл кончается переводом строки', txt.endsWith('\n'));
+}
+
+// Разметка организации
+{
+  const { json, missing, text } = buildOrganisationSchema(audit, { lang: 'ru' });
+  assert.equal(json['@type'], 'Organization');
+  assert.equal(json.name, 'ШопРу');
+  assert.equal(json.url, 'https://shop.ru/');
+  ok('профили сайта попали в sameAs', json.sameAs.length === 2 && json.sameAs.every((u) => u.startsWith('https://')));
+  ok('разметка это валидный JSON', JSON.parse(text)['@type'] === 'Organization');
+  // Вот главное: чего нет в данных, того нет и в разметке.
+  ok('адреса в разметке нет, он в списке пропусков', !('address' in json) && missing.some((m) => m.field === 'address'));
+  ok('почты нет, она в списке пропусков', !('email' in json) && missing.some((m) => m.field === 'email'));
+  ok('телефон найден на сайте, значит в пропуски не попал', !missing.some((m) => m.field === 'telephone'));
+  ok('ни одно поле не выдумано', !JSON.stringify(json).includes('ВПИСАТЬ'));
+  ok('название взято из заголовка, значит проверять его не просим', !missing.some((m) => m.field === 'name'));
+}
+
+// Название компании стоит то в конце заголовка, то в начале: берём короткую часть
+{
+  const name = (title, host = 'x.ru') => buildOrganisationSchema({ meta: { host }, sample: [{ url: `https://${host}/`, title }] }).json.name;
+  ok('хвост из одного слова это бренд', name('Станки для деревообработки · ШопРу') === 'ШопРу');
+  ok('начало из двух слов тоже бренд', name('MORE Group: агентство недвижимости на Пхукете') === 'MORE Group');
+  ok('через двоеточие и точку разделяется тоже', name('Проверка сайта: ваш сайт глазами ИИ · OperStack') === 'OperStack');
+  ok('служебное слово в начале бренд не перебивает', name('Главная | Акме Корп Лтд') === 'Акме Корп Лтд');
+}
+
+// Названия компании в заголовке главной нет: домен подставлен, но помечен на проверку
+{
+  const noBrand = { meta: { host: 'shop.ru', site: 'https://shop.ru/' }, sample: [{ url: 'https://shop.ru/', title: 'Купить станки для деревообработки недорого', h1: 'Станки' }] };
+  const { json, missing } = buildOrganisationSchema(noBrand, { lang: 'ru' });
+  ok('фраза со страницы не выдана за название компании', json.name === 'shop.ru');
+  ok('и покупателя просят проверить название', missing.some((m) => m.field === 'name' && m.what.includes('shop.ru')));
+}
+
+// Заголовки и описания
+{
+  const fixes = fixTitlesAndDescriptions(audit, { lang: 'ru' });
+  const byPath = Object.fromEntries(fixes.map((f) => [f.path, f]));
+  ok('страница с длинным заголовком найдена', byPath['/catalog/cnc/'].title.problem.includes('обрежется'));
+  ok('предложенный заголовок укладывается в норму аудита', byPath['/catalog/cnc/'].title.suggestion.length >= 40 && byPath['/catalog/cnc/'].title.suggestion.length <= 60);
+  ok('заголовок собран из H1 страницы', byPath['/catalog/cnc/'].title.suggestion.startsWith('Станки с ЧПУ'));
+  ok('заголовок с многоточием не предлагается', !byPath['/catalog/cnc/'].title.suggestion.includes('\u2026'));
+  // Коротким H1 длинный заголовок не починить, и тогда правки нет, а не огрызок с многоточием.
+  ok('что нечем починить, то не предлагается', !byPath['/catalog/rare/']?.title);
+  ok('страница без описания найдена', byPath['/catalog/'].description.problem.includes('нет вовсе'));
+  ok('описание собрано из первого абзаца страницы', byPath['/catalog/'].description.suggestion.startsWith('Сто двадцать моделей'));
+  ok('рядом всегда сказано, что там сейчас', fixes.every((f) => (!f.title || 'now' in f.title) && (!f.description || 'now' in f.description)));
+  ok('главная в порядке и в список не попала', !byPath['/']);
+}
+
+// Пустой аудит ничего не ломает и ничего не выдумывает
+{
+  const empty = { meta: {}, sample: [] };
+  ok('карта пустого сайта не падает', typeof buildLlmsTxt(empty) === 'string');
+  ok('и честно просит вписать, чем занимается сайт', buildLlmsTxt(empty).includes('TODO'));
+  ok('разметка пустого сайта не падает', buildOrganisationSchema(empty).json['@type'] === 'Organization');
+  ok('правок у пустого сайта нет', fixTitlesAndDescriptions(empty).length === 0);
+}
+
+console.log('\nготовые файлы: всё сходится');
+
+/*
+ * Готовые файлы это то, за что платят 149. Сторож ниже следит, чтобы они не уехали в отчёт
+ * дешёвой ступени: там их печатать нельзя, иначе дорогой товар нечем отличать от дешёвого.
+ */
+{
+  const { toHtml } = await import('./render.mjs');
+  const base = JSON.parse(readFileSync(new URL('../examples/sample-audit.json', import.meta.url), 'utf8'));
+  const cheap = toHtml({ ...base, meta: { ...base.meta, tier: '29' } });
+  const paid = toHtml({ ...base, meta: { ...base.meta, tier: 'audit' } });
+  ok('в отчёте за 29 готовых файлов нет', (cheap.match(/class="page handover-page"/g) || []).length === 0);
+  ok('в аудите за 149 они есть', (paid.match(/class="page handover-page"/g) || []).length >= 2 && /&quot;\@type&quot;: &quot;Organization&quot;/.test(paid));
+}
+
+/*
+ * Сайт нередко перечисляет в своём sameAs партнёров, застройщиков и просто домены площадок.
+ * Вставить это в разметку значит сказать поисковику, что покупатель и Sansiri одна организация.
+ */
+{
+  const messy = {
+    meta: { host: 'shop.ru', site: 'https://shop.ru/' },
+    entity: { profiles: ['https://www.instagram.com/shopru/', 'https://t.me/shopru'], telephone: true, email: true },
+    sample: [{ url: 'https://shop.ru/', title: 'Станки · ШопРу', description: 'Продаём станки.' }],
+  };
+  const { json } = buildOrganisationSchema(messy, { lang: 'ru' });
+  ok('профили это адреса страниц, а не домены', json.sameAs.every((u) => new URL(u).pathname.length > 1));
+  const bare = { ...messy, entity: { ...messy.entity, profiles: [] } };
+  const r = buildOrganisationSchema(bare, { lang: 'ru' });
+  ok('профилей нет, значит поля sameAs нет', !('sameAs' in r.json));
+  ok('и о пропуске сказано прямо', r.missing.some((m) => m.field === 'sameAs'));
+}
+
+/*
+ * Правка обязана чинить. Заголовок, где поменялся только знак между словами, длину не чинит,
+ * а описание, оборванное на многоточии, это не готовое поле, а недоделка.
+ */
+{
+  const a = {
+    meta: { host: 'shop.ru', site: 'https://shop.ru/' },
+    sample: [
+      { url: 'https://shop.ru/', title: 'Станки для деревообработки с гарантией и сервисом · ШопРу', description: 'Продаём и обслуживаем станки для деревообработки по всей России: сто двадцать моделей в наличии, доставка за три дня.' },
+      { url: 'https://shop.ru/privacy-policy/', title: 'Политика | ШопРу', description: '', h1: 'Политика' },
+      { url: 'https://shop.ru/cnc/', title: 'ЧПУ | ШопРу', description: '', h1: 'ЧПУ' },
+      { url: 'https://shop.ru/dostavka/', title: 'Доставка станков по России за три дня со склада в Москве', description: 'Мы возим станки по всей России. Доставка за три дня со склада в Москве, подъём на этаж и пусконаладка входят в цену. Работаем с 2011 года и держим свой парк машин.', h1: 'Доставка', firstPara: 'Мы возим станки по всей России. Доставка за три дня со склада в Москве, подъём на этаж и пусконаладка входят в цену. Работаем с 2011 года и держим свой парк машин.' },
+    ],
+  };
+  const fixes = fixTitlesAndDescriptions(a, { lang: 'ru' });
+  const byPath = Object.fromEntries(fixes.map((f) => [f.path, f]));
+  ok('служебная страница в список не попала', !byPath['/privacy-policy/']);
+  ok('перестановка знака починкой не считается', !byPath['/cnc/']);
+  const d = byPath['/dostavka/'].description;
+  ok('описание обрезано по концу предложения', d.suggestion.endsWith('.') && !d.suggestion.includes('…'));
+  ok('и укладывается в лимит', d.suggestion.length >= 70 && d.suggestion.length <= 160);
+}

package/src/test-prospect-count.mjs

@@ -0,0 +1,12 @@
+// Фраза про короткий ответ зависит от числа страниц (задание 26.09.2026): «Not one page» только при нуле.
+import assert from 'node:assert/strict';
+import { prospectRow } from './prospect.mjs';
+const audit = (value, status) => ({ meta: { host: 'a.test' }, scores: {}, checks: [{ id: 'answer-first', status, label: 'Answer-first opening paragraph', value }] });
+const warn = prospectRow(audit('5 of 8 sampled page(s) open with 20 to 90 words carrying a figure, right after the H1', 'warn'));
+assert.equal(warn.say, 'Only 5 of your 8 checked pages open with a short direct answer, and that opening is exactly what gets quoted.');
+const bad = prospectRow(audit('0 of 8 sampled page(s) open with 20 to 90 words carrying a figure, right after the H1', 'bad'));
+assert.match(bad.say, /^Not one page opens/);
+const ru = prospectRow(audit('5 of 8 sampled page(s) open with 20 to 90 words carrying a figure, right after the H1', 'warn'), { lang: 'ru' });
+assert.equal(ru.say, 'Короткий прямой ответ в первом абзаце есть только на 5 из 8 проверенных страниц, а цитируют именно его.');
+assert.match(prospectRow(audit('', 'bad')).say, /^Not one page opens/, 'без числа прежняя фраза');
+console.log('test-prospect-count: ok');