@houtini/seo-audit-console 0.3.0 → 0.4.3

package/dist/core/reconFetch.js

@@ -0,0 +1,49 @@
+import { extractPage } from './extract.js';
+export async function fetchOwnPage(url, hostForm = 'asis', timeoutMs = 20000) {
+    const host = new URL(url).hostname.replace(/^www\./, '');
+    const res = await fetch(url, {
+        headers: { 'user-agent': 'seo-audit-console recon (+https://github.com/houtini-ai/seo-audit)' },
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    const html = await res.text();
+    const ex = extractPage(html, url, host, { hostForm }, res.headers.get('x-robots-tag'));
+    const chunks = ex.bodyChunks ?? [];
+    const fulltextLower = chunks.map(c => `${c.heading} ${c.text}`).join(' ').toLowerCase();
+    // jsonLd is a JSON *string* (array of raw blocks) — parse ONCE, then each block (itself a
+    // JSON string or object) may carry an @graph. (Build lesson: don't iterate the raw string.)
+    const types = new Set();
+    let dateModified = null, datePublished = null;
+    try {
+        const blocks = ex.jsonLd ? JSON.parse(ex.jsonLd) : [];
+        for (const block of blocks) {
+            const obj = typeof block === 'string' ? JSON.parse(block) : block;
+            for (const node of (obj['@graph'] ?? [obj])) {
+                const t = node['@type'];
+                (Array.isArray(t) ? t : [t]).forEach((x) => x && types.add(x));
+                if (node.dateModified && !dateModified)
+                    dateModified = String(node.dateModified).slice(0, 10);
+                if (node.datePublished && !datePublished)
+                    datePublished = String(node.datePublished).slice(0, 10);
+            }
+        }
+    }
+    catch { /* malformed JSON-LD — leave types empty rather than throw */ }
+    return {
+        url,
+        status: res.status,
+        title: ex.title,
+        h1: ex.h1,
+        wordCount: ex.wordCount ?? fulltextLower.split(/\s+/).length,
+        headings: chunks.filter(c => c.heading).map(c => ({ level: c.level, heading: c.heading, chars: c.text.length })),
+        fulltextLower,
+        jsonLdTypes: [...types],
+        hasProductOrReview: types.has('Product') || types.has('Review') || types.has('AggregateRating'),
+        dateModified,
+        datePublished,
+    };
+}
+/** Which of these terms does the page text actually contain? Powers the coverage-gap probe. */
+export function coverageProbe(fulltextLower, terms) {
+    return terms.map(t => ({ term: t, present: fulltextLower.includes(t.toLowerCase()) }));
+}
+//# sourceMappingURL=reconFetch.js.map

package/dist/core/reconFetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconFetch.js","sourceRoot":"","sources":["../../src/core/reconFetch.ts"],"names":[],"mappings":"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"}

package/dist/core/reconResearch.d.ts

@@ -0,0 +1,42 @@
+import type { FirecrawlClient } from './FirecrawlClient.js';
+import type { SupadataClient } from './SupadataClient.js';
+/** User-agent modes for the free HTTP fetch. 'browser' mimics a real visit arriving from Google
+ * (referer + cross-site fetch metadata) — this is what gets past Reddit and the mid-tier.
+ * 'googlebot' spoofs Googlebot's UA (UA-gated sites only; strict-verified Cloudflare rejects it).
+ * Cloudflare *managed-challenge* sites (e.g. PCMag) reject every HTTP-only client regardless. */
+export type UaMode = 'browser' | 'googlebot';
+/**
+ * Route a competitor URL to the right fetcher by who owns the source:
+ *   YouTube/TikTok/X → Supadata (transcript)   — Firecrawl can't read video
+ *   Reddit           → its own .json endpoint   — Firecrawl hard-blocks Reddit
+ *   everything else  → Firecrawl (markdown, proxy:auto for bot-protected sites)
+ * Each returns a uniform shape so the recon packet is easy for the research session to diff.
+ */
+export interface CompetitorContent {
+    url: string;
+    kind: 'video' | 'reddit' | 'page';
+    title: string | null;
+    content: string;
+    cached: boolean;
+    error?: string;
+}
+/** Reddit serves clean JSON at url.json — title + selftext + top comments, no scraper needed.
+ * Needs the browser header profile (UA + Google referer) — a bot UA gets a 403. */
+export declare function fetchRedditJson(url: string, maxChars?: number, ua?: UaMode): Promise<{
+    title: string | null;
+    content: string;
+}>;
+/** Free HTTP fallback for pages Firecrawl refuses (its blocklist covers major publishers).
+ * Fetches with a browser-like UA and reuses our own extractor for clean main-content text. */
+export declare function fetchPlainPage(url: string, maxChars?: number, ua?: UaMode): Promise<{
+    title: string | null;
+    content: string;
+}>;
+export declare function fetchCompetitorContent(url: string, clients: {
+    firecrawl: FirecrawlClient | null;
+    supadata: SupadataClient | null;
+}, opts?: {
+    maxChars?: number;
+    ua?: UaMode;
+}): Promise<CompetitorContent>;
+//# sourceMappingURL=reconResearch.d.ts.map

package/dist/core/reconResearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconResearch.d.ts","sourceRoot":"","sources":["../../src/core/reconResearch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D;;;iGAGiG;AACjG,MAAM,MAAM,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC;AAmB7C;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD;mFACmF;AACnF,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAO,EAAE,EAAE,GAAE,MAAkB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAkB9I;AAED;8FAC8F;AAC9F,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAO,EAAE,EAAE,GAAE,MAAkB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAQ7I;AAED,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAA;CAAE,EAC/E,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,OAAO,CAAC,iBAAiB,CAAC,CA2B5B"}

package/dist/core/reconResearch.js

@@ -0,0 +1,101 @@
+import { Agent, fetch as ufetch } from 'undici';
+import { hostOf } from './serpRecon.js';
+import { extractPage } from './extract.js';
+const httpAgent = new Agent({ allowH2: true, connections: 6, keepAliveTimeout: 30_000 });
+const CHROME_UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
+const GOOGLEBOT_UA = 'Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Googlebot/2.1; +http://www.google.com/bot.html) Chrome/131.0.0.0 Safari/537.36';
+function browserHeaders(mode) {
+    if (mode === 'googlebot') {
+        return { 'user-agent': GOOGLEBOT_UA, 'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8', 'accept-encoding': 'gzip, deflate, br', 'from': 'googlebot(at)googlebot.com' };
+    }
+    return {
+        'user-agent': CHROME_UA,
+        'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8',
+        'accept-language': 'en-GB,en-US;q=0.9,en;q=0.8',
+        'accept-encoding': 'gzip, deflate, br',
+        'referer': 'https://www.google.com/',
+        'sec-ch-ua': '"Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"',
+        'sec-ch-ua-mobile': '?0', 'sec-ch-ua-platform': '"Windows"',
+        'sec-fetch-dest': 'document', 'sec-fetch-mode': 'navigate', 'sec-fetch-site': 'cross-site', 'sec-fetch-user': '?1',
+        'upgrade-insecure-requests': '1',
+    };
+}
+const isVideo = (host) => /youtube|youtu\.be|tiktok|twitter\.com|x\.com/.test(host);
+const isReddit = (host) => /reddit\.com/.test(host);
+/** Reddit serves clean JSON at url.json — title + selftext + top comments, no scraper needed.
+ * Needs the browser header profile (UA + Google referer) — a bot UA gets a 403. */
+export async function fetchRedditJson(url, maxChars = 4000, ua = 'browser') {
+    const jsonUrl = url.split('?')[0].replace(/\/$/, '') + '.json';
+    const res = await ufetch(jsonUrl, { headers: browserHeaders(ua), dispatcher: httpAgent, signal: AbortSignal.timeout(20000) });
+    if (!res.ok)
+        throw new Error(`Reddit .json ${res.status}`);
+    const data = await res.json();
+    const post = data?.[0]?.data?.children?.[0]?.data ?? {};
+    const comments = data?.[1]?.data?.children ?? [];
+    const parts = [];
+    if (post.title)
+        parts.push(`# ${post.title}`);
+    if (post.selftext)
+        parts.push(post.selftext);
+    const top = comments
+        .map(c => c?.data)
+        .filter(d => d && d.body && d.body !== '[deleted]')
+        .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+        .slice(0, 12)
+        .map(d => `- (${d.score ?? 0}) ${d.body}`);
+    if (top.length)
+        parts.push('## Top comments', ...top);
+    return { title: post.title ?? null, content: parts.join('\n\n').slice(0, maxChars) };
+}
+/** Free HTTP fallback for pages Firecrawl refuses (its blocklist covers major publishers).
+ * Fetches with a browser-like UA and reuses our own extractor for clean main-content text. */
+export async function fetchPlainPage(url, maxChars = 4000, ua = 'browser') {
+    const res = await ufetch(url, { headers: browserHeaders(ua), dispatcher: httpAgent, signal: AbortSignal.timeout(20000) });
+    if (!res.ok)
+        throw new Error(`plain fetch ${res.status}`);
+    const html = await res.text();
+    const host = new URL(url).hostname.replace(/^www\./, '');
+    const ex = extractPage(html, url, host, { hostForm: 'asis' }, null);
+    const text = (ex.bodyChunks ?? []).map(c => `${c.heading} ${c.text}`).join('\n').trim();
+    return { title: ex.title, content: text.slice(0, maxChars) };
+}
+export async function fetchCompetitorContent(url, clients, opts = {}) {
+    const host = hostOf(url);
+    const max = opts.maxChars ?? 4000;
+    const ua = opts.ua ?? 'browser';
+    try {
+        if (isVideo(host)) {
+            if (!clients.supadata)
+                return { url, kind: 'video', title: null, content: '', cached: false, error: 'SUPADATA_API_KEY not set — cannot transcribe video' };
+            const t = await clients.supadata.transcript(url, { maxChars: Math.max(max, 5000) });
+            return { url, kind: 'video', title: null, content: t.content, cached: t.cached };
+        }
+        if (isReddit(host)) {
+            // .json first (cleaner structured data); HTML fallback. Both need the browser profile.
+            try {
+                const r = await fetchRedditJson(url, max, ua);
+                return { url, kind: 'reddit', title: r.title, content: r.content, cached: false };
+            }
+            catch {
+                const r = await fetchPlainPage(url, max, ua);
+                return { url, kind: 'reddit', title: r.title, content: r.content, cached: false };
+            }
+        }
+        // Pages: Firecrawl first (cleaner, handles JS); fall back to the free browser-profile fetch
+        // for sites Firecrawl refuses ("we do not support this site") or when no key is set.
+        if (clients.firecrawl) {
+            try {
+                const s = await clients.firecrawl.scrape(url, { maxChars: max, proxy: 'auto' });
+                return { url, kind: 'page', title: s.title, content: s.markdown, cached: s.cached };
+            }
+            catch { /* fall through to the browser-profile fetch */ }
+        }
+        const p = await fetchPlainPage(url, max, ua);
+        return { url, kind: 'page', title: p.title, content: p.content, cached: false };
+    }
+    catch (e) {
+        const kind = isVideo(host) ? 'video' : isReddit(host) ? 'reddit' : 'page';
+        return { url, kind, title: null, content: '', cached: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+//# sourceMappingURL=reconResearch.js.map

package/dist/core/reconResearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconResearch.js","sourceRoot":"","sources":["../../src/core/reconResearch.ts"],"names":[],"mappings":"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"}

package/dist/core/serpRecon.d.ts

@@ -0,0 +1,46 @@
+import type { DfsResponse } from './DataForSeoClient.js';
+/**
+ * Parse a DataForSEO SERP-advanced response into the fields content recon needs:
+ * where WE actually rank in organic, whether the AI Overview cites us and who it does
+ * cite, and how much of the SERP is video/product (format signals). This is the single
+ * fetch that powers the organic-rank x AIO-citation verdict matrix.
+ */
+export interface SerpReconResult {
+    itemTypes: string[];
+    ourOrganicRank: number | null;
+    aioPresent: boolean;
+    aioCitesUs: boolean;
+    aioAsync: boolean;
+    aioReferences: {
+        rank: number | null;
+        domain: string;
+        url: string;
+        title: string;
+    }[];
+    videoPresent: boolean;
+    organicAbove: {
+        rank: number;
+        domain: string;
+        url: string;
+        title: string;
+    }[];
+    videoItems: {
+        url: string;
+        title: string;
+        source: string;
+    }[];
+}
+/** Registrable-ish host: lowercase, strip scheme/path/www. Good enough to match a domain field. */
+export declare function hostOf(s: string | undefined | null): string;
+export declare function parseSerpForRecon(resp: DfsResponse, ownDomain: string): SerpReconResult;
+/**
+ * The deterministic verdict from organic rank x AIO citation (Richard's rule):
+ * strong organic but NOT in the AIO = a data-accuracy/freshness problem — Google ranks
+ * us but won't quote us.
+ */
+export type ReconVerdict = 'defend-and-deepen' | 'accuracy-or-freshness' | 'consolidate-weak-page' | 'competitive-gap';
+export declare function reconVerdict(r: SerpReconResult): {
+    verdict: ReconVerdict;
+    note: string;
+};
+//# sourceMappingURL=serpRecon.d.ts.map

package/dist/core/serpRecon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serpRecon.d.ts","sourceRoot":"","sources":["../../src/core/serpRecon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrF,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7E,UAAU,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC9D;AAED,mGAAmG;AACnG,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAG3D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CA2CvF;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,mBAAmB,GAAG,uBAAuB,GAAG,uBAAuB,GAAG,iBAAiB,CAAC;AAEvH,wBAAgB,YAAY,CAAC,CAAC,EAAE,eAAe,GAAG;IAAE,OAAO,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAkBxF"}

package/dist/core/serpRecon.js

@@ -0,0 +1,71 @@
+/** Registrable-ish host: lowercase, strip scheme/path/www. Good enough to match a domain field. */
+export function hostOf(s) {
+    if (!s)
+        return '';
+    return String(s).replace(/^https?:\/\//i, '').replace(/\/.*$/, '').replace(/^www\./i, '').toLowerCase().trim();
+}
+export function parseSerpForRecon(resp, ownDomain) {
+    const own = hostOf(ownDomain);
+    const result = resp.tasks?.[0]?.result?.[0] ?? {};
+    const items = result.items ?? [];
+    const itemTypes = result.item_types ?? [...new Set(items.map(i => i.type))];
+    let ourOrganicRank = null;
+    const organic = [];
+    let aioPresent = false, aioCitesUs = false, aioAsync = false, videoPresent = false;
+    const aioReferences = [];
+    const videoItems = [];
+    for (const it of items) {
+        const t = it.type;
+        if (t === 'organic') {
+            const domain = hostOf(it.domain || it.url);
+            const rank = Number(it.rank_group) || organic.length + 1;
+            organic.push({ rank, domain, url: it.url ?? '', title: it.title ?? '' });
+            if (own && domain === own && ourOrganicRank == null)
+                ourOrganicRank = rank;
+        }
+        else if (t === 'ai_overview') {
+            aioPresent = true;
+            aioAsync = !!it.asynchronous_ai_overview;
+            const refs = it.references ?? [];
+            let i = 0;
+            for (const ref of refs) {
+                const domain = hostOf(ref.domain || ref.url);
+                aioReferences.push({ rank: Number(ref.rank_absolute) || ++i, domain, url: ref.url ?? '', title: ref.title ?? '' });
+                if (own && domain === own)
+                    aioCitesUs = true;
+            }
+        }
+        else if (t === 'video' || t === 'short_videos') {
+            videoPresent = true;
+            for (const v of it.items ?? []) {
+                if (v?.url)
+                    videoItems.push({ url: v.url, title: v.title ?? '', source: hostOf(v.url) });
+            }
+        }
+    }
+    // Organic ranked above us (the ones actually beating us); if we're absent, the whole top block.
+    const organicAbove = ourOrganicRank == null
+        ? organic.slice(0, 8)
+        : organic.filter(o => o.rank < ourOrganicRank);
+    return { itemTypes, ourOrganicRank, aioPresent, aioCitesUs, aioAsync, aioReferences, videoPresent, organicAbove, videoItems };
+}
+export function reconVerdict(r) {
+    const strongOrganic = r.ourOrganicRank != null && r.ourOrganicRank <= 5;
+    const shape = r.videoPresent ? ' The SERP carries a video pack, so some click loss is format, not content.' : '';
+    if (!r.aioPresent) {
+        return strongOrganic
+            ? { verdict: 'defend-and-deepen', note: `No AI Overview on this SERP; you rank organic #${r.ourOrganicRank}. Defend and deepen.${shape}` }
+            : { verdict: 'competitive-gap', note: `No AI Overview; you rank organic ${r.ourOrganicRank ?? 'outside top results'}. Close the competitive gap.${shape}` };
+    }
+    if (strongOrganic && r.aioCitesUs) {
+        return { verdict: 'defend-and-deepen', note: `You rank organic #${r.ourOrganicRank} and the AI Overview already cites you. Deepen to become the primary source.${shape}` };
+    }
+    if (strongOrganic && !r.aioCitesUs) {
+        return { verdict: 'accuracy-or-freshness', note: `You rank organic #${r.ourOrganicRank} but the AI Overview does NOT cite you — a data-accuracy or freshness signal. Make the facts current, correct and marked up so they are liftable.${shape}` };
+    }
+    if (!strongOrganic && r.aioCitesUs) {
+        return { verdict: 'consolidate-weak-page', note: `The AI Overview cites you but your organic rank is weak (${r.ourOrganicRank ?? 'absent'}) — you have a quotable nugget on an under-powered page; consolidate and strengthen it.${shape}` };
+    }
+    return { verdict: 'competitive-gap', note: `Not cited in the AI Overview and organic rank is ${r.ourOrganicRank ?? 'absent'} — full coverage gap; run the deep competitor diff.${shape}` };
+}
+//# sourceMappingURL=serpRecon.js.map

package/dist/core/serpRecon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serpRecon.js","sourceRoot":"","sources":["../../src/core/serpRecon.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAqEpE,wBAAgB,OAAO,IAAI,MAAM,CAGhC;AA6KD,wBAAgB,YAAY,IAAI;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAmnD9E"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA2EpE,wBAAgB,OAAO,IAAI,MAAM,CAGhC;AA8KD,wBAAgB,YAAY,IAAI;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAw0D9E"}

package/dist/server.js

@@ -11,6 +11,12 @@ import { getDashboardData } from './core/dashboardData.js';
 import { startDashboardServer, stopDashboardServer, dashboardServerUrl, listLocalProperties } from './core/webServer.js';
 import { computeSerpFootprint, persistSerpFootprint } from './core/serpFootprint.js';
 import { computeMarketSizing, persistMarketSizing } from './core/marketSizing.js';
+import { FirecrawlClient } from './core/FirecrawlClient.js';
+import { SupadataClient } from './core/SupadataClient.js';
+import { fetchCompetitorContent } from './core/reconResearch.js';
+import { fetchOwnPage } from './core/reconFetch.js';
+import { parseSerpForRecon, reconVerdict } from './core/serpRecon.js';
+import { selectReconTargets, deterministicTodos, persistReconPage, insertTodos } from './audit/recon.js';
 /** A clickable browser-dashboard link appended to tool outputs — the user should always
  * know the full interactive report is one click away (or one serve_dashboard call away). */
 function browserLink(siteUrl) {
@@ -165,6 +171,7 @@ Raw access: query_audit runs any single check with full evidence; every table ab
 - **Market read:** serp_features (feature/AIO exposure, volume-weighted) + domain_visibility for the client and each named rival (one cached call each) → who is structurally winning, and how much of the market SERP features already absorb.
 - **Content plan:** suggest_pages (demand you already earn impressions for) + topic_gaps (demand rivals own that you don't) → draft_content for the winners. Every proposal traces to real impressions or a rival's real footprint - no invented "keyword ideas".
 - **Fix-and-prove cycle:** fix_finding on the top finding → ship → start_crawl → detect_changes shows the fix landed → re-run run_audit and watch the finding drop off. That screenshot is the client update.
+- **Content recon (why a page is losing):** recon_targets picks the worst declining/striking pages, fetches our live page + the Google SERP (organic rank + AI-Overview citations + video), and classifies WHY — the sharpest class is "we rank but the AI Overview won't quote us" = a data-accuracy/freshness/markup problem. Then research the competitor set it returns (firecrawl for pages, supadata for the ranking videos), write the gaps back with save_recon_todo, and track the fixes with recon_todos (which can re-measure whether you moved from uncited→cited). Pass location to match where your impressions come from — organic rank is location-sensitive.
 - **Cost rule of thumb:** an entire competitive read (visibility + footprint + gaps for 4 domains) is a handful of cached Labs calls - under a dollar. If a plan involves looping SERP calls over a keyword list, it is the wrong plan; a Labs endpoint already has that answer top-down.
 
 Plan the join first (url_key / query / domain), state the grain of each side, then run the fewest paid calls that answer it.`;
@@ -246,6 +253,12 @@ export function createServer() {
         : null;
     const rankTracker = dfs ? new RankTracker(dfs, dataDir()) : null;
     const backlinks = dfs ? new Backlinks(dfs, dataDir()) : null;
+    // Firecrawl (competitor-page scraping for content recon) — optional; degrades gracefully.
+    const firecrawlKey = process.env.FIRECRAWL_API_KEY;
+    const firecrawl = firecrawlKey ? new FirecrawlClient(firecrawlKey, path.join(dataDir(), 'firecrawl-cache.db')) : null;
+    // Supadata (transcribes the ranking videos for content recon) — optional; degrades gracefully.
+    const supadataKey = process.env.SUPADATA_API_KEY;
+    const supadata = supadataKey ? new SupadataClient(supadataKey, path.join(dataDir(), 'supadata-cache.db')) : null;
     const entities = new Entities(new WikidataClient(path.join(dataDir(), 'wikidata-cache.db')), dataDir());
     const refresh = new Refresh(sync, crawler, inspector, rankTracker);
     const requireGsc = (v) => {
@@ -874,6 +887,223 @@ export function createServer() {
             },
         };
     });
+    // ── Content recon (recon_targets) — the data-intensive "why are we losing, what to do" mission ──
+    server.registerTool('recon_targets', {
+        title: 'Content recon: why a page is losing, and what to do about it',
+        description: '[Paid: DataForSEO SERP per page (~$0.004 each), bounded to the batch | Use for: the deep "why are we behind and what to add" recon] For each of your worst declining / striking-distance pages (auto-selected by impressions x decline, position 3-15; or pass explicit urls), this fetches OUR live page with the crawler, pulls the live Google SERP (DataForSEO SERP-advanced), and classifies WHY we are behind using the organic-rank x AI-Overview-citation matrix: defend-and-deepen (cited + strong), accuracy-or-freshness (rank but the AIO will not quote us - the sharpest, most actionable class), consolidate-weak-page, or competitive-gap. It writes a per-page classification plus deterministic to-dos (schema gaps, freshness, cannibalisation, video format) into a trackable ledger, and returns the competitor set (organic-above + AI-Overview references + ranking videos) for the research session to diff. Set scrapeCompetitors:true to also pull the top competitors as content, routed by source: YouTube/video → Supadata transcript (SUPADATA_API_KEY), Reddit → its .json, other pages → Firecrawl (FIRECRAWL_API_KEY) with a free HTTP fallback. Cloudflare-challenge sites (e.g. PCMag) still can\'t be fetched from a server and come back as a per-URL error — the SERP still tells you they rank; if one matters, ask the user to paste its copy or supply a text file and diff that in. Transcribe the videos (usually what wins these SERPs) and use the reachable pages. Then write findings back with save_recon_todo; track with recon_todos.',
+        inputSchema: {
+            siteUrl: z.string(),
+            limit: z.number().int().min(1).max(15).optional().describe('Pages per batch (default 5)'),
+            minImpressions: z.number().int().min(1).optional(),
+            location: z.union([z.string(), z.number()]).optional(),
+            urls: z.array(z.string()).optional().describe('Analyse these exact pages instead of auto-selecting'),
+            scrapeCompetitors: z.boolean().optional().describe('Also fetch the top competitors (video→transcript, pages→markdown/HTML)'),
+            crawlAs: z.enum(['browser', 'googlebot']).optional().describe('UA for the free HTTP fetch: browser (default, mimics a visit from Google — gets Reddit + mid-tier) or googlebot'),
+        },
+    }, async ({ siteUrl, limit, minImpressions, location, urls, scrapeCompetitors, crawlAs }) => {
+        const client = requireDfs(dfs);
+        const db = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
+        try {
+            const fresh = gscFreshness(db.db);
+            if (!fresh.effectiveMax)
+                return { content: [{ type: 'text', text: `No synced GSC data for ${siteUrl} — run refresh_property first.` }], structuredContent: { error: 'empty', siteUrl } };
+            const today = new Date().toISOString().slice(0, 10);
+            const ownDomain = dfsHost(siteUrl);
+            const hostForm = hostFormForProperty(siteUrl) ?? 'asis';
+            let targets;
+            if (urls?.length) {
+                targets = [];
+                for (const u of urls) {
+                    const key = urlKey(u, { hostForm });
+                    const row = db.db.prepare(`SELECT query, SUM(impressions) imp, SUM(clicks) clk, SUM(position*impressions)*1.0/NULLIF(SUM(impressions),0) pos
+              FROM search_analytics WHERE page_key=? AND query IS NOT NULL AND date > date(?, '-28 days') AND date <= ? GROUP BY query ORDER BY imp DESC LIMIT 1`)
+                        .get(key, fresh.effectiveMax, fresh.effectiveMax);
+                    if (row?.query)
+                        targets.push({ urlKey: key, query: row.query, impressions: row.imp, clicks: row.clk, position: Math.round(row.pos * 10) / 10, priorPosition: null, slipped: false, competingUrls: 0 });
+                }
+            }
+            else {
+                targets = selectReconTargets(db.db, { ...(limit != null ? { limit } : {}), ...(minImpressions != null ? { minImpressions } : {}), maxDate: fresh.effectiveMax });
+            }
+            if (!targets.length)
+                return { content: [{ type: 'text', text: `No recon targets found (declining/striking-distance pages, position 3-15, ${minImpressions ?? 300}+ impressions). Try a lower minImpressions or pass explicit urls.` }], structuredContent: { siteUrl, targets: [] } };
+            const results = [];
+            let cost = 0;
+            for (const t of targets) {
+                let own = null;
+                try {
+                    own = await fetchOwnPage(t.urlKey, hostForm === 'asis' ? 'asis' : hostForm);
+                }
+                catch { /* page unreachable — classify on SERP alone */ }
+                const serpResp = await client.serpOrganic(t.query, location, 'en', 20);
+                cost += serpResp.cost;
+                const serp = parseSerpForRecon(serpResp, ownDomain);
+                const verdict = reconVerdict(serp);
+                const baseline = { organicRank: serp.ourOrganicRank, aioCitesUs: serp.aioCitesUs, gscPosition: t.position, gscImpressions: t.impressions, at: today };
+                persistReconPage(db.db, {
+                    urlKey: t.urlKey, query: t.query, verdict: verdict.verdict, verdictNote: verdict.note,
+                    organicRank: serp.ourOrganicRank, gscPosition: t.position, gscImpressions: t.impressions,
+                    aioPresent: serp.aioPresent, aioCitesUs: serp.aioCitesUs, videoPresent: serp.videoPresent,
+                    hasProductSchema: own?.hasProductOrReview ?? false, schemaTypes: own?.jsonLdTypes ?? [],
+                    competitors: { organicAbove: serp.organicAbove, aioReferences: serp.aioReferences, videoItems: serp.videoItems },
+                });
+                const todos = own ? deterministicTodos(t, own, serp, verdict, today) : [];
+                const inserted = todos.length ? insertTodos(db.db, t.urlKey, t.query, todos, baseline, 'auto') : 0;
+                let competitorContent = undefined;
+                if (scrapeCompetitors && (firecrawl || supadata)) {
+                    // Build a routed candidate set: organic-above + a couple of AI-Overview references +
+                    // one ranking video, deduped, our own domain removed. Each URL routes by domain
+                    // (YouTube→supadata, Reddit→.json, else→firecrawl). Bounded to keep the payload sane.
+                    const seen = new Set();
+                    const candidates = [];
+                    const add = (u) => { if (u && !seen.has(u) && dfsHost(u) !== ownDomain) {
+                        seen.add(u);
+                        candidates.push(u);
+                    } };
+                    serp.organicAbove.forEach(o => add(o.url));
+                    serp.aioReferences.slice(0, 4).forEach(r => add(r.url));
+                    serp.videoItems.slice(0, 1).forEach(v => add(v.url));
+                    competitorContent = [];
+                    for (const url of candidates.slice(0, 3)) {
+                        competitorContent.push(await fetchCompetitorContent(url, { firecrawl, supadata }, { maxChars: 4000, ua: crawlAs }));
+                    }
+                }
+                results.push({
+                    urlKey: t.urlKey, query: t.query, impressions: t.impressions, gscPosition: t.position, priorPosition: t.priorPosition, slipped: t.slipped,
+                    organicRank: serp.ourOrganicRank, aioPresent: serp.aioPresent, aioCitesUs: serp.aioCitesUs, videoPresent: serp.videoPresent,
+                    verdict: verdict.verdict, verdictNote: verdict.note,
+                    ownHeadings: own?.headings.map(h => h.heading) ?? null, schemaTypes: own?.jsonLdTypes ?? null, hasProductSchema: own?.hasProductOrReview ?? null, dateModified: own?.dateModified ?? null,
+                    todos, todosInserted: inserted,
+                    competitors: { organicAbove: serp.organicAbove, aioReferences: serp.aioReferences, videoItems: serp.videoItems },
+                    ...(competitorContent ? { competitorContent } : {}),
+                });
+            }
+            const md = `# Content recon — ${siteUrl}\n\n${results.length} page(s), ${results.reduce((s, r) => s + r.todosInserted, 0)} to-dos saved. DataForSEO SERP cost $${cost.toFixed(4)}.\n\n` +
+                results.map(r => {
+                    const flags = [r.aioPresent ? (r.aioCitesUs ? 'AIO: cited' : 'AIO: NOT cited') : 'no AIO', r.videoPresent ? 'video pack' : null].filter(Boolean).join(' · ');
+                    return `## ${r.urlKey}\n"${r.query}" — organic #${r.organicRank ?? '?'} (GSC avg ${r.gscPosition}${r.slipped ? `, slipped from ${r.priorPosition}` : ''}), ${r.impressions} impr. ${flags}\n**${r.verdict}** — ${r.verdictNote}\n` +
+                        (r.todos.length ? '\nTo do:\n' + r.todos.map((t) => `- [${t.type}] ${t.action}`).join('\n') : '');
+                }).join('\n\n') +
+                (() => {
+                    const errs = results.flatMap(r => (r.competitorContent ?? []).filter((c) => c.error));
+                    if (!errs.length)
+                        return '';
+                    const needKey = errs.filter(c => /not set/i.test(c.error));
+                    const blocked = errs.filter(c => !/not set/i.test(c.error));
+                    let note = '';
+                    if (blocked.length)
+                        note += `\n\n${blocked.length} competitor(s) couldn't be fetched (bot-protection like Cloudflare, a block, or a fetch error): ${blocked.slice(0, 5).map(c => c.url).join(', ')}. If one matters, paste its copy here or drop a text file and I'll diff it in.`;
+                    if (needKey.length)
+                        note += `\n\n${needKey.length} competitor(s) skipped for a missing API key: ${[...new Set(needKey.map(c => c.error))].join('; ')}.`;
+                    return note;
+                })() +
+                `\n\nNext: research the competitors (transcribe the videos, read the reachable pages), write gaps back with save_recon_todo, and track with recon_todos.` + browserLink(siteUrl);
+            return { content: [{ type: 'text', text: md }], structuredContent: { siteUrl, cost, targets: results } };
+        }
+        finally {
+            db.close();
+        }
+    });
+    // save_recon_todo — the research session writes its content-gap / originality findings back
+    // into the ledger against a page (source: 'research').
+    server.registerTool('save_recon_todo', {
+        title: 'Save content-recon to-dos (research writeback)',
+        description: 'Write content-recon findings back into the trackable ledger for a page — the gaps and originality the research session found by diffing competitors (firecrawl) and videos (supadata) against our content. Each to-do is an action with a type (content-gap / originality / schema / freshness / format), rationale and evidence. Snapshots the page baseline so the fix\'s effect on rank/AIO-citation is measurable later. Run recon_targets first (it classifies the page and seeds the deterministic to-dos); this adds the judgement ones. Track everything with recon_todos.',
+        inputSchema: {
+            siteUrl: z.string(),
+            urlKey: z.string().describe('The page (any URL form — normalised to its key)'),
+            todos: z.array(z.object({
+                action: z.string(),
+                type: z.string().optional(),
+                rationale: z.string().optional(),
+                evidence: z.record(z.any()).optional(),
+                priority: z.number().optional(),
+            })).min(1),
+        },
+    }, async ({ siteUrl, urlKey: rawUrl, todos }) => {
+        const db = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
+        try {
+            const key = urlKey(rawUrl, { hostForm: hostFormForProperty(siteUrl) ?? 'asis' });
+            const page = db.db.prepare(`SELECT query, organic_rank, aio_cites_us, gsc_position FROM recon_page WHERE url_key=?`).get(key);
+            const baseline = page ? { organicRank: page.organic_rank, aioCitesUs: !!page.aio_cites_us, gscPosition: page.gsc_position, at: new Date().toISOString().slice(0, 10) } : {};
+            const drafts = todos.map(t => ({ action: t.action, type: t.type ?? 'content-gap', rationale: t.rationale ?? '', evidence: t.evidence ?? {}, priority: t.priority ?? 0 }));
+            const n = insertTodos(db.db, key, page?.query ?? '', drafts, baseline, 'research');
+            return { content: [{ type: 'text', text: `Saved ${n} recon to-do(s) for ${key}${n < drafts.length ? ` (${drafts.length - n} already open)` : ''}. Track with recon_todos.` }], structuredContent: { urlKey: key, inserted: n } };
+        }
+        finally {
+            db.close();
+        }
+    });
+    // recon_todos — list, track and annotate the ledger. No id → list (optionally filtered);
+    // id → update status and/or append a dated annotation, and optionally re-measure the outcome.
+    server.registerTool('recon_todos', {
+        title: 'List, track and annotate content-recon to-dos',
+        description: 'The content-recon to-do board. With no id: list to-dos (optionally filter by page or status), grouped by page with each page\'s verdict — the pick-a-page-to-work-on surface, and the hand-off to content-machine. With id: update one to-do — set status (open → researching → drafted → shipped → dismissed) and/or append a dated annotation note (your own observations, the history). On status:shipped with remeasure:true it re-fetches the SERP and records the outcome, so you can see whether the fix moved you from AIO-uncited to cited, or up the organic ranks.',
+        inputSchema: {
+            siteUrl: z.string(),
+            urlKey: z.string().optional().describe('Filter the list to one page'),
+            status: z.enum(['open', 'researching', 'drafted', 'shipped', 'dismissed']).optional().describe('Filter the list, or the new status when id is set'),
+            id: z.number().int().optional().describe('Update this to-do'),
+            note: z.string().optional().describe('Append a dated annotation to this to-do'),
+            remeasure: z.boolean().optional().describe('On status:shipped, re-fetch the SERP and record the outcome (paid)'),
+            location: z.union([z.string(), z.number()]).optional(),
+        },
+    }, async ({ siteUrl, urlKey: rawUrl, status, id, note, remeasure, location }) => {
+        const db = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
+        try {
+            if (id != null) {
+                const row = db.db.prepare(`SELECT * FROM recon_todo WHERE id=?`).get(id);
+                if (!row)
+                    throw new Error(`No recon to-do #${id}.`);
+                let notes = row.notes ?? '';
+                if (note)
+                    notes = (notes ? notes + '\n' : '') + `[${new Date().toISOString().slice(0, 10)}] ${note}`;
+                let outcome = row.outcome;
+                let outcomeNote = '';
+                if (status === 'shipped' && remeasure && dfs) {
+                    const serpResp = await dfs.serpOrganic(row.query, location, 'en', 20);
+                    const serp = parseSerpForRecon(serpResp, dfsHost(siteUrl));
+                    outcome = JSON.stringify({ organicRank: serp.ourOrganicRank, aioCitesUs: serp.aioCitesUs, at: new Date().toISOString().slice(0, 10) });
+                    const base = row.baseline ? JSON.parse(row.baseline) : {};
+                    outcomeNote = ` Outcome: organic ${base.organicRank ?? '?'}→${serp.ourOrganicRank ?? '?'}, AIO cited ${base.aioCitesUs ? 'yes' : 'no'}→${serp.aioCitesUs ? 'yes' : 'no'}.`;
+                }
+                db.db.prepare(`UPDATE recon_todo SET status=COALESCE(?,status), notes=?, outcome=COALESCE(?,outcome), updated_at=datetime('now') WHERE id=?`)
+                    .run(status ?? null, notes, outcome ?? null, id);
+                return { content: [{ type: 'text', text: `Updated to-do #${id}${status ? ` → ${status}` : ''}${note ? ' (note added)' : ''}.${outcomeNote}` }], structuredContent: { id, status: status ?? row.status, outcome: outcome ? JSON.parse(outcome) : null } };
+            }
+            const key = rawUrl ? urlKey(rawUrl, { hostForm: hostFormForProperty(siteUrl) ?? 'asis' }) : null;
+            const where = [];
+            const args = [];
+            if (key) {
+                where.push('url_key=?');
+                args.push(key);
+            }
+            if (status) {
+                where.push('status=?');
+                args.push(status);
+            }
+            const rows = db.db.prepare(`SELECT id, url_key, query, action, type, rationale, priority, status, source, notes, baseline, outcome
+          FROM recon_todo ${where.length ? 'WHERE ' + where.join(' AND ') : ''} ORDER BY url_key, priority DESC`).all(...args);
+            if (!rows.length)
+                return { content: [{ type: 'text', text: `No recon to-dos${key ? ` for ${key}` : ''}${status ? ` with status ${status}` : ''}. Run recon_targets to generate some.` }], structuredContent: { todos: [] } };
+            const byPage = new Map();
+            for (const r of rows)
+                (byPage.get(r.url_key) ?? byPage.set(r.url_key, []).get(r.url_key)).push(r);
+            const verdictStmt = db.db.prepare(`SELECT verdict, verdict_note FROM recon_page WHERE url_key=?`);
+            const md = `# Content-recon to-dos — ${rows.length} item(s)${status ? `, status ${status}` : ''}\n\n` +
+                [...byPage.entries()].map(([url, items]) => {
+                    const v = verdictStmt.get(url);
+                    return `## ${url}${v ? `\n_${v.verdict}_ — ${v.verdict_note}` : ''}\n\n| # | Status | Type | Action |\n|---|---|---|---|\n` +
+                        items.map(i => `| ${i.id} | ${i.status} | ${i.type ?? ''} | ${String(i.action).replace(/\|/g, '\\|')} |`).join('\n') +
+                        (items.some(i => i.notes) ? '\n\nNotes:\n' + items.filter(i => i.notes).map(i => `- #${i.id}: ${String(i.notes).replace(/\n/g, ' / ')}`).join('\n') : '');
+                }).join('\n\n') +
+                browserLink(siteUrl);
+            return { content: [{ type: 'text', text: md }], structuredContent: { todos: rows } };
+        }
+        finally {
+            db.close();
+        }
+    });
     // keyword_list — demand-first clustering ("list mode"): a keyword list becomes topics
     // with own/weak/absent verdicts, clustered by the URL Google already answers them with.
     server.registerTool('keyword_list', {