@operstack/audit 0.1.0 → 0.3.0

package/README.md

@@ -15,9 +15,26 @@ Everything an external auditor can see without Search Console or analytics acces
 - 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.
+- Off-page and trust, from the site itself: the postal address in the structured data, published phone and email, `sameAs` profiles claimed on other hosts, an about page, privacy and terms.
+- The conversion path: whether every page offers a way to get in touch, whether a call to action sits in the first screen, how far down the page the first form sits, how many fields it asks for, and whether a messenger link exists.
 - 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.
+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 are computed, never typed.** The six area scores on page 2 are rendered from the checks each time the report is built: a check that passes counts one, a check that needs attention a half, a failing check nothing, and `na` is ignored. A number written by hand into `audit.json` is ignored and named by `operstack-audit check`. An area with no checks is printed as **not measured** rather than scored, so nothing rests on an impression. Each card also shows the count it came from, so a reader can recompute it from the checklist.
+
+## What you need to run this
+
+**Nothing. No account, no key, no subscription.** `collect` reads the site the way any visitor reads it, and every score in the report is computed from that. Two people auditing the same site on the same day get the same numbers.
+
+Two things are optional, and the report always says which was used:
+
+| Optional | Cost | What it adds |
+|---|---|---|
+| Google Search Console and Bing Webmaster Tools | Free, but you need your own free account and a verified site | Impressions, clicks, positions and the real queries. These go into the narrative; no score depends on them. |
+| A backlink tool, passed in with `--backlinks links.json` | Paid, and never required | One row with the referring domain count and authority score, printed as a note. **It is not counted in any score**, so the report stays reproducible without it. |
+
+The rule: **if a number costs money to obtain, it does not move a score.** Section 09 of every report prints the sources table so the reader can see exactly what was used and what it cost.
 
 ## What the analyst writes
 
@@ -35,7 +52,7 @@ Ten A4 pages: cover, executive summary with a scorecard, site overview with the
 
 ## 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.
+The external tier reads public pages only. It does not run a lab performance test and does not see impressions or conversions. Conversion is scored on the contact path the pages offer, which is measurable from the HTML, not on visitor behaviour, which is not. Reviews and press are not read at all, and the report says so rather than guessing.
 
 ## License
 

package/bin/audit.mjs

@@ -2,15 +2,18 @@
 /**
  * OperStack audit generator.
  *
- *   operstack-audit collect https://example.com [--pages 20] [--out audit.json]
+ *   operstack-audit collect https://example.com [--pages 20] [--out audit.json] [--backlinks links.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
+ *       lists narrative fields still holding placeholders and any score the checks do not support
+ *
+ * Scores are never typed by hand: the report always prints what the collected checks give,
+ * and an area with no checks is printed as "not measured" rather than scored low.
  */
-import { collect } from '../src/collect.mjs';
+import { collect, verifyScores } from '../src/collect.mjs';
 import { render, checkNarrative } from '../src/render.mjs';
 import { writeFileSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
@@ -20,19 +23,23 @@ const opt = (k, d) => { const i = rest.indexOf(k); return i === -1 ? d : rest[i
 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>');
+  console.log('Usage:\n  operstack-audit collect <url> [--pages 20] [--out audit.json] [--backlinks links.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 backlinksFile = opt('--backlinks', '');
+  const backlinks = backlinksFile ? JSON.parse(readFileSync(resolve(backlinksFile), 'utf8')) : null;
+  const audit = await collect(target, { pages: Number(opt('--pages', 20)), backlinks, 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(`wrote ${out}: ${audit.checks.length} checks, ${audit.sample.length} pages sampled, scores ${Object.entries(audit.scores).map(([k, v]) => `${k} ${v === null ? 'not measured' : v}`).join(', ')}`);
   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 drift = verifyScores(audit);
+  if (drift.length) { for (const d of drift) console.error(`score ignored, ${d}`); console.error('the report prints the score the checks give, not the one stored in the JSON.'); }
   const { html, pdf } = await render(audit, { out, pdf: has('--pdf') });
   console.log(`wrote ${out} (${html.length} bytes)${pdf ? `\nwrote ${pdf}` : ''}`);
   const missing = checkNarrative(audit);
@@ -40,6 +47,9 @@ if (cmd === 'collect') {
 } 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); }
+  const drift = verifyScores(audit);
+  if (missing.length) { console.log(`${missing.length} field(s) to write:`); for (const m of missing) console.log(`  ${m}`); }
+  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 { console.error(`unknown command ${cmd}`); process.exit(2); }

package/examples/sample-audit.json

@@ -1,79 +1,465 @@
 {
-  "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" },
+  "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": 5,
+    "SEO, content and structure": 4,
+    "AEO, answers and snippets": 10,
+    "GEO, visibility in AI systems": 5,
+    "Off-page and trust": null,
+    "Conversion and UX": null
+  },
   "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."]
+    "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"]],
+    "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" }
+    {
+      "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" }
+    {
+      "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"]
+    "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"],
+    "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"]],
+    "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"],
+    "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"]]
+    "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"],
+  "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"] }
+    {
+      "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": [] }
+    {
+      "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": []
+  "notes": [],
+  "scoreBasis": {
+    "SEO, technical": {
+      "counted": 9,
+      "ok": 3,
+      "warn": 3,
+      "bad": 3,
+      "note": "3 of 9 checks pass, 3 need attention, 3 fail"
+    },
+    "SEO, content and structure": {
+      "counted": 7,
+      "ok": 1,
+      "warn": 3,
+      "bad": 3,
+      "note": "1 of 7 checks pass, 3 need attention, 3 fail"
+    },
+    "AEO, answers and snippets": {
+      "counted": 2,
+      "ok": 2,
+      "warn": 0,
+      "bad": 0,
+      "note": "2 of 2 checks pass"
+    },
+    "GEO, visibility in AI systems": {
+      "counted": 2,
+      "ok": 1,
+      "warn": 0,
+      "bad": 1,
+      "note": "1 of 2 checks pass, 1 fail"
+    },
+    "Off-page and trust": {
+      "counted": 0,
+      "ok": 0,
+      "warn": 0,
+      "bad": 0,
+      "note": "not measured: no backlink or mention tool is used in this audit"
+    },
+    "Conversion and UX": {
+      "counted": 0,
+      "ok": 0,
+      "warn": 0,
+      "bad": 0,
+      "note": "not measured: no analytics or behaviour data was reviewed"
+    }
+  }
 }

package/package.json

@@ -1,18 +1,41 @@
 {
   "name": "@operstack/audit",
-  "version": "0.1.0",
+  "version": "0.3.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"],
+  "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')\"",
+    "test": "node src/test-scores.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": ["seo", "aeo", "geo", "audit", "llms-txt", "site-audit", "report"],
-  "engines": { "node": ">=20" },
-  "dependencies": { "node-html-parser": "^9.0.4" }
+  "keywords": [
+    "seo",
+    "aeo",
+    "geo",
+    "audit",
+    "llms-txt",
+    "site-audit",
+    "report"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "node-html-parser": "^9.0.4"
+  }
 }

package/src/collect.mjs

@@ -65,7 +65,49 @@ function analysePage(url, html) {
   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 };
+  // Conversion path, read from the page itself. No analytics is needed to see whether a visitor
+  // who wants to talk to this business can find a way to do it, and how far down it is.
+  const bodyInner = body?.innerHTML || html;
+  const CONTACT_INTENT = /contact|enquir|inquir|get in touch|request a|book a|call us|consult|get a quote|free quote|связ|заяв|консульт|оставить/i;
+  const hrefsLower = links.map((h) => h.toLowerCase());
+  const telLinks = hrefsLower.filter((h) => h.startsWith('tel:')).length;
+  const mailLinks = hrefsLower.filter((h) => h.startsWith('mailto:')).length;
+  const messengerLinks = hrefsLower.filter((h) => /(wa\.me|api\.whatsapp\.com|t\.me\/|telegram\.me|m\.me\/|viber:|signal\.me)/.test(h)).length;
+  const contactPages = hrefsLower.filter((h) => /\/(contact|contacts|contact-us|kontakt|svyaz|contacto)\/?($|[?#])/.test(h)).length;
+  const formEls = root.querySelectorAll('form');
+  const realForms = formEls.filter((f) => !/search/i.test(`${f.getAttribute('class') || ''} ${f.getAttribute('id') || ''} ${f.getAttribute('role') || ''} ${f.getAttribute('action') || ''}`));
+  const firstForm = realForms[0] || null;
+  const formFields = firstForm ? firstForm.querySelectorAll('input, textarea, select').filter((i) => !/^(hidden|submit|button|image)$/i.test(i.getAttribute('type') || '')).length : 0;
+  const formAt = firstForm ? bodyInner.indexOf(firstForm.outerHTML.slice(0, 120)) : -1;
+  const formDepth = firstForm && formAt >= 0 && bodyInner.length ? Math.round((formAt / bodyInner.length) * 100) : null;
+  const firstScreen = bodyInner.slice(0, Math.max(1200, Math.round(bodyInner.length * 0.15)));
+  const ctaFirstScreen = (firstScreen.match(/<a[^>]*>[\s\S]*?<\/a>|<button[^>]*>[\s\S]*?<\/button>/gi) || [])
+    .some((el) => CONTACT_INTENT.test(el.replace(/<[^>]+>/g, ' ')) || CONTACT_INTENT.test(el));
+  // Trust signals a visitor and a rating system both look for, all of them public on the page.
+  const sameAs = [...ld.matchAll(/"sameAs"\s*:\s*(\[[^\]]*\]|"[^"]+")/g)].flatMap((m) => m[1].match(/https?:\/\/[^"\s,\]]+/g) || []);
+  const trust = {
+    postalAddress: /"(?:PostalAddress|streetAddress|addressLocality)"/.test(ld),
+    telephone: /"telephone"\s*:/.test(ld) || telLinks > 0,
+    email: /"email"\s*:/.test(ld) || mailLinks > 0,
+    sameAs: [...new Set(sameAs.map((u) => { try { return new URL(u).host.replace(/^www\./, ''); } catch { return ''; } }).filter(Boolean))],
+    aboutPage: hrefsLower.some((h) => /\/(about|about-us|our-story|team|company|o-nas)\/?($|[?#])/.test(h)),
+    policyPages: [...new Set(hrefsLower.filter((h) => /\/(privacy|privacy-policy|terms|terms-of-use|legal|cookie|cookies|disclaimer)/.test(h)).map((h) => (h.match(/\/(privacy|terms|legal|cookie|disclaimer)/) || [])[1]).filter(Boolean))],
+    author: /"author"\s*:/.test(ld),
+  };
+  // Answer-first family, the same measures the free AI visibility check uses, so the two agree.
+  // Site chrome is stripped, except a <header> that carries the H1: that is the article head, not chrome.
+  const bodyHtml = (html.match(/<body[\s\S]*<\/body>/i) || [html])[0]
+    .replace(/<(nav|footer|aside|script|style)[\s\S]*?<\/\1>/gi, ' ')
+    .replace(/<header[\s\S]*?<\/header>/gi, (block) => (/<h1[\s>]/i.test(block) ? block : ' '));
+  const plain = (x) => x.replace(/<[^>]+>/g, ' ').replace(/&nbsp;/g, ' ').replace(/\s+/g, ' ').trim();
+  const afterH1 = bodyHtml.split(/<\/h1>/i)[1] || '';
+  const firstPara = plain((afterH1.match(/<p[^>]*>([\s\S]*?)<\/p>/i) || ['', ''])[1]);
+  const firstParaWords = (firstPara.match(/[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu) || []).length;
+  const answerFirst = firstParaWords >= 20 && firstParaWords <= 90 && /\d/.test(firstPara);
+  const h2Count = (bodyHtml.match(/<h2[\s>]/gi) || []).length;
+  const tables = (bodyHtml.match(/<table[\s>]/gi) || []).length;
+  const sourcePhrases = (text.match(/\b(according to|source:|sources:|data from|reported by|published by|registry|statistics office|central bank)\b/gi) || []).length;
+  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, firstPara: firstPara.slice(0, 220), firstParaWords, answerFirst, h2Count, tables, sourcePhrases , telLinks, mailLinks, messengerLinks, contactPages, forms: realForms.length, formFields, formDepth, ctaFirstScreen, trust };
 }
 
 async function readSitemap(url, seen = new Set(), depth = 0) {
@@ -82,7 +124,8 @@ async function readSitemap(url, seen = new Set(), depth = 0) {
   return out;
 }
 
-export async function collect(startUrl, { pages = 20, log = () => {} } = {}) {
+export async function collect(startUrl, { pages = 20, log = () => {}, backlinks = null } = {}) {
+  const opts = { backlinks };
   const origin = new URL(startUrl).origin;
   const host = new URL(startUrl).host;
   const checks = [];
@@ -115,7 +158,14 @@ export async function collect(startUrl, { pages = 20, log = () => {} } = {}) {
   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'));
+  // The two kinds of AI agent are not the same decision. A search fetcher is the one that can cite the
+  // site in an answer, so blocking it costs visibility and is scored. A training crawler is a policy
+  // choice the owner is entitled to make, so it is reported and never scored.
+  const AI_FETCHERS = ['oai-searchbot', 'chatgpt-user', 'perplexitybot', 'perplexity-user', 'claude-searchbot', 'claude-user', 'bingbot', 'duckassistbot', 'applebot'];
+  const blockedFetchers = blockedAgents.filter((a) => AI_FETCHERS.includes(a));
+  const blockedTrainers = blockedAgents.filter((a) => !AI_FETCHERS.includes(a));
+  checks.push(row('ai-search-access', 'geo', 'AI search fetchers allowed', blockedFetchers.length ? 'bad' : 'ok', blockedFetchers.length ? `${blockedFetchers.length} blocked: ${blockedFetchers.join(', ')}` : 'every AI search fetcher may read the site', blockedFetchers.length ? 'these are the agents that fetch a page to cite it in an answer' : ''));
+  if (blockedTrainers.length) checks.push(row('robots-ai', 'geo', 'AI training crawlers blocked (policy)', 'na', `${blockedTrainers.length} agent(s) fully disallowed: ${blockedTrainers.join(', ')}`, 'a policy choice, not a defect: these systems will not train on the site, and will not cite it from their own crawl either'));
 
   log('sitemaps');
   const candidates = sitemapUrls.length ? sitemapUrls : [`${origin}/sitemap.xml`, `${origin}/sitemap_index.xml`, `${origin}/sitemap-index.xml`];
@@ -179,17 +229,69 @@ export async function collect(startUrl, { pages = 20, log = () => {} } = {}) {
   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` : ''}`));
+  if (good.length) {
+    const af = good.filter((p) => p.answerFirst).length;
+    checks.push(row('answer-first', 'aeo', 'Answer-first opening paragraph', af === good.length ? 'ok' : af ? 'warn' : 'bad', `${af} of ${good.length} sampled page(s) open with 20 to 90 words carrying a figure, right after the H1`, af === good.length ? '' : 'that paragraph is the one an answer engine lifts'));
+    const structured = good.filter((p) => p.h2Count >= 3).length;
+    checks.push(row('sections', 'aeo', 'Section structure', structured === good.length ? 'ok' : structured ? 'warn' : 'bad', `${structured} of ${good.length} sampled page(s) carry three or more H2 sections`, structured === good.length ? '' : 'engines quote sections, not walls of text'));
+    const withTables = good.filter((p) => p.tables > 0).length;
+    checks.push(row('tables', 'aeo', 'Tables in the content', withTables ? 'ok' : 'warn', withTables ? `${withTables} of ${good.length} sampled page(s) use a table` : 'no table on the sampled pages', withTables ? '' : 'tables are the second most quoted format after the opening paragraph'));
+    const sourced = good.filter((p) => p.sourcePhrases > 0).length;
+    checks.push(row('sources', 'content', 'Sources named in the text', sourced === good.length ? 'ok' : sourced ? 'warn' : 'bad', `${sourced} of ${good.length} sampled page(s) name where a figure comes from`, sourced === good.length ? '' : 'an unsourced figure is the first thing an engine drops'));
+  }
   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);
+  // ---- Off-page and trust ----------------------------------------------------------------
+  // Link data comes from Semrush when SEMRUSH_API_KEY is set. Without it the three link rows are
+  // reported as not measured and the area is still scored on the trust signals, which are free.
+  log('off-page and trust');
+  const pagesForTrust = hp ? [hp, ...good] : good;
+  const anyTrust = (f) => pagesForTrust.some(f);
+  const links = await semrushBacklinks(host, log, opts.backlinks || null);
+  if (links.ok) {
+    const followShare = links.total ? Math.round((links.follows / links.total) * 100) : 0;
+    checks.push(row('links-profile', 'offpage', 'Backlink profile (optional extra)', 'na', `${links.domains} referring domain(s), ${links.total} link(s), ${followShare}% follow, authority score ${links.ascore} of 100`, `${links.source}. A paid tool, not required for this report and not counted in any score.`));
+  }
+  const addr = anyTrust((p) => p.trust?.postalAddress);
+  checks.push(row('trust-entity', 'offpage', 'Who the business is, in machine-readable form', addr ? 'ok' : 'warn', addr ? 'a postal address is published in the structured data' : 'no postal address in the structured data', addr ? '' : 'rating systems and answer engines use it to tell one business from another'));
+  const tel = anyTrust((p) => p.trust?.telephone); const mail = anyTrust((p) => p.trust?.email);
+  checks.push(row('trust-contact', 'offpage', 'Direct contact details', tel && mail ? 'ok' : tel || mail ? 'warn' : 'bad', [tel ? 'phone' : '', mail ? 'email' : ''].filter(Boolean).join(' and ') || 'neither a phone nor an email is published'));
+  const ownHost = host.replace(/^www\./, '');
+  const profiles = [...new Set(pagesForTrust.flatMap((p) => p.trust?.sameAs || []))].filter((h) => h !== ownHost && !h.endsWith(`.${ownHost}`));
+  checks.push(row('trust-profiles', 'offpage', 'Profiles the site claims elsewhere', profiles.length >= 2 ? 'ok' : profiles.length ? 'warn' : 'bad', profiles.length ? `${profiles.length}: ${profiles.slice(0, 5).join(', ')}` : 'no sameAs links: the site claims no profile anywhere else', profiles.length ? '' : 'the cheapest off-site signal there is, and it is free'));
+  const about = anyTrust((p) => p.trust?.aboutPage);
+  checks.push(row('trust-about', 'offpage', 'A page that says who is behind the site', about ? 'ok' : 'warn', about ? 'linked from the sampled pages' : 'no about or team page is linked'));
+  const policies = [...new Set(pagesForTrust.flatMap((p) => p.trust?.policyPages || []))];
+  checks.push(row('trust-policies', 'offpage', 'Privacy and terms', policies.length >= 2 ? 'ok' : policies.length ? 'warn' : 'bad', policies.length ? policies.join(', ') : 'neither a privacy policy nor terms are linked'));
+
+  // ---- Conversion path -------------------------------------------------------------------
+  // Measured from the pages, not from analytics: whether a visitor who wants to talk can, and how
+  // far down the page the way to do it sits. Behaviour data, when the client grants it, adds to this.
+  const withForm = pagesForTrust.filter((p) => p.forms > 0);
+  const reachable = pagesForTrust.filter((p) => p.forms > 0 || p.telLinks || p.mailLinks || p.messengerLinks || p.contactPages);
+  checks.push(row('conv-contact-path', 'conversion', 'A way to get in touch', reachable.length === pagesForTrust.length ? 'ok' : reachable.length ? 'warn' : 'bad', `${reachable.length} of ${pagesForTrust.length} sampled page(s) offer a form, a contact link or a contact page`));
+  const withCta = pagesForTrust.filter((p) => p.ctaFirstScreen);
+  checks.push(row('conv-cta', 'conversion', 'A call to action in the first screen', withCta.length >= pagesForTrust.length * 0.8 ? 'ok' : withCta.length ? 'warn' : 'bad', `${withCta.length} of ${pagesForTrust.length} sampled page(s) put one in the first 15% of the page`, withCta.length === pagesForTrust.length ? '' : 'a reader who is convinced at the top should not have to hunt'));
+  const depths = withForm.map((p) => p.formDepth).filter((d) => d !== null && d !== undefined);
+  if (depths.length) {
+    const md = median(depths);
+    checks.push(row('conv-form-depth', 'conversion', 'How far down the form sits', md < 50 ? 'ok' : md < 80 ? 'warn' : 'bad', `median ${md}% of the way down the page, measured on ${depths.length} page(s)`, md >= 80 ? 'on a long page almost nobody scrolls that far, least of all on a phone' : ''));
+  } else checks.push(row('conv-form-depth', 'conversion', 'How far down the form sits', withForm.length ? 'na' : 'bad', withForm.length ? 'position could not be measured' : 'no form on the sampled pages'));
+  const fields = withForm.map((p) => p.formFields).filter((n) => n > 0);
+  if (fields.length) { const mf = median(fields); checks.push(row('conv-form-fields', 'conversion', 'What the form asks for', mf <= 4 ? 'ok' : mf <= 6 ? 'warn' : 'bad', `median ${mf} field(s) before a visitor can send anything`, mf > 4 ? 'every extra field costs replies, and a phone number costs the most' : '')); }
+  const msg = pagesForTrust.filter((p) => p.messengerLinks > 0);
+  checks.push(row('conv-messenger', 'conversion', 'A messenger link', msg.length ? 'ok' : 'warn', msg.length ? `on ${msg.length} of ${pagesForTrust.length} sampled page(s)` : 'none on the sampled pages', msg.length ? '' : 'for an international audience reading on a phone, one messenger link is usually worth more than a form'));
+
+  const { scores, scoreBasis } = computeScores(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,
+    scoreBasis,
     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,
@@ -199,6 +301,10 @@ export async function collect(startUrl, { pages = 20, log = () => {} } = {}) {
     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}}']] },
+    sources: [
+      { name: 'The site itself', access: 'Free, no account needed', detail: `robots.txt, the sitemaps, llms.txt, the homepage and ${good.length} sampled page(s), read exactly as any visitor reads them` },
+      ...(links.ok ? [{ name: links.source, access: 'Paid tool, optional', detail: 'reported for context only, not counted in any score' }] : []),
+    ],
     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(['{{...}}']) },
@@ -211,18 +317,88 @@ export async function collect(startUrl, { pages = 20, log = () => {} } = {}) {
   };
 }
 
+
+/**
+ * Backlink profile from the Semrush analytics API, when SEMRUSH_API_KEY is in the environment.
+ * Every failure returns ok:false with the reason, which the report prints instead of a score.
+ */
+async function semrushBacklinks(host, log = () => {}, supplied = null) {
+  if (supplied) {
+    const need = ['ascore', 'total', 'domains'];
+    const missing = need.filter((k) => typeof supplied[k] !== 'number');
+    if (missing.length) return { ok: false, reason: `the supplied link data is missing ${missing.join(', ')}` };
+    return { ok: true, source: supplied.source || 'supplied link data', follows: supplied.follows ?? 0, nofollows: supplied.nofollows ?? 0, ...supplied };
+  }
+  const key = process.env.SEMRUSH_API_KEY;
+  if (!key) return { ok: false, reason: 'no link tool was used: no SEMRUSH_API_KEY and no link data supplied' };
+  const url = `https://api.semrush.com/analytics/v1/?key=${encodeURIComponent(key)}&type=backlinks_overview&target=${encodeURIComponent(host)}&target_type=root_domain&export_columns=ascore,total,domains_num,follows_num,nofollows_num`;
+  const r = await get(url, { timeout: 20000 });
+  if (!r.ok || /^ERROR/.test(r.text.trim())) {
+    const msg = (r.text || '').trim().slice(0, 120) || `HTTP ${r.status}`;
+    log(`  link data unavailable: ${msg}`);
+    return { ok: false, reason: /132/.test(msg) ? 'the link tool had no API units left this month' : `the link tool answered: ${msg}` };
+  }
+  const [head, line] = r.text.trim().split(/\r?\n/);
+  if (!line) return { ok: false, reason: 'the link tool returned no row for this domain' };
+  const cols = head.split(';'); const vals = line.split(';');
+  const n = (name) => Number(vals[cols.indexOf(name)] || 0);
+  return { ok: true, source: `Semrush Backlink Analytics, ${new Date().toISOString().slice(0, 10)}`, ascore: n('ascore'), total: n('total'), domains: n('domains_num'), follows: n('follows_num'), nofollows: n('nofollows_num') };
+}
+
 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;
+/**
+ * The six areas of the report. `groups` lists the check groups that feed the score.
+ * An area with no groups is an area this audit does not test: it is reported as
+ * "not measured", never as a low score. Nothing in a report may be scored by hand.
+ */
+export const SCORE_AREAS = [
+  { label: 'SEO, technical', groups: ['technical'] },
+  { label: 'SEO, content and structure', groups: ['onpage', 'content'] },
+  { label: 'AEO, answers and snippets', groups: ['aeo'] },
+  { label: 'GEO, visibility in AI systems', groups: ['geo'] },
+  { label: 'Off-page and trust', groups: ['offpage'] },
+  { label: 'Conversion and UX', groups: ['conversion'] },
+];
+
+/**
+ * Score every area from the collected checks: ok 1, warn 0.5, bad 0, na ignored, rounded to 0-10.
+ * Returns the scores and the count each one came from, so the report can print its own evidence.
+ * An area with no counted check scores null and carries the reason it was not measured.
+ */
+export function computeScores(checks) {
+  const scores = {}; const scoreBasis = {};
+  for (const area of SCORE_AREAS) {
+    const rows = (checks || []).filter((c) => area.groups.includes(c.group) && c.status !== 'na');
+    if (!rows.length) {
+      scores[area.label] = null;
+      scoreBasis[area.label] = { counted: 0, ok: 0, warn: 0, bad: 0, note: `not measured: ${area.reason || 'this audit collected no check in this area'}` };
+      continue;
+    }
+    const ok = rows.filter((c) => c.status === 'ok').length;
+    const warn = rows.filter((c) => c.status === 'warn').length;
+    const bad = rows.filter((c) => c.status === 'bad').length;
+    scores[area.label] = Math.round(((ok + warn * 0.5) / rows.length) * 10);
+    scoreBasis[area.label] = { counted: rows.length, ok, warn, bad, note: `${ok} of ${rows.length} checks pass${warn ? `, ${warn} ${warn === 1 ? 'needs' : 'need'} attention` : ''}${bad ? `, ${bad} ${bad === 1 ? 'fails' : 'fail'}` : ''}` };
+  }
+  return { scores, scoreBasis };
+}
+
+/** Every way the scores stored in an audit disagree with its own checks. Empty means reproducible. */
+export function verifyScores(audit) {
+  const { scores } = computeScores(audit.checks || []);
+  const show = (v) => (v === null || v === undefined ? 'not measured' : `${v}/10`);
+  const problems = [];
+  for (const [label, expected] of Object.entries(scores)) {
+    const stored = (audit.scores || {})[label];
+    const actual = stored === undefined ? null : stored;
+    if (actual !== expected) problems.push(`${label}: the report says ${show(actual)}, the checks give ${show(expected)}`);
   }
-  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;
+  for (const label of Object.keys(audit.scores || {})) {
+    if (!(label in scores)) problems.push(`${label}: not one of the six audit areas, so nothing measures it`);
+  }
+  return problems;
 }
+
+/** @deprecated kept for 0.1.x callers: use computeScores, which also returns the evidence. */
+export function suggestScores(checks) { return computeScores(checks).scores; }

package/src/render.mjs

@@ -7,11 +7,12 @@ import { writeFileSync, existsSync, mkdtempSync, rmSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { computeScores } from './collect.mjs';
 
 const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 const isPlaceholder = (s) => typeof s === 'string' && /\{\{[^}]*\}\}/.test(s);
 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 STATUS = { ok: ['✓ OK', 'status-ok'], warn: ['△ Partial', 'status-warn'], bad: ['✗ Problem', 'status-bad'], na: ['· Note', 'status-na'] };
 const scoreClass = (n) => (n === null || n === undefined ? '' : n <= 3 ? 'low' : n <= 6 ? 'mid' : 'ok');
 
 export function checkNarrative(audit) {
@@ -22,6 +23,7 @@ export function checkNarrative(audit) {
     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);
+  (audit.critical || []).forEach((c, i) => { if (!c.text && !c.cost && !c.fix) out.push(`critical[${i}].text (the issue "${c.title || '?'}" would print as a bare headline)`); });
   return out;
 }
 
@@ -59,6 +61,8 @@ function css() {
   .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; }
+  .score-num.na { font-family: inherit; font-size: 10pt; font-weight: 600; color: var(--muted); letter-spacing: .02em; }
+  .scorecard-foot { font-size: 8.5pt; color: var(--muted); margin: -3mm 0 6mm; }
   .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; }
@@ -68,7 +72,9 @@ function css() {
   .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; }
+  .card h4 { font-size: 10pt; margin-bottom: 1.5mm; } .card p { font-size: 9.3pt; margin: 0 0 1.5mm; } .card p:last-child { margin-bottom: 0; }
+  .card-tag { display: inline-block; font-size: 7.5pt; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); margin-right: 2mm; }
+  .card-empty { color: var(--danger); font-style: italic; }
   .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; }
@@ -89,25 +95,37 @@ const statusCell = (s) => { const [label, cls] = STATUS[s] || STATUS.na; return
 
 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 groups = [['technical', 'Technical'], ['onpage', 'On-page'], ['content', 'Content'], ['aeo', 'Answer engines'], ['geo', 'Generative engines'], ['offpage', 'Off-page and trust'], ['conversion', 'Conversion'], ['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('');
+  const { scores: measured, scoreBasis } = computeScores(a.checks || []);
+  const scoreCards = Object.entries(measured).map(([label, n]) => {
+    const basis = scoreBasis[label] || {};
+    const num = n === null ? '<span class="score-num na">not measured</span>' : `<span class="score-num ${scoreClass(n)}">${n}/10</span>`;
+    const note = n === null ? String(basis.note || '').replace(/^not measured:\s*/, '') : basis.note || '';
+    return `<div class="score"><div class="label">${esc(label)}</div><div class="score-row">${num}<span class="score-note">${esc(note)}</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, '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><p class="scorecard-foot">Each score counts the checks in this report: a check that passes scores one, a check that needs attention a half, a failing check nothing. An area marked <strong>not measured</strong> is an area this audit does not test, and is never scored on an impression. Every figure here can be recomputed from section 04 onwards.</p><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>';
+  const cardBody = (c) => [
+    c.text ? `<p>${t(c.text)}</p>` : '',
+    c.cost ? `<p><span class="card-tag">What it costs</span>${t(c.cost)}</p>` : '',
+    c.fix ? `<p><span class="card-tag">Fix</span>${t(c.fix)}</p>` : '',
+  ].join('') || '<p class="card-empty">This issue has no description in the audit file.</p>';
+  const cards = (a.critical || []).map((c, i) => `<div class="card ${c.level === 'warn' ? 'warn' : ''}"><h4>${i + 1}. ${t(c.title)}</h4>${cardBody(c)}</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('');
+  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.charAt(0).toUpperCase() + c.comment.slice(1))}` : ''}</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 checkTable = (g) => (checksBy(g).length ? `<table><tr><th>Check</th><th>Status</th><th>Finding</th></tr>${checksBy(g).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('')}</table>` : '');
+  pages.push(`<div class="page">${header(a, 'Off-page, conversion, limitations')}<div class="eyebrow">07 · Off-page</div><h2>Off-page and trust</h2>${checkTable('offpage')}${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>${checkTable('conversion')}<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>Where the data comes from</h2>${(a.sources || []).length ? `<table><tr><th>Source</th><th>Access</th><th>What was read</th></tr>${a.sources.map((s) => `<tr><td>${t(s.name)}</td><td>${t(s.access)}</td><td>${t(s.detail)}</td></tr>`).join('')}</table><p class="scorecard-foot">Every score in this report is computed from sources marked free. Nothing that costs money is counted in a score, so you can re-run this audit yourself and get the same numbers.</p>` : ''}<h3>Limitations</h3>${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>`;

package/src/test-scores.mjs

@@ -0,0 +1,75 @@
+/**
+ * The rule this file exists to defend: no number in a report is typed by a human.
+ * Every score is computed from the collected checks, and an area with no checks is
+ * printed as "not measured" rather than scored on an impression.
+ */
+import { computeScores, verifyScores, SCORE_AREAS } from './collect.mjs';
+import { toHtml, checkNarrative } from './render.mjs';
+
+let failed = 0;
+const is = (name, actual, expected) => {
+  const ok = JSON.stringify(actual) === JSON.stringify(expected);
+  if (!ok) { failed++; console.error(`FAIL ${name}\n  expected ${JSON.stringify(expected)}\n  actual   ${JSON.stringify(actual)}`); }
+  else console.log(`ok   ${name}`);
+};
+const ok = (name, cond) => is(name, Boolean(cond), true);
+
+const checks = [
+  { group: 'technical', status: 'ok' }, { group: 'technical', status: 'ok' },
+  { group: 'technical', status: 'warn' }, { group: 'technical', status: 'na' },
+  { group: 'aeo', status: 'bad' }, { group: 'aeo', status: 'ok' },
+];
+const { scores, scoreBasis } = computeScores(checks);
+
+is('ok 1, warn 0.5, bad 0, na ignored', scores['SEO, technical'], 8);
+is('an area with half its checks failing scores 5', scores['AEO, answers and snippets'], 5);
+is('na is not counted', scoreBasis['SEO, technical'].counted, 3);
+is('an area with no checks is not measured', scores['Off-page and trust'], null);
+is('and says why', scoreBasis['Off-page and trust'].note, 'not measured: this audit collected no check in this area');
+is('conversion is not measured either', scores['Conversion and UX'], null);
+is('every area is accounted for', Object.keys(scores).length, SCORE_AREAS.length);
+is('the basis is printable evidence', scoreBasis['AEO, answers and snippets'].note, '1 of 2 checks pass, 1 fails');
+
+// an area is scored as soon as its checks are collected, and only then
+const withOffpage = computeScores([
+  ...checks,
+  { group: 'offpage', status: 'ok' }, { group: 'offpage', status: 'warn' }, { group: 'offpage', status: 'na' },
+  { group: 'conversion', status: 'bad' }, { group: 'conversion', status: 'ok' },
+]);
+is('off-page is scored from its own checks', withOffpage.scores['Off-page and trust'], 8);
+is('and the na row is not counted', withOffpage.scoreBasis['Off-page and trust'].counted, 2);
+is('conversion is scored from its own checks', withOffpage.scores['Conversion and UX'], 5);
+is('an area with checks is never "not measured"', withOffpage.scoreBasis['Conversion and UX'].note, '1 of 2 checks pass, 1 fails');
+
+const typed = { checks, scores: { 'SEO, technical': 2, 'Off-page and trust': 6, 'Made-up area': 9 } };
+const problems = verifyScores(typed);
+ok('a typed score is caught', problems.some((p) => p.startsWith('SEO, technical:')));
+ok('a score for an unmeasured area is caught', problems.some((p) => p.startsWith('Off-page and trust:')));
+ok('an invented area is caught', problems.some((p) => p.includes('not one of the six audit areas')));
+is('a report that matches its checks has no problems', verifyScores({ checks, scores }), []);
+
+const audit = {
+  meta: { host: 'example.com', collectedAt: '2026-09-11T00:00:00.000Z', tool: 'test', auditType: 'test' },
+  client: { name: 'Example', subject: 'test', reportDate: '2026-09-11' },
+  scores: { 'SEO, technical': 2, 'Off-page and trust': 2 },
+  checks,
+  summary: { lead: 'x', verdict: 'x', priorities: ['x'] },
+  overview: { rows: [['a', 'b']], note: 'x' },
+  critical: [{ title: 'An issue with no text', cost: 'what it costs', fix: 'how to fix it' }, { title: 'A bare headline' }],
+  content: { strengths: ['x'], weaknesses: ['x'], gaps: ['x'] },
+  aeo: { works: ['x'], blocks: ['x'], recommendation: 'x' },
+  geo: { rows: [['a', 'b', 'c']], callout: 'x' },
+  offpage: { listed: ['x'], note: 'x' },
+  conversion: { rows: [['a', 'b']] },
+  limitations: ['x'], roadmap: [{ badge: 'w', title: 't', items: ['x'] }], closing: 'x', sample: [],
+};
+const html = toHtml(audit);
+ok('the report prints the computed score, not the typed one', html.includes('8/10'));
+ok('the typed 2/10 never reaches the page', !html.includes('>2/10<'));
+ok('an unmeasured area says so', html.includes('not measured'));
+ok('the scorecard shows the count it came from', html.includes('2 of 3 checks pass'));
+ok('a critical issue prints what it costs and how to fix it', html.includes('What it costs') && html.includes('how to fix it'));
+ok('a critical issue with no body is reported', checkNarrative(audit).some((m) => m.startsWith('critical[1].text')));
+
+if (failed) { console.error(`\n${failed} test(s) failed`); process.exit(1); }
+console.log('\nall scoring tests pass');