@houtini/seo-audit-console 0.8.0 → 0.9.1

package/dist/audit/checks.js

@@ -5,33 +5,17 @@ import { expectedCtr } from '../core/ctrModel.js';
 import { latestTwoCrawls } from './drift.js';
 import { HTML_CT } from '../core/sql.js';
 const rows = (ctx, sql, ...args) => ctx.db.prepare(sql).all(...args);
-// Streaming variant — yields one row at a time instead of materialising the whole result set. Use for
-// checks that scan a large/fat column (e.g. body_chunks) and only need independent per-row work, so a
-// big content site doesn't load every page's body text into one array.
 const iterRows = (ctx, sql, ...args) => ctx.db.prepare(sql).iterate(...args);
-// d is the finalised GSC date (partial trailing days already trimmed upstream); cap the window at
-// it so checks never count unfinalised days. winPrev already caps below d, so it's unaffected.
 const win = (d) => `date > date('${d}', '-28 days') AND date <= '${d}'`;
-// Prior 28-day window (the 28 days BEFORE the current window) — for period-over-period checks.
 const winPrev = (d) => `date <= date('${d}', '-28 days') AND date > date('${d}', '-56 days')`;
-// SQL clause to drop branded queries (whole-token match). Branded multi-URL ranking is sitelinks,
-// not cannibalisation; branded top-queries aren't anchor targets. The brand is re-sanitised to
-// alnum HERE (not trusting the caller) so inlining it into SQL is unconditionally injection-safe.
 const brandExcl = (c) => {
     const b = (c.brand ?? '').replace(/[^a-z0-9]/g, '');
     return b ? `AND (' ' || LOWER(query) || ' ') NOT LIKE '% ${b} %'` : '';
 };
-// Days of GSC history actually held — period-over-period checks need enough span to be meaningful.
 const spanDays = (c) => {
-    // Span must be measured up to the FINALISED max date the windows actually key off
-    // (gscMaxDate is trimmed ~3 days below raw MAX(date)) — measuring the raw span lets the
-    // ≥56-day guard pass while the previous-28d window still reaches before MIN(date),
-    // undercounting the prior period (rising-pages FPs, traffic-decay FNs).
     const r = c.db.prepare(`SELECT julianday(?) - julianday(MIN(date)) d FROM search_analytics`).get(c.gscMaxDate ?? null);
     return r?.d ?? 0;
 };
-// Newest dateModified/datePublished anywhere in a page's JSON-LD (recurses @graph/arrays) — the
-// effective "last meaningfully updated" date. json_ld is a JSON array of raw block strings.
 const newestSchemaDate = (jl) => {
     if (!jl)
         return null;
@@ -58,27 +42,15 @@ const newestSchemaDate = (jl) => {
             try {
                 scan(JSON.parse(block));
             }
-            catch { /* skip block */ }
+            catch { }
         }
     }
-    catch { /* skip */ }
+    catch { }
     return bestStr;
 };
-// Paginated archive URLs (/page/2, ?page=3, ?paged=2). They legitimately share titles/metas with
-// page 1 and are intentionally absent from sitemaps, so they must NOT generate duplicate-title /
-// duplicate-meta / missing-meta / not-in-sitemap false positives. Pass the column reference
-// (e.g. 'url_key' or 'p.url_key') so it composes with table aliases.
-const notPagination = (col = 'url_key') => 
-// Anchor the param name to ?/& — a bare LIKE '%page=%' also matches per_page=/on_page=/
-// homepage=, wrongly exempting those URLs from duplicate-title/meta/sitemap checks.
-`${col} NOT GLOB '*/page/[0-9]*' AND ${col} NOT GLOB '*[?&]page=[0-9]*' AND ${col} NOT GLOB '*[?&]paged=[0-9]*'`;
-// Significant query terms (drop stopwords; keep ≥2 chars so "vr"/"pc"/"ai" count).
+const notPagination = (col = 'url_key') => `${col} NOT GLOB '*/page/[0-9]*' AND ${col} NOT GLOB '*[?&]page=[0-9]*' AND ${col} NOT GLOB '*[?&]paged=[0-9]*'`;
 const STOP = new Set(['the', 'a', 'an', 'and', 'or', 'of', 'for', 'to', 'in', 'on', 'with', 'your', 'you', 'is', 'are', 'best', 'how', 'what', 'vs', 'why', 'can']);
 const terms = (s) => (s || '').toLowerCase().replace(/[^a-z0-9 ]+/g, ' ').split(/\s+/).filter(t => t.length >= 2 && !STOP.has(t));
