@operstack/audit 0.7.2 → 0.9.0

package/README.md

@@ -46,6 +46,28 @@ 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).
 
+## 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.
+
+```
+npx @operstack/audit collect https://example.com --out audit.json
+npx @operstack/audit draft audit.json --lang en
+npx @operstack/audit render audit.json --pdf
+```
+
+Technically: `draft` fills the narrative fields (`summary`, `client.subject`, `overview.note`, `content`, `aeo`, `geo`, `offpage`, `conversion`, `roadmap`, `closing`) from the collected checks. Priorities and roadmap items are written as actions, taken from the same table the Fix checklist uses, so a finding and the work that closes it read the same. Fields an analyst has already written are left alone; anything still empty is listed at the end. For a Russian report over an English audit, check and area names are translated first.
+
+## Handing the work to an AI agent: `prompts`
+
+**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
+```
+
+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.
+
 ## The Fix package: turning findings into agreed work
 
 An audit says what is wrong. `fix-plan` says what we will do about it, before anyone pays.

package/bin/audit.mjs

@@ -14,6 +14,10 @@
  *       what was closed, what was not, and how much to refund
  *   operstack-audit foundation-scope audit.json [--lang ru|en] [--new-pages 3] [--gsc]
  *       the text work the Foundation package would do, page by page, with the price it adds up to
+ *   operstack-audit draft audit.json [--lang ru|en] [--out audit.json]
+ *       fills the narrative fields from the checks so the analyst edits instead of writing
+ *   operstack-audit prompts audit.json [--lang ru|en] [--limit 3] [--out prompts.md]
+ *       every finding rewritten as a task an AI agent can execute
  *   operstack-audit check audit.json
  *       lists narrative fields still holding placeholders and any score the checks do not support
  *
@@ -23,6 +27,8 @@
 import { collect, verifyScores } from '../src/collect.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';
+import { renderAgentPrompts, agentPrompts } from '../src/prompts.mjs';
 import { render, checkNarrative } from '../src/render.mjs';
 import { writeFileSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
@@ -38,6 +44,10 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
     '      collect the public signals of a site into audit.json',
     '  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]',
+    '      fill the narrative from the checks: the analyst edits a draft instead of writing one',
+    '  operstack-audit prompts <audit.json> [--lang ru|en] [--limit 3] [--out prompts.md]',
+    '      every finding rewritten as a task you can paste into Cursor or Claude Code',
     '  operstack-audit check <audit.json>',
     '      list narrative fields still holding placeholders and any score the checks do not support',
     '',
@@ -76,6 +86,26 @@ if (cmd === 'collect') {
   if (drift.length) { console.log(`${drift.length} score(s) that no check supports:`); for (const d of drift) console.log(`  ${d}`); }
   if (!missing.length && !drift.length) console.log('every narrative field is written and every score matches its checks');
   else process.exit(1);
+} else if (cmd === 'draft') {
+  const audit = JSON.parse(readFileSync(resolve(target), 'utf8'));
+  const before = stillEmpty(audit).length;
+  const drafted = draftNarrative(audit, { lang: opt('--lang', audit.meta?.lang || 'en') });
+  const after = stillEmpty(drafted);
+  const out = resolve(opt('--out', target));
+  writeFileSync(out, JSON.stringify(drafted, null, 2));
+  console.log(`${before} field(s) were empty, ${after.length} left`);
+  if (after.length) for (const f of after) console.log(`  still yours to write: ${f}`);
+  console.log(`wrote ${out}`);
+  console.log('read it before sending: the draft states only what was measured, and says so where nothing was.');
+} else if (cmd === 'prompts') {
+  const audit = JSON.parse(readFileSync(resolve(target), 'utf8'));
+  const lang = opt('--lang', audit.meta?.lang || 'en');
+  const limit = Number(opt('--limit', 0));
+  const list = agentPrompts(audit, { lang, limit });
+  const out = resolve(opt('--out', target.replace(/\.json$/, '') + '-prompts.md'));
+  writeFileSync(out, renderAgentPrompts(audit, { lang, limit }));
+  console.log(`${list.length} task(s): ${list.filter((x) => x.hasOwnText).length} written for that finding, ${list.filter((x) => !x.hasOwnText).length} generic`);
+  console.log(`wrote ${out}`);
 } else if (cmd === 'fix-plan') {
   const audit = JSON.parse(readFileSync(resolve(target), 'utf8'));
   // Язык покупки решает и валюту, и письмо: за доллары платят по английскому списку, за рубли по русскому.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operstack/audit",
-  "version": "0.7.2",
+  "version": "0.9.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",
@@ -13,7 +13,9 @@
     "./package.json": "./package.json",
     "./i18n": "./src/i18n.mjs",
     "./fix": "./src/fix.mjs",
-    "./foundation": "./src/foundation.mjs"
+    "./foundation": "./src/foundation.mjs",
+    "./narrative": "./src/narrative.mjs",
+    "./prompts": "./src/prompts.mjs"
   },
   "files": [
     "bin",
@@ -24,7 +26,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node src/test-scores.mjs && node src/test-fix.mjs && node src/test-foundation.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 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/fix.mjs

@@ -19,6 +19,7 @@
  * с английскими названиями проверок это брак, который клиент видит первым.
  */
 import { localiseChecks } from './i18n.mjs';
+import { agentPrompt } from './prompts.mjs';
 
 /** Что мы делаем по каждой проверке. Без этого «закроем» это слово, а не работа. */
 export const FIX_ACTIONS = {
@@ -220,14 +221,24 @@ export function renderFixPlan(plan) {
   return L.join('\n');
 }
 
-/** Чек-лист исполнителю: тот же список, но по порядку работы. */
-export function renderFixChecklist(plan) {
+/**
+ * Чек-лист исполнителю: тот же список, но по порядку работы.
+ * @param {object} plan результат buildFixPlan
+ * @param {{withPrompts?: boolean}} opts withPrompts добавляет задания для ИИ-агента: работа по ним
+ *   идёт быстрее, потому что исполнитель не переписывает задачу своими словами.
+ */
+export function renderFixChecklist(plan, opts = {}) {
   const t = dict(plan.lang);
   const L = [t.listTitle(plan.host), '', t.listHead(plan.platform, plan.price, plan.currency, plan.share), ''];
   plan.included.forEach((x, i) => {
     L.push(`- [ ] ${i + 1}. ${x.check.label} (\`${x.check.id}\`)`);
     L.push(`      ${t.was}: ${x.check.value}`);
     L.push(`      ${t.todo}: ${x.action}`);
+    if (opts.withPrompts) {
+      L.push('');
+      L.push(agentPrompt(x.check, { lang: plan.lang }).split('\n').map((line) => `      ${line}`).join('\n'));
+      L.push('');
+    }
   });
   L.push('');
   L.push(t.listTail);

package/src/i18n.mjs

@@ -17,6 +17,8 @@ const plural = (n, one, few, many) => {
   const d = Math.abs(n) % 10; const dd = Math.abs(n) % 100;
   return `${n} ${d === 1 && dd !== 11 ? one : d >= 2 && d <= 4 && (dd < 10 || dd >= 20) ? few : many}`;
 };
+/** Проценты по-русски склоняются: 31 процент, 32 процента, 35 процентов. */
+const pct = (n) => plural(Number(n), 'процент', 'процента', 'процентов');
 const pages = (n) => plural(Number(n), 'страница', 'страницы', 'страниц');
 const pagesOf = (a, b) => `${a} из ${pages(b)}`;
 
