@aiguru/google-web-operations 0.6.4

package/packages/core/src/paths.js

@@ -0,0 +1,46 @@
+/**
+ * Where things live.
+ *
+ * Two layouts, decided once at startup:
+ *
+ *   checkout   the repository itself (has .git, not under node_modules):
+ *              sites/, .gwo-data/, secrets/ and .env sit next to the code.
+ *   installed  the package under a global node_modules (npm i -g), or any
+ *              copy without .git: operator state lives in GWO_HOME, default
+ *              ~/.gwo, so upgrading the package never touches sites, data
+ *              or secrets.
+ *
+ * Code paths (playbooks, hosts, the default policy) always come from the
+ * package. Each state path can still be overridden by its own variable.
+ * Everything resolves from this file's location, never from the working
+ * directory: the MCP server is launched by hosts from arbitrary directories.
+ */
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+/** Package root: packages/core/src -> ../../.. */
+export const ROOT = path.resolve(import.meta.dirname, '..', '..', '..');
+const env = (name) => process.env[name]?.trim() || undefined;
+const underNodeModules = /[\\/]node_modules[\\/]/.test(ROOT);
+/** Operator state directory. */
+export const HOME_DIR = env('GWO_HOME') ?? (!underNodeModules && existsSync(path.join(ROOT, '.git')) ? ROOT : path.join(homedir(), '.gwo'));
+export const IS_CHECKOUT = HOME_DIR === ROOT;
+// Operator configuration from <home>/.env (gitignored; see .env.example), and
+// from <root>/.env in a checkout. Loaded here because every app imports this
+// module first and hosts start the MCP server with no environment of their
+// own. Variables already set in the process win.
+for (const f of [...new Set([path.join(HOME_DIR, '.env'), path.join(ROOT, '.env')])]) {
+    try {
+        if (existsSync(f))
+            process.loadEnvFile(f);
+    }
+    catch { /* unreadable .env: run without it */ }
+}
+export const SITES_DIR = env('GWO_SITES_DIR') ?? path.join(HOME_DIR, 'sites');
+export const DATA_DIR = env('GWO_DATA_DIR') ?? path.join(HOME_DIR, '.gwo-data');
+export const SECRETS_DIR = env('GWO_SECRETS_DIR') ?? path.join(HOME_DIR, 'secrets');
+/** The operator may keep a tightened copy of the policy in the home directory; otherwise the package's. */
+export const POLICY_FILE = env('GWO_POLICY_FILE')
+    ?? (existsSync(path.join(HOME_DIR, 'policies', 'default.yaml')) ? path.join(HOME_DIR, 'policies', 'default.yaml') : path.join(ROOT, 'policies', 'default.yaml'));
+export const PLAYBOOKS_DIR = path.join(ROOT, 'packages', 'playbooks');
+export const HOSTS_DIR = path.join(ROOT, 'hosts');

package/packages/core/src/registry.js

