@operstack/audit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OperStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @operstack/audit
+
+The SEO, AEO and GEO audit generator behind the OperStack audit service. It collects the public signals of a site into one JSON file, leaves the narrative to an analyst or an agent, and renders a print-ready report.
+
+```
+npx @operstack/audit collect https://example.com --pages 20 --out audit.json
+npx @operstack/audit check audit.json
+npx @operstack/audit render audit.json --pdf
+```
+
+## What `collect` gathers
+
+Everything an external auditor can see without Search Console or analytics access:
+
+- HTTPS, www canonicalisation, time to first byte on the homepage.
+- robots.txt, the sitemap it names (or the usual paths), the URL count, foreign hosts in the sitemap, sitemap URLs that redirect or break.
+- llms.txt: present, text or HTML, and whether its links point at the site or somewhere else.
+- The homepage and a sample of pages from the sitemap: title and description lengths, shortcodes or encoded data in the description, H1 count, alt coverage, canonical, robots meta, viewport (zoom blocked), Open Graph and Twitter cards, JSON-LD types (FAQPage, Organization and business types), script and stylesheet counts, hreflang, exposed dates, word counts, duplicate titles, thin pages, utility pages in the index, and on WordPress the xmlrpc endpoint.
+
+Every finding becomes a row with a status (`ok`, `warn`, `bad`, `na`), a value and a comment. `bad` rows are copied into the critical-issues page automatically. Scores per group are suggested from the statuses; the analyst can overwrite them.
+
+## What the analyst writes
+
+`check` lists every narrative field still holding a `{{placeholder}}`: the client name and subject, the executive summary and verdict, three priorities, the overview note, content strengths and gaps, the AEO and GEO commentary, off-page, conversion rows, the roadmap and the closing message. The rendered report highlights any placeholder in yellow so a draft cannot ship by accident.
+
+An agent can fill these fields from the JSON: the Claude Code plugin `operstack-seo` reads `audit.json`, writes the narrative and calls `render`.
+
+## What `render` produces
+
+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).
+
+## Example
+
+`examples/sample-audit.json` is a complete, fictional audit of "Example Villas". `npm run sample` renders it to HTML and PDF next to the JSON.
+
+## Limits
+
+The external tier reads public pages only. It does not run a lab performance test, does not query keyword or backlink tools, and does not see impressions or conversions. The report says so on its limitations page.
+
+## License
+
+MIT. Built by OperStack.