@@ -89,7 +91,7 @@ const RU = {
   hreflang: { label: 'hreflang', value: (v) => (/none/.test(v) ? 'нет, сайт одноязычный' : `${plural(Number(nums(v)[0]), 'альтернатива', 'альтернативы', 'альтернатив')}`) },
   cms: { label: 'Движок сайта', value: (v) => v },
   xmlrpc: { label: 'xmlrpc.php', value: (v) => `отвечает ${nums(v)[0]}`, comment: () => 'открытая точка для атак, пользы для поиска никакой' },
-  alt: { label: 'Подписи к картинкам', value: (v) => { const n = nums(v); return `${n[0]} из ${n[1]} картинок имеют подпись, это ${n[2]} процентов, на ${pages(n[3])} выборки`; } },
+  alt: { label: 'Подписи к картинкам', value: (v) => { const n = nums(v); return `${n[0]} из ${n[1]} картинок имеют подпись, это ${pct(n[2])}, на ${pages(n[3])} выборки`; } },
   'h1-sample': { label: 'Структура заголовков', value: (v) => (/one H1 per page/.test(v) ? 'по одному H1 на страницу' : `${nums(v)[0]} из ${pages(nums(v)[1])} имеют больше одного H1`) },
   'dup-titles': { label: 'Повторы заголовков', value: (v) => (/its own title/.test(v) ? 'у каждой проверенной страницы свой заголовок' : `${plural(Number(nums(v)[0]), 'заголовок повторяется', 'заголовка повторяются', 'заголовков повторяются')} на разных страницах`) },
   thin: { label: 'Тонкие страницы', value: (v) => (/median/.test(v) ? `медиана ${plural(Number(nums(v)[0]), 'слово', 'слова', 'слов')} на страницу` : `${nums(v)[0]} из ${pages(nums(v)[1])} короче 300 слов`) },
@@ -103,7 +105,7 @@ 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])} выборки показывают дату`) },
-  'links-profile': { label: 'Профиль внешних ссылок (необязательное дополнение)', value: (v) => { const n = nums(v); return `${plural(Number(n[0]), 'ссылающийся домен', 'ссылающихся домена', 'ссылающихся доменов')}, ${plural(Number(n[1]), 'ссылка', 'ссылки', 'ссылок')}, ${n[2]} процентов передают вес, показатель авторитета ${n[3]} из 100`; }, comment: (c) => `${c.split('.')[0]}. Платный инструмент, для этого отчёта не обязателен и ни в одну оценку не входит.` },
+  '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': {
     label: 'Прямые контакты',
@@ -115,7 +117,7 @@ const RU = {
   'trust-policies': { label: 'Политика и условия', value: (v) => (/neither/.test(v) ? 'ни политики конфиденциальности, ни условий на сайте нет' : `есть: ${v.replace(/privacy/g, 'политика').replace(/terms/g, 'условия').replace(/legal/g, 'правовая страница').replace(/cookie/g, 'куки').replace(/disclaimer/g, 'оговорка')}`) },
   'conv-contact-path': { label: 'Способ связаться', value: (v) => { const n = nums(v); return `${n[0]} из ${pages(n[1])} выборки дают форму, контактную ссылку или страницу контактов`; } },
   'conv-cta': { label: 'Призыв к действию в первом экране', value: (v) => { const n = nums(v); return `${n[0]} из ${pages(n[1])} выборки ставят его в первых ${n[2]} процентах страницы`; }, comment: (c) => (c ? 'читателю, которого убедили сверху, не должно приходиться искать' : '') },
-  'conv-form-depth': { label: 'На какой глубине лежит форма', value: (v) => (/no form/.test(v) ? 'на проверенных страницах формы нет' : /could not be measured/.test(v) ? 'положение формы измерить не удалось' : `медиана ${nums(v)[0]} процентов вниз по странице, измерено на ${pages(nums(v)[1])}`), comment: (c) => (c ? 'на длинной странице дотуда почти никто не доходит, особенно с телефона' : '') },
+  'conv-form-depth': { label: 'На какой глубине лежит форма', value: (v) => (/no form/.test(v) ? 'на проверенных страницах формы нет' : /could not be measured/.test(v) ? 'положение формы измерить не удалось' : `медиана ${pct(nums(v)[0])} вниз по странице, измерено на ${pages(nums(v)[1])}`), comment: (c) => (c ? 'на длинной странице дотуда почти никто не доходит, особенно с телефона' : '') },
   'conv-form-fields': { label: 'Сколько полей просит форма', value: (v) => `медиана ${plural(Number(nums(v)[0]), 'поле', 'поля', 'полей')} до отправки`, comment: (c) => (c ? 'каждое лишнее поле стоит ответов, а телефон дороже всех' : '') },
   'conv-messenger': { label: 'Ссылка на мессенджер', value: (v) => (/none/.test(v) ? 'на проверенных страницах нет' : `на ${nums(v)[0]} из ${pages(nums(v)[1])} выборки`), comment: (c) => (c ? 'для международной аудитории с телефона одна ссылка на мессенджер обычно ценнее формы' : '') },
 };

package/src/index.mjs

@@ -3,3 +3,5 @@ export { render, checkNarrative } from './render.mjs';
 export { localiseChecks, localiseBasisNote, untranslated, AREAS_RU } from './i18n.mjs';
 export { buildFixPlan, renderFixPlan, renderFixChecklist, buildFixReport, renderFixReport, FIX_ACTIONS } from './fix.mjs';
 export { buildFoundationScope, renderFoundationScope, renderFoundationChecklist } from './foundation.mjs';
+export { draftNarrative, stillEmpty } from './narrative.mjs';
+export { agentPrompt, agentPrompts, renderAgentPrompts } from './prompts.mjs';

package/src/narrative.mjs

@@ -0,0 +1,272 @@
+/**
+ * Черновик текста аудита, собранный из проверок.
+ *
+ * Раньше десятиcтраничный отчёт выходил из сборщика с тридцатью двумя дырами: резюме, приоритеты,
+ * разбор контента, вывод. Их писал человек, то есть каждая продажа стоила часа работы, и продать
+ * десять аудитов в неделю было физически нельзя. Здесь эти дыры закрываются словами, собранными
+ * из тех же цифр, что уже измерены. Аналитику остаётся править, а не писать с нуля.
+ *
+ * Два правила, которые тут важнее всего.
+ *
+ * Первое: ни одного факта о бизнесе клиента мы не выдумываем. Всё, что пишется, либо посчитано
+ * проверками, либо прочитано с самой страницы, и тогда помечено как прочитанное, чтобы аналитик
+ * подтвердил. Там, где знания нет, стоит честная строка «не измеряли», а не догадка.
+ *
+ * Второе: отчёт читает не сеошник. Его читает владелец, который платил агентству, результата не
+ * увидел и теперь разбирается сам. Поэтому каждая мысль сначала объясняется человеческими словами
+ * (что это значит для него и его денег), и только потом называется технически.
+ */
+
+const T = {
+  ru: {
+    subjectFrom: (d) => `По описанию на главной: ${d}. Подтвердите, что это верно.`,
+    subjectNone: 'На главной не сказано, чем занимается компания. Это и есть первая проблема: если это непонятно человеку, это непонятно и поисковику, и ИИ.',
+    unknownLang: 'не указан в коде страниц',
+    sells: (d) => d ? `${d} (взято из описания главной, подтвердите)` : 'из описания на главной не понять, подтвердите',
+    leadWhat: (h, n) => `${h} это сайт из ${n} ${plural(n, 'страницы', 'страниц', 'страниц')}, и он читается машинами: мы открыли его так же, как их открывают поисковик и ИИ.`,
+    leadGood: (areas) => areas.length ? `Хорошо сделано вот что: ${listRu(areas)}.` : 'Ни одна из шести областей пока не выглядит сильной стороной.',
+    leadBad: (area, n) => n ? `Держит сайт назад другое: ${n} ${plural(n, 'проверка провалена', 'проверки провалены', 'проверок провалено')}, тяжелее всего дела в области «${area}».` : `Проваленных проверок нет, но до потолка не хватает мелочей, тяжелее всего в области «${area}».`,
+    verdict: (openN, mech) => openN
+      ? `Главное: ${openN} ${plural(openN, 'вещь мешает', 'вещи мешают', 'вещей мешают')} сайту показываться и попадать в ответы ИИ. Из них ${mech} ${plural(mech, 'правится', 'правятся', 'правятся')} технически, без переписывания текстов, то есть быстро, а ${openN - mech} ${plural(openN - mech, 'потребует', 'потребуют', 'потребуют')} ваших фактов: цифр, источников, ответов на вопросы покупателей.`
+      : 'Главное: критичных поломок нет. Дальше сайт растёт не починкой, а текстами: ответами на вопросы покупателей, цифрами и источниками, по которым вас можно процитировать.',
+    noteOffer: (cta, contact) => `Что видит человек, попавший на сайт: ${cta}. ${contact[0].toUpperCase()}${contact.slice(1)}.`,
+    ctaYes: 'на первом экране есть понятный призыв к действию',
+    ctaNo: 'на первом экране нечего нажать, и это значит, что пришедший уходит',
+    contactYes: 'связаться можно почти с любой страницы',
+    contactNo: 'связаться с большинства страниц нельзя, человеку приходится искать',
+    strengthNone: 'Сильных сторон в текстах проверки не нашли.',
+    weakNone: 'Слабых мест в текстах проверки не нашли.',
+    gapsNone: 'Пробелов по страницам из выборки не видно.',
+    aeoWorksNone: 'Пока ничего из того, что помогает попасть в ответы, на сайте не работает.',
+    aeoBlocksNone: 'Прямых помех для попадания в ответы не нашли.',
+    aeoRec: (p) => p ? `Начните с одной страницы: ${p}. Поставьте в её начало прямой ответ с цифрой и назовите источник этой цифры рядом. Так страницу можно процитировать.` : 'Поставьте в начало каждой важной страницы прямой ответ с цифрой и назовите рядом источник. Цитируют то, что можно вырезать одним абзацем.',
+    geoEntity: ['Кто вы, понятно машине', (ok) => ok ? 'да' : 'нет'],
+    notMeasured: 'не измеряли',
+    geoMentions: 'Упоминания на чужих сайтах',
+    geoReviews: 'Отзывы и публикации',
+    geoMentionsNote: 'Не измеряли: данные о ссылках и упоминаниях продаются за деньги, а мы обещали отчёт только по бесплатным источникам.',
+    geoCallout: (ok) => ok
+      ? 'Роботы, которые достают страницу, чтобы процитировать её в ответе, на сайт пущены. Это половина дела: дальше вопрос в том, есть ли что цитировать.'
+      : 'Роботы, которые достают страницу для цитаты в ответе ИИ, на сайт не пущены. Пока это так, попасть в ответы невозможно физически, чего бы вы ни написали.',
+    offpageListed: (profiles) => profiles.length ? `Заявлены профили: ${profiles.join(', ')}.` : 'Ни одного профиля компании на других площадках в коде сайта не заявлено.',
+    offpageNote: 'Мы не покупаем данные о ссылках, поэтому не пишем ни цифр про их количество, ни оценок за них. Что проверяемо бесплатно: сказал ли сайт сам, где ещё вас искать, и совпадает ли это с реальностью.',
+    convForm: (v) => v,
+    priceRow: 'Цена видна',
+    priceNo: 'на проверенных страницах цены нет',
+    closing: (host, bad) => bad
+      ? `Мы посмотрели ${host} глазами машины и написали, что увидели, без общих слов. Сначала делается то, что чинится технически: это быстро и это видно в цифрах. Потом берутся тексты, и вот там понадобитесь вы, потому что цифры и факты про ваш бизнес знаете только вы.`
+      : `Мы посмотрели ${host} глазами машины. Технически сайт в порядке, чинить нечего, и это честный вывод, а не комплимент. Рост дальше только через тексты: ответы на вопросы покупателей с цифрами и источниками.`,
+    weekFill: 'Больше ничего срочного не нашли',
+    monthFill: 'Тексты по вашим фактам: ответы в начале страниц, источники к цифрам, недостающие страницы',
+    quarterFill: 'Повторная проверка и сравнение с этим отчётом',
+  },
+  en: {
+    subjectFrom: (d) => `From the homepage description: ${d}. Please confirm this is right.`,
+    subjectNone: 'The homepage does not say what the business does. That is the first problem: if a person cannot tell, neither can a search engine or an AI.',
+    unknownLang: 'not declared in the page code',
+    sells: (d) => d ? `${d} (taken from the homepage description, please confirm)` : 'the homepage description does not say, please confirm',
+    leadWhat: (h, n) => `${h} is a site of ${n} page${n === 1 ? '' : 's'}, and it was read the way machines read it: the way a search engine and an AI open it.`,
+    leadGood: (areas) => areas.length ? `What is done well: ${listEn(areas)}.` : 'None of the six areas reads as a strength yet.',
+    leadBad: (area, n) => n ? `What holds it back: ${n} check${n === 1 ? '' : 's'} failed, and the hardest area is "${area}".` : `No check is failing, but the last points are missing, mostly in "${area}".`,
+    verdict: (openN, mech) => openN
+      ? `The point: ${openN} thing${openN === 1 ? '' : 's'} stop this site from being shown and from being quoted by AI. ${mech} of them are mechanical, fixable without rewriting a word, which means quickly; the other ${openN - mech} need your facts: figures, sources, answers to what buyers ask.`
+      : 'The point: nothing is broken. From here the site grows through text, not repair: answers to what buyers ask, figures, and the sources behind them.',
+    noteOffer: (cta, contact) => `What a visitor meets: ${cta}. ${contact[0].toUpperCase()}${contact.slice(1)}.`,
+    ctaYes: 'the first screen has a clear thing to do',
+    ctaNo: 'the first screen has nothing to click, which means arrivals leave',
+    contactYes: 'getting in touch is possible from almost any page',
+    contactNo: 'most pages offer no way to get in touch, so a visitor has to go looking',
+    strengthNone: 'The checks found no strength in the text.',
+    weakNone: 'The checks found no weakness in the text.',
+    gapsNone: 'No gaps are visible across the sampled pages.',
+    aeoWorksNone: 'Nothing that helps a page get quoted is working yet.',
+    aeoBlocksNone: 'Nothing directly blocks a page from being quoted.',
+    aeoRec: (p) => p ? `Start with one page: ${p}. Put a direct answer carrying a figure at the top and name where that figure comes from, right beside it. That is what makes a page quotable.` : 'Put a direct answer carrying a figure at the top of every page that matters, and name the source beside it. What gets quoted is what can be lifted in one paragraph.',
+    notMeasured: 'not measured',
+    geoMentions: 'Mentions elsewhere',
+    geoReviews: 'Reviews and press',
+    geoMentionsNote: 'Not measured: link and mention data is sold for money, and this report was promised on free sources only.',
+    geoCallout: (ok) => ok
+      ? 'The fetchers that pull a page in order to quote it in an answer are allowed in. That is half the job: the rest is whether there is anything worth quoting.'
+      : 'The fetchers that pull a page to quote it in an AI answer are blocked. While that is true, being quoted is physically impossible, whatever you write.',
+    offpageListed: (profiles) => profiles.length ? `Profiles declared: ${profiles.join(', ')}.` : 'The site declares no company profile anywhere else.',
+    offpageNote: 'We do not buy link data, so we print no number of links and no score built on one. What is checkable for free: whether the site says where else to find you, and whether that matches reality.',
+    priceRow: 'Price visible',
+    priceNo: 'no price on the pages we read',
+    closing: (host, bad) => bad
+      ? `We looked at ${host} the way a machine looks at it and wrote down what we saw, without generalities. What gets fixed first is what is mechanical: it is quick and it shows in the numbers. Then comes the text, and there we need you, because only you know the figures and facts of your business.`
+      : `We looked at ${host} the way a machine looks at it. Technically it is in order and there is nothing to repair, and that is a finding, not a compliment. Growth from here comes through text: answers to buyers' questions, with figures and sources.`,
+    weekFill: 'Nothing else is urgent',
+    monthFill: 'Text from your facts: answers at the top of pages, sources beside figures, the pages you are missing',
+    quarterFill: 'A second run, compared against this report',
+  },
+};
+
+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] || '';
+
+/** Проверки, которые 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']);
+
+import { localiseChecks, AREAS_RU } from './i18n.mjs';
+import { FIX_ACTIONS } from './fix.mjs';
+
+const byId = (checks, id) => (checks || []).find((c) => c.id === id);
+const open = (c) => c && (c.status === 'warn' || c.status === 'bad');
+
+/**
+ * Заполняет пустые поля отчёта словами, собранными из проверок.
+ * @param {object} audit результат collect()
+ * @param {{lang?: 'ru'|'en'}} opts
+ */
+export function draftNarrative(audit, opts = {}) {
+  const lang = opts.lang || audit.meta?.lang || 'en';
+  const t = T[lang === 'ru' ? 'ru' : 'en'];
+  const a = JSON.parse(JSON.stringify(audit));
+  // Отчёт по-русски по английскому аудиту: названия проверок и областей переводим здесь же,
+  // иначе владелец читает русский текст с английскими вставками и перестаёт нам верить.
+  const needsRu = lang === 'ru' && a.meta?.lang !== 'ru';
+  const checks = needsRu ? localiseChecks(a.checks || [], 'ru') : (a.checks || []);
+  const areaName = (k) => (needsRu ? (AREAS_RU[k] || k) : k);
+  const host = a.meta?.host || '';
+  const sample = (a.sample || []).filter((p) => p.title !== undefined);
+  const home = sample[0] || {};
+
+  const bad = checks.filter((c) => c.status === 'bad');
+  const warn = checks.filter((c) => c.status === 'warn');
+  const mechanical = [...bad, ...warn].filter((c) => MECHANICAL.has(c.id)).length;
+  const scores = Object.entries(a.scores || {}).filter(([, v]) => typeof v === 'number');
+  const strong = scores.filter(([, v]) => v >= 8).map(([k]) => areaName(k));
+  const weakest = areaName(scores.slice().sort((x, y) => x[1] - y[1])[0]?.[0] || '');
+
+  // Кто клиент. Имя это адрес сайта, предмет прочитан с главной и помечен как прочитанный.
+  const desc = String(home.description || '').trim().slice(0, 180);
+  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;
+
+  // Резюме.
+  if (String(a.summary.lead).includes('{{')) {
+    a.summary.lead = [t.leadWhat(host, sample.length), t.leadGood(strong), t.leadBad(weakest, bad.length)].join(' ');
+  }
+  if (String(a.summary.verdict).includes('{{')) a.summary.verdict = t.verdict(bad.length + warn.length, mechanical);
+  // Приоритет это не название проверки, а действие: владелец должен прочитать и понять, что делать.
+  const actionText = (c) => {
+    const rule = FIX_ACTIONS[c.id];
+    const L = lang === 'ru' ? 'ru' : 'en';
+    if (rule && rule.action) return rule.action[L];
+    // Проверки, которые закрываются только фактами клиента: называем работу, а не оправдание.
+    const TEXT_WORK = {
+      ru: { thin: 'Наполнить короткие страницы фактами: цифрами, условиями, сроками', 'answer-first': 'Поставить в начало страницы прямой ответ с цифрой', sources: 'Подписать к каждой цифре, откуда она взята', sections: 'Разбить страницу на разделы по вопросам читателя', tables: 'Собрать таблицу из ваших данных: таблицы цитируют охотнее абзацев' },
+      en: { thin: 'Fill the short pages with facts: figures, terms, timings', 'answer-first': 'Put a direct answer carrying a figure at the top of the page', sources: 'Name where each figure comes from', sections: 'Break the page into sections that follow the reader\'s questions', tables: 'Build a table from your data: tables get quoted more readily than prose' },
+    };
+    const own = TEXT_WORK[L][c.id];
+    if (own) return own;
+    if (rule && rule.why) return L === 'ru' ? `Это работа с текстами: ${rule.why.ru}` : `This is text work: ${rule.why.en}`;
+    return c.label;
+  };
+  const action = (c) => `${actionText(c)}. ${lang === 'ru' ? 'Сейчас' : 'Now'}: ${c.value}`;
+  const top = [...bad, ...warn].slice(0, 3);
+  a.summary.priorities = (a.summary.priorities || []).map((p, i) => {
+    if (!String(p).includes('{{')) return p;
+    const c = top[i];
+    return c ? action(c) : (lang === 'ru' ? 'Ничего срочного больше не нашли' : 'Nothing else is urgent');
+  });
+
+  // Обзор.
+  a.overview.rows = (a.overview.rows || []).map(([k, v]) => {
+    if (!String(v).includes('{{')) return [k, v];
+    if (/language|язык/i.test(k)) return [k, a.meta?.language || t.unknownLang];
+    if (/sold|продаётся|продается/i.test(k)) return [k, t.sells(desc)];
+    return [k, t.notMeasured];
+  });
+  if (String(a.overview.note).includes('{{')) {
+    const cta = byId(checks, 'conv-cta');
+    const path = byId(checks, 'conv-contact-path');
+    a.overview.note = t.noteOffer(open(cta) ? t.ctaNo : t.ctaYes, open(path) ? t.contactNo : t.contactYes);
+  }
+
+  // Контент, AEO, GEO, ссылки, конверсия: строки собираются из своих же групп проверок.
+  const group = (g) => checks.filter((c) => c.group === g);
+  const fillList = (arr, source, empty) => (arr || []).map((x, i) => {
+    if (!String(x).includes('{{')) return x;
+    const c = source[i];
+    return c ? `${c.label}: ${c.value}` : empty;
+  });
+  a.content.strengths = fillList(a.content.strengths, group('content').filter((c) => c.status === 'ok'), t.strengthNone);
+  a.content.weaknesses = fillList(a.content.weaknesses, group('content').filter(open), t.weakNone);
+  a.content.gaps = fillList(a.content.gaps, group('content').filter((c) => c.status === 'bad'), t.gapsNone);
+  a.aeo.works = fillList(a.aeo.works, group('aeo').filter((c) => c.status === 'ok'), t.aeoWorksNone);
+  a.aeo.blocks = fillList(a.aeo.blocks, group('aeo').filter(open), t.aeoBlocksNone);
+  if (String(a.aeo.recommendation).includes('{{')) {
+    const thinnest = sample.filter((p) => p.answerFirst === false).sort((x, y) => (y.words || 0) - (x.words || 0))[0];
+    a.aeo.recommendation = t.aeoRec(thinnest ? thinnest.url : '');
+  }
+
+  const entity = byId(checks, 'trust-entity') || byId(checks, 'org-schema');
+  a.geo.rows = (a.geo.rows || []).map((row, i) => {
+    const [label, status, detail] = row;
+    if (!String(status).includes('{{') && !String(detail).includes('{{')) return row;
+    if (i === 0) return [label, entity && entity.status === 'ok' ? (lang === 'ru' ? 'да' : 'yes') : (lang === 'ru' ? 'нет' : 'no'), entity ? entity.value : t.notMeasured];
+    if (i === 1) return [t.geoMentions, t.notMeasured, t.geoMentionsNote];
+    return [t.geoReviews, t.notMeasured, t.geoMentionsNote];
+  });
+  if (String(a.geo.callout).includes('{{')) {
+    const fetchers = byId(checks, 'ai-search-access');
+    a.geo.callout = t.geoCallout(!fetchers || fetchers.status === 'ok');
+  }
+
+  const profilesCheck = byId(checks, 'trust-profiles');
+  const profiles = profilesCheck && profilesCheck.status === 'ok' ? String(profilesCheck.value).split(/[,:]/).slice(1).map((s) => s.trim()).filter(Boolean) : [];
+  a.offpage.listed = (a.offpage.listed || []).map((x) => String(x).includes('{{') ? t.offpageListed(profiles) : x);
+  if (String(a.offpage.note).includes('{{')) a.offpage.note = t.offpageNote;
+
+  a.conversion.rows = (a.conversion.rows || []).map(([label, status]) => {
+    if (!String(status).includes('{{')) return [label, status];
+    if (/form|форм/i.test(label)) { const c = byId(checks, 'conv-form-fields') || byId(checks, 'conv-form-depth'); return [label, c ? c.value : t.notMeasured]; }
+    if (/messenger|мессендж/i.test(label)) { const c = byId(checks, 'conv-messenger'); return [label, c ? c.value : t.notMeasured]; }
+    if (/price|цена/i.test(label)) return [label, t.priceNo];
+    return [label, t.notMeasured];
+  });
+
+  // Дорожная карта: недостающие строки берутся из открытых проверок по их же смыслу.
+  const mech = [...bad, ...warn].filter((c) => MECHANICAL.has(c.id));
+  const textWork = [...bad, ...warn].filter((c) => !MECHANICAL.has(c.id));
+  // Строки, которые сборщик уже написал по-английски, в русском отчёте переводим по той же проверке.
+  const labelToCheck = new Map(checks.map((c) => [c.label, c]));
+  const englishLabel = new Map((a.checks || []).map((c, i) => [c.label, checks[i]]));
+  const retitle = (item) => {
+    const m = /^Fix:\s*(.+)$/.exec(String(item));
+    if (!m) return item;
+    const c = labelToCheck.get(m[1]) || englishLabel.get(m[1]);
+    return c ? actionText(c) : item;
+  };
+  a.roadmap = (a.roadmap || []).map((phase, pi) => ({
+    ...phase,
+    items: (phase.items || []).map((item, ii) => {
+      if (!String(item).includes('{{')) return needsRu ? retitle(item) : item;
+      const pool = pi === 0 ? mech : pi === 1 ? textWork : [];
+      const c = pool[ii];
+      if (c) return actionText(c);
+      return pi === 0 ? t.weekFill : pi === 1 ? t.monthFill : t.quarterFill;
+    }),
+  }));
+
+  if (String(a.closing).includes('{{')) a.closing = t.closing(host, bad.length);
+  return a;
+}
+
+/** Что осталось пустым после черновика: аналитик правит только это. */
+export function stillEmpty(audit) {
+  const out = [];
+  const walk = (o, path = '') => {
+    if (typeof o === 'string') { if (o.includes('{{')) out.push(path); return; }
+    if (Array.isArray(o)) { o.forEach((x, i) => walk(x, `${path}[${i}]`)); return; }
+    if (o && typeof o === 'object') for (const k of Object.keys(o)) walk(o[k], path ? `${path}.${k}` : k);
+  };
+  walk(audit);
+  return out;
+}