-// A query term is "present" in the title if a TITLE WORD matches it (exact, or a
-// plural/stem prefix either way for ≥4-char tokens), or the space-collapsed title
-// contains it (for multi-word brands like "sync mesh" ≈ "syncmesh", ≥5 chars).
-// Word-level avoids substring false-matches (e.g. "art" inside "smart").
 const titleHasTerm = (title, term) => {
     const t = title.toLowerCase();
     const words = t.split(/[^a-z0-9]+/).filter(Boolean);
@@ -86,7 +58,6 @@ const titleHasTerm = (title, term) => {
         return true;
     return term.length >= 5 && t.replace(/[^a-z0-9]+/g, '').includes(term);
 };
-// Validate captured JSON-LD per page, keeping findings whose issue-kinds match `kinds`.
 function schemaFindings(ctx, kinds) {
     const set = new Set(kinds);
     const out = [];
@@ -97,11 +68,8 @@ function schemaFindings(ctx, kinds) {
     }
     return out;
 }
-// Position→expected-CTR curve lives in core/ctrModel (shared with the dashboard). Re-export it so
-// existing `import { expectedCtr } from './checks.js'` call sites keep working.
 export { expectedCtr };
 export const CHECKS = [
-    // ── On-page (crawl, deterministic) ──────────────────────────────────────
     {
         id: 'missing-title', category: 'onpage', severity: 'crit', labels: ['D'], certainty: 1, effortBase: 1, fixType: 'per-page',
         title: 'Missing title tag', fix: 'Add a unique, descriptive <title> (~50–60 chars).',
@@ -132,19 +100,11 @@ export const CHECKS = [
         title: 'Thin content', fix: 'Expand or consolidate — under ~200 words of body text.',
         run: (c) => rows(c, `SELECT url_key urlKey, word_count FROM pages WHERE status_code=200 AND indexable=1 AND word_count < 200`).map(r => ({ urlKey: r.urlKey, evidence: { wordCount: r.word_count } })),
     },
-    // ── Indexation / crawlability ───────────────────────────────────────────
     {
-        // RETIRED: 'canonical-mismatch' (was HIGH). A 200 page whose canonical points to a *healthy*
-        // 200 indexable URL is intentional consolidation (slug variants, category merges) — normal SEO,
-        // not an issue, yet it fired HIGH on every such page (pure noise). Every actionable case is
-        // already covered by a higher-signal check: broken-canonical-target (unhealthy target),
-        // canonical-ignored (Google ranks the non-canonical page), canonical-conflict (GSC disagrees).
-        // So plain "canonical points elsewhere" has no high-confidence residual — removed.
         id: 'broken-internal-links', category: 'crawlability', severity: 'crit', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'automated',
         title: 'Internal links to 4xx/5xx', fix: 'Repoint internal links to a live, canonical URL.',
         run: (c) => rows(c, `SELECT l.target_key urlKey, p.status_code status, COUNT(DISTINCT l.source_key) sources FROM links l JOIN pages p ON p.url_key=l.target_key WHERE l.is_internal=1 AND p.status_code >= 400 AND p.status_code NOT IN (429,503) GROUP BY l.target_key`).map(r => ({ urlKey: r.urlKey, evidence: { status: r.status, linkingPages: r.sources } })),
     },
-    // ── Extractor-dependent (images + canonical shape) ──────────────────────
     {
         id: 'image-alt', category: 'onpage', severity: 'low', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'per-page',
         title: 'Images missing alt text', fix: 'Add descriptive alt text to content images (alt="" only for decorative).',
@@ -160,13 +120,8 @@ export const CHECKS = [
         title: 'Multiple canonical tags', fix: 'Keep exactly one rel=canonical — conflicting canonicals let Google pick (or ignore) one.',
         run: (c) => rows(c, `SELECT url_key urlKey, canonical_count cnt FROM pages WHERE status_code=200 AND canonical_count > 1`).map(r => ({ urlKey: r.urlKey, evidence: { canonicalCount: r.cnt } })),
     },
-    // ── Extractor additions (CLS, headings, mixed content, directives, social) ───
     {
         id: 'images-missing-dimensions', category: 'onpage', severity: 'low', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'per-page',
-        // Lint, NOT a measured Core Web Vital. Missing width/height attributes only cause CLS if the
-        // CSS doesn't already reserve space — modern themes using aspect-ratio / fixed boxes have ~0
-        // measured CLS despite missing attributes. So we report it as a hygiene lint and explicitly say
-        // it's not a confirmed CWV issue; escalate only against field CLS (high-yield-cwv-fail does that).
         title: 'Images missing width/height attributes', fix: 'Add width & height (or rely on CSS aspect-ratio) so the browser reserves space. NOTE: this is a lint — if your CSS already reserves space (aspect-ratio / fixed box) measured CLS is likely ~0 and there is nothing to fix. Confirm with field CLS before prioritising.',
         run: (c) => rows(c, `SELECT url_key urlKey, images_missing_dimensions n, image_count total FROM pages WHERE status_code=200 AND indexable=1 AND images_missing_dimensions > 0`).map(r => ({ urlKey: r.urlKey, evidence: { missingDimensions: r.n, total: r.total, note: 'lint only — no measured CLS impact unless field data shows layout shift' } })),
     },
@@ -190,13 +145,11 @@ export const CHECKS = [
         title: 'No social share tags', fix: 'Add Open Graph (og:title/og:image) and/or Twitter Card tags so shared links render a rich preview.',
         run: (c) => rows(c, `SELECT url_key urlKey FROM pages WHERE status_code=200 AND indexable=1 AND (og_tags IS NULL OR og_tags='') AND (twitter_tags IS NULL OR twitter_tags='')`).map(r => ({ urlKey: r.urlKey, evidence: {} })),
     },
-    // ── Security / war-stories (headers now captured) ───────────────────────
     {
         id: 'missing-hsts', category: 'security', severity: 'low', labels: ['D'], certainty: 1, effortBase: 1, fixType: 'global',
         title: 'Missing HSTS header', fix: 'Add Strict-Transport-Security with a sensible max-age.',
         run: (c) => rows(c, `SELECT url_key urlKey FROM pages WHERE status_code=200 AND ${HTML_CT} AND (security_headers IS NULL OR security_headers NOT LIKE '%hsts%') LIMIT 1`).map(r => ({ urlKey: r.urlKey, evidence: { note: 'representative page; HSTS is site-wide' } })),
     },
-    // ── Merged GSC × crawl (the differentiator) ─────────────────────────────
     {
         id: 'noindex-with-traffic', category: 'indexation', severity: 'crit', labels: ['D', 'G'], certainty: 1, effortBase: 1, fixType: 'per-page',
         title: 'Noindex page still getting clicks', fix: 'Remove noindex if the page should rank — it earns clicks.',
@@ -245,7 +198,6 @@ export const CHECKS = [
         title: 'Striking-distance query (page 2)', fix: 'Small on-page + internal-link push could reach page 1.',
         run: (c) => c.gscMaxDate ? rows(c, `SELECT page_key urlKey, query, SUM(position*impressions)*1.0/NULLIF(SUM(impressions),0) position, SUM(impressions) impressions FROM search_analytics WHERE query IS NOT NULL AND ${win(c.gscMaxDate)} GROUP BY query, page_key HAVING SUM(position*impressions)*1.0/NULLIF(SUM(impressions),0)>10 AND SUM(position*impressions)*1.0/NULLIF(SUM(impressions),0)<=20 AND SUM(impressions)>=20 ORDER BY impressions DESC LIMIT 50`).map(r => ({ urlKey: r.urlKey, evidence: { query: r.query, position: Math.round(r.position * 10) / 10, impressions: r.impressions } })) : [],
     },
-    // ── Additions from industry checklist review (buildable on current data) ──
     {
         id: 'title-too-long', category: 'onpage', severity: 'low', labels: ['D'], certainty: 1, effortBase: 1, fixType: 'per-page',
         title: 'Title over ~60 chars', fix: 'Trim the title so the primary keyword sits within ~60 chars.',
@@ -264,8 +216,6 @@ export const CHECKS = [
     {
         id: 'redirect-chain', category: 'crawlability', severity: 'med', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'automated',
         title: 'Redirect chain (2+ hops)', fix: 'Collapse to a single hop to the final URL.',
-        // Count hops in SQL (json_array_length, guarded by json_valid) and filter to >=2 there — so we
-        // never pull every redirect-bearing page into JS just to count + drop most of them.
         run: (c) => rows(c, `SELECT url_key urlKey, json_array_length(redirects) hops FROM pages
       WHERE redirects IS NOT NULL AND json_valid(redirects) AND json_array_length(redirects) >= 2`)
             .map(r => ({ urlKey: r.urlKey, evidence: { hops: r.hops } })),
@@ -273,13 +223,6 @@ export const CHECKS = [
     {
         id: 'internal-links-to-redirects', category: 'crawlability', severity: 'med', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'automated',
         title: 'Internal links pointing through redirects', fix: 'Repoint internal links to the final URL (saves crawl + equity).',
-        // Flag a link ONLY if the raw href it uses is itself a redirect source — i.e. that exact URL
-        // appears as a `from` hop in some redirect chain. The old query flagged any link whose target
-        // page merely HAD a `redirects` entry, which fired site-wide on www-canonical properties: every
-        // page records the seed apex→www hop, yet the actual hrefs already use the final (www) URL and
-        // never redirect. Matching the href (fragment-stripped) against the real redirect-source set is
-        // robust to that artefact. Kept entirely in SQL (json_each over pages.redirects) so we never
-        // materialise the whole links table in JS — the links table is the largest in the DB.
         run: (c) => {
             return rows(c, `
         WITH redir_src AS (
@@ -302,11 +245,8 @@ export const CHECKS = [
     {
         id: 'missing-structured-data', category: 'schema', severity: 'low', labels: ['D'], certainty: 1, effortBase: 5, fixType: 'per-page',
         title: 'No structured data', fix: 'Add relevant JSON-LD (Article, Product, Organization…).',
-        // Only "no structured data" if there's no JSON-LD AND no Microdata/RDFa either — else a
-        // page using valid Microdata (common on older themes) is falsely flagged.
         run: (c) => rows(c, `SELECT url_key urlKey FROM pages WHERE status_code=200 AND indexable=1 AND (json_ld IS NULL OR json_ld='') AND COALESCE(has_microdata,0)=0 AND COALESCE(has_rdfa,0)=0`).map(r => ({ urlKey: r.urlKey, evidence: {} })),
     },
-    // ── Schema validation (validate captured json_ld vs maintained Rich-Results map) ──
     {
         id: 'invalid-schema', category: 'schema', severity: 'high', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'per-page',
         title: 'Invalid structured data', fix: 'Fix the JSON-LD so each block parses and carries @context (https://schema.org) + a valid @type.',
@@ -335,15 +275,6 @@ export const CHECKS = [
     {
         id: 'keyword-cannibalisation', category: 'merged', severity: 'high', labels: ['G'], certainty: 1, effortBase: 5, fixType: 'per-page',
         title: 'Keyword cannibalisation', fix: 'Consolidate or differentiate — multiple URLs compete for one query.',
-        // A URL only "competes" if it ranks for the query (impression-weighted pos < 20) AND holds a
-        // non-trivial share of the leader's impressions — ≥10% of the leader OR ≥500 impressions in its
-        // own right, and ≥10 impressions minimum. Without that floor, incidental long-tail appearances
-        // (a page picking up 1–7 impressions for the query) counted as competitors: e.g. "best vr headset"
-        // reported 10 URLs when ONE page held 59,570 impressions at pos 1.1 and the other nine had 1–7
-        // each — not cannibalisation, Google had decided. The absolute ≥500 backstop keeps a genuine
-        // mid-volume rival under a dominant leader (e.g. 60k leader + a real 4k second page = 6.7%, below
-        // the 10% bar) from being silently dropped. We also exclude "dominance" where the best pages both
-        // sit at pos 1–2 (indented/double results are good). Branded queries are dropped via brandExcl.
         run: (c) => {
             if (!c.gscMaxDate)
                 return [];
@@ -368,9 +299,6 @@ export const CHECKS = [
                 const keys = String(r.pk || '').split('\x1f'), imps = String(r.im || '').split('\x1f'), poss = String(r.ps || '').split('\x1f');
                 const items = keys.map((u, i) => ({ url: u, impressions: Number(imps[i]) || 0, position: Number(poss[i]) || 0, title: titleOf.get(u)?.title ?? null }))
                     .sort((a, b) => b.impressions - a.impressions);
-                // Differentiation signal: do the top-2 competing pages share significant title terms beyond the
-                // query itself? If not (and both are titled), they're likely intentionally distinct pages (e.g.
-                // pairwise comparisons), not true duplicates competing for one intent — annotate, don't suppress.
                 const q = new Set(terms(r.query));
                 const sig = items.slice(0, 2).map(it => terms(it.title ?? '').filter((w) => !q.has(w)));
                 const differentiated = sig.length === 2 && items[0].title != null && items[1].title != null
@@ -389,22 +317,16 @@ export const CHECKS = [
     {
         id: 'ctr-below-expected', category: 'merged', severity: 'high', labels: ['G'], certainty: 1, effortBase: 3, fixType: 'per-page',
         title: 'CTR far below position-expected', fix: 'Rewrite title/meta — ranking well but under-clicked (snippet opportunity).',
-        // High-confidence floor: ≥500 impressions/28d. A title/meta rewrite (HIGH, ~3h) is only
-        // worth flagging where the snippet earns enough visibility for a CTR lift to pay back — a
-        // 100-impression page at 1% vs 3% expected is a 2-clicks gap, not a HIGH issue.
         run: (c) => c.gscMaxDate ? rows(c, `SELECT page_key urlKey, SUM(position*impressions)*1.0/NULLIF(SUM(impressions),0) position, SUM(clicks) clicks, SUM(impressions) impressions FROM search_analytics WHERE page_key IS NOT NULL AND ${win(c.gscMaxDate)} GROUP BY page_key HAVING SUM(position*impressions)*1.0/NULLIF(SUM(impressions),0) <= 10 AND SUM(impressions) >= 500`)
             .map(r => { const ctr = r.clicks / r.impressions; const exp = expectedCtr(r.position); return { urlKey: r.urlKey, ctr, exp, position: r.position, impressions: r.impressions }; })
             .filter(x => x.ctr < x.exp * 0.5)
             .map(x => {
             const ev = { position: Math.round(x.position * 10) / 10, ctr: Math.round(x.ctr * 1000) / 10 + '%', expectedCtr: Math.round(x.exp * 1000) / 10 + '%', impressions: x.impressions };
-            // Extreme case: near-zero CTR at a strong position isn't a title problem — a SERP feature
-            // (image/video/AI overview) or navigational intent is taking the clicks. Different fix.
             if (x.position <= 5 && x.ctr < x.exp * 0.15)
                 ev.note = 'near-zero CTR for the position — likely a SERP feature or navigational intent taking the clicks; check the live SERP before rewriting the title/meta';
             return { urlKey: x.urlKey, evidence: ev };
         }) : [],
     },
-    // ── Period-over-period (GSC history by date) — the trend questions SEOs live in ──
     {
         id: 'traffic-decay', category: 'merged', severity: 'high', labels: ['G'], certainty: 1, effortBase: 5, fixType: 'per-page',
         title: 'Page losing clicks (period-over-period)', fix: 'Refresh and expand the content, and check for lost rankings — this page’s Search Console clicks fell sharply against the previous 28 days.',
@@ -416,7 +338,6 @@ export const CHECKS = [
       FROM prev LEFT JOIN cur ON cur.page_key=prev.page_key
       WHERE prev.c >= 30 AND COALESCE(cur.c,0) < prev.c * 0.6
       ORDER BY (prev.c - COALESCE(cur.c,0)) DESC LIMIT 40`)
-            // page_key IS a url_key — carry it in the joinable column, not just evidence.
             .map(r => ({ urlKey: r.url, evidence: { url: r.url, previousClicks: r.prevC, currentClicks: r.curC, clicksLost: r.prevC - r.curC, dropPercent: Math.round((1 - r.curC / r.prevC) * 100) + '%', clicks: r.prevC - r.curC, impressions: r.curI, position: Math.round(r.pos * 10) / 10 } })),
     },
     {
@@ -447,7 +368,6 @@ export const CHECKS = [
         title: 'Indexable page with no search traffic', fix: 'No impressions in 90 days despite being indexable — consolidate, improve, or noindex/prune to concentrate crawl budget and internal authority (confirm it isn’t seasonal or brand-new first).',
         run: (c) => (!c.gscMaxDate || spanDays(c) < 90) ? [] : rows(c, `SELECT url_key urlKey, ipr FROM pages WHERE status_code=200 AND indexable=1 AND ${HTML_CT} AND COALESCE(click_depth, 999) >= 1 AND url_key NOT IN (SELECT DISTINCT page_key FROM search_analytics WHERE page_key IS NOT NULL AND date <= '${c.gscMaxDate}' AND date > date('${c.gscMaxDate}','-90 days') AND impressions > 0) ORDER BY ipr DESC LIMIT 100`).map(r => ({ urlKey: r.urlKey, evidence: { note: 'indexable but zero impressions in 90 days', ipr: Math.round(r.ipr) } })),
     },
-    // ── On-page parity (crawl-only, deterministic) ──
     {
         id: 'duplicate-meta-description', category: 'onpage', severity: 'low', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'per-page',
         title: 'Duplicate meta description', fix: 'Give each indexable page a unique meta description.',
@@ -506,7 +426,6 @@ export const CHECKS = [
                 .map(x => ({ urlKey: x.urlKey, evidence: { topQuery: x.query, impressions: x.impressions, h1: x.h1 } }));
         },
     },
-    // ── Content cluster (AI-era / RAG layer): exploit the chunked body text captured at crawl ──
     {
         id: 'body-missing-top-query', category: 'merged', severity: 'med', labels: ['D', 'G'], certainty: 1, effortBase: 5, fixType: 'per-page',
         title: 'Top query missing from the page body', fix: 'The page ranks for this query yet its terms appear nowhere — not the title, H1, or body copy. Add a section that actually covers the topic; if it can’t, the page is too thin to hold the ranking and a stronger page should target it.',
@@ -527,8 +446,8 @@ export const CHECKS = [
                     for (const ch of JSON.parse(x.bc))
                         body += ` ${ch.heading || ''} ${ch.text || ''}`;
                 }
-                catch { /* skip */ }
-                return !q.some((w) => titleHasTerm(body, w)); // none of the query's terms appear on the page
+                catch { }
+                return !q.some((w) => titleHasTerm(body, w));
             }).map(x => ({ urlKey: x.urlKey, evidence: { topQuery: x.query, impressions: x.impressions, note: 'query terms absent from title, H1 and body' } }));
         },
     },
@@ -565,7 +484,7 @@ export const CHECKS = [
             return r.filter(x => {
                 const q = terms(x.query);
                 if (q.length < 2)
-                    return false; // only multi-term queries can be "scattered"
+                    return false;
                 let chunks;
                 try {
                     chunks = JSON.parse(x.bc);
@@ -575,8 +494,8 @@ export const CHECKS = [
                 }
                 const whole = `${x.title || ''} ${chunks.map(ch => `${ch.heading || ''} ${ch.text || ''}`).join(' ')}`;
                 if (!q.every((w) => titleHasTerm(whole, w)))
-                    return false; // page must contain all terms (else it's body-missing)
-                return !chunks.some(ch => { const h = `${ch.heading || ''} ${ch.text || ''}`; return q.every((w) => titleHasTerm(h, w)); }); // but no single chunk does
+                    return false;
+                return !chunks.some(ch => { const h = `${ch.heading || ''} ${ch.text || ''}`; return q.every((w) => titleHasTerm(h, w)); });
             }).map(x => ({ urlKey: x.urlKey, evidence: { topQuery: x.query, impressions: x.impressions, note: 'terms present but never together in one passage' } }));
         },
     },
@@ -605,10 +524,6 @@ export const CHECKS = [
         },
     },
     {
-        // Hobo "Signal Coherence" / Goldmine; leak: anchor_mismatch. Google leans on internal anchors to
-        // understand a page's topic — if the IN-CONTENT inbound anchors never mention the query the page
-        // actually ranks for, that's an incoherent internal signal. Guard against boilerplate FPs by using
-        // ONLY placement='body' anchors (nav/footer/aside excluded) and requiring ≥3 of them.
         id: 'anchor-text-incoherent', category: 'merged', severity: 'med', labels: ['D', 'G'], certainty: 1, effortBase: 3, fixType: 'per-page',
         title: 'Internal anchors don’t mention the page’s top query', fix: 'The in-content internal links pointing at this page never use its top-ranking query in their anchor text — and Google leans on internal anchors to understand what a page is about. Re-anchor the key internal links with descriptive, query-relevant text instead of generic “read more” / brand-only labels.',
         run: (c) => {
@@ -619,12 +534,6 @@ export const CHECKS = [
          FROM search_analytics WHERE query IS NOT NULL AND page_key IS NOT NULL AND ${win(c.gscMaxDate)} ${brandExcl(c)} GROUP BY page_key, query) s
         JOIN pages p ON p.url_key = s.page_key
         WHERE s.rn = 1 AND p.indexable = 1 AND s.impr >= 100`);
-            // Pool only GENUINE editorial anchors. "Chrome" (nav/footer/breadcrumb/CTA) is detected
-            // STRUCTURALLY, not via an English word-list: an anchor text reused across a large share of
-            // the site's pages is templated boilerplate — e.g. the EHI homepage's 2,940 inbound "Home"
-            // breadcrumb links — and that holds in any language ("Startseite", "Accueil"…). We also drop
-            // self-links and anchors with no letters ("(0)", page numbers, arrows). Editorial in-content
-            // anchors recur on only a handful of pages, so they survive.
             const anchors = new Map();
             for (const a of rows(c, `
         WITH body_anchors AS (
@@ -645,18 +554,13 @@ export const CHECKS = [
             return top.filter(x => {
                 const a = anchors.get(x.urlKey);
                 if (!a || a.n < 3)
-                    return false; // need enough genuine in-content inbound links to judge
+                    return false;
                 const q = terms(x.query);
                 return q.length > 0 && !q.some((w) => titleHasTerm(a.pool, w));
             }).map(x => { const a = anchors.get(x.urlKey); return { urlKey: x.urlKey, evidence: { topQuery: x.query, impressions: x.impressions, inboundInContentLinks: a.n } }; });
         },
     },
     {
-        // The "RAG snippetability" test. A local cross-encoder (the kind AI search uses to re-rank) scored
-        // every chunk against the page's top query; we persisted the single best-passage score. A low max
-        // means no dense, extractable answer anywhere on the page — it will lose in AI/passage search even
-        // if it keyword-matches. Model-derived (not deterministic truth) → N label, includeJudgement-gated.
-        // Requires `score_passages` to have run (like CWV needs page_lighthouse).
         id: 'weak-passage-answer', category: 'merged', severity: 'high', labels: ['G', 'N'], certainty: 0.8, effortBase: 5, fixType: 'per-page',
         title: 'No passage strongly answers the ranking query (AI-search risk)', fix: 'A local neural reranker found no single passage on this page that confidently answers its top query — the page covers the topic loosely but offers no dense, extractable answer, so AI/passage search will prefer a clearer source. Add a focused, self-contained passage: a heading that states the question + a direct ~50-word answer up top. Run `score_passages` to (re)populate.',
         run: (c) => rows(c, `SELECT url_key urlKey, max_passage_score mps, max_passage_query q, max_passage_impr impr FROM pages
@@ -664,10 +568,6 @@ export const CHECKS = [
             .map(x => ({ urlKey: x.urlKey, evidence: { topQuery: x.q, maxPassageScore: x.mps, impressions: x.impr ?? 0, note: 'best passage scores below the reranker confidence threshold' } })),
     },
     {
-        // Dejan: search weights the opening heavily and AI answers front-load. If the ranking query's
-        // terms are present LATER in the page but absent from the opening (~first 2 chunks / ~200 words),
-        // the answer is buried. (body-missing-top-query handles total absence; this is the buried case.)
-        // Informational intent only — front-loading matters less for navigational/transactional queries.
         id: 'answer-not-front-loaded', category: 'merged', severity: 'med', labels: ['G', 'N'], certainty: 0.6, effortBase: 3, fixType: 'per-page',
         title: 'Answer to the ranking query is buried, not front-loaded', fix: 'The page covers its top query but the terms don’t appear up top (the intro / first section). Google weights the opening heavily and AI answers front-load — move a direct ~50–100-word answer to the first section. (Heuristic — informational queries.)',
         run: (c) => {
@@ -699,14 +599,10 @@ export const CHECKS = [
         },
     },
     {
-        // Dejan "density beats length": AI grounds ~370 words/page, diminishing past ~1,500. A very long
-        // page with an over-long unbroken section grounds poorly — split it into focused, headed passages.
         id: 'content-bloat', category: 'content', severity: 'low', labels: ['D', 'N'], certainty: 0.6, effortBase: 5, fixType: 'per-page',
         title: 'Over-long section dilutes AI-grounding (density beats length)', fix: 'This page has a very long unbroken section. AI search grounds only ~370 words per page with sharp diminishing returns past ~1,500 — break the long section into focused, headed passages (or tighten it) so each answers one thing cleanly.',
         run: (c) => {
             const out = [];
-            // Use the real (uncapped) word_count ÷ number of headed sections — chunk TEXT is capped at
-            // extraction, so we infer over-long sections from words-per-heading, not from chunk length.
             for (const x of iterRows(c, `SELECT url_key urlKey, word_count wc, body_chunks bc FROM pages WHERE status_code=200 AND indexable=1 AND ${HTML_CT} AND word_count >= 2500 AND body_chunks IS NOT NULL`)) {
                 let chunks;
                 try {
@@ -724,15 +620,11 @@ export const CHECKS = [
         },
     },
     {
-        // Hobo Level 3 freshness / lastSignificantUpdate. Gemini guard: YoY windows (negate seasonality
-        // + zero-click-SERP CTR loss). Flag when the page hasn't been meaningfully re-dated in >12 months
-        // AND clicks are down >25% YoY AND impressions down >15% YoY (impressions confirm ranking decay,
-        // not just CTR). Needs ~13 months of GSC — guarded by spanDays so it stays silent on shallow syncs.
         id: 'stale-content', category: 'merged', severity: 'med', labels: ['D', 'G'], certainty: 1, effortBase: 5, fixType: 'per-page',
         title: 'Stale page declining year-on-year', fix: 'This page hasn’t been meaningfully updated in over a year and its Search Console clicks are down sharply versus the same period last year — refresh and expand the content (and honestly re-date it) to rebuild the freshness signal Google rewards.',
         run: (c) => {
             if (!c.gscMaxDate || spanDays(c) < 455)
-                return []; // YoY window reaches back 455 days — anything less truncates the prior-year period
+                return [];
             const d = c.gscMaxDate;
             const out = [];
             const rs = rows(c, `
@@ -748,7 +640,7 @@ export const CHECKS = [
                     continue;
                 const ageDays = (Date.parse(d) - Date.parse(dm)) / 86400000;
                 if (!(ageDays >= 365))
-                    continue; // only genuinely stale pages (>12 months since last schema date)
+                    continue;
                 out.push({ urlKey: x.url, evidence: { url: x.url, dateModified: dm.slice(0, 10), clicksYoY: `${x.pyC}→${x.curC} (-${Math.round((1 - x.curC / x.pyC) * 100)}%)`, impressionsYoY: `${x.pyI}→${x.curI}`, clicks: x.pyC - x.curC, impressions: x.pyI } });
             }
             return out;
@@ -790,23 +682,17 @@ export const CHECKS = [
                     without.push(p.urlKey);
             }
             if (pages.length === 0 || withBc / pages.length < 0.4)
-                return []; // site doesn't use breadcrumbs → design choice, not a bug
+                return [];
             return without.map(u => ({ urlKey: u, evidence: { note: 'site uses BreadcrumbList elsewhere; missing here' } }));
         },
     },
-    // ── Merged crawl × Search Console — the "expert questions" that need both datasets ──
     {
         id: 'ghost-pages', category: 'merged', severity: 'high', labels: ['D', 'G'], certainty: 1, effortBase: 5, fixType: 'per-page',
         title: 'Ranking page the crawl can’t reach', fix: 'Google sends impressions/clicks to this URL but the site crawl never reached it — add internal links so it’s discoverable (or confirm it should exist and isn’t blocked).',
         run: (c) => {
             if (!c.gscMaxDate)
                 return [];
-            // Only meaningful on a COMPLETE crawl — if the crawl hit its maxPages cap, "absent
-            // from crawl" is unreliable. Tie the guard to the crawl that produced the CURRENT
-            // pages (not the latest crawl_metadata row, which may be a later failed crawl).
             const m = c.db.prepare('SELECT urls_crawled c, max_pages m FROM crawl_metadata WHERE crawl_id = (SELECT crawl_id FROM pages LIMIT 1)').get();
-            // max_pages is nullable (NULL = no cap = complete crawl) — `c >= null` coerces to
-            // `c >= 0`, which would silently disable the check forever on capless crawls.
             if (!m || m.c === 0 || (m.m != null && m.c >= m.m))
                 return [];
             return rows(c, `SELECT page_key urlKey, SUM(clicks) clicks, SUM(impressions) impressions FROM search_analytics
@@ -831,7 +717,6 @@ export const CHECKS = [
                 .map(x => ({ urlKey: x.urlKey, evidence: { topQuery: x.query, impressions: x.impressions, title: x.title } }));
         },
     },
-    // ── Internal link graph (iPR + click-depth + anchor text, from the crawl `links` table) ──
     {
         id: 'deep-pages', category: 'crawlability', severity: 'med', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'per-page',
         title: 'Page buried deep in the structure', fix: 'Add in-content (body) links from higher-level pages — this page is 4+ clicks from the homepage via body links.',
@@ -843,10 +728,6 @@ export const CHECKS = [
         run: (c) => c.gscMaxDate ? rows(c, `SELECT p.url_key urlKey, p.ipr ipr, p.inlink_count inl, SUM(sa.impressions) impressions FROM pages p JOIN search_analytics sa ON sa.page_key=p.url_key WHERE p.indexable=1 AND p.ipr < 30 AND p.inlink_count BETWEEN 1 AND 3 AND sa.${win(c.gscMaxDate)} GROUP BY p.url_key HAVING SUM(sa.impressions) >= 300 ORDER BY impressions DESC`).map(r => ({ urlKey: r.urlKey, evidence: { impressions: r.impressions, ipr: Math.round(r.ipr), inlinks: r.inl } })) : [],
     },
     {
-        // The tier BETWEEN "orphan" (0 inlinks) and "fine": pages reached almost only via nav/footer.
-        // inlink_count counts ALL internal links, so a page sitting in the global nav looks well-linked
-        // even with zero EDITORIAL links — yet Google leans on in-content links for topic + equity. We
-        // count distinct in-content (placement='body') inbound sources; ≤2 + real demand = under-linked.
         id: 'underlinked-editorial', category: 'merged', severity: 'high', labels: ['D', 'G'], certainty: 1, effortBase: 3, fixType: 'per-page',
         title: 'High demand, almost no in-content internal links', fix: 'This page earns real impressions but is reached mainly via nav/footer — add descriptive in-content links to it from related articles. Editorial body links pass more topical context and equity than templated nav links.',
         run: (c) => c.gscMaxDate ? rows(c, `
@@ -858,18 +739,6 @@ export const CHECKS = [
       HAVING SUM(sa.impressions) >= 300 AND bodyLinks <= 2
       ORDER BY impressions DESC LIMIT 40`).map(r => ({ urlKey: r.urlKey, evidence: { impressions: r.impressions, inContentLinks: r.bodyLinks, note: 'reached mainly via nav/footer — thin on editorial (in-content) links' } })) : [],
     },
-    // NOTE: internal anchor-text checks (over-optimisation + generic/empty anchors) prototyped
-    // and PULLED twice. Re-evaluated 2026-06-22 against the AgricIDaniel/claude-seo and
-    // Bhanunamikaze/Agentic-SEO-Skill repos, this time using the links.placement='body' filter
-    // plus excluding anchors that match the target's own title/H1. On real data (ehi.com.au) the
-    // dominant survivors are still false positives: sitewide template CTAs ("home" 864/865,
-    // "contact us", "apply today") and category links whose anchor IS the page title. The
-    // page-level "mostly generic-anchored" variant returned 0 signal; raw empty anchors are
-    // image/thumbnail-link noise (3,764/23,435 body links). Reliable detection needs an
-    // editorial-vs-template link classifier we don't store (placement='body' still includes
-    // in-template CTAs and product grids). Keep pulled — a wrong finding is worse than none.
-    // ── Backlinks (need page_backlinks populated via pull_backlinks; gate so we never assert
-    //    "no external links" without data) ──
     {
         id: 'backlinks-to-404', category: 'crawlability', severity: 'crit', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'per-page',
         title: 'External backlinks pointing to a dead page', fix: '301-redirect this URL to the best live equivalent — external link equity is hitting a 4xx/5xx page and being wasted.',
@@ -882,17 +751,14 @@ export const CHECKS = [
         run: (c) => {
             const has = c.db.prepare('SELECT COUNT(*) n FROM page_backlinks').get().n;
             if (!has)
-                return []; // backlinks not pulled — can't credibly assert "no external links"
+                return [];
             return rows(c, `SELECT p.url_key urlKey FROM pages p LEFT JOIN page_backlinks b ON b.url_key=p.url_key WHERE p.status_code=200 AND p.indexable=1 AND p.inlink_count=0 AND COALESCE(b.backlinks,0)=0`)
                 .map(r => ({ urlKey: r.urlKey, evidence: { inlinks: 0, backlinks: 0 } }));
         },
     },
-    // ── Phase 6a — expert questions where crawl (intent) and reality diverge ──
     {
         id: 'ipr-bleed-by-status', category: 'crawlability', severity: 'high', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'automated',
         title: 'Internal link equity flowing into dead URLs', fix: 'Repoint or 301 these internal links — they target non-200 URLs and waste the internal PageRank of the (often high-authority) pages linking to them.',
-        // Sum the iPR of the SOURCE pages linking to each non-200 internal target. "Found a 404" is
-        // junior; "this 404 drains the equity of N high-iPR pages" is the director-level find.
         run: (c) => rows(c, `SELECT l.target_key urlKey, COUNT(DISTINCT l.source_key) linkingPages,
         ROUND(SUM(src.ipr), 1) wastedIpr, t.status_code st
       FROM links l
@@ -905,9 +771,6 @@ export const CHECKS = [
     {
         id: 'broken-canonical-target', category: 'indexation', severity: 'high', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'per-page',
         title: 'Canonical points to a broken or unhealthy URL', fix: 'Point the canonical at a live, indexable, self-canonical HTTPS URL — Google ignores a canonical whose target is a 4xx/5xx/redirect, noindex, itself canonicalised elsewhere (a chain/loop), or an HTTPS→HTTP downgrade.',
-        // Join the declared canonical_key back to the crawl. Only flag when we crawled the target.
-        // Skip self-canonicals. Covers: non-200 target, noindex target, canonical chain/loop (target
-        // canonicalises onward), and HTTPS→HTTP downgrade (research: Sitebulb indexability hints).
         run: (c) => rows(c, `SELECT p.url_key urlKey, p.canonical_url canon, p.canonical_key ck, t.status_code st, t.noindex ni, t.canonical_key tck
       FROM pages p JOIN pages t ON t.url_key = p.canonical_key
       WHERE p.canonical_key IS NOT NULL AND p.canonical_key != p.url_key AND p.status_code = 200
@@ -925,8 +788,6 @@ export const CHECKS = [
     {
         id: 'faceted-spider-trap', category: 'crawlability', severity: 'high', labels: ['D', 'G'], certainty: 1, effortBase: 5, fixType: 'global',
         title: 'Indexable faceted URLs burning crawl budget', fix: 'noindex (or robots-disallow / canonicalise) multi-parameter filter URLs — they are indexable but earn zero search traffic, so they only waste crawl budget and risk index bloat.',
-        // Multi-parameter (>=2 params), indexable, zero GSC impressions in-window = classic facet trap.
-        // Gate on GSC so "zero search value" is a real claim, not just "no data".
         run: (c) => {
             if (!c.gscMaxDate)
                 return [];
@@ -939,8 +800,6 @@ export const CHECKS = [
     {
         id: 'soft-404-shell', category: 'indexation', severity: 'med', labels: ['D', 'G'], certainty: 1, effortBase: 3, fixType: 'per-page',
         title: 'Soft 404 — 200 OK but Google treats it as not-found', fix: 'Either populate the page with real content, or return a true 404/410 (or noindex) — it serves 200 but Google has flagged it as a soft 404.',
-        // URL Inspection page-fetch-state = soft 404 while the crawler sees a 200. The crawler alone
-        // would call this page fine; Google disagrees. Needs URL Inspection populated.
         run: (c) => rows(c, `SELECT i.url_key urlKey, p.word_count wc, p.bytes bytes
       FROM url_inspection i JOIN pages p ON p.url_key = i.url_key
       WHERE LOWER(i.page_fetch_state) LIKE '%soft%' AND p.status_code = 200`).map(r => ({ urlKey: r.urlKey, evidence: { pageFetchState: 'soft 404', wordCount: r.wc, bytes: r.bytes } })),
@@ -948,9 +807,6 @@ export const CHECKS = [
     {
         id: 'rich-result-issues', category: 'schema', severity: 'med', labels: ['D', 'G'], certainty: 1, effortBase: 3, fixType: 'per-page',
         title: 'Google-verified rich result issues (URL Inspection)', fix: 'Fix the structured-data issues Google itself reports for this page — these come from the URL Inspection API (Google’s own validation), not our local validator, so they are authoritative. Address the listed issue messages per rich-result type.',
-        // Parses the stored richResultsResult JSON (url_inspection.rich_results) that inspect_urls
-        // already captures: detectedItems[].items[].issues[] carries Google's severity + message.
-        // Needs URL Inspection populated (run inspect_urls). Zero API cost — data is already in the DB.
         run: (c) => {
             const out = [];
             for (const r of iterRows(c, `SELECT url_key urlKey, rich_results rr FROM url_inspection WHERE rich_results IS NOT NULL AND rich_results != ''`)) {
@@ -961,8 +817,6 @@ export const CHECKS = [
                 catch {
                     continue;
                 }
-                // Dedup per (type, severity, message) with a count — a listicle repeats the same
-                // "Missing field review" warning per product item; keep one sample item per group.
                 const groups = new Map();
                 for (const det of parsed?.detectedItems ?? []) {
                     for (const item of det?.items ?? []) {
@@ -994,17 +848,14 @@ export const CHECKS = [
         title: 'hreflang missing return tag (not reciprocated)', fix: 'Add the reciprocal hreflang on the target page — Google ignores one-way hreflang annotations that don’t link back.',
         run: (c) => hreflangFindings(c).noReturn,
     },
-    // ── 6a finishers — consume persisted DataForSEO enrichments (gated; need the data pulled) ──
     {
         id: 'intent-vs-pagetype-mismatch', category: 'merged', severity: 'med', labels: ['G', 'N'], certainty: 0.7, effortBase: 8, fixType: 'per-page',
         title: 'Page type mismatches its query intent', fix: 'Reformat or retarget the page — its template doesn’t match the SERP intent for its top query (e.g. a product page ranking for an informational query, or an article for a transactional one). Run search_intent siteUrl:<property> to populate intents.',
-        // Join each page's top GSC query → persisted keyword_intent → page schema flavour (from json_ld).
-        // Judgement (N, 0.7): intent + schema-type inference is heuristic, so it only runs with includeJudgement.
         run: (c) => {
             if (!c.gscMaxDate)
                 return [];
             if ((c.db.prepare('SELECT COUNT(*) n FROM keyword_intent').get().n) === 0)
-                return []; // intents not pulled
+                return [];
             const r = rows(c, `SELECT s.page_key urlKey, s.query query, ki.intent intent, p.json_ld jsonLd FROM
         (SELECT page_key, query, ROW_NUMBER() OVER (PARTITION BY page_key ORDER BY SUM(impressions) DESC) rn
          FROM search_analytics WHERE query IS NOT NULL AND page_key IS NOT NULL AND ${win(c.gscMaxDate)} GROUP BY page_key, query) s
@@ -1035,7 +886,7 @@ export const CHECKS = [
             if (!c.gscMaxDate)
                 return [];
             if ((c.db.prepare('SELECT COUNT(*) n FROM page_cwv').get().n) === 0)
-                return []; // CWV not pulled
+                return [];
             return rows(c, `SELECT cw.url_key urlKey, cw.lcp_ms lcp, cw.cls cls, cw.performance perf,
           (SELECT COALESCE(SUM(clicks),0) FROM search_analytics sa WHERE sa.page_key = cw.url_key AND ${win(c.gscMaxDate)}) clicks
         FROM page_cwv cw
@@ -1044,14 +895,13 @@ export const CHECKS = [
                 .map(r => ({ urlKey: r.urlKey, evidence: { clicks: r.clicks, lcpMs: r.lcp != null ? Math.round(r.lcp) : null, cls: r.cls != null ? Math.round(r.cls * 1000) / 1000 : null, performance: r.perf != null ? Math.round(r.perf * 100) : null } }));
         },
     },
-    // ── 6b — per-template systemic issues (template-typed, deterministic) ──
     {
         id: 'pagination-canonical-to-page-1', category: 'crawlability', severity: 'high', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'global',
         title: 'Paginated pages canonicalising away from themselves', fix: 'Make each paginated page (page 2, 3, …) self-canonical. Canonicalising page 2+ back to page 1 tells Google the deeper pages are duplicates, so products/articles linked only from page 2+ drop out of the crawl.',
         run: (c) => rows(c, `SELECT url_key urlKey, url, canonical_url canon FROM pages
         WHERE status_code=200 AND canonical_count>0 AND canonical_key IS NOT NULL AND canonical_key != url_key
           AND (rel_prev=1 OR url LIKE '%/page/%' OR url GLOB '*[?&]page=[0-9]*' OR url GLOB '*[?&]paged=[0-9]*' OR url GLOB '*[?&]p=[0-9]*')`)
-            .filter(r => !/[?&](page|p)=1(\b|&|$)/.test(r.url) && !/\/page\/1(\/?$|\?)/.test(r.url)) // page 1 self-canonicalising to base is fine
+            .filter(r => !/[?&](page|p)=1(\b|&|$)/.test(r.url) && !/\/page\/1(\/?$|\?)/.test(r.url))
             .map(r => ({ urlKey: r.urlKey, evidence: { url: r.url, canonical: r.canon } })),
     },
     {
@@ -1074,13 +924,12 @@ export const CHECKS = [
             return out;
         },
     },
-    // ── 6d — Wikidata entity layer (heuristic H1→QID; N/judgement, gated on resolve_entities) ──
     {
         id: 'entity-internal-link-gap', category: 'crawlability', severity: 'low', labels: ['N'], certainty: 0.5, effortBase: 3, fixType: 'per-page',
         title: 'Topically related pages not internally linked', fix: 'Add an internal link from the broader page to the more specific one — Wikidata says their entities are related (subclass-of / part-of) but no internal link connects them, leaving a gap in the topical mesh. Run resolve_entities first; verify the entity match before acting (heuristic).',
         run: (c) => {
             if ((c.db.prepare('SELECT COUNT(*) n FROM page_entity').get().n) === 0)
-                return []; // not resolved
+                return [];
             return rows(c, `SELECT parent.url_key urlKey, child.url_key target, parent.label pl, child.label cl, ee.relation rel
         FROM entity_edge ee
         JOIN page_entity child  ON child.qid = ee.qid
@@ -1090,7 +939,6 @@ export const CHECKS = [
                 .map(r => ({ urlKey: r.urlKey, evidence: { suggestLinkTo: r.target, parentEntity: r.pl, childEntity: r.cl, relation: r.rel } }));
         },
     },
-    // ── Sitemap ↔ crawl reconciliation (gated on a sitemap having been fetched) ──
     {
         id: 'sitemap-non-indexable', category: 'indexation', severity: 'high', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'global',
         title: 'Sitemap lists non-indexable URLs', fix: 'Remove URLs from the XML sitemap that are 4xx/5xx, redirected, noindex, canonicalised or robots-blocked — the sitemap should list only canonical, indexable pages, or Google loses trust in it.',
@@ -1121,7 +969,6 @@ export const CHECKS = [
                 .map(r => ({ urlKey: r.urlKey, evidence: { inlinks: 0, note: 'in sitemap, no internal links' } }));
         },
     },
-    // ── Cheap performance proxies (from data captured at crawl time — no extra fetch) ──
     {
         id: 'slow-response', category: 'performance', severity: 'med', labels: ['D'], certainty: 1, effortBase: 5, fixType: 'global',
         title: 'Slow server response (TTFB proxy)', fix: 'Investigate slow server/TTFB — caching, CDN, or backend. Response time over ~1.5s hurts Core Web Vitals and crawl rate.',
@@ -1131,11 +978,6 @@ export const CHECKS = [
     {
         id: 'large-html', category: 'performance', severity: 'low', labels: ['D'], certainty: 1, effortBase: 5, fixType: 'per-page',
         title: 'Large HTML document (transferred)', fix: 'Trim the HTML payload — bloated markup slows render and First Contentful Paint (often huge inline SVG/CSS/JSON or unminified output). Judged on TRANSFERRED bytes, not raw: behind a compressing CDN (brotli/gzip) raw size matters far less.',
-        // Severity is on what the browser actually downloads, not raw bytes: a 200KB page served brotli
-        // is ~45KB over the wire and is NOT a real perf problem. We estimate transfer size (raw × ~0.22
-        // for br/gzip, else raw) and only flag pages whose ESTIMATED transferred HTML exceeds ~60KB.
-        // Prefilter at the 60KB threshold itself, not higher — an UNCOMPRESSED 60–150KB page
-        // (est = raw) is exactly the case that matters most and must reach the est filter.
         run: (c) => rows(c, `SELECT url_key urlKey, bytes, content_encoding enc FROM pages WHERE status_code=200 AND ${HTML_CT} AND bytes > 60000 ORDER BY bytes DESC`)
             .map(r => { const compressed = /br|gzip|deflate|zstd/i.test(r.enc || ''); const est = compressed ? Math.round(r.bytes * 0.22) : r.bytes; return { urlKey: r.urlKey, est, compressed, raw: r.bytes }; })
             .filter(x => x.est > 60000)
@@ -1147,7 +989,6 @@ export const CHECKS = [
         run: (c) => rows(c, `SELECT url_key urlKey FROM pages WHERE status_code=200 AND ${HTML_CT} AND (content_encoding IS NULL OR content_encoding='')`)
             .map(r => ({ urlKey: r.urlKey, evidence: {} })),
     },
-    // ── Checklist-coverage additions (2026-07-20 — see plan/checklist-coverage.md) ──
     {
         id: 'robots-blocked-with-traffic', category: 'crawlability', severity: 'high', labels: ['D', 'G'], certainty: 1, effortBase: 1, fixType: 'per-page',
         title: 'Robots-blocked page still earning search traffic', fix: 'This URL is disallowed in robots.txt yet Google still shows it (usually as a bare "no information" result) and users still land on it. Either unblock it so it can be crawled and ranked properly, or — if it genuinely shouldn\'t be found — unblock it AND add noindex (a robots-blocked page can never see the noindex).',
@@ -1184,8 +1025,6 @@ export const CHECKS = [
     {
         id: 'favicon-missing', category: 'onpage', severity: 'low', labels: ['D'], certainty: 1, effortBase: 1, fixType: 'global',
         title: 'No favicon declared', fix: 'Add a favicon (<link rel="icon" …>) — Google shows it next to your result on mobile, and a missing one costs a little trust/recognition on every SERP appearance. One line in the template.',
-        // Gated on the column being populated (has_favicon is NULL on crawls from before this
-        // was captured) — never flag from a pre-feature crawl.
         run: (c) => {
             const hp = c.db.prepare(`SELECT url_key, has_favicon hf FROM pages WHERE status_code=200 AND has_favicon IS NOT NULL ORDER BY (click_depth=0) DESC, inlink_count DESC LIMIT 1`).get();
             return hp && hp.hf === 0 ? [{ urlKey: hp.url_key, evidence: { note: 'no <link rel="icon"> on the homepage' } }] : [];
@@ -1197,10 +1036,9 @@ export const CHECKS = [
         run: (c) => {
             const all = c.db.prepare(`SELECT url_key, lastmod FROM sitemap_urls WHERE lastmod IS NOT NULL AND lastmod <> ''`).all();
             if (all.length < 20)
-                return []; // too few dated URLs to judge the pattern
+                return [];
             const ev = { urlsWithLastmod: all.length };
             let tripped = false;
-            // Tell 1: a generator stamping every URL with "now" — >90% share one date, and that date is recent.
             const byDay = new Map();
             for (const r of all)
                 byDay.set(r.lastmod.slice(0, 10), (byDay.get(r.lastmod.slice(0, 10)) ?? 0) + 1);
@@ -1210,19 +1048,13 @@ export const CHECKS = [
                 tripped = true;
                 ev.sharedStamp = `${Math.round(topN / all.length * 100)}% of URLs claim ${topDay} — a generation timestamp, not a change date`;
             }
-            // Tell 2: dates in the future.
             const future = all.filter(r => Date.parse(r.lastmod) > Date.now() + 86400000).length;
             if (future > 0) {
                 tripped = true;
                 ev.futureDates = future;
             }
-            // Tell 3: lastmod claims a change between our two most recent crawls, yet none of the
-            // tracked page fields (status, title, meta, H1, word count, schema types) changed.
             const crawls = latestTwoCrawls(c.db);
             if (crawls.length === 2) {
-                // Compare DATE prefixes on both sides — lastmod is stored verbatim and often a full
-                // timestamp; compared raw against a 10-char date, same-day stamps sort "after" the
-                // boundary and are silently excluded (exactly the stamp-everything-today pattern).
                 const phantom = c.db.prepare(`SELECT s.url_key FROM sitemap_urls s
            JOIN page_snapshots n ON n.url_key = s.url_key AND n.crawl_id = ?
            JOIN page_snapshots o ON o.url_key = s.url_key AND o.crawl_id = ?
@@ -1242,8 +1074,6 @@ export const CHECKS = [
     {
         id: 'no-304-revalidation', category: 'performance', severity: 'low', labels: ['D'], certainty: 1, effortBase: 1, fixType: 'global',
         title: 'Server ignores conditional requests (no 304)', fix: 'Pages advertise Last-Modified/ETag but the server re-serves a full 200 when asked "has this changed?" (If-Modified-Since / If-None-Match). A properly configured server answers 304 Not Modified — it saves bandwidth on every revalidating crawler and cache, and signals stability to Googlebot. Usually a server/CDN setting.',
-        // Populated by the crawler's post-crawl probe (pages.conditional_304); NULL-gated so
-        // pre-feature crawls never flag. Fires only when NO probed page honoured the request.
         run: (c) => {
             const r = c.db.prepare(`SELECT COUNT(*) probed, COALESCE(SUM(conditional_304),0) ok FROM pages WHERE conditional_304 IS NOT NULL`).get();
             if (r.probed < 5 || r.ok > 0)
@@ -1255,45 +1085,12 @@ export const CHECKS = [
     {
         id: 'analytics-missing', category: 'onpage', severity: 'med', labels: ['D'], certainty: 1, effortBase: 1, fixType: 'global',
         title: 'No client-side analytics detected', fix: 'No analytics or tag-manager snippet was found on any crawled page (GA4, GTM, Plausible, Matomo, Fathom, Clarity…). If you measure server-side, ignore this; otherwise you\'re flying blind — install an analytics package before making SEO decisions.',
-        // Fires only when EVERY populated page lacks a snippet — one page with analytics = installed.
         run: (c) => {
             const r = c.db.prepare(`SELECT COUNT(*) total, COALESCE(SUM(has_analytics),0) withA FROM pages WHERE status_code=200 AND ${HTML_CT} AND has_analytics IS NOT NULL`).get();
             return r.total >= 3 && r.withA === 0 ? [{ urlKey: null, evidence: { pagesChecked: r.total, note: 'no known analytics snippet on any crawled page (server-side measurement is invisible to a crawl)' } }] : [];
         },
     },
-    // ── Google "AI features / succeeding in AI search" guide (developers.google.com/search/docs/
-    // fundamentals/ai-optimization-guide, read 2026-08-02) — principle → check mapping:
-    //   • Unique/compelling/non-commodity, people-first content .... thin-content, content-bloat,
-    //     ai-slop-signals (NEW below — mechanical/templated prose is the anti-signal of "unique take")
-    //   • Unique point of view / first-hand experience .............. article-no-author (NEW below —
-    //     unattributed articles are the deterministically checkable slice), stale-content
-    //   • Clear organisation (paragraphs/sections/headings) ......... poor-chunkability, content-bloat,
-    //     heading-hierarchy; answer coverage: body-missing-top-query, rag-answer-gap,
-    //     answer-not-front-loaded, weak-passage-answer, low-extractability
-    //   • Indexed + snippet-eligible / technical requirements ....... indexation family (noindex,
-    //     canonical, robots-blocked-with-traffic), soft-404-shell, sitemap reconciliation
-    //   • Crawlable public content .................................. crawlability family, broken links,
-    //     redirect chains; freshness-honesty (sitemap-lastmod-untrustworthy, no-304-revalidation)
-    //   • Semantic HTML / parseable ................................. heading-hierarchy, missing-h1,
-    //     multiple-h1, missing-lang
-    //   • Reduce duplicate content .................................. duplicate-title/meta, canonical
-    //     family, faceted-spider-trap, keyword-cannibalisation
-    //   • Images/video supporting text .............................. image-alt, images-missing-dimensions
-    //   • Page experience / latency ................................. performance proxies, high-yield-cwv-fail
-    //   • Structured data honesty (not required, but keep it valid) . schema-validate family,
-    //     article-date-illogical
-    //   • Don't chunk artificially / rewrite for AI ................. covered by NOT having such checks;
-    //     our chunk checks reward structure for humans, not tiny AI fragments
-    //   • "Don't create llms.txt" ................................... tension with agent-readiness probes,
-    //     which score llms.txt for *agent* (not Google AI-search) consumption — left as-is, different audience
-    //   • Merchant Center / Business Profile / GenAI report ......... out of scope (not crawl/GSC data)
-    {
-        // Anti-signal of the guide's "unique, non-commodity, people-first content": prose that reads
-        // machine-generated. Three heuristics over body_chunks — slop-lexicon density, sentence-length
-        // uniformity (low variance = mechanical), repeated chunk openers (page-internal boilerplate).
-        // Precision over recall: absolute floors on every signal, ≥2 signals required, AND the composite
-        // score must sit in the top decile of pages showing any signal. Judgement-gated — a human wrote
-        // "delve" long before LLMs did.
+    {
         id: 'ai-slop-signals', category: 'content', severity: 'low', labels: ['N'], certainty: 0.5, effortBase: 5, fixType: 'per-page',
         title: 'Prose shows machine-generated (slop) signals', fix: 'This page’s copy trips several statistical tells of generic AI-generated text: stock filler phrases, unusually uniform sentence lengths, and/or sections that all open the same way. Google’s AI-search guidance rewards unique, people-first content with a first-hand point of view — rewrite the flagged sections with specifics only you can supply (real experience, real numbers, real opinions) and cut the filler. (Heuristic — verify by reading the page; competent human writing can trip these tells.)',
         run: (c) => {
@@ -1322,7 +1119,6 @@ export const CHECKS = [
                 const bodyWords = body.split(/\s+/).filter(Boolean).length;
                 if (bodyWords < 250)
                     continue;
-                // (i) slop-lexicon density (hits per 1000 words, ≥3 distinct terms required)
                 const hits = new Map();
                 for (const p of PHRASES) {
                     let n = 0, i = -1;
@@ -1334,7 +1130,6 @@ export const CHECKS = [
                 const totalHits = [...hits.values()].reduce((a, b) => a + b, 0);
                 const density = totalHits / bodyWords * 1000;
                 const lexSignal = hits.size >= 3 && density >= 2.5;
-                // (ii) sentence-length uniformity — coefficient of variation over sentence word-counts
                 const sentences = body.split(/[.!?]+\s/).map(s => s.split(/\s+/).filter(Boolean).length).filter(n => n >= 5 && n <= 60);
                 let cv = null;
                 if (sentences.length >= 12) {
@@ -1342,11 +1137,9 @@ export const CHECKS = [
                     cv = Math.sqrt(sentences.reduce((a, b) => a + (b - mean) ** 2, 0) / sentences.length) / mean;
                 }
                 const uniformSignal = cv !== null && cv < 0.28;
-                // (iii) repeated openers across the page's own chunks (first 3 words, ≥3 chunks sharing one)
                 const openers = new Map();
                 if (texts.length >= 5)
                     for (const t of texts) {
-                        // Letters only — numeric/UI-chrome openers ("Show 10 20…") are widget text, not prose.
                         const o = t.toLowerCase().replace(/[^a-z\s]/g, ' ').split(/\s+/).filter(w => w.length >= 2).slice(0, 3).join(' ');
                         if (o.split(' ').length === 3)
                             openers.set(o, (openers.get(o) ?? 0) + 1);
@@ -1361,10 +1154,6 @@ export const CHECKS = [
             }
             if (!metrics.length)
                 return [];
-            // Outliers only: the LEXICON signal is mandatory (uniform sentences + repeated openers
-            // without a single slop phrase is template chrome, not slop — live-verified on simracing),
-            // plus ≥1 corroborating signal, AND composite score in the top decile of pages that showed
-            // any signal at all.
             const sorted = metrics.map(m => m.score).sort((a, b) => a - b);
             const p90 = sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.9))];
             return metrics
@@ -1381,11 +1170,6 @@ export const CHECKS = [
         },
     },
     {
-        // The guide's "unique point of view based on personal experience or expertise", cut down to its
-        // deterministically checkable slice: an Article/BlogPosting that carries schema yet names no
-        // author. Attribution is the machine-readable experience/expertise signal; a byline-less article
-        // is the commodity-content default. Only fires where Article schema EXISTS (no schema at all is
-        // schema-opportunity territory, not this check).
         id: 'article-no-author', category: 'schema', severity: 'low', labels: ['D'], certainty: 1, effortBase: 1, fixType: 'per-page',
         title: 'Article schema with no author attribution', fix: 'This page marks itself up as an Article/BlogPosting but declares no author. Google’s AI-search guidance rewards content with a demonstrable first-hand point of view — add `author` (a Person with a real name, ideally linking to an author page) to the Article schema and a visible byline to match.',
         run: (c) => {
@@ -1407,7 +1191,117 @@ export const CHECKS = [
             return out;
         },
     },
+    {
+        id: 'discover-max-image-preview', category: 'onpage', severity: 'med', labels: ['D'], certainty: 1, effortBase: 1, fixType: 'global', yieldCoef: 0.15,
+        title: 'Article missing max-image-preview:large (no large Discover card)',
+        fix: 'Add `<meta name="robots" content="max-image-preview:large">` (or the same directive in an X-Robots-Tag header). Without it Google cannot feature the article with the large, high-CTR image card in Google Discover and image search — you get a thumbnail or nothing. This is usually one site-wide template/config change (WordPress core already emits it; a plugin or theme has overridden it here).',
+        run: (c) => rows(c, `SELECT url_key urlKey, json_ld jsonLd, og_tags ogTags, robots, x_robots_tag xrt FROM pages WHERE ${DISCOVER_PREFILTER}`)
+            .filter(r => isDiscoverEligible(r.jsonLd, r.ogTags) && !hasMaxImagePreviewLarge(r.robots, r.xrt) && !hasPreviewRestriction(r.robots, r.xrt))
+            .map(r => ({ urlKey: r.urlKey, evidence: { robots: r.robots ?? null, xRobotsTag: r.xrt ?? null, note: 'article-type page without max-image-preview:large' } })),
+    },
+    {
+        id: 'discover-missing-og', category: 'onpage', severity: 'med', labels: ['D'], certainty: 1, effortBase: 1, fixType: 'per-page', yieldCoef: 0.12,
+        title: 'Article missing og:title or og:image (Discover cards use these)',
+        fix: 'Add both `og:title` and `og:image` — Google frequently builds the Discover headline and card image straight from Open Graph. Make og:image ≥1200px wide at 16:9, and write og:title for click-through, not just for social.',
+        run: (c) => rows(c, `SELECT url_key urlKey, json_ld jsonLd, og_tags ogTags FROM pages WHERE ${DISCOVER_PREFILTER}`)
+            .filter(r => isDiscoverEligible(r.jsonLd, r.ogTags))
+            .map(r => ({ urlKey: r.urlKey, missing: ['og:title', 'og:image'].filter(k => { const v = parseOg(r.ogTags)[k]; return !(v && String(v).trim()); }) }))
+            .filter(x => x.missing.length)
+            .map(x => ({ urlKey: x.urlKey, evidence: { missing: x.missing } })),
+    },
+    {
+        id: 'discover-slow-response', category: 'performance', severity: 'med', labels: ['D', 'N'], certainty: 0.5, effortBase: 5, fixType: 'global', yieldCoef: 0.1,
+        title: 'Article response looks slow for Discover (>600ms wall-time)',
+        fix: 'Aim for server response (TTFB) under 600ms — under 200ms is optimal — since Discover favours freshly-crawlable content. NOTE: the figure here is whole-fetch WALL TIME (it includes the HTML download and any retry/back-off), not a clean server TTFB, so confirm against a real TTFB or field measurement before prioritising. Caching, a CDN, or backend work are the usual levers.',
+        run: (c) => rows(c, `SELECT url_key urlKey, json_ld jsonLd, og_tags ogTags, response_time_ms ms FROM pages WHERE ${DISCOVER_PREFILTER} AND response_time_ms > 600 AND (redirects IS NULL OR redirects='') ORDER BY response_time_ms DESC`)
+            .filter(r => isDiscoverEligible(r.jsonLd, r.ogTags))
+            .map(r => ({ urlKey: r.urlKey, evidence: { wallTimeMs: r.ms, target: '<600ms (ideal <200ms)', note: 'whole-fetch wall time incl. HTML download / retries — a proxy, not a measured TTFB' } })),
+    },
+    {
+        id: 'discover-crawl-waste', category: 'crawlability', severity: 'med', labels: ['D'], certainty: 1, effortBase: 5, fixType: 'global', yieldCoef: 0.1,
+        title: 'High crawl waste (budget spent on redirects / non-indexable URLs)',
+        fix: 'Google allocates a finite crawl budget per host; spending it on redirects, error pages and non-indexable URLs slows discovery of your real content (and Discover leans on fast discovery). Aim for almost everything Google crawls to be an indexable 200 — repoint internal links off redirects/404s, prune faceted/parameter URLs, and keep the sitemap to canonical indexable pages.',
+        run: (c) => {
+            const clause = `status_code IS NOT NULL AND status_code NOT IN (429,503)`;
+            const tot = (rows(c, `SELECT COUNT(*) n FROM pages WHERE ${clause}`)[0]?.n) || 0;
+            if (tot < 50)
+                return [];
+            const byReason = rows(c, `SELECT COALESCE(indexable_reason,'(other)') reason, COUNT(*) n FROM pages WHERE ${clause} AND indexable=0 AND COALESCE(indexable_reason,'') != 'non-html' GROUP BY 1 ORDER BY 2 DESC`);
+            const nonIndexable = byReason.reduce((s, r) => s + r.n, 0);
+            const redirected = (rows(c, `SELECT COUNT(*) n FROM pages WHERE ${clause} AND redirects IS NOT NULL AND redirects != ''`)[0]?.n) || 0;
+            const waste = nonIndexable + redirected;
+            const ratio = waste / tot;
+            if (ratio < 0.3)
+                return [];
+            return [{ urlKey: null, evidence: { crawledUrls: tot, wasted: waste, wasteRatio: Math.round(ratio * 1000) / 10 + '%', redirected, nonIndexableByReason: Object.fromEntries(byReason.map(r => [r.reason, r.n])), note: 'crawled URLs that redirect or cannot be indexed (429/503 throttling and non-HTML assets excluded)' } }];
+        },
+    },
+    {
+        id: 'discover-generic-article-type', category: 'schema', severity: 'low', labels: ['D', 'N'], certainty: 0.5, effortBase: 1, fixType: 'global',
+        title: 'Generic Article type where a more specific one fits',
+        fix: 'The page’s Article markup uses only the generic `Article` type. Google recommends the most specific applicable type — `NewsArticle` for news, `LiveBlogPosting` for live coverage, `ProfilePage` for a person/creator profile — which unlocks richer Discover/News treatment. Usually one template/plugin setting. Only change it if the more specific type genuinely fits (judgement).',
+        run: (c) => rows(c, `SELECT url_key urlKey, json_ld jsonLd FROM pages WHERE status_code=200 AND indexable=1 AND ${HTML_CT} AND json_ld LIKE '%Article%'`)
+            .map(r => { const present = new Set(); for (const n of discoverArticleNodes(r.jsonLd))
+            for (const t of nodeTypeList(n))
+                if (DISCOVER_TYPES.includes(t))
+                    present.add(t); return { urlKey: r.urlKey, present }; })
+            .filter(x => x.present.has('article') && x.present.size === 1)
+            .map(x => ({ urlKey: x.urlKey, evidence: { articleTypesDeclared: ['Article'], note: 'the Article schema declares only the generic Article type — no more specific subtype' } })),
+    },
+    {
+        id: 'discover-image-schema', category: 'schema', severity: 'med', labels: ['D'], certainty: 1, effortBase: 3, fixType: 'per-page', yieldCoef: 0.12,
+        title: 'Article schema declares no image (Discover needs a large image)',
+        fix: 'Add an `image` to the Article structured data — Discover cards need a big image and cannot build one from the page alone. Google wants a high-res image (≥1200px wide), ideally in three crops: 16:9 (1200×675), 4:3 (1200×900) and 1:1 (1200×1200). The main visible image at the top of the article should match the 16:9 schema image.',
+        run: (c) => rows(c, `SELECT url_key urlKey, json_ld jsonLd, og_tags ogTags FROM pages WHERE ${DISCOVER_PREFILTER}`)
+            .map(r => ({ urlKey: r.urlKey, nodes: discoverArticleNodes(r.jsonLd) }))
+            .filter(x => x.nodes.length > 0 && !x.nodes.some(hasSchemaImage))
+            .map(x => ({ urlKey: x.urlKey, evidence: { note: 'no `image` on the Article schema — Discover cannot build a large image card from schema alone' } })),
+    },
 ];
+const DISCOVER_TYPES = ['article', 'newsarticle', 'blogposting', 'liveblogposting', 'profilepage', 'reportagenewsarticle', 'opinionnewsarticle', 'reviewnewsarticle', 'techarticle', 'scholarlyarticle'];
+const DISCOVER_PREFILTER = `status_code=200 AND indexable=1 AND ${HTML_CT} AND (json_ld LIKE '%Article%' OR json_ld LIKE '%BlogPosting%' OR json_ld LIKE '%ProfilePage%' OR og_tags LIKE '%article%')`;
+function nodeTypeList(n) {
+    const t = n?.['@type'];
+    if (typeof t === 'string')
+        return [t.toLowerCase()];
+    if (Array.isArray(t))
+        return t.filter((x) => typeof x === 'string').map(x => x.toLowerCase());
+    return [];
+}
+function discoverArticleNodes(jsonLd) {
+    return parseJsonLdNodes(jsonLd).filter(n => nodeTypeList(n).some(t => DISCOVER_TYPES.includes(t)));
+}
+function parseOg(ogTags) {
+    if (!ogTags)
+        return {};
+    try {
+        const o = JSON.parse(ogTags);
+        return o && typeof o === 'object' && !Array.isArray(o) ? o : {};
+    }
+    catch {
+        return {};
+    }
+}
+function isDiscoverEligible(jsonLd, ogTags) {
+    if (discoverArticleNodes(jsonLd).length)
+        return true;
+    if (parseJsonLdNodes(jsonLd).some(n => nodeTypeList(n).length))
+        return false;
+    return (parseOg(ogTags)['og:type'] ?? '').toLowerCase() === 'article';
+}
+function hasMaxImagePreviewLarge(robots, xrt) {
+    return `${robots ?? ''} ${xrt ?? ''}`.toLowerCase().replace(/\s+/g, '').includes('max-image-preview:large');
+}
+function hasPreviewRestriction(robots, xrt) {
+    const s = `${robots ?? ''} ${xrt ?? ''}`.toLowerCase().replace(/\s+/g, '');
+    return s.includes('max-image-preview:none') || s.includes('max-image-preview:standard') || s.includes('nosnippet');
+}
+function hasSchemaImage(node) {
+    const img = node?.image;
+    const one = (v) => typeof v === 'string' ? v.trim().length > 0
+        : !!v && typeof v === 'object' && !Array.isArray(v) && !!(v.url || v.contentUrl || v['@id']);
+    return Array.isArray(img) ? img.some(one) : one(img);
+}
 const sitemapHasRows = (c) => (c.db.prepare('SELECT COUNT(*) n FROM sitemap_urls').get().n) > 0;
 let _hreflangCache = null;
 function hreflangFindings(ctx) {
@@ -1419,7 +1313,6 @@ function hreflangFindings(ctx) {
     const status = new Map();
     for (const p of ctx.db.prepare(`SELECT url_key, status_code, noindex FROM pages`).all())
         status.set(p.url_key, { status: p.status_code, noindex: p.noindex });
-    // declared[sourceKey] = set of internal alternate targetKeys (excluding self)
     const declared = new Map();
     const parsed = [];
     for (const p of pageRows) {
@@ -1442,13 +1335,10 @@ function hreflangFindings(ctx) {
                 continue;
             }
             if (key === p.url_key)
-                continue; // self-reference
+                continue;
             targets.push({ key, lang: (lang || '').toLowerCase() });
         }
         parsed.push({ srcKey: p.url_key, targets });
-        // A return link via x-default is a VALID return tag (common when x-default is the
-        // homepage) — include all targets here; x-default is only excluded as a reciprocation
-        // *requirement* in the loop below, never as a way of satisfying one.
         declared.set(p.url_key, new Set(targets.map(t => t.key)));
     }
     const broken = [];
@@ -1460,8 +1350,6 @@ function hreflangFindings(ctx) {
             const st = status.get(t.key);
             if (st && (st.status !== 200 || st.noindex === 1))
                 brokenTargets.push(t.key);
-            // reciprocation only for internal, live (200) targets we crawled, excluding x-default
-            // (a broken target is already reported by broken-hreflang-target — don't double-flag)
             if (t.lang !== 'x-default' && st && st.status === 200 && st.noindex !== 1 && !(declared.get(t.key)?.has(srcKey)))
                 missingReturn.push(t.key);
         }