package/bin/audit.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * OperStack audit generator.
+ *
+ *   operstack-audit collect https://example.com [--pages 20] [--out audit.json]
+ *       fetches the public signals (robots, sitemaps, llms.txt, sampled pages) and writes
+ *       audit.json with every technical row filled and the narrative fields left for the analyst
+ *   operstack-audit render audit.json [--out report.html] [--pdf]
+ *       renders the report from the JSON; --pdf also prints a PDF with headless Chrome
+ *   operstack-audit check audit.json
+ *       lists narrative fields still holding placeholders
+ */
+import { collect } from '../src/collect.mjs';
+import { render, checkNarrative } from '../src/render.mjs';
+import { writeFileSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const [cmd, target, ...rest] = process.argv.slice(2);
+const opt = (k, d) => { const i = rest.indexOf(k); return i === -1 ? d : rest[i + 1]; };
+const has = (k) => rest.includes(k);
+
+if (!cmd || cmd === '--help' || cmd === '-h') {
+  console.log('Usage:\n  operstack-audit collect <url> [--pages 20] [--out audit.json]\n  operstack-audit render <audit.json> [--out report.html] [--pdf]\n  operstack-audit check <audit.json>');
+  process.exit(cmd ? 0 : 2);
+}
+if (cmd === 'collect') {
+  if (!/^https?:\/\//.test(target || '')) { console.error('collect needs an absolute URL'); process.exit(2); }
+  const audit = await collect(target, { pages: Number(opt('--pages', 20)), log: (m) => console.error(`  ${m}`) });
+  const out = resolve(opt('--out', 'audit.json'));
+  writeFileSync(out, JSON.stringify(audit, null, 2));
+  console.log(`wrote ${out}: ${audit.checks.length} checks, ${audit.sample.length} pages sampled, suggested scores ${Object.entries(audit.scores).map(([k, v]) => `${k} ${v}`).join(', ')}`);
+  console.log(`next: fill the narrative fields (operstack-audit check ${out} lists them), then render.`);
+} else if (cmd === 'render') {
+  const audit = JSON.parse(readFileSync(resolve(target), 'utf8'));
+  const out = resolve(opt('--out', target.replace(/\.json$/, '') + '.html'));
+  const { html, pdf } = await render(audit, { out, pdf: has('--pdf') });
+  console.log(`wrote ${out} (${html.length} bytes)${pdf ? `\nwrote ${pdf}` : ''}`);
+  const missing = checkNarrative(audit);
+  if (missing.length) console.log(`note: ${missing.length} narrative field(s) still carry placeholders: ${missing.slice(0, 6).join(', ')}${missing.length > 6 ? ', ...' : ''}`);
+} else if (cmd === 'check') {
+  const audit = JSON.parse(readFileSync(resolve(target), 'utf8'));
+  const missing = checkNarrative(audit);
+  if (!missing.length) console.log('every narrative field is written');
+  else { console.log(`${missing.length} field(s) to write:`); for (const m of missing) console.log(`  ${m}`); process.exit(1); }
+} else { console.error(`unknown command ${cmd}`); process.exit(2); }

package/examples/sample-audit.json

@@ -0,0 +1,79 @@
+{
+  "meta": { "site": "https://www.example-villas.example/", "host": "www.example-villas.example", "collectedAt": "2026-09-10T09:00:00.000Z", "tool": "@operstack/audit 0.1.0", "auditType": "External audit (no Search Console or analytics access)" },
+  "client": { "name": "Example Villas", "subject": "A pool villa developer's site in a fictional resort market: technical SEO, content, answer-engine readiness and a 90 day plan.", "reportDate": "2026-09-10", "preparedBy": "OperStack" },
+  "scores": { "SEO, technical": 3, "SEO, content and structure": 4, "AEO, answers and snippets": 5, "GEO, visibility in AI systems": 2, "Off-page and trust": 6, "Conversion and UX": 5 },
+  "scoreNotes": { "SEO, technical": "Broken sitemap, slow first byte, template leftovers", "SEO, content and structure": "A blog exists; the homepage sells three things at once", "AEO, answers and snippets": "FAQ schema present, answers shallow", "GEO, visibility in AI systems": "llms.txt points at a demo domain", "Off-page and trust": "Portal listings exist, brand name collides", "Conversion and UX": "Form works, price is a placeholder" },
+  "summary": {
+    "lead": "The site is a working marketing page for a villa developer. Search engines index about 18 pages, an eight-article blog is live and FAQ markup is in place. It does not work as a search engine asset yet: the sitemap answers 404, the homepage description carries a form shortcode, and the AI index describes another business.",
+    "verdict": "The site is not invisible, it is misread. Three technical defects and a homepage that sells three products at once cost it most of its organic potential. Every critical item can be fixed inside two weeks.",
+    "priorities": ["Technical foundation: sitemap, meta description, llms.txt, utility pages out of the index.", "Demand-led structure: one page per project, one per location, one buyer guide.", "Trust content: sourced ownership answers, comparison tables and a FAQ that answer engines can quote."]
+  },
+  "overview": {
+    "rows": [["CMS / stack", "WordPress, page builder, commerce plugin, forms plugin"], ["Pages in sitemap", "21"], ["Language", "English, single version"], ["What is sold", "Two villa projects presented on one homepage"]],
+    "note": "Three offers share the homepage: a price headline with a placeholder, a block about a seven-villa project and a block about a second phase with overlapping copy. A visitor and a crawler both leave unsure which product the site sells."
+  },
+  "critical": [
+    { "title": "XML sitemap answers 404", "text": "robots.txt points at sitemap_index.xml and the server returns 404. Search engines crawl without a map: slower and less complete.", "level": "bad" },
+    { "title": "Homepage meta description contains a form shortcode", "text": "The description field holds an encoded form tag. In results it renders as technical garbage instead of a sales sentence.", "level": "bad" },
+    { "title": "llms.txt describes a demo site", "text": "The file exists, which is a positive signal, but its links go to a template demo domain with unrelated products. An AI system reading it may misidentify the business.", "level": "bad" },
+    { "title": "Commerce utility pages are indexable", "text": "Shop, compare and wishlist pages carry index directives and demo products. They add noise to a 21 page index.", "level": "warn" }
+  ],
+  "checks": [
+    { "id": "https", "group": "technical", "label": "HTTPS", "status": "ok", "value": "certificate active" },
+    { "id": "www", "group": "technical", "label": "www canonicalisation", "status": "ok", "value": "non-www redirects to www (301)" },
+    { "id": "ttfb", "group": "technical", "label": "Time to first byte (homepage)", "status": "bad", "value": "3,300 ms", "comment": "single request from the auditor, not a lab test" },
+    { "id": "robots", "group": "technical", "label": "robots.txt", "status": "warn", "value": "3 disallow rule(s), 1 sitemap line(s)", "comment": "the sitemap it names answers 404" },
+    { "id": "sitemap", "group": "technical", "label": "XML sitemap", "status": "bad", "value": "sitemap_index.xml answers HTTP 404" },
+    { "id": "canonical", "group": "technical", "label": "Canonical tag", "status": "ok", "value": "https://www.example-villas.example/" },
+    { "id": "viewport", "group": "technical", "label": "Mobile viewport", "status": "warn", "value": "width=device-width, initial-scale=1, user-scalable=no", "comment": "blocks zoom: bad for accessibility and mobile SEO" },
+    { "id": "og", "group": "technical", "label": "Open Graph and Twitter cards", "status": "warn", "value": "og:title, og:image, twitter:summary_large_image", "comment": "description carries the same shortcode" },
+    { "id": "resources", "group": "technical", "label": "Page weight (homepage)", "status": "bad", "value": "39 script file(s), 14 stylesheet(s), 39 image(s)" },
+    { "id": "title", "group": "onpage", "label": "Homepage title", "status": "warn", "value": "\"Home - Example Villas\" (21 chars)", "comment": "short: the words that earn the click are missing" },
+    { "id": "description", "group": "onpage", "label": "Homepage meta description", "status": "bad", "value": "contains a shortcode or encoded data" },
+    { "id": "h1", "group": "onpage", "label": "H1 on homepage", "status": "warn", "value": "3 H1 tag(s)", "comment": "more than one H1 dilutes the page topic" },
+    { "id": "alt", "group": "onpage", "label": "Image alt text", "status": "bad", "value": "3 of 39 images carry alt text (8%) across 12 sampled page(s)" },
+    { "id": "h1-sample", "group": "onpage", "label": "Heading structure across sample", "status": "bad", "value": "9 of 12 pages carry more than one H1" },
+    { "id": "thin", "group": "content", "label": "Thin pages in sample", "status": "ok", "value": "median 1,600 words per page" },
+    { "id": "dates", "group": "content", "label": "Publication dates exposed", "status": "warn", "value": "modified dates precede published dates on 3 articles" },
+    { "id": "schema", "group": "aeo", "label": "Structured data on homepage", "status": "ok", "value": "RealEstateAgent, Organization, FAQPage" },
+    { "id": "faq-schema", "group": "aeo", "label": "FAQPage schema", "status": "ok", "value": "present on 1 sampled page(s)" },
+    { "id": "llms", "group": "geo", "label": "llms.txt", "status": "bad", "value": "14 link(s), 12 to other hosts", "comment": "links to a template demo domain: an AI system may misidentify the business" },
+    { "id": "org-schema", "group": "geo", "label": "Organization or business schema", "status": "ok", "value": "present" }
+  ],
+  "content": {
+    "strengths": ["FAQ block on the homepage, a base for answer engines", "Enquiry form with a budget field", "Location block with real distances", "Key features with figures: 7 villas, 240 sqm plots"],
+    "weaknesses": ["Title and description do not name the product or the place", "No single H1 with the project name and a real price", "The ownership FAQ is one sentence where buyers need a table", "Two different office addresses in the footer"],
+    "gaps": ["/projects/<name>/: prices, floor plans, gallery, FAQ", "/location/<district>/: map, distances, infrastructure", "/foreign-buyers-guide/: ownership routes, fees, timeline", "/availability/: current prices and stock"]
+  },
+  "aeo": {
+    "works": ["FAQPage schema with seven questions", "Organization and business schema", "Question and answer format in the FAQ block", "Blog articles cover informational intent"],
+    "blocks": ["Ownership answers too short: no lease route, no risks", "No comparison tables for ownership options", "No sourced yield or price figures", "No expert bylines"],
+    "recommendation": "Publish one buyer guide with tables on ownership routes, fees and timeline, written so that a single paragraph can be quoted as the answer."
+  },
+  "geo": {
+    "rows": [["Entity clarity", "△ Weak", "Schema present, but content confuses two project names"], ["Brand disambiguation", "✗ Problem", "The brand name matches a residential district in another country"], ["Third-party mentions", "✓ Present", "Listings on three property portals"], ["Reviews and PR", "✗ None", "No independent reviews found"]],
+    "callout": "Brand collision: for the bare brand name, search engines show a district elsewhere rather than the developer. Use the brand together with the place in titles, schema and external profiles."
+  },
+  "offpage": {
+    "listed": ["Two property portals carry the project with prices", "One aggregator carries a developer profile", "One agency page carries villa specifications"],
+    "note": "Portal listings drive discovery, but the authority accrues to the portals. The owned site's job is to become the primary source the portals link to."
+  },
+  "conversion": {
+    "rows": [["Enquiry form", "✓ Works, budget field present"], ["Price on homepage", "✗ Placeholder instead of a figure"], ["Footer address", "✗ Two different addresses"], ["Call to action", "△ No clear next step"], ["Messengers", "△ Phone and email only"], ["Commerce plugin for 3 villas", "△ Adds weight without benefit"]]
+  },
+  "limitations": ["Google Search Console: no impressions, clicks or query data", "Analytics: no traffic or behaviour data", "Keyword and backlink tools: not used in the external tier", "Lab performance report: not run; the first-byte figure is a single request"],
+  "roadmap": [
+    { "badge": "Week 1", "title": "Critical, quick wins", "items": ["Fix the XML sitemap and confirm the URL in robots.txt answers 200", "Rewrite the homepage title and description; remove the shortcode", "Rewrite llms.txt for the actual business; remove demo links", "Set noindex on shop, compare and wishlist", "One H1 on the homepage with the project name and a real starting price", "Remove user-scalable=no"] },
+    { "badge": "Weeks 2 to 4", "title": "Foundation", "items": ["Project page with prices, plans and FAQ", "Buyer guide with ownership routes and fees", "Location page with map and distances", "Alt text on every image", "Search Console and Bing Webmaster connected", "One product line on the homepage, or two clearly separated"] },
+    { "badge": "Months 2 to 3", "title": "Organic growth, AEO and GEO", "items": ["12 to 15 articles by intent cluster", "Product and place schema on villa pages", "PR and mentions in local property media", "Business profile for the office and the project location", "FAQ expanded to 15 to 20 sourced answers", "Comparison tables for ownership, fees and timeline"] }
+  ],
+  "closing": "A beautiful site and a search asset are not the same thing. This one is pointed the right way, with a blog, a FAQ and schema, but was never cleaned up after launching on a template. The critical items take two weeks and show in Search Console within 30 to 60 days.",
+  "sample": [
+    { "url": "https://www.example-villas.example/", "title": "Home - Example Villas", "words": 940, "h1Count": 3, "images": 21, "imagesNoAlt": 19, "schemaTypes": ["RealEstateAgent", "Organization", "FAQPage"] },
+    { "url": "https://www.example-villas.example/about/", "title": "About - Example Villas", "words": 420, "h1Count": 2, "images": 6, "imagesNoAlt": 6, "schemaTypes": [] },
+    { "url": "https://www.example-villas.example/blog/why-invest/", "title": "Why invest in a pool villa", "words": 1610, "h1Count": 2, "images": 4, "imagesNoAlt": 4, "schemaTypes": ["Article"] },
+    { "url": "https://www.example-villas.example/blog/location/", "title": "The location explained", "words": 1580, "h1Count": 2, "images": 5, "imagesNoAlt": 4, "schemaTypes": ["Article"] },
+    { "url": "https://www.example-villas.example/contact/", "title": "Contact - Example Villas", "words": 180, "h1Count": 1, "images": 3, "imagesNoAlt": 3, "schemaTypes": [] }
+  ],
+  "notes": []
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@operstack/audit",
+  "version": "0.1.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",
+  "author": "OperStack",
+  "bin": { "operstack-audit": "bin/audit.mjs" },
+  "exports": { ".": "./src/index.mjs" },
+  "files": ["bin", "src", "templates", "examples/sample-audit.json", "README.md", "LICENSE"],
+  "scripts": {
+    "test": "node bin/audit.mjs render examples/sample-audit.json --out /tmp/operstack-audit-sample.html && node -e \"const s=require('fs').readFileSync('/tmp/operstack-audit-sample.html','utf8'); if(!s.includes('Executive summary')) process.exit(1); console.log('render ok', s.length, 'bytes')\"",
+    "sample": "node bin/audit.mjs render examples/sample-audit.json --pdf"
+  },
+  "keywords": ["seo", "aeo", "geo", "audit", "llms-txt", "site-audit", "report"],
+  "engines": { "node": ">=20" },
+  "dependencies": { "node-html-parser": "^9.0.4" }
+}

package/src/collect.mjs

@@ -0,0 +1,228 @@
+/**
+ * Collect public signals from a site. Everything here is what an external auditor sees:
+ * robots.txt, sitemaps, llms.txt, the homepage and a sample of pages from the sitemap.
+ * No Search Console, no analytics. The narrative fields are left for the analyst.
+ */
+import { parse } from 'node-html-parser';
+
+const UA = 'Mozilla/5.0 (compatible; OperStackAudit/0.1; +https://oper-stack.com)';
+
+async function get(url, { method = 'GET', timeout = 15000 } = {}) {
+  const c = new AbortController(); const t = setTimeout(() => c.abort(), timeout);
+  const started = Date.now();
+  try {
+    const res = await fetch(url, { method, redirect: 'manual', signal: c.signal, headers: { 'user-agent': UA, accept: 'text/html,application/xml,text/plain,*/*' } });
+    const ttfb = Date.now() - started;
+    const text = method === 'GET' ? await res.text() : '';
+    return { ok: res.ok, status: res.status, location: res.headers.get('location'), type: res.headers.get('content-type') || '', text, ttfb, url };
+  } catch (e) { return { ok: false, status: 0, error: e.name === 'AbortError' ? 'timeout' : e.message, text: '', ttfb: Date.now() - started, url }; }
+  finally { clearTimeout(t); }
+}
+
+async function follow(url, max = 5) {
+  const hops = [];
+  let cur = url;
+  for (let i = 0; i < max; i++) {
+    const r = await get(cur);
+    hops.push({ url: cur, status: r.status, location: r.location });
+    if (r.status >= 300 && r.status < 400 && r.location) { cur = new URL(r.location, cur).href; continue; }
+    return { final: cur, response: r, hops };
+  }
+  return { final: cur, response: await get(cur), hops };
+}
+
+const row = (id, group, label, status, value, comment = '') => ({ id, group, label, status, value, comment });
+
+function analysePage(url, html) {
+  const root = parse(html, { blockTextElements: { script: true, style: true, noscript: true } });
+  const attr = (sel, a) => root.querySelector(sel)?.getAttribute(a) ?? '';
+  const title = root.querySelector('title')?.text.trim() ?? '';
+  const description = attr('meta[name="description"]', 'content').trim();
+  const h1s = root.querySelectorAll('h1').map((h) => h.text.trim()).filter(Boolean);
+  const imgs = root.querySelectorAll('img');
+  const imgsNoAlt = imgs.filter((i) => !(i.getAttribute('alt') || '').trim()).length;
+  const canonical = attr('link[rel="canonical"]', 'href');
+  const robots = attr('meta[name="robots"]', 'content');
+  const viewport = attr('meta[name="viewport"]', 'content');
+  const og = { title: attr('meta[property="og:title"]', 'content'), description: attr('meta[property="og:description"]', 'content'), image: attr('meta[property="og:image"]', 'content') };
+  const twitter = attr('meta[name="twitter:card"]', 'content');
+  const generator = attr('meta[name="generator"]', 'content');
+  const hreflang = root.querySelectorAll('link[rel="alternate"][hreflang]').length;
+  const scripts = root.querySelectorAll('script[src]').length;
+  const stylesheets = root.querySelectorAll('link[rel="stylesheet"]').length;
+  const schemaTypes = [];
+  for (const s of root.querySelectorAll('script[type="application/ld+json"]')) {
+    try {
+      const j = JSON.parse(s.text);
+      const walk = (x) => { if (Array.isArray(x)) x.forEach(walk); else if (x && typeof x === 'object') { if (x['@type']) schemaTypes.push(...[].concat(x['@type'])); if (x['@graph']) walk(x['@graph']); } };
+      walk(j);
+    } catch { schemaTypes.push('(invalid JSON-LD)'); }
+  }
+  const body = root.querySelector('body');
+  const text = (body?.text ?? '').replace(/\s+/g, ' ').trim();
+  const words = (text.match(/[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu) || []).length;
+  const links = root.querySelectorAll('a[href]').map((a) => a.getAttribute('href') || '');
+  const ld = root.querySelectorAll('script[type="application/ld+json"]').map((x) => x.text).join('\n');
+  const dates = { published: attr('meta[property="article:published_time"]', 'content') || (ld.match(/"datePublished"\s*:\s*"([^"]+)"/) || [])[1] || '', modified: attr('meta[property="article:modified_time"]', 'content') || (ld.match(/"dateModified"\s*:\s*"([^"]+)"/) || [])[1] || '' };
+  const shortcode = /\[[a-z_-]+ [^\]]*\]/i.test(description) || /^[A-Za-z0-9+/=]{40,}$/.test(description);
+  return { url, title, titleLength: title.length, description, descriptionLength: description.length, descriptionGarbage: shortcode, h1Count: h1s.length, h1: h1s[0] || '', images: imgs.length, imagesNoAlt: imgsNoAlt, canonical, robots, viewport, og, twitter, generator, hreflang, scripts, stylesheets, schemaTypes: [...new Set(schemaTypes)], words, links, dates };
+}
+
+async function readSitemap(url, seen = new Set(), depth = 0) {
+  if (seen.has(url) || depth > 3) return [];
+  seen.add(url);
+  const r = await get(url);
+  if (!r.ok) return [];
+  const locs = [...r.text.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/g)].map((m) => m[1]);
+  const out = [];
+  for (const l of locs) {
+    if (/\.xml(\.gz)?$/i.test(l) || /sitemap/i.test(l) && !/\.(html?|php)$/i.test(l) && r.text.includes('<sitemapindex')) out.push(...(await readSitemap(l, seen, depth + 1)));
+    else out.push(l);
+  }
+  return out;
+}
+
+export async function collect(startUrl, { pages = 20, log = () => {} } = {}) {
+  const origin = new URL(startUrl).origin;
+  const host = new URL(startUrl).host;
+  const checks = [];
+  const notes = [];
+
+  log(`homepage ${startUrl}`);
+  const home = await follow(startUrl);
+  const homePage = home.response.ok ? analysePage(home.final, home.response.text) : null;
+  checks.push(row('https', 'technical', 'HTTPS', home.final.startsWith('https://') ? 'ok' : 'bad', home.final.startsWith('https://') ? 'certificate active' : 'site served over http'));
+  const altHost = host.startsWith('www.') ? host.slice(4) : `www.${host}`;
+  const alt = await follow(`${new URL(home.final).protocol}//${altHost}/`);
+  const altOk = alt.final.replace(/\/$/, '') === new URL(home.final).origin.replace(/\/$/, '') || alt.hops.some((h) => h.status >= 300 && h.status < 400);
+  checks.push(row('www', 'technical', 'www canonicalisation', alt.response.status === 0 ? 'warn' : altOk ? 'ok' : 'warn', alt.response.status === 0 ? `${altHost} does not resolve` : altOk ? `${altHost} redirects to ${new URL(home.final).host}` : `${altHost} answers ${alt.response.status} without redirecting`));
+  checks.push(row('ttfb', 'technical', 'Time to first byte (homepage)', home.response.ttfb > 2500 ? 'bad' : home.response.ttfb > 1200 ? 'warn' : 'ok', `${home.response.ttfb} ms`, 'single request from the auditor, not a lab test'));
+
+  log('robots.txt');
+  const robots = await get(`${origin}/robots.txt`);
+  const sitemapUrls = robots.ok ? [...robots.text.matchAll(/^sitemap:\s*(\S+)/gim)].map((m) => m[1]) : [];
+  // robots.txt is read per user-agent block: a "Disallow: /" under an AI crawler is a policy, under * it is a catastrophe.
+  const blocks = []; let cur = null;
+  for (const line of robots.ok ? robots.text.split(/\r?\n/) : []) {
+    const l = line.replace(/#.*$/, '').trim(); if (!l) continue;
+    const m = l.match(/^([a-z-]+):\s*(.*)$/i); if (!m) continue;
+    const [, k, v] = m; const key = k.toLowerCase();
+    if (key === 'user-agent') { if (!cur || cur.rules.length) { cur = { agents: [], rules: [] }; blocks.push(cur); } cur.agents.push(v.trim().toLowerCase()); }
+    else if (cur && (key === 'disallow' || key === 'allow')) cur.rules.push({ key, value: v.trim() });
+  }
+  const disallows = blocks.flatMap((b) => b.rules.filter((r) => r.key === 'disallow' && r.value).map((r) => r.value));
+  const starBlocksAll = blocks.some((b) => b.agents.includes('*') && b.rules.some((r) => r.key === 'disallow' && r.value === '/'));
+  const blockedAgents = blocks.filter((b) => !b.agents.includes('*') && b.rules.some((r) => r.key === 'disallow' && r.value === '/')).flatMap((b) => b.agents);
+  checks.push(row('robots', 'technical', 'robots.txt', robots.ok ? (sitemapUrls.length ? 'ok' : 'warn') : 'bad', robots.ok ? `${disallows.length} disallow rule(s) in ${blocks.length} agent block(s), ${sitemapUrls.length} sitemap line(s)` : `HTTP ${robots.status}`, robots.ok && !sitemapUrls.length ? 'no Sitemap: line' : ''));
+  if (starBlocksAll) checks.push(row('robots-block', 'technical', 'robots.txt blocks the whole site', 'bad', 'Disallow: / under User-agent: *', 'search engines are told not to crawl anything'));
+  if (blockedAgents.length) checks.push(row('robots-ai', 'geo', 'AI crawlers blocked in robots.txt', 'na', `${blockedAgents.length} agent(s) fully disallowed, e.g. ${blockedAgents.slice(0, 4).join(', ')}`, 'a policy choice: these systems will not read the site or cite it from a fresh crawl'));
+
+  log('sitemaps');
+  const candidates = sitemapUrls.length ? sitemapUrls : [`${origin}/sitemap.xml`, `${origin}/sitemap_index.xml`, `${origin}/sitemap-index.xml`];
+  let sitemapPages = []; let sitemapStatus = 'missing'; let sitemapSource = '';
+  for (const u of candidates) {
+    const r = await get(u);
+    if (r.ok && /<(urlset|sitemapindex)/.test(r.text)) { sitemapPages = await readSitemap(u); sitemapStatus = 'ok'; sitemapSource = u; break; }
+    if (sitemapUrls.includes(u)) { sitemapStatus = `HTTP ${r.status}`; sitemapSource = u; }
+  }
+  checks.push(row('sitemap', 'technical', 'XML sitemap', sitemapStatus === 'ok' ? 'ok' : 'bad', sitemapStatus === 'ok' ? `${sitemapPages.length} URL(s) in ${sitemapSource}` : sitemapSource ? `${sitemapSource} answers ${sitemapStatus}` : 'no sitemap found at the usual paths', sitemapStatus !== 'ok' && sitemapUrls.length ? 'robots.txt points at a sitemap that does not answer' : ''));
+  const foreign = sitemapPages.filter((u) => { try { return new URL(u).host !== host && new URL(u).host !== altHost; } catch { return true; } });
+  if (foreign.length) checks.push(row('sitemap-foreign', 'technical', 'Sitemap lists other hosts', 'bad', `${foreign.length} URL(s) on other hosts, e.g. ${foreign[0]}`));
+
+  log('llms.txt');
+  const llms = await get(`${origin}/llms.txt`);
+  const llmsIsText = llms.ok && !/<html/i.test(llms.text.slice(0, 500));
+  const llmsLinks = llmsIsText ? [...llms.text.matchAll(/https?:\/\/[^\s)\]]+/g)].map((m) => m[0]) : [];
+  const llmsForeign = llmsLinks.filter((u) => { try { const h = new URL(u).host; return h !== host && h !== altHost; } catch { return false; } });
+  checks.push(row('llms', 'geo', 'llms.txt', !llms.ok ? 'warn' : !llmsIsText ? 'bad' : llmsForeign.length > llmsLinks.length / 2 && llmsLinks.length > 3 ? 'bad' : 'ok',
+    !llms.ok ? 'not present' : !llmsIsText ? 'answers with an HTML page, not a text index' : `${llmsLinks.length} link(s), ${llmsForeign.length} to other hosts`,
+    !llms.ok ? 'answer engines get nothing to read; a generated index is a one-day job' : llmsForeign.length > 3 ? `links to ${[...new Set(llmsForeign.map((u) => new URL(u).host))].slice(0, 3).join(', ')}: an AI system may misidentify the business` : ''));
+
+  log(`sampling up to ${pages} pages`);
+  const norm = (u) => { try { const x = new URL(u); x.hash = ''; x.search = ''; if (!x.pathname.includes('.') && !x.pathname.endsWith('/')) x.pathname += '/'; return x.href.toLowerCase(); } catch { return u; } };
+  const seenUrl = new Set([norm(home.final), norm(startUrl)]);
+  const pool = [home.final, ...sitemapPages.filter((u) => { const n = norm(u); if (seenUrl.has(n)) return false; seenUrl.add(n); return true; })];
+  const sample = [];
+  for (const u of pool.slice(0, pages)) {
+    const r = await get(u);
+    if (r.ok && /html/i.test(r.type)) sample.push(analysePage(u, r.text));
+    else if (r.status >= 300 && r.status < 400) sample.push({ url: u, redirect: r.location, status: r.status });
+    else sample.push({ url: u, status: r.status, error: r.error });
+  }
+  const good = sample.filter((p) => p.title !== undefined);
+  const hp = homePage || good[0];
+
+  if (hp) {
+    checks.push(row('title', 'onpage', 'Homepage title', hp.titleLength >= 40 && hp.titleLength <= 60 ? 'ok' : hp.titleLength ? 'warn' : 'bad', `"${hp.title}" (${hp.titleLength} chars)`, hp.titleLength < 40 ? 'short: the words that earn the click are missing' : hp.titleLength > 60 ? 'cut in results' : ''));
+    checks.push(row('description', 'onpage', 'Homepage meta description', hp.descriptionGarbage ? 'bad' : hp.descriptionLength >= 70 && hp.descriptionLength <= 160 ? 'ok' : hp.descriptionLength ? 'warn' : 'bad', hp.descriptionGarbage ? 'contains a shortcode or encoded data' : `${hp.descriptionLength} chars`, hp.descriptionGarbage ? 'renders as technical garbage in the snippet' : !hp.descriptionLength ? 'missing' : ''));
+    checks.push(row('h1', 'onpage', 'H1 on homepage', hp.h1Count === 1 ? 'ok' : hp.h1Count === 0 ? 'bad' : 'warn', `${hp.h1Count} H1 tag(s)`, hp.h1Count > 1 ? 'more than one H1 dilutes the page topic' : hp.h1Count === 0 ? 'no H1' : ''));
+    checks.push(row('canonical', 'technical', 'Canonical tag', hp.canonical ? 'ok' : 'warn', hp.canonical || 'missing'));
+    checks.push(row('viewport', 'technical', 'Mobile viewport', !hp.viewport ? 'bad' : /user-scalable\s*=\s*no|maximum-scale\s*=\s*1(\.0)?\b/i.test(hp.viewport) ? 'warn' : 'ok', hp.viewport || 'missing', /user-scalable\s*=\s*no/i.test(hp.viewport) ? 'blocks zoom: bad for accessibility and mobile SEO' : ''));
+    checks.push(row('og', 'technical', 'Open Graph and Twitter cards', hp.og.title && hp.og.image ? (hp.twitter ? 'ok' : 'warn') : 'warn', [hp.og.title ? 'og:title' : '', hp.og.image ? 'og:image' : '', hp.twitter ? `twitter:${hp.twitter}` : ''].filter(Boolean).join(', ') || 'none'));
+    checks.push(row('schema', 'aeo', 'Structured data on homepage', hp.schemaTypes.length ? (hp.schemaTypes.includes('(invalid JSON-LD)') ? 'warn' : 'ok') : 'warn', hp.schemaTypes.join(', ') || 'no JSON-LD'));
+    checks.push(row('faq-schema', 'aeo', 'FAQPage schema', good.some((p) => p.schemaTypes.includes('FAQPage')) ? 'ok' : 'warn', good.some((p) => p.schemaTypes.includes('FAQPage')) ? `present on ${good.filter((p) => p.schemaTypes.includes('FAQPage')).length} sampled page(s)` : 'not found in the sample'));
+    checks.push(row('org-schema', 'geo', 'Organization or business schema', good.some((p) => p.schemaTypes.some((t) => /Organization|LocalBusiness|RealEstateAgent|Corporation/.test(t))) ? 'ok' : 'warn', good.some((p) => p.schemaTypes.some((t) => /Organization|LocalBusiness|RealEstateAgent|Corporation/.test(t))) ? 'present' : 'not found: answer engines have no entity to attach the site to'));
+    checks.push(row('resources', 'technical', 'Page weight (homepage)', hp.scripts > 30 ? 'bad' : hp.scripts > 15 ? 'warn' : 'ok', `${hp.scripts} script file(s), ${hp.stylesheets} stylesheet(s), ${hp.images} image(s)`));
+    if (hp.generator) checks.push(row('cms', 'overview', 'CMS', 'na', hp.generator));
+    checks.push(row('hreflang', 'technical', 'hreflang', hp.hreflang ? 'ok' : 'na', hp.hreflang ? `${hp.hreflang} alternate(s)` : 'none (single language)'));
+  }
+  const imgs = good.reduce((a, p) => a + p.images, 0); const noAlt = good.reduce((a, p) => a + p.imagesNoAlt, 0);
+  if (imgs) checks.push(row('alt', 'onpage', 'Image alt text', noAlt / imgs > 0.5 ? 'bad' : noAlt / imgs > 0.2 ? 'warn' : 'ok', `${imgs - noAlt} of ${imgs} images carry alt text (${Math.round((1 - noAlt / imgs) * 100)}%) across ${good.length} sampled page(s)`));
+  const multiH1 = good.filter((p) => p.h1Count > 1).length;
+  if (good.length > 1) checks.push(row('h1-sample', 'onpage', 'Heading structure across sample', multiH1 ? (multiH1 > good.length / 2 ? 'bad' : 'warn') : 'ok', multiH1 ? `${multiH1} of ${good.length} pages carry more than one H1` : 'one H1 per page'));
+  const titles = new Map(); for (const p of good) titles.set(p.title, (titles.get(p.title) || 0) + 1);
+  const dupTitles = [...titles].filter(([, n]) => n > 1);
+  if (good.length > 1) checks.push(row('dup-titles', 'onpage', 'Duplicate titles in sample', dupTitles.length ? 'warn' : 'ok', dupTitles.length ? `${dupTitles.length} title(s) shared by several pages, e.g. "${dupTitles[0][0]}"` : 'every sampled page has its own title'));
+  const thin = good.filter((p) => p.words < 300);
+  if (good.length > 1) checks.push(row('thin', 'content', 'Thin pages in sample', thin.length > good.length / 2 ? 'bad' : thin.length ? 'warn' : 'ok', thin.length ? `${thin.length} of ${good.length} pages under 300 words` : `median ${median(good.map((p) => p.words))} words per page`));
+  const utility = sitemapPages.filter((u) => /\/(shop|cart|checkout|wishlist|compare|my-account|tag|author|feed)\/?/i.test(new URL(u).pathname));
+  if (utility.length) checks.push(row('utility', 'technical', 'Utility pages in the sitemap', 'warn', `${utility.length} URL(s) such as ${new URL(utility[0]).pathname}`, 'cart, wishlist, tag and author pages add noise to the index'));
+  const redirected = sample.filter((p) => p.redirect).length; const broken = sample.filter((p) => p.status && p.status >= 400).length;
+  if (sitemapPages.length) checks.push(row('sitemap-health', 'technical', 'Sitemap URLs that answer 200', broken ? 'bad' : redirected ? 'warn' : 'ok', `${sample.length - redirected - broken} of ${sample.length} sampled URLs answer 200${redirected ? `, ${redirected} redirect` : ''}${broken ? `, ${broken} broken` : ''}`));
+  const dated = good.filter((p) => p.dates.modified || p.dates.published).length;
+  if (good.length > 2) checks.push(row('dates', 'content', 'Publication dates exposed', dated ? 'ok' : 'warn', dated ? `${dated} of ${good.length} sampled pages expose dates` : 'no article dates in the sample: answer engines cannot tell what is current'));
+  if (/wordpress/i.test(hp?.generator || '')) { const x = await get(`${origin}/xmlrpc.php`, { method: 'HEAD' }); if (x.status === 405 || x.status === 200) checks.push(row('xmlrpc', 'technical', 'xmlrpc.php', 'warn', `answers ${x.status}`, 'pingback endpoint open: attack surface with no SEO value')); }
+
+  const scores = suggestScores(checks);
+  const critical = checks.filter((c) => c.status === 'bad').map((c) => ({ title: c.label, text: `${c.value}${c.comment ? `. ${c.comment}` : ''}`, level: 'bad' }));
+
+  return {
+    meta: { site: home.final, host, collectedAt: new Date().toISOString(), tool: '@operstack/audit 0.1.0', auditType: 'External audit (no Search Console or analytics access)', language: hp ? (hp.og?.locale || '') : '' },
+    client: { name: '{{CLIENT NAME}}', subject: '{{What the site sells and where}}', reportDate: new Date().toISOString().slice(0, 10), preparedBy: 'OperStack' },
+    scores,
+    summary: { lead: '{{Three sentences: what the site is, what works, what holds it back.}}', verdict: '{{Key takeaway in three sentences, ending with how fast the critical issues can be fixed.}}', priorities: ['{{Priority one}}', '{{Priority two}}', '{{Priority three}}'] },
+    overview: { rows: [['CMS / stack', hp?.generator || '{{stack}}'], ['Pages in sitemap', String(sitemapPages.length)], ['Language', '{{language}}'], ['What is sold', '{{products}}']], note: '{{One paragraph on how the offer is structured on the site and whether it is clear.}}' },
+    critical,
+    checks,
+    content: { strengths: ['{{strength}}'], weaknesses: ['{{weakness}}'], gaps: ['{{missing landing page or cluster}}'] },
+    aeo: { works: ['{{what already works}}'], blocks: ['{{what blocks answer-engine wins}}'], recommendation: '{{One recommendation with a page name.}}' },
+    geo: { rows: [['Entity clarity', '{{status}}', '{{detail}}'], ['Third-party mentions', '{{status}}', '{{detail}}'], ['Reviews and PR', '{{status}}', '{{detail}}']], callout: '{{Brand disambiguation note or the single biggest GEO risk.}}' },
+    offpage: { listed: ['{{where the brand is already listed}}'], note: '{{One paragraph.}}' },
+    conversion: { rows: [['Contact form', '{{status}}'], ['Price visible', '{{status}}'], ['Messengers', '{{status}}']] },
+    limitations: ['Google Search Console: no impressions, clicks or query data', 'Analytics: no traffic or behaviour data', 'Keyword and backlink tools: not used in the external tier'],
+    roadmap: [
+      { badge: 'Week 1', title: 'Critical, quick wins', items: critical.map((c) => `Fix: ${c.title}`).concat(['{{...}}']) },
+      { badge: 'Weeks 2 to 4', title: 'Foundation', items: ['{{pillar pages, alt text, Search Console and Bing connected}}'] },
+      { badge: 'Months 2 to 3', title: 'Organic growth, AEO and GEO', items: ['{{content clusters, schema, PR, reviews}}'] },
+    ],
+    closing: '{{Key message for the client in three sentences.}}',
+    sample: sample.map((p) => p.title !== undefined ? { url: p.url, title: p.title, words: p.words, h1Count: p.h1Count, images: p.images, imagesNoAlt: p.imagesNoAlt, schemaTypes: p.schemaTypes } : p),
+    notes,
+  };
+}
+
+function median(a) { const s = [...a].sort((x, y) => x - y); return s.length ? s[Math.floor(s.length / 2)] : 0; }
+
+/** 0 to 10 per group from the statuses: ok 1, warn 0.5, bad 0; na ignored. An analyst may override. */
+export function suggestScores(checks) {
+  const groups = { technical: 'SEO, technical', onpage: 'SEO, content and structure', content: 'SEO, content and structure', aeo: 'AEO, answers and snippets', geo: 'GEO, visibility in AI systems' };
+  const acc = {};
+  for (const c of checks) {
+    const g = groups[c.group]; if (!g || c.status === 'na') continue;
+    acc[g] ??= { n: 0, s: 0 }; acc[g].n++; acc[g].s += c.status === 'ok' ? 1 : c.status === 'warn' ? 0.5 : 0;
+  }
+  const out = {};
+  for (const [g, { n, s }] of Object.entries(acc)) out[g] = Math.round((s / n) * 10);
+  for (const g of ['Off-page and trust', 'Conversion and UX']) out[g] = out[g] ?? null;
+  return out;
+}