package/src/prompts.mjs

@@ -0,0 +1,156 @@
+/**
+ * Находка превращается в задание для ИИ-агента.
+ *
+ * Наш покупатель правит сайт не руками: он открывает Cursor или Claude Code и говорит агенту, что
+ * сделать. До сих пор мы отдавали ему список «что не так», а формулировку задания он придумывал
+ * сам. Здесь это делается за него: каждая найденная проблема выходит текстом, который вставляется
+ * в агента и исполняется без правок.
+ *
+ * У каждого задания три обязательные части, иначе агент делает не то:
+ *   1. Что сейчас: измеренное число, чтобы агент знал точку отсчёта и не чинил уже целое.
+ *   2. Что сделать: одно действие, границы, и прямой запрет выдумывать факты о бизнесе.
+ *   3. Как проверить: признак, по которому видно, что работа сделана, а не «кажется сделана».
+ *
+ * Заданий с собственным текстом столько, сколько проверок мы умеем чинить осмысленно. Для
+ * остальных собирается общее задание из описания работы: оно короче, но не врёт.
+ */
+import { FIX_ACTIONS } from './fix.mjs';
+import { localiseChecks } from './i18n.mjs';
+
+const P = {
+  alt: {
+    ru: { task: 'Пройди по шаблонам и контенту сайта и проставь атрибут alt каждой картинке, у которой его нет или он пустой. Подпись описывает своими словами, что изображено, от пяти до пятнадцати слов, без перечисления ключевых слов. Если картинка чисто декоративная, поставь пустой alt="", это правильно и намеренно. Если по имени файла и окружающему тексту непонятно, что на картинке, не выдумывай: собери такие файлы в список в конце ответа и не трогай их.', verify: 'В собранном HTML не осталось картинок без атрибута alt.' },
+    en: { task: 'Go through the site templates and content and give every image an alt attribute where it is missing or empty. The text describes in plain words what the image shows, five to fifteen words, no keyword lists. Purely decorative images take an empty alt="", deliberately. Where the file name and the surrounding text do not tell you what the image shows, do not invent it: list those files at the end and leave them alone.', verify: 'No image in the built HTML is left without an alt attribute.' },
+  },
+  'conv-cta': {
+    ru: { task: 'Поставь на первый экран каждой важной страницы одно понятное действие: кнопку или ссылку, которая говорит, что произойдёт после нажатия («Получить расчёт», «Посмотреть цены», «Написать в Telegram»). Одно действие на экран, не три. Текст кнопки бери из того, что реально происходит дальше, не выдумывай новых обещаний и сроков.', verify: 'На каждой такой странице в верхних тридцати процентах высоты есть кликабельное действие.' },
+    en: { task: 'Put one clear thing to do in the first screen of every page that matters: a button or link that says what happens next ("Get a quote", "See prices", "Message us"). One action per screen, not three. Take the wording from what actually happens next; do not invent new promises or timings.', verify: 'Every such page has a clickable action within the top thirty percent of its height.' },
+  },
+  'conv-messenger': {
+    ru: { task: 'Добавь в подвал и на страницу контактов прямую ссылку на мессенджер, которым компания действительно пользуется. Ссылка должна открывать диалог, а не страницу профиля. Если ты не знаешь, какой мессенджер используется, не выбирай его сам: оставь место и спроси владельца.', verify: 'Ссылка открывается и ведёт в диалог, а не на общую страницу.' },
+    en: { task: 'Add a direct messenger link to the footer and the contact page, for a messenger the business actually uses. The link opens a conversation, not a profile page. If you do not know which messenger they use, do not choose one: leave the slot and ask the owner.', verify: 'The link opens and starts a conversation rather than a general page.' },
+  },
+  robots: {
+    ru: { task: 'Перепиши robots.txt: убери запреты, которые закрывают обычные страницы сайта, оставь закрытыми только служебные адреса (корзина, личный кабинет, поиск по сайту, страницы благодарности). В конце добавь строку Sitemap с полным адресом карты сайта. Ничего не закрывай «на всякий случай»: каждый запрет должен иметь причину.', verify: 'Главная и разделы сайта открыты для всех роботов, в файле есть строка Sitemap, и она отдаёт карту по указанному адресу.' },
+    en: { task: 'Rewrite robots.txt: drop the rules that block ordinary pages, keep blocked only the utility addresses (cart, account, site search, thank-you pages). Add a Sitemap line with the full address at the end. Block nothing "just in case": every rule needs a reason.', verify: 'The homepage and sections are open to all robots, the file has a Sitemap line, and that address serves the sitemap.' },
+  },
+  'ai-search-access': {
+    ru: { task: 'Открой в robots.txt роботов, которые достают страницу, чтобы процитировать её в ответе ИИ: OAI-SearchBot, ChatGPT-User, PerplexityBot, Perplexity-User, Claude-SearchBot, Claude-User, DuckAssistBot, Applebot. Это не те роботы, что обучают модели, это те, что приносят вас в ответ на вопрос покупателя. Обучающие краулеры (GPTBot, CCBot, ClaudeBot, Google-Extended) оставь как есть: закрывать их или нет, решает владелец.', verify: 'В robots.txt ни один из перечисленных восьми агентов не запрещён.' },
+    en: { task: 'In robots.txt, allow the fetchers that pull a page to quote it in an AI answer: OAI-SearchBot, ChatGPT-User, PerplexityBot, Perplexity-User, Claude-SearchBot, Claude-User, DuckAssistBot, Applebot. These are not the training crawlers; these are the ones that bring you into an answer to a buyer\'s question. Leave the training crawlers (GPTBot, CCBot, ClaudeBot, Google-Extended) as they are: blocking them is the owner\'s call.', verify: 'None of those eight agents is disallowed in robots.txt.' },
+  },
+  llms: {
+    ru: { task: 'Сгенерируй файл llms.txt в корне сайта: заголовок с названием компании и одной строкой о том, чем она занимается, затем разделы по типам страниц, в каждом ссылки вида «- [Заголовок](полный адрес): одно предложение о чём страница». Бери только страницы, открытые для индексации. Не включай страницы с noindex, служебные адреса и то, что отвечает перенаправлением.', verify: 'Файл отдаётся по адресу /llms.txt, все ссылки в нём ведут на страницы этого же сайта и отвечают кодом 200.' },
+    en: { task: 'Generate an llms.txt at the site root: a heading with the company name and one line on what it does, then sections by page type, each holding links shaped "- [Title](full URL): one sentence on what the page is". Include only pages open to indexing. Leave out noindex pages, utility addresses, and anything that answers with a redirect.', verify: 'The file is served at /llms.txt, and every link in it points at this site and answers 200.' },
+  },
+  sitemap: {
+    ru: { task: 'Почини карту сайта: она должна содержать все страницы, открытые для индексации, и только их. Убери из неё служебные адреса, страницы с noindex и адреса, отвечающие перенаправлением. Проставь честную дату последнего изменения для каждой страницы, не сегодняшнюю дату для всех.', verify: 'Карта отдаётся по адресу из robots.txt, все адреса в ней отвечают кодом 200, дат «сегодня» у всех страниц нет.' },
+    en: { task: 'Fix the sitemap: it must list every page open to indexing and nothing else. Remove utility addresses, noindex pages and anything that answers with a redirect. Give each page an honest last-modified date, not today\'s date for all of them.', verify: 'The sitemap is served at the address in robots.txt, every URL in it answers 200, and the dates are not all today.' },
+  },
+  title: {
+    ru: { task: 'Перепиши заголовок страницы (тег title) так, чтобы он укладывался в 60 знаков и говорил, что на странице, словами, которыми это ищет человек. Название компании в конце только если остаётся место. Не повторяй одно и то же слово дважды и не пиши список ключевых слов через запятую.', verify: 'Длина title не больше 60 знаков, и он отличается от заголовков других страниц.' },
+    en: { task: 'Rewrite the page title so it fits 60 characters and says what is on the page, in the words a person would search with. Put the company name at the end only if there is room. Do not repeat a word twice and do not write a comma-separated keyword list.', verify: 'The title is 60 characters or fewer and differs from other pages\' titles.' },
+  },
+  description: {
+    ru: { task: 'Перепиши описание страницы (meta description) в 120-160 знаков: что человек найдёт на странице и почему ему стоит зайти. Одно предложение, без рекламных восклицаний. Убери из него любые остатки кода и шорткодов. Не обещай того, чего на странице нет.', verify: 'Описание есть, его длина от 120 до 160 знаков, и оно описывает именно эту страницу.' },
+    en: { task: 'Rewrite the meta description in 120 to 160 characters: what the reader will find on the page and why it is worth opening. One sentence, no exclamation marks. Strip any leftover code or shortcodes. Do not promise anything the page does not have.', verify: 'The description exists, is 120 to 160 characters, and describes this page in particular.' },
+  },
+  h1: {
+    ru: { task: 'Оставь на странице ровно один заголовок первого уровня (H1), он должен совпадать по смыслу с тем, что на странице. Остальные крупные заголовки переведи в H2. Не делай H1 из логотипа и из названия сайта в шапке.', verify: 'На странице ровно один H1, и он про содержание страницы, а не про название сайта.' },
+    en: { task: 'Leave exactly one first-level heading (H1) on the page, matching what the page is about. Demote the other large headings to H2. Do not make an H1 out of the logo or the site name in the header.', verify: 'The page has exactly one H1, and it is about the page rather than the site name.' },
+  },
+  canonical: {
+    ru: { task: 'Проставь на каждой странице канонический адрес (link rel="canonical") с полным адресом этой же страницы, включая протокол и домен, без параметров отслеживания. На страницах с постраничной навигацией канонический адрес указывает на саму страницу, а не на первую.', verify: 'На каждой странице есть канонический адрес, он абсолютный и указывает на неё саму.' },
+    en: { task: 'Give every page a canonical link with the full address of that same page, protocol and domain included, without tracking parameters. On paginated pages the canonical points at the page itself, not at page one.', verify: 'Every page has a canonical link, absolute, pointing at itself.' },
+  },
+  og: {
+    ru: { task: 'Добавь на страницы карточки для соцсетей и мессенджеров: og:title, og:description, og:image с картинкой не меньше 1200 на 630 точек, og:url. Заголовок и описание бери со страницы, не выдумывай новых. Проверь, что картинка отдаётся по прямой ссылке без авторизации.', verify: 'При вставке ссылки в мессенджер появляется карточка с заголовком, описанием и картинкой.' },
+    en: { task: 'Add social cards to the pages: og:title, og:description, og:image at 1200 by 630 or larger, og:url. Take the title and description from the page itself; do not write new ones. Check the image is served over a plain link without authentication.', verify: 'Pasting the link into a messenger shows a card with title, description and image.' },
+  },
+  schema: {
+    ru: { task: 'Добавь на главную страницу разметку организации (schema.org Organization) в формате JSON-LD: название, адрес сайта, логотип, город и страна, почта или телефон, и ссылки на профили компании в других местах. Заполняй только тем, что действительно есть: выдуманный адрес или несуществующий профиль хуже, чем его отсутствие.', verify: 'Разметка проходит проверку в Rich Results Test, и каждое поле в ней соответствует правде.' },
+    en: { task: 'Add Organization markup (schema.org, JSON-LD) to the homepage: name, site address, logo, city and country, email or phone, and links to the company\'s profiles elsewhere. Fill it only with what actually exists: an invented address or a profile that is not yours is worse than nothing.', verify: 'The markup passes the Rich Results Test and every field in it is true.' },
+  },
+  'faq-schema': {
+    ru: { task: 'Найди страницы, где уже есть блок вопросов и ответов, и размечай их схемой FAQPage в JSON-LD. Текст в разметке должен слово в слово совпадать с тем, что видит человек на странице. Не добавляй в разметку вопросы, которых на странице нет.', verify: 'Разметка проходит проверку, и каждый вопрос из неё виден на самой странице.' },
+    en: { task: 'Find the pages that already carry a questions-and-answers block and mark them up as FAQPage in JSON-LD. The text in the markup must match word for word what a person sees on the page. Do not add questions that are not on the page.', verify: 'The markup validates and every question in it is visible on the page itself.' },
+  },
+  'trust-entity': {
+    ru: { task: 'Допиши в разметку организации город и страну (PostalAddress с addressLocality и addressCountry). Это то, по чему ИИ понимает, кто вы и откуда. Бери реальный адрес компании: если публиковать его полностью не хочется, достаточно города и страны.', verify: 'В разметке организации есть город и страна, и они совпадают с действительностью.' },
+    en: { task: 'Add the city and country to the Organization markup (PostalAddress with addressLocality and addressCountry). This is how an AI knows who you are and where. Use the real address: if you would rather not publish it in full, the city and country are enough.', verify: 'The Organization markup carries a city and country, and they are true.' },
+  },
+  'trust-contact': {
+    ru: { task: 'Опубликуй прямые контакты на странице контактов и в подвале: почта, мессенджер, форма. Те же контакты продублируй в разметке организации (contactPoint). Публикуй только те адреса, которые действительно читают: неотвечающий ящик хуже, чем его отсутствие.', verify: 'Контакты видны на странице и присутствуют в разметке, письмо на указанный адрес доходит.' },
+    en: { task: 'Publish direct contacts on the contact page and in the footer: email, messenger, form. Mirror the same contacts in the Organization markup (contactPoint). Publish only addresses somebody actually reads: a mailbox nobody opens is worse than none.', verify: 'The contacts are visible on the page and present in the markup, and mail to that address arrives.' },
+  },
+  dates: {
+    ru: { task: 'Выведи на страницах дату публикации и дату последнего изменения: видимой строкой для человека и полями datePublished и dateModified в разметке. Дата изменения должна меняться только тогда, когда текст действительно правился, а не при каждой сборке сайта.', verify: 'На странице видна дата, в разметке есть оба поля, и дата изменения не равна дате сборки.' },
+    en: { task: 'Expose the published and last-modified dates on the pages: as a visible line for the reader and as datePublished and dateModified in the markup. The modified date changes only when the text actually changed, not on every build.', verify: 'The page shows a date, the markup carries both fields, and the modified date is not simply the build date.' },
+  },
+  'answer-first': {
+    ru: { task: 'Перепиши начало страницы так, чтобы первый абзац сразу отвечал на вопрос, ради которого страницу открыли: от двадцати до девяноста слов, и в нём должна быть конкретная цифра (цена, срок, доля, количество). Цифру бери у владельца сайта и рядом назови, откуда она. Если цифры нет, не придумывай её: спроси владельца и оставь пометку.', verify: 'Первый абзац после заголовка укладывается в 20-90 слов и содержит цифру с названным источником.' },
+    en: { task: 'Rewrite the opening so the first paragraph answers the question the page was opened for: twenty to ninety words, carrying a concrete figure (a price, a timing, a share, a count). Get the figure from the site owner and name its source beside it. If there is no figure, do not invent one: ask the owner and leave a marker.', verify: 'The first paragraph after the heading is 20 to 90 words and carries a figure with a named source.' },
+  },
+  sources: {
+    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.' },
+  },
+  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.' },
+  },
+};
+
+const withLang = (v, lang) => v[lang === 'ru' ? 'ru' : 'en'];
+
+const HEAD = {
+  ru: { now: 'Сейчас', task: 'Задача', verify: 'Как проверить', pages: 'Страницы, где это видно', genericVerify: 'Прогони проверку сайта заново: эта строка должна перестать быть проблемой, а остальные не должны испортиться.', rule: 'Правило: не выдумывай факты о бизнесе. Всё, чего нет на сайте и чего тебе не сказали, спрашивай у владельца и оставляй пометку.' },
+  en: { now: 'Now', task: 'Task', verify: 'How to check', pages: 'Pages where this shows', genericVerify: 'Run the site check again: this line must stop being a finding, and nothing else may get worse.', rule: 'Rule: invent no facts about the business. Anything not on the site and not told to you, ask the owner and leave a marker.' },
+};
+
+/**
+ * Задание для ИИ-агента по одной находке.
+ * @param {object} check строка проверки из аудита
+ * @param {{lang?: 'ru'|'en', urls?: string[]}} opts
+ */
+export function agentPrompt(check, opts = {}) {
+  const lang = opts.lang === 'ru' ? 'ru' : 'en';
+  const h = HEAD[lang];
+  const own = P[check.id] ? withLang(P[check.id], lang) : null;
+  const rule = FIX_ACTIONS[check.id];
+  const fallback = rule && rule.action ? withLang(rule.action, lang) : (rule && rule.why ? withLang(rule.why, lang) : check.label);
+
+  const lines = [`### ${check.label}`, '', `**${h.now}:** ${check.value}`, '', `**${h.task}:** ${own ? own.task : fallback}`];
+  // Проверка обязательна у каждого задания: без неё агент не знает, когда остановиться.
+  lines.push('', `**${h.verify}:** ${own ? own.verify : h.genericVerify}`);
+  if (opts.urls && opts.urls.length) { lines.push('', `**${h.pages}:** ${opts.urls.slice(0, 8).join(', ')}`); }
+  lines.push('', h.rule);
+  return lines.join('\n');
+}
+
+/** Все задания по открытым находкам аудита, в порядке важности. */
+export function agentPrompts(audit, opts = {}) {
+  const lang = opts.lang === 'ru' ? 'ru' : 'en';
+  const limit = Number(opts.limit ?? 0);
+  // Русский файл по английскому аудиту: названия и значения проверок переводим, иначе владелец
+  // читает русское задание с английскими вставками и не понимает, про что оно.
+  const source = lang === 'ru' && audit.meta?.lang !== 'ru' ? localiseChecks(audit.checks || [], 'ru') : (audit.checks || []);
+  const checks = source.filter((c) => c.status === 'bad' || c.status === 'warn');
+  const ordered = [...checks.filter((c) => c.status === 'bad'), ...checks.filter((c) => c.status === 'warn')];
+  const chosen = limit > 0 ? ordered.slice(0, limit) : ordered;
+  return chosen.map((c) => ({ id: c.id, hasOwnText: Boolean(P[c.id]), text: agentPrompt(c, { lang }) }));
+}
+
+/** Файл, который отдаётся клиенту вместе с отчётом. */
+export function renderAgentPrompts(audit, opts = {}) {
+  const lang = opts.lang === 'ru' ? 'ru' : 'en';
+  const host = audit.meta?.host || '';
+  const list = agentPrompts(audit, opts);
+  const intro = lang === 'ru'
+    ? [`# Задания для ИИ-агента: ${host}`, '',
+       'Это тот же список находок, что в отчёте, но переписанный так, чтобы его можно было отдать ИИ-агенту (Cursor, Claude Code, любому другому) и он сделал работу. Копируй задание целиком, вместе со строками «Сейчас» и «Как проверить»: без них агент не поймёт, откуда начинать и чем закончить.', '',
+       'Делайте по одному заданию за раз и проверяйте результат, прежде чем брать следующее. Агент, которому дали десять задач сразу, делает первую и половину остальных.', '']
+    : [`# Prompts for an AI agent: ${host}`, '',
+       'This is the same list of findings as in the report, rewritten so you can hand it to an AI agent (Cursor, Claude Code, any other) and it does the work. Copy a task whole, including the "Now" and "How to check" lines: without them the agent does not know where it starts or when it is done.', '',
+       'Do one task at a time and check the result before taking the next. An agent given ten tasks at once does the first and half of the rest.', ''];
+  return [intro.join('\n').trimEnd(), ...list.map((x) => x.text)].join('\n\n');
+}