@@ -0,0 +1,114 @@
+/**
+ * Site registry: one YAML file per site under sites/.
+ *
+ * Registry files hold references (ids, hosts, property names) and policy.
+ * Credentials live in sites/<host>.secrets.yaml, which is gitignored and
+ * merged in at load time under a separate key so they never leak into
+ * public views.
+ */
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { parse } from 'yaml';
+import { SITES_DIR } from "./paths.js";
+const REQUIRED = ['site_id', 'name', 'production_url'];
+/** Fill defaults and validate the few fields everything else depends on. */
+function normalise(raw, file) {
+    for (const k of REQUIRED) {
+        if (raw[k] === undefined || raw[k] === null || raw[k] === '') {
+            throw new Error(`${file}: missing required field "${k}"`);
+        }
+    }
+    const productionUrl = String(raw.production_url);
+    try {
+        new URL(productionUrl);
+    }
+    catch {
+        throw new Error(`${file}: production_url is not a URL`);
+    }
+    const seo = raw.seo ?? {};
+    const policy = raw.policy ?? {};
+    const cadence = raw.cadence ?? {};
+    return {
+        site_id: String(raw.site_id),
+        name: String(raw.name),
+        enabled: raw.enabled !== false,
+        production_url: productionUrl,
+        alt_hosts: raw.alt_hosts ?? [],
+        locales: raw.locales ?? [],
+        default_locale: String(raw.default_locale ?? raw.locales?.[0] ?? 'he'),
+        timezone: String(raw.timezone ?? 'Asia/Jerusalem'),
+        platform: raw.platform ?? 'custom',
+        tier: raw.tier ?? 'full',
+        seo: {
+            sitemap: seo.sitemap ?? '/sitemap.xml',
+            robots: seo.robots ?? '/robots.txt',
+            ...(seo.trailing_slash !== undefined ? { trailing_slash: seo.trailing_slash } : {}),
+        },
+        google: raw.google ?? {},
+        write: raw.write ?? { adapter: 'none' },
+        ...(raw.conversions ? { conversions: raw.conversions } : {}),
+        ...(raw.findings ? { findings: raw.findings } : {}),
+        policy: {
+            profile: policy.profile ?? 'standard-client-site',
+            ...(policy.overrides ? { overrides: policy.overrides } : {}),
+        },
+        cadence: { daily: cadence.daily ?? true, weekly: cadence.weekly ?? true, monthly: cadence.monthly ?? true },
+        ...(raw.contacts ? { contacts: raw.contacts } : {}),
+        ...(raw.notes ? { notes: String(raw.notes) } : {}),
+    };
+}
+/**
+ * A site file is any *.yaml in sites/ that is not documentation, a template,
+ * an example, or a secrets file. Exported so tests can pin the rule.
+ */
+export function isSiteFile(name) {
+    return name.endsWith('.yaml')
+        && !name.endsWith('.secrets.yaml')
+        && !name.endsWith('.example.yaml')
+        && !name.startsWith('schema')
+        && !name.startsWith('_');
+}
+/** Load all sites. Disabled sites are excluded unless asked for. */
+export function listSites({ includeDisabled = false } = {}) {
+    if (!existsSync(SITES_DIR))
+        return [];
+    const files = readdirSync(SITES_DIR).filter(isSiteFile);
+    const out = [];
+    for (const file of files) {
+        const full = path.join(SITES_DIR, file);
+        const raw = parse(readFileSync(full, 'utf8'));
+        const site = { ...normalise(raw, file), _file: file };
+        const secretsFile = full.replace(/\.yaml$/, '.secrets.yaml');
+        if (existsSync(secretsFile)) {
+            site._secrets = parse(readFileSync(secretsFile, 'utf8'));
+        }
+        if (site.enabled || includeDisabled)
+            out.push(site);
+    }
+    return out.sort((a, b) => a.site_id.localeCompare(b.site_id));
+}
+/** Find one site by id or by any of its hosts. */
+export function getSite(idOrHost) {
+    const all = listSites({ includeDisabled: true });
+    const needle = idOrHost.toLowerCase().replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+    const hit = all.find((s) => s.site_id.toLowerCase() === needle ||
+        hostOf(s.production_url) === needle ||
+        s.alt_hosts.some((h) => hostOf(h) === needle));
+    if (!hit) {
+        throw new Error(`Unknown site "${idOrHost}". Known: ${all.map((s) => s.site_id).join(', ') || '(none)'}`);
+    }
+    return hit;
+}
+/** The site record without secrets or loader metadata. Safe to return to a host. */
+export function publicView(site) {
+    const { _secrets: _s, _file: _f, ...rest } = site;
+    return rest;
+}
+function hostOf(u) {
+    try {
+        return new URL(u).host.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}

package/packages/core/src/report/monthly.js

@@ -0,0 +1,272 @@
+/**
+ * Monthly client report.
+ *
+ * Three parts, kept separate so each is testable on its own:
+ *   collectMonthly()      gathers the month's numbers: scan health now and
+ *                         a month ago, Search Console and GA4 totals for
+ *                         this month and last, and what the audit log says
+ *                         was done, blocked or proposed.
+ *   composeClientReport() turns numbers plus the agent's narrative into the
+ *                         client-facing document model (Hebrew or English),
+ *                         following the gwo-client-report-template playbook:
+ *                         three questions, one small table, no jargon. Pure.
+ *   renderClientReport()  writes the .docx (inside the company template when
+ *                         GWO_DOCX_TEMPLATE is set) and a Markdown twin.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { ga4, gsc } from "../../../connectors/google/src/index.js";
+import { buildDocx } from "../../../connectors/docx/src/index.js";
+import * as storage from "../../../storage/src/index.js";
+import { DATA_DIR } from "../paths.js";
+import { getSite } from "../registry.js";
+/** "YYYY-MM" -> this month and the previous one, as inclusive ISO date windows. */
+export function monthWindows(month) {
+    const m = month.match(/^(\d{4})-(\d{2})$/);
+    if (!m)
+        throw new Error(`month must be YYYY-MM, got "${month}"`);
+    const y = Number(m[1]), mo = Number(m[2]) - 1;
+    const iso = (d) => d.toISOString().slice(0, 10);
+    const first = new Date(Date.UTC(y, mo, 1)), last = new Date(Date.UTC(y, mo + 1, 0));
+    const pFirst = new Date(Date.UTC(y, mo - 1, 1)), pLast = new Date(Date.UTC(y, mo, 0));
+    return { month: { start: iso(first), end: iso(last) }, previous: { start: iso(pFirst), end: iso(pLast) }, label: first };
+}
+/** The month before the current one: the one a report is normally written for. */
+export function defaultMonth(now = new Date()) {
+    const d = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1));
+    return d.toISOString().slice(0, 7);
+}
+const problems = (s) => s.blocker + s.high + s.medium;
+export async function collectMonthly(site, month) {
+    const windows = monthWindows(month);
+    const scan = storage.loadScan(site.site_id);
+    const snaps = storage.listSnapshots(site.site_id);
+    const beforeName = [...snaps].reverse().find((n) => n < windows.month.start);
+    const beforeSnap = beforeName ? storage.loadSnapshot(site.site_id, beforeName) : null;
+    const data = {
+        siteId: site.site_id, siteName: site.name, month, windows,
+        health: {
+            now: scan ? { pages: scan.pagesCrawled, summary: scan.summary, suppressed: scan.suppressed?.count ?? 0 } : null,
+            before: beforeSnap?.findingsBySeverity ?? null,
+        },
+        search: null, searchError: null, traffic: null, trafficError: null,
+        activity: { scans: 0, writes: {}, blocked: 0, proposed: 0 },
+    };
+    const property = site.google.search_console?.property;
+    if (property) {
+        try {
+            const totals = async (w) => {
+                const r = await gsc.summarisePerformance(property, w.start, w.end, 5);
+                return { clicks: r.totals?.clicks ?? 0, impressions: r.totals?.impressions ?? 0, position: r.totals?.position ?? null };
+            };
+            data.search = { now: await totals(windows.month), before: await totals(windows.previous) };
+        }
+        catch (e) {
+            data.searchError = e.message;
+        }
+    }
+    const pid = site.google.ga4?.property_id;
+    if (pid) {
+        try {
+            const sum = async (w) => {
+                const r = (await ga4.summariseTraffic(pid, w.start, w.end));
+                let sessions = 0, keyEvents = 0;
+                for (const row of r.rows ?? []) {
+                    sessions += Number(row.metricValues?.[0]?.value ?? 0);
+                    keyEvents += Number(row.metricValues?.[2]?.value ?? 0);
+                }
+                return { sessions, keyEvents };
+            };
+            data.traffic = { now: await sum(windows.month), before: await sum(windows.previous) };
+        }
+        catch (e) {
+            data.trafficError = e.message;
+        }
+    }
+    const inMonth = (r) => r.at >= windows.month.start && r.at < `${windows.month.end}T23:59:59.999Z`;
+    for (const r of storage.readAudit(site.site_id, { limit: 10_000 }).filter(inMonth)) {
+        if (r.operation === 'web.scan')
+            data.activity.scans++;
+        else if (r.status === 'success' && r.verified)
+            data.activity.writes[r.operation] = (data.activity.writes[r.operation] ?? 0) + 1;
+        else if (r.status === 'blocked')
+            data.activity.blocked++;
+        else if (r.status === 'proposed')
+            data.activity.proposed++;
+    }
+    return data;
+}
+const T = {
+    he: {
+        title: (name) => `דוח חודשי: ${name}`,
+        by: 'AI Guru, תפעול אתרים',
+        how: 'איך האתר מתפקד', did: 'מה עשינו החודש', need: 'מה אנחנו צריכים מכם', next: 'החודש הבא',
+        cols: ['', 'החודש', 'חודש שעבר', 'שינוי'],
+        rows: ['ביקורים מגוגל', 'הופעות בתוצאות החיפוש', 'מיקום ממוצע'],
+        noSearch: 'נתוני החיפוש של גוגל עדיין לא מחוברים לדוח הזה. נחבר אותם ברגע שהגישה תאושר.',
+        traffic: (s, k, ps) => `בסך הכול ${fmt(s)} ביקורים באתר החודש (${fmt(ps)} בחודש שעבר), מתוכם ${fmt(k)} פניות שנמדדו.`,
+        health: (pages, now, before) => `בבדיקה הטכנית האחרונה נסרקו ${fmt(pages)} עמודים. ${now === 0 ? 'לא נמצאו בעיות שדורשות טיפול' : `${fmt(now)} נושאים דורשים טיפול`}${before !== null ? ` (${fmt(before)} בתחילת החודש)` : ''}.`,
+        autoHeadline: (c, p) => c === 0 && p === 0 ? 'האתר עדיין בשלב בניית הנוכחות בגוגל: התנועה מחיפוש נמוכה, וזה צפוי בשלב הזה.' : c >= p ? `יותר ביקורים מגוגל מאשר בחודש שעבר: ${fmt(c)} לעומת ${fmt(p)}.` : `פחות ביקורים מגוגל מאשר בחודש שעבר: ${fmt(c)} לעומת ${fmt(p)}. פירוט בהמשך.`,
+        scans: (n) => `ביצענו ${fmt(n)} בדיקות אוטומטיות של האתר, כולל מעקב יומי אחרי שינויים ותקלות.`,
+        ops: {
+            'gsc.submit_sitemap': () => 'הגשנו לגוגל מפת אתר מעודכנת.',
+            'content.set_meta_description': (n) => `כתבנו תיאורים לתוצאות החיפוש עבור ${fmt(n)} עמודים.`,
+            'content.set_title': (n) => `שיפרנו כותרות ב-${fmt(n)} עמודים.`,
+            'content.set_schema': (n) => `הוספנו נתונים מובנים שעוזרים לגוגל ולמנועי AI להבין ${fmt(n)} עמודים.`,
+            'ga4.create_key_event': () => 'הגדרנו את מדידת הפניות באנליטיקס.',
+            'gtm.publish': () => 'עדכנו את מערך המדידה באתר.',
+            'gtm.workspace.create': null, 'gtm.stage.tag': null, 'gtm.stage.trigger': null, 'gtm.stage.variable': null,
+            'github.open_pr': (n) => `הגשנו ${fmt(n)} חבילות שינויים לאישור המפתח.`,
+        },
+        otherOp: (n) => `בוצעו ${fmt(n)} שינויים נוספים באתר, כולם אומתו.`,
+        nothingDone: 'החודש עקבנו אחרי האתר ולא נדרש שינוי.',
+        pending: (n) => `${fmt(n)} שינויים מוצעים ממתינים לאישורכם. נשמח לעבור עליהם יחד.`,
+        nothingNeeded: 'אין צורך בדבר החודש.',
+        defaultNext: 'נמשיך במעקב היומי ובשיפורים השבועיים, ונעדכן על כל שינוי מהותי.',
+    },
+    en: {
+        title: (name) => `Monthly report: ${name}`,
+        by: 'AI Guru, web operations',
+        how: 'How the site is doing', did: 'What we did this month', need: 'What we need from you', next: 'Next month',
+        cols: ['', 'This month', 'Last month', 'Change'],
+        rows: ['Visits from Google', 'Times shown in results', 'Average position'],
+        noSearch: 'Google Search data is not connected to this report yet. It will be as soon as access is granted.',
+        traffic: (s, k, ps) => `${fmt(s, 'en')} visits in total this month (${fmt(ps, 'en')} last month), of which ${fmt(k, 'en')} measured enquiries.`,
+        health: (pages, now, before) => `The last technical check covered ${fmt(pages, 'en')} pages. ${now === 0 ? 'Nothing needs attention' : `${fmt(now, 'en')} items need attention`}${before !== null ? ` (${fmt(before, 'en')} at the start of the month)` : ''}.`,
+        autoHeadline: (c, p) => c === 0 && p === 0 ? 'The site is still building its presence on Google: search traffic is low, which is expected at this stage.' : c >= p ? `More visits from Google than last month: ${fmt(c, 'en')} against ${fmt(p, 'en')}.` : `Fewer visits from Google than last month: ${fmt(c, 'en')} against ${fmt(p, 'en')}. Details below.`,
+        scans: (n) => `We ran ${fmt(n, 'en')} automated checks of the site, including daily monitoring for changes and faults.`,
+        ops: {
+            'gsc.submit_sitemap': () => 'Submitted an updated sitemap to Google.',
+            'content.set_meta_description': (n) => `Wrote search-result descriptions for ${fmt(n, 'en')} pages.`,
+            'content.set_title': (n) => `Improved titles on ${fmt(n, 'en')} pages.`,
+            'content.set_schema': (n) => `Added structured data that helps Google and AI engines understand ${fmt(n, 'en')} pages.`,
+            'ga4.create_key_event': () => 'Set up enquiry measurement in Analytics.',
+            'gtm.publish': () => 'Updated the site\'s measurement setup.',
+            'gtm.workspace.create': null, 'gtm.stage.tag': null, 'gtm.stage.trigger': null, 'gtm.stage.variable': null,
+            'github.open_pr': (n) => `Submitted ${fmt(n, 'en')} change sets for the developer to approve.`,
+        },
+        otherOp: (n) => `${fmt(n, 'en')} further changes were made to the site, all verified.`,
+        nothingDone: 'This month we monitored the site and no change was needed.',
+        pending: (n) => `${fmt(n, 'en')} proposed changes are waiting for your approval. We would be glad to go through them with you.`,
+        nothingNeeded: 'Nothing this month.',
+        defaultNext: 'We continue the daily monitoring and weekly improvements, and will flag anything material.',
+    },
+};
+function fmt(n, lang = 'he') {
+    return new Intl.NumberFormat(lang === 'he' ? 'he-IL' : 'en-GB', { maximumFractionDigits: 1 }).format(n);
+}
+function delta(now, before, lang, invert = false) {
+    if (before === 0 && now === 0)
+        return '–';
+    const d = now - before;
+    const good = invert ? d < 0 : d > 0;
+    const sign = d > 0 ? '+' : '';
+    const pct = before ? ` (${sign}${Math.round((d / before) * 100)}%)` : '';
+    return `${sign}${fmt(d, lang)}${pct}${d === 0 ? '' : good ? ' ▲' : ' ▼'}`;
+}
+function monthLabel(d, lang) {
+    return new Intl.DateTimeFormat(lang === 'he' ? 'he' : 'en-GB', { month: 'long', year: 'numeric', timeZone: 'UTC' }).format(d);
+}
+/** Client-facing document from numbers plus narrative. Pure. */
+export function composeClientReport(data, narrative, lang) {
+    const t = T[lang];
+    const blocks = [];
+    const title = t.title(data.siteName);
+    blocks.push({ kind: 'title', text: title });
+    blocks.push({ kind: 'subtitle', text: `${monthLabel(data.windows.label, lang)} · ${t.by}` });
+    // 1. How the site is doing
+    blocks.push({ kind: 'heading', level: 1, text: t.how });
+    const s = data.search;
+    blocks.push({ kind: 'paragraph', text: narrative.headline ?? (s ? t.autoHeadline(s.now.clicks, s.before.clicks) : t.noSearch) });
+    if (s) {
+        blocks.push({ kind: 'table', header: t.cols, rows: [
+                [t.rows[0], fmt(s.now.clicks, lang), fmt(s.before.clicks, lang), delta(s.now.clicks, s.before.clicks, lang)],
+                [t.rows[1], fmt(s.now.impressions, lang), fmt(s.before.impressions, lang), delta(s.now.impressions, s.before.impressions, lang)],
+                [t.rows[2], s.now.position === null ? '–' : fmt(s.now.position, lang), s.before.position === null ? '–' : fmt(s.before.position, lang),
+                    s.now.position !== null && s.before.position !== null ? delta(s.now.position, s.before.position, lang, true) : '–'],
+            ] });
+    }
+    if (data.traffic)
+        blocks.push({ kind: 'paragraph', text: t.traffic(data.traffic.now.sessions, data.traffic.now.keyEvents, data.traffic.before.sessions) });
+    if (data.health.now) {
+        blocks.push({ kind: 'paragraph', text: t.health(data.health.now.pages, problems(data.health.now.summary), data.health.before ? problems(data.health.before) : null) });
+    }
+    // 2. What we did
+    blocks.push({ kind: 'heading', level: 1, text: t.did });
+    let did = narrative.did;
+    if (!did) {
+        did = [];
+        if (data.activity.scans)
+            did.push(t.scans(data.activity.scans));
+        let other = 0;
+        for (const [op, n] of Object.entries(data.activity.writes)) {
+            const phrase = t.ops[op];
+            if (phrase === null)
+                continue; // internal step, covered by its parent operation
+            if (phrase)
+                did.push(phrase(n));
+            else
+                other += n;
+        }
+        if (other)
+            did.push(t.otherOp(other));
+        if (!did.length)
+            did.push(t.nothingDone);
+    }
+    blocks.push({ kind: 'bullets', items: did });
+    // 3. What we need
+    blocks.push({ kind: 'heading', level: 1, text: t.need });
+    const need = narrative.need ?? (data.activity.blocked + data.activity.proposed ? [t.pending(data.activity.blocked + data.activity.proposed)] : [t.nothingNeeded]);
+    blocks.push({ kind: 'bullets', items: need });
+    // 4. Next month
+    blocks.push({ kind: 'heading', level: 1, text: t.next });
+    blocks.push({ kind: 'paragraph', text: narrative.next ?? t.defaultNext });
+    return { title, lang, blocks, markdown: toMarkdown(blocks) };
+}
+function toMarkdown(blocks) {
+    const out = [];
+    for (const b of blocks) {
+        switch (b.kind) {
+            case 'title':
+                out.push(`# ${b.text}`, '');
+                break;
+            case 'subtitle':
+                out.push(`*${b.text}*`, '');
+                break;
+            case 'heading':
+                out.push(`${'#'.repeat(b.level + 1)} ${b.text}`, '');
+                break;
+            case 'paragraph':
+                out.push(b.text, '');
+                break;
+            case 'bullets':
+                out.push(...b.items.map((i) => `- ${i}`), '');
+                break;
+            case 'table':
+                out.push(`| ${b.header.join(' | ')} |`, `|${b.header.map(() => '---').join('|')}|`, ...b.rows.map((r) => `| ${r.join(' | ')} |`), '');
+                break;
+        }
+    }
+    return out.join('\n').trim() + '\n';
+}
+/** Collect, compose, write .docx and .md under .gwo-data/<site>/reports/. */
+export async function renderClientReport(siteIdOrHost, opts = {}) {
+    const site = getSite(siteIdOrHost);
+    const month = opts.month ?? defaultMonth();
+    const lang = opts.lang ?? (site.default_locale.toLowerCase().startsWith('he') ? 'he' : 'en');
+    const data = await collectMonthly(site, month);
+    const report = composeClientReport(data, opts.narrative ?? {}, lang);
+    const templatePath = opts.templatePath ?? process.env['GWO_DOCX_TEMPLATE']?.trim() ?? '';
+    const template = templatePath && existsSync(templatePath) ? templatePath : undefined;
+    const bytes = await buildDocx({ blocks: report.blocks, rtl: lang === 'he', title: report.title }, template ? { templatePath: template } : {});
+    const dir = opts.outDir ?? path.join(DATA_DIR, site.site_id, 'reports');
+    mkdirSync(dir, { recursive: true });
+    const docx = path.join(dir, `${month}-client.docx`), md = path.join(dir, `${month}-client.md`);
+    writeFileSync(docx, bytes);
+    writeFileSync(md, report.markdown);
+    storage.appendAudit({ siteId: site.site_id, operation: 'report.client_monthly', status: 'observed', risk: 'auto',
+        summary: `Client report for ${month} (${lang}) written to ${docx}${template ? ' in the company template' : ' without a template'}`,
+        data: { search: data.search, traffic: data.traffic, activity: data.activity } });
+    return { docx, md, template: template ?? null, lang, month, markdown: report.markdown,
+        notes: [data.searchError && `Search Console: ${data.searchError}`, data.trafficError && `GA4: ${data.trafficError}`].filter(Boolean) };
+}

package/packages/core/src/scan/render.js

@@ -0,0 +1,40 @@
+export function renderScan(scan, { maxGroups = 40 } = {}) {
+    const s = scan.summary;
+    const lines = [];
+    lines.push(`# Site scan: ${scan.origin}`);
+    lines.push(`Crawled ${scan.pagesCrawled} pages in ${(scan.durationMs / 1000).toFixed(1)}s at ${scan.at}`);
+    lines.push(`Sitemap: ${scan.sitemap.ok ? `${scan.sitemap.count} URLs` : `unreachable (${scan.sitemap.status})`}`);
+    lines.push(`Findings: ${s.blocker} blocker, ${s.high} high, ${s.medium} medium, ${s.low} low, ${s.info} info`);
+    const sup = scan.suppressed ?? { count: 0, rules: {} };
+    if (sup.count)
+        lines.push(`Suppressed by site decisions: ${sup.count} (${Object.entries(sup.rules).map(([id, n]) => `${id} x${n}`).join(', ')})`);
+    lines.push('');
+    const blocked = scan.robotsChecks.filter((c) => c.kind === 'ai' && !c.allowed).map((c) => c.agent);
+    lines.push(`AI crawlers: ${blocked.length ? `blocked ${blocked.join(', ')}` : 'none blocked'}; llms.txt: ${scan.llmsTxt.ok ? 'present' : 'absent'}`);
+    const live = scan.hostProbe.filter((h) => h.status >= 200 && h.status < 300).map((h) => h.url);
+    lines.push(`Host variants answering 200: ${live.join(', ') || 'none (root redirects)'}`);
+    lines.push('');
+    const grouped = new Map();
+    for (const x of scan.findings)
+        grouped.set(x.id, [...(grouped.get(x.id) ?? []), x]);
+    const entries = [...grouped.entries()];
+    const shown = entries.slice(0, maxGroups);
+    lines.push('## Findings (grouped by rule, most severe first; low and info are opportunities, not faults)');
+    for (const [id, group] of shown) {
+        const x = group[0];
+        const scope = x.url ? `${group.length} page${group.length > 1 ? 's' : ''}` : 'site-wide';
+        lines.push(`- [${x.severity.toUpperCase()}] ${x.title}  (${id}; ${scope})`);
+        lines.push(`  ${x.detail}`);
+        if (x.evidence)
+            lines.push(`  evidence: ${x.evidence.split('\n')[0]?.slice(0, 160)}`);
+        if (x.fix)
+            lines.push(`  fix: ${x.fix}`);
+        if (x.url && group.length > 1 && group.length <= 6)
+            lines.push(`  pages: ${group.map((g) => g.url).join(', ')}`);
+        else if (x.url && group.length > 6)
+            lines.push(`  pages: ${group.slice(0, 3).map((g) => g.url).join(', ')} and ${group.length - 3} more`);
+    }
+    if (entries.length > shown.length)
+        lines.push(`... ${entries.length - shown.length} more rule groups in the saved scan file.`);
+    return lines.join('\n');
+}