package/src/index.mjs

@@ -0,0 +1,2 @@
+export { collect } from './collect.mjs';
+export { render, checkNarrative } from './render.mjs';

package/src/render.mjs

@@ -0,0 +1,137 @@
+/**
+ * Render audit.json into the OperStack report: A4 pages, print-ready, and optionally a PDF
+ * through headless Chrome. Every narrative field is read from the JSON; a field that still
+ * holds a {{placeholder}} is rendered highlighted so it cannot ship unnoticed.
+ */
+import { writeFileSync, existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const isPlaceholder = (s) => typeof s === 'string' && /\{\{[^}]*\}\}/.test(s);
+const t = (s) => (isPlaceholder(s) ? `<mark class="todo">${esc(s)}</mark>` : esc(s));
+const STATUS = { ok: ['✓ OK', 'status-ok'], warn: ['△ Partial', 'status-warn'], bad: ['✗ Problem', 'status-bad'], na: ['·', 'status-na'] };
+const scoreClass = (n) => (n === null || n === undefined ? '' : n <= 3 ? 'low' : n <= 6 ? 'mid' : 'ok');
+
+export function checkNarrative(audit) {
+  const out = [];
+  const walk = (v, path) => {
+    if (typeof v === 'string') { if (isPlaceholder(v)) out.push(path); }
+    else if (Array.isArray(v)) v.forEach((x, i) => walk(x, `${path}[${i}]`));
+    else if (v && typeof v === 'object') for (const [k, x] of Object.entries(v)) walk(x, path ? `${path}.${k}` : k);
+  };
+  for (const k of ['client', 'summary', 'overview', 'critical', 'content', 'aeo', 'geo', 'offpage', 'conversion', 'roadmap', 'closing']) walk(audit[k], k);
+  return out;
+}
+
+function css() {
+  return `
+  @page { size: A4; margin: 0; }
+  :root { --ink:#14181c; --ink-2:#3b474d; --muted:#5c6b6f; --rule:#d8dedb; --paper:#fff; --panel:#f3f5f6; --accent:#0b7a75; --accent-soft:#dcefed; --gold:#8a6b38; --gold-soft:#f5efe3; --danger:#b3261e; --warn:#9a6700; --ok:#1f7a3d; --pad:16mm; }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: "IBM Plex Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; color: var(--ink); background: #e9ecec; font-size: 10.2pt; line-height: 1.5; }
+  .page { width: 210mm; min-height: 297mm; margin: 0 auto 8mm; background: var(--paper); padding: var(--pad) var(--pad) 22mm; position: relative; page-break-after: always; }
+  .page:last-child { page-break-after: auto; }
+  h1, h2, h3 { font-family: "Fraunces", "Iowan Old Style", Georgia, serif; font-weight: 600; color: var(--ink); line-height: 1.15; }
+  h2 { font-size: 19pt; margin-bottom: 4mm; padding-bottom: 2mm; border-bottom: 2px solid var(--accent-soft); }
+  h3 { font-size: 11.5pt; margin: 6mm 0 2.5mm; }
+  p { margin-bottom: 3mm; color: var(--ink-2); }
+  p.lead { font-size: 11pt; color: var(--ink); }
+  ul, ol { margin: 0 0 4mm 5mm; color: var(--ink-2); } li { margin-bottom: 1.5mm; }
+  .eyebrow { font-size: 8pt; letter-spacing: .12em; text-transform: uppercase; color: var(--accent); font-weight: 600; margin-bottom: 2mm; }
+  .cover { min-height: calc(297mm - 38mm); display: flex; flex-direction: column; justify-content: space-between; }
+  .cover-top { border-top: 3px solid var(--accent); padding-top: 8mm; }
+  .cover h1 { font-size: 34pt; margin: 2mm 0 4mm; }
+  .cover-sub { font-size: 13pt; color: var(--ink-2); max-width: 85%; margin-bottom: 10mm; }
+  .cover-url { display: inline-block; background: var(--accent-soft); color: var(--accent); padding: 2.5mm 4.5mm; border-radius: 4px; font-weight: 600; font-size: 11pt; }
+  .cover-meta { display: grid; grid-template-columns: 1fr 1fr; gap: 6mm; margin-top: 14mm; padding-top: 6mm; border-top: 1px solid var(--rule); }
+  .cover-meta dt { font-size: 7.5pt; text-transform: uppercase; letter-spacing: .08em; color: var(--muted); margin-bottom: 1mm; }
+  .cover-meta dd { font-size: 11pt; font-weight: 600; }
+  .cover-foot { font-size: 8.5pt; color: var(--muted); border-top: 1px solid var(--rule); padding-top: 4mm; }
+  .page-header { display: flex; justify-content: space-between; align-items: center; padding-bottom: 3mm; margin-bottom: 6mm; border-bottom: 1px solid var(--rule); font-size: 8pt; color: var(--muted); }
+  .page-header strong { color: var(--accent); }
+  .page-footer { position: absolute; bottom: 9mm; left: var(--pad); right: var(--pad); display: flex; justify-content: space-between; font-size: 8pt; color: var(--muted); border-top: 1px solid var(--rule); padding-top: 2.5mm; }
+  .scorecard { display: grid; grid-template-columns: 1fr 1fr; gap: 3mm; margin: 5mm 0 6mm; }
+  .score { border: 1px solid var(--rule); border-radius: 4px; padding: 3.5mm 4mm; background: #fafbfb; }
+  .score .label { font-size: 8pt; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); margin-bottom: 1.5mm; }
+  .score-row { display: flex; align-items: center; justify-content: space-between; gap: 3mm; }
+  .score-num { font-family: "Fraunces", Georgia, serif; font-size: 22pt; font-weight: 600; color: var(--accent); line-height: 1; font-variant-numeric: tabular-nums; }
+  .score-num.low { color: var(--danger); } .score-num.mid { color: var(--warn); } .score-num.ok { color: var(--ok); }
+  .score-note { font-size: 8.5pt; color: var(--muted); flex: 1; text-align: right; }
+  .verdict { background: var(--ink); color: #e8ecef; border-radius: 4px; padding: 5mm 6mm; margin: 5mm 0; }
+  .verdict p { color: #e8ecef; margin: 0; }
+  table { width: 100%; border-collapse: collapse; margin: 3mm 0 5mm; font-size: 9.2pt; }
+  th { text-align: left; padding: 2.5mm 3mm; font-size: 7.8pt; letter-spacing: .06em; text-transform: uppercase; color: var(--muted); border-bottom: 2px solid var(--ink); font-weight: 600; }
+  td { padding: 2.2mm 3mm; border-bottom: 1px solid var(--rule); vertical-align: top; }
+  .status-ok { color: var(--ok); font-weight: 600; white-space: nowrap; } .status-warn { color: var(--warn); font-weight: 600; white-space: nowrap; } .status-bad { color: var(--danger); font-weight: 600; white-space: nowrap; } .status-na { color: var(--muted); }
+  .cards { display: grid; gap: 3mm; margin: 4mm 0; }
+  .card { border-left: 3px solid var(--danger); background: #fbf1f0; padding: 3.5mm 4mm; border-radius: 0 4px 4px 0; }
+  .card.warn { border-left-color: var(--warn); background: #fdf8ee; }
+  .card h4 { font-size: 10pt; margin-bottom: 1.5mm; } .card p { font-size: 9.3pt; margin: 0; }
+  .two-col { display: grid; grid-template-columns: 1fr 1fr; gap: 6mm; }
+  .callout { background: var(--gold-soft); border-radius: 4px; padding: 4mm 5mm; margin: 4mm 0; border: 1px solid #e8dcc8; }
+  .callout p { color: var(--ink); margin: 0; font-size: 9.5pt; }
+  .phase { margin-bottom: 5mm; } .phase-head { display: flex; align-items: center; gap: 3mm; margin-bottom: 2.5mm; }
+  .badge { background: var(--accent); color: #fff; font-size: 7.8pt; font-weight: 700; letter-spacing: .06em; text-transform: uppercase; padding: 1mm 2.5mm; border-radius: 3px; white-space: nowrap; }
+  .phase-title { font-weight: 700; font-size: 10.5pt; }
+  .todo { background: #ffe58a; color: #5b4300; padding: 0 .3em; }
+  code { font-family: "IBM Plex Mono", Menlo, monospace; font-size: 8.8pt; background: var(--panel); padding: 0 .3em; border-radius: 2px; }
+  @media print { body { background: #fff; } .page { margin: 0; } }
+  `;
+}
+
+const header = (audit, section) => `<div class="page-header"><strong>${esc(audit.client.name)}</strong><span>SEO, AEO and GEO audit · ${esc(section)}</span></div>`;
+const footer = (audit, n) => `<div class="page-footer"><span>${esc(audit.client.preparedBy || 'OperStack')} · ${esc(audit.client.reportDate)}</span><span>${n}</span></div>`;
+const list = (items) => `<ul>${(items || []).map((i) => `<li>${t(i)}</li>`).join('')}</ul>`;
+const olist = (items) => `<ol>${(items || []).map((i) => `<li>${t(i)}</li>`).join('')}</ol>`;
+const statusCell = (s) => { const [label, cls] = STATUS[s] || STATUS.na; return `<td class="${cls}">${label}</td>`; };
+
+export function toHtml(audit) {
+  const a = audit;
+  const groups = [['technical', 'Technical'], ['onpage', 'On-page'], ['content', 'Content'], ['aeo', 'Answer engines'], ['geo', 'Generative engines'], ['overview', 'Overview']];
+  const checksBy = (g) => (a.checks || []).filter((c) => c.group === g);
+  const scoreCards = Object.entries(a.scores || {}).map(([label, n]) => `<div class="score"><div class="label">${esc(label)}</div><div class="score-row"><span class="score-num ${scoreClass(n)}">${n === null || n === undefined ? 'n/a' : `${n}/10`}</span><span class="score-note">${esc((a.scoreNotes || {})[label] || '')}</span></div></div>`).join('');
+  let n = 1;
+  const pages = [];
+  pages.push(`<div class="page"><div class="cover"><div><div class="cover-top"><div class="eyebrow">Digital marketing audit</div><h1>SEO, AEO and GEO<br>audit report</h1><p class="cover-sub">${t(a.client.subject)}</p><span class="cover-url">${esc(a.meta.host)}</span></div>
+    <dl class="cover-meta"><div><dt>Audit subject</dt><dd>${t(a.client.name)}</dd></div><div><dt>Report date</dt><dd>${esc(a.client.reportDate)}</dd></div><div><dt>Audit type</dt><dd>${esc(a.meta.auditType)}</dd></div><div><dt>Prepared by</dt><dd>${esc(a.client.preparedBy || 'OperStack')}</dd></div></dl></div>
+    <div class="cover-foot">Public signals were collected by ${esc(a.meta.tool)} on ${esc((a.meta.collectedAt || '').slice(0, 10))}. Every status in this report can be reproduced from the site as it stood on that day.</div></div></div>`);
+  n++;
+  pages.push(`<div class="page">${header(a, 'Executive summary')}<div class="eyebrow">01 · Summary</div><h2>Executive summary</h2><p class="lead">${t(a.summary.lead)}</p><div class="scorecard">${scoreCards}</div><div class="verdict"><p><strong>Key takeaway:</strong> ${t(a.summary.verdict)}</p></div><h3>Three priorities</h3>${olist(a.summary.priorities)}${footer(a, n++)}</div>`);
+  pages.push(`<div class="page">${header(a, 'Site overview')}<div class="eyebrow">02 · Overview</div><h2>What the site is</h2><table><tr><th>Parameter</th><th>Value</th></tr>${(a.overview.rows || []).map(([k, v]) => `<tr><td>${t(k)}</td><td>${t(v)}</td></tr>`).join('')}</table><p>${t(a.overview.note)}</p><h3>Pages sampled</h3><table><tr><th>URL</th><th>Title</th><th>Words</th><th>H1</th><th>Alt</th></tr>${(a.sample || []).filter((p) => p.title !== undefined).slice(0, 14).map((p) => `<tr><td><code>${esc(new URL(p.url).pathname)}</code></td><td>${esc(p.title)}</td><td>${p.words}</td><td>${p.h1Count}</td><td>${p.images ? `${p.images - p.imagesNoAlt}/${p.images}` : '·'}</td></tr>`).join('')}</table>${footer(a, n++)}</div>`);
+  const cards = (a.critical || []).map((c, i) => `<div class="card ${c.level === 'warn' ? 'warn' : ''}"><h4>${i + 1}. ${t(c.title)}</h4><p>${t(c.text)}</p></div>`).join('') || '<p>No critical defects were found in the public signals.</p>';
+  pages.push(`<div class="page">${header(a, 'Critical issues')}<div class="eyebrow">03 · P0</div><h2>Critical issues, fix first</h2><div class="cards">${cards}</div>${footer(a, n++)}</div>`);
+  const techRows = [...checksBy('technical'), ...checksBy('onpage')].map((c) => `<tr><td>${esc(c.label)}</td>${statusCell(c.status)}<td>${esc(c.value)}${c.comment ? `<br><span style="color:var(--muted)">${esc(c.comment)}</span>` : ''}</td></tr>`).join('');
+  pages.push(`<div class="page">${header(a, 'Technical SEO')}<div class="eyebrow">04 · Technical</div><h2>Technical and on-page checklist</h2><table><tr><th>Check</th><th>Status</th><th>Finding</th></tr>${techRows}</table>${footer(a, n++)}</div>`);
+  pages.push(`<div class="page">${header(a, 'Content and on-page')}<div class="eyebrow">05 · Content</div><h2>Content and on-page SEO</h2><div class="two-col"><div><h3>Strengths</h3>${list(a.content.strengths)}</div><div><h3>Weaknesses</h3>${list(a.content.weaknesses)}</div></div><h3>Structural gaps: pages that do not exist yet</h3>${list(a.content.gaps)}${checksBy('content').length ? `<table><tr><th>Check</th><th>Status</th><th>Finding</th></tr>${checksBy('content').map((c) => `<tr><td>${esc(c.label)}</td>${statusCell(c.status)}<td>${esc(c.value)}</td></tr>`).join('')}</table>` : ''}${footer(a, n++)}</div>`);
+  const geoRows = [...checksBy('aeo'), ...checksBy('geo')].map((c) => `<tr><td>${esc(c.label)}</td>${statusCell(c.status)}<td>${esc(c.value)}${c.comment ? `. ${esc(c.comment)}` : ''}</td></tr>`).join('') + (a.geo.rows || []).map(([k, s, d]) => `<tr><td>${t(k)}</td><td>${t(s)}</td><td>${t(d)}</td></tr>`).join('');
+  pages.push(`<div class="page">${header(a, 'AEO and GEO')}<div class="eyebrow">06 · AEO / GEO</div><h2>Answer engines: AEO</h2><p class="lead">Whether the site's answers can be lifted into "People also ask", AI overviews, ChatGPT and Perplexity.</p><div class="two-col"><div><h3>What already works</h3>${list(a.aeo.works)}</div><div><h3>What blocks the wins</h3>${list(a.aeo.blocks)}</div></div><div class="callout"><p><strong>Recommendation:</strong> ${t(a.aeo.recommendation)}</p></div><h2>Generative engines: GEO</h2><table><tr><th>Signal</th><th>Status</th><th>Detail</th></tr>${geoRows}</table><div class="callout"><p>${t(a.geo.callout)}</p></div>${footer(a, n++)}</div>`);
+  pages.push(`<div class="page">${header(a, 'Off-page, conversion, limitations')}<div class="eyebrow">07 · Off-page</div><h2>Off-page and external presence</h2>${list(a.offpage.listed)}<p>${t(a.offpage.note)}</p><div class="eyebrow" style="margin-top:8mm">08 · Conversion</div><h2>Conversion and UX</h2><table><tr><th>Element</th><th>Status</th></tr>${(a.conversion.rows || []).map(([k, v]) => `<tr><td>${t(k)}</td><td>${t(v)}</td></tr>`).join('')}</table><div class="eyebrow" style="margin-top:8mm">09 · Limitations</div><h2>Audit limitations</h2><p>This report is based on public data only:</p>${list(a.limitations)}${footer(a, n++)}</div>`);
+  const phases = (a.roadmap || []).map((p) => `<div class="phase"><div class="phase-head"><span class="badge">${esc(p.badge)}</span><span class="phase-title">${t(p.title)}</span></div>${olist(p.items)}</div>`).join('');
+  pages.push(`<div class="page">${header(a, 'Roadmap')}<div class="eyebrow">10 · Roadmap</div><h2>Work plan: priorities and timeline</h2>${phases}<div class="verdict"><p><strong>Key message:</strong> ${t(a.closing)}</p></div>${footer(a, n++)}</div>`);
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${esc(a.client.name)}: SEO, AEO and GEO audit</title><link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600&family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono&display=swap"><style>${css()}</style></head><body>${pages.join('\n')}</body></html>`;
+}
+
+function findChrome() {
+  const candidates = [process.env.CHROME_PATH, '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium', '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser', 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'].filter(Boolean);
+  return candidates.find((p) => existsSync(p));
+}
+
+export async function render(audit, { out, pdf = false } = {}) {
+  const html = toHtml(audit);
+  writeFileSync(out, html);
+  let pdfPath = null;
+  if (pdf) {
+    const chrome = findChrome();
+    if (!chrome) { console.error('no Chrome found; set CHROME_PATH or open the HTML and print to PDF'); }
+    else {
+      pdfPath = out.replace(/\.html?$/, '') + '.pdf';
+      const profile = mkdtempSync(join(tmpdir(), 'operstack-audit-'));
+      const r = spawnSync(chrome, ['--headless=new', '--disable-gpu', '--no-first-run', '--no-default-browser-check', `--user-data-dir=${profile}`, '--virtual-time-budget=8000', '--no-pdf-header-footer', `--print-to-pdf=${pdfPath}`, `file://${out}`], { encoding: 'utf8', timeout: 90000 });
+      rmSync(profile, { recursive: true, force: true });
+      if (!existsSync(pdfPath)) { console.error(`Chrome did not write the PDF${r.stderr ? `: ${r.stderr.slice(-300)}` : ''}`); pdfPath = null; }
+    }
+  }
+  return { html, pdf: pdfPath };
+}