package/src/test-narrative.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/** Черновик текста аудита: заполняет всё, ничего не выдумывает, читается человеком. */
+import { draftNarrative, stillEmpty } 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 audit = (over = {}) => ({
+  meta: { host: 'x.ru', site: 'https://x.ru', collectedAt: '2026-09-11T00:00:00.000Z', lang: 'en', language: '' },
+  client: { name: '{{CLIENT NAME}}', subject: '{{What the site sells and where}}', reportDate: '2026-09-11', preparedBy: 'OperStack' },
+  scores: { 'SEO, technical': 9, 'SEO, content and structure': 4, 'AEO, answers and snippets': 6, 'GEO, visibility in AI systems': 8, 'Off-page and trust': null, 'Conversion and UX': 5 },
+  summary: { lead: '{{a}}', verdict: '{{b}}', priorities: ['{{1}}', '{{2}}', '{{3}}'] },
+  overview: { rows: [['CMS / stack', 'Astro'], ['Pages in sitemap', '40'], ['Language', '{{language}}'], ['What is sold', '{{products}}']], note: '{{note}}' },
+  content: { strengths: ['{{s}}'], weaknesses: ['{{w}}'], gaps: ['{{g}}'] },
+  aeo: { works: ['{{x}}'], blocks: ['{{y}}'], recommendation: '{{r}}' },
+  geo: { rows: [['Entity clarity', '{{s}}', '{{d}}'], ['Third-party mentions', '{{s}}', '{{d}}'], ['Reviews and PR', '{{s}}', '{{d}}']], callout: '{{c}}' },
+  offpage: { listed: ['{{l}}'], note: '{{n}}' },
+  conversion: { rows: [['Contact form', '{{s}}'], ['Price visible', '{{s}}'], ['Messengers', '{{s}}']] },
+  roadmap: [
+    { badge: 'Week 1', title: 'Critical', items: ['Fix: Image alt text', '{{...}}'] },
+    { badge: 'Weeks 2 to 4', title: 'Foundation', items: ['{{...}}'] },
+    { badge: 'Months 2 to 3', title: 'Growth', items: ['{{...}}'] },
+  ],
+  closing: '{{close}}',
+  sample: [{ url: 'https://x.ru/', title: 'Дом', description: 'Мы продаём станки', words: 900, answerFirst: false }],
+  checks: [
+    { id: 'alt', group: 'onpage', label: 'Image alt text', status: 'bad', value: '3 of 10 images carry alt text (30%) across 5 sampled page(s)' },
+    { id: 'thin', group: 'content', label: 'Thin pages in sample', status: 'warn', value: '4 of 20 pages under 300 words' },
+    { id: 'answer-first', group: 'aeo', label: 'Answer-first opening paragraph', status: 'bad', value: '2 of 20 sampled page(s) open with a figure' },
+    { id: 'sources', group: 'aeo', label: 'Sources named in the text', status: 'ok', value: '18 of 20 name a source' },
+    { id: 'dates', group: 'content', label: 'Publication dates exposed', status: 'ok', value: '19 of 20 expose dates' },
+    { id: 'conv-cta', group: 'conversion', label: 'A call to action in the first screen', status: 'bad', value: '1 of 20 put it in the first 30%' },
+    { id: 'conv-messenger', group: 'conversion', label: 'Messenger link', status: 'ok', value: 'telegram found' },
+    { id: 'trust-entity', group: 'trust', label: 'Who the business is', status: 'ok', value: 'city and country in the structured data' },
+    { id: 'ai-search-access', group: 'geo', label: 'AI search fetchers allowed', status: 'ok', value: 'every AI search fetcher may read the site' },
+  ],
+  ...over,
+});
+
+const d = draftNarrative(audit(), { lang: 'ru' });
+is('не осталось ни одной дыры', stillEmpty(d), []);
+ok('имя клиента это адрес сайта, а не выдумка', d.client.name === 'x.ru');
+ok('предмет взят с главной и помечен как прочитанный', d.client.subject.includes('Мы продаём станки') && /подтвердите/i.test(d.client.subject));
+
+// Ничего не выдумываем: там, где не мерили, так и написано
+ok('упоминания на чужих сайтах помечены как неизмеренные', d.geo.rows[1][1] === 'не измеряли');
+ok('и объяснено почему', /за деньги/.test(d.geo.rows[1][2]));
+ok('в разделе ссылок сказано, что данные платные', /не покупаем данные/.test(d.offpage.note));
+ok('язык не выдуман, если его нет в коде', /не указан/.test(d.overview.rows[2][1]));
+
+// Числа сходятся между собой
+const openN = 4; const mech = 2; // alt, conv-cta механические; thin и answer-first это тексты
+ok('в выводе число открытых проверок верное', d.summary.verdict.includes(`${openN} вещи`) || d.summary.verdict.includes(`${openN} вещей`));
+ok('и механических не больше, чем всех', d.summary.verdict.includes(`${mech} правятся`) || d.summary.verdict.includes(`${mech} правится`));
+
+// Приоритеты это действие, а не название проверки
+ok('приоритет говорит, что делать', /Проставить подписи/.test(d.summary.priorities[0]));
+ok('и показывает, как сейчас', /Сейчас:/.test(d.summary.priorities[0]));
+ok('работа с текстами названа работой, а не отговоркой', d.summary.priorities.some((p) => /Наполнить короткие страницы|прямой ответ/.test(p)));
+
+// Русский отчёт по английскому аудиту не должен содержать английских названий проверок
+const ruText = JSON.stringify([d.summary, d.content, d.aeo, d.roadmap, d.closing]);
+ok('в русском черновике нет английских названий проверок', !/Image alt text|Thin pages|call to action/.test(ruText));
+ok('области названы по-русски', /техническая часть|Конверсия/.test(d.summary.lead));
+
+// Дорожная карта: уже написанные строки переведены, пустые заполнены
+ok('готовая строка карты переведена', d.roadmap[0].items[0].includes('подписи'));
+ok('пустая строка карты заполнена делом', !d.roadmap[1].items[0].includes('{{'));
+
+// Английский отчёт остаётся английским
+const e = draftNarrative(audit(), { lang: 'en' });
+is('по-английски тоже без дыр', stillEmpty(e), []);
+ok('английский черновик без кириллицы', !/[А-Яа-яЁё]/.test(JSON.stringify([e.summary, e.aeo, e.closing])));
+ok('и приоритет тоже действие', /Write alt text/.test(e.summary.priorities[0]));
+
+// Здоровый сайт: вывод не пугает, а говорит правду
+const clean = draftNarrative(audit({ checks: [
+  { id: 'alt', group: 'onpage', label: 'Image alt text', status: 'ok', value: 'all images carry alt text' },
+  { id: 'ai-search-access', group: 'geo', label: 'AI search fetchers allowed', status: 'ok', value: 'allowed' },
+] }), { lang: 'ru' });
+ok('на чистом сайте вывод говорит, что чинить нечего', /критичных поломок нет/.test(clean.summary.verdict));
+ok('и заключение не выдумывает проблем', /нечего/.test(clean.closing));
+
+// Ничего уже написанного человеком не затирается
+const edited = audit();
+edited.summary.lead = 'Текст, который написал аналитик.';
+const keep = draftNarrative(edited, { lang: 'ru' });
+is('правку аналитика черновик не трогает', keep.summary.lead, 'Текст, который написал аналитик.');
+
+// Заблокированные фетчеры это прямой приговор, а не намёк
+const blocked = draftNarrative(audit({ checks: [{ id: 'ai-search-access', group: 'geo', label: 'AI search fetchers allowed', status: 'bad', value: '3 blocked' }] }), { lang: 'ru' });
+ok('если роботы ИИ закрыты, об этом сказано прямо', /невозможно физически/.test(blocked.geo.callout));
+
+if (bad) { console.error(`\n${bad} тест(ов) упало`); process.exit(1); }
+console.log('\nвсе тесты черновика прошли');

package/src/test-prompts.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/** Задания для ИИ-агента: полнота, язык, запрет на выдумки. */
+import { agentPrompt, agentPrompts, renderAgentPrompts } from './prompts.mjs';
+import { FIX_ACTIONS } from './fix.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 c = (id, status, label, value) => ({ id, status, label, value, group: 'technical' });
+const audit = (checks, lang = 'en') => ({ meta: { host: 'x.ru', lang }, checks });
+
+const one = agentPrompt(c('alt', 'bad', 'Подписи к картинкам', '3 из 10 картинок с подписью'), { lang: 'ru' });
+ok('в задании есть точка отсчёта', one.includes('**Сейчас:** 3 из 10'));
+ok('в задании есть само действие', one.includes('**Задача:**'));
+ok('в задании есть признак готовности', one.includes('**Как проверить:**'));
+ok('в задании есть запрет выдумывать', one.includes('не выдумывай факты о бизнесе'));
+
+// Даже там, где своего текста нет, все три части на месте
+const generic = agentPrompt(c('xmlrpc', 'warn', 'xmlrpc.php', 'открыт'), { lang: 'ru' });
+ok('общее задание тоже с проверкой', generic.includes('**Как проверить:**'));
+ok('и с действием из набора работ', generic.includes('Закрыть открытую точку'));
+
+// Порядок: сначала провалы, потом предупреждения
+const list = agentPrompts(audit([c('og', 'warn', 'OG', 'нет'), c('robots', 'bad', 'robots', 'закрыт')]), { lang: 'ru' });
+is('первым идёт провал, а не предупреждение', list[0].id, 'robots');
+is('заданий столько же, сколько открытых проверок', list.length, 2);
+is('пройденные проверки заданий не порождают', agentPrompts(audit([c('og', 'ok', 'OG', 'есть')])).length, 0);
+is('лимит режет список', agentPrompts(audit([c('og', 'warn', 'OG', 'нет'), c('robots', 'bad', 'r', 'з')]), { limit: 1 }).length, 1);
+
+// Язык: русский файл по английскому аудиту не должен содержать английских проверок
+const ruFile = renderAgentPrompts(audit([c('alt', 'bad', 'Image alt text', '3 of 10 images carry alt text (30%) across 5 sampled page(s)')], 'en'), { lang: 'ru' });
+ok('название проверки переведено', ruFile.includes('Подписи к картинкам'));
+ok('и значение тоже', !ruFile.includes('images carry alt text'));
+const enFile = renderAgentPrompts(audit([c('alt', 'bad', 'Image alt text', '3 of 10 images')], 'en'), { lang: 'en' });
+ok('английский файл без кириллицы', !/[А-Яа-яЁё]/.test(enFile));
+
+// Задания не обещают того, чего мы не знаем
+const contact = agentPrompt(c('conv-messenger', 'bad', 'Мессенджер', 'нет'), { lang: 'ru' });
+ok('не выбирает мессенджер за клиента', /не знаешь, какой мессенджер|спроси владельца/.test(contact));
+const src = agentPrompt(c('sources', 'bad', 'Источники', '2 из 20'), { lang: 'ru' });
+ok('запрещает ставить ссылку наугад', /не ставь ссылку наугад|неверный источник хуже/.test(src));
+const af = agentPrompt(c('answer-first', 'bad', 'Ответ в начале', '2 из 20'), { lang: 'ru' });
+ok('запрещает придумывать цифру', /не придумывай её|спроси владельца/.test(af));
+
+// Покрытие: у каждой проверки, которую мы беремся чинить, задание осмысленное
+const mechanical = Object.entries(FIX_ACTIONS).filter(([, r]) => r.scope === 'always' || r.scope === 'files');
+const empty = mechanical.filter(([id]) => {
+  const p = agentPrompt(c(id, 'bad', id, 'значение'), { lang: 'ru' });
+  return !p.includes('**Задача:**') || p.split('**Задача:**')[1].trim().length < 20;
+}).map(([id]) => id);
+is('у каждой чинимой проверки есть внятное задание', empty, []);
+
+// Шапка файла объясняет, как этим пользоваться
+const head = renderAgentPrompts(audit([c('robots', 'bad', 'robots', 'закрыт')]), { lang: 'ru' });
+ok('шапка объясняет, что копировать', /Копируй задание целиком/.test(head));
+ok('и предупреждает делать по одному', /по одному заданию за раз/.test(head));
+ok('в файле нет пустых сдвоенных строк', !/\n\n\n/.test(head));
+
+if (bad) { console.error(`\n${bad} тест(ов) упало`); process.exit(1); }
+console.log('\nвсе тесты заданий прошли');