@houtini/seo-audit-console 0.9.0 → 0.10.0

package/dist/server.js

@@ -18,15 +18,10 @@ import { fetchCompetitorContent, routeFor } from './core/reconResearch.js';
 import { fetchOwnPage } from './core/reconFetch.js';
 import { parseSerpForRecon, reconVerdict } from './core/serpRecon.js';
 import { selectReconTargets, deterministicTodos, persistReconPage, insertTodos, pageState, crawlRealityOverride, clusterCannibalisation, opportunityBasis } 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) {
     const base = dashboardServerUrl();
     if (base)
         return `\n\n📊 Browser dashboard: ${base}/dashboard${siteUrl ? `?siteUrl=${encodeURIComponent(siteUrl)}` : ''}`;
-    // No live server: point at the dashboard surfaces that always work. get_dashboard renders the
-    // interactive dashboard in chat (works through the Docker gateway where a served port would not);
-    // serve_dashboard opens a browser tab locally; export_report writes a shareable HTML file.
     return `\n\n📊 See it in the dashboard — run get_dashboard${siteUrl ? ` for ${siteUrl}` : ''} (interactive, in chat), serve_dashboard (browser tab), or export_report (shareable HTML).`;
 }
 import { runAudit, runSingleCheck, listChecks } from './audit/engine.js';
@@ -62,9 +57,6 @@ import { gscFreshness } from './core/gscFreshness.js';
 import { clusterKeywordList } from './audit/keywordList.js';
 const SERVER_NAME = 'seo-audit-console';
 const SERVER_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
-// Where per-property crawl/audit DBs live. Resolution order (computed once per run):
-//   SAC_DATA_DIR env  >  persisted choice (~/.seo-audit-console.json)  >  Documents default.
-// The user can set the persisted choice through the `data_location` tool (no JSON editing).
 const CONFIG_PATH = path.join(homedir(), '.seo-audit-console.json');
 const DEFAULT_DATA_DIR = path.join(homedir(), 'Documents', 'seo-audit-console');
 function readConfigDataDir() {
@@ -82,111 +74,102 @@ export function dataDir() {
     return RESOLVED_DATA_DIR;
 }
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// Version the widget URIs: hosts may cache ui:// resources by URI indefinitely, so an
-// unversioned URI can pin users to a stale (or broken) cached bundle across releases.
 const DASHBOARD_URI = `ui://dashboard/main-${SERVER_VERSION}.html`;
 const SYNC_PROGRESS_URI = `ui://sync-progress/main-${SERVER_VERSION}.html`;
-// Must match the categories actually used by CHECKS (src/audit/checks.ts) so category
-// filters never silently return empty. (Was listing performance/agentic/integrity/war-stories
-// which no check uses, and omitting content/security which checks do use.)
 const CHECK_CATEGORIES = [
     'crawlability', 'indexation', 'onpage', 'content', 'schema', 'security', 'performance', 'merged',
 ];
 function isoDaysAgo(days) {
     return new Date(Date.now() - days * 86400000).toISOString().slice(0, 10);
 }
-// Server-level instructions (MCP `initialize` result): teach the assistant how the data
-// sources JOIN so it can COMPOSE bespoke multi-source analyses, not just run presets.
-const SERVER_INSTRUCTIONS = `SEO Audit Console fuses four data sources into one SQLite database per property: Google Search Console history, a first-party site crawl, GSC URL Inspection, and on-demand DataForSEO (SERP/Labs/Backlinks). Its real power is COMPOSITION — joining sources to answer questions no single tool answers.
-
-JOIN KEYS (memorise these):
-- url_key — one normalised URL form (https, unified www/apex, sorted params, no tracking params/fragments). Joins the crawl (pages, links) ↔ GSC (search_analytics.page_key) ↔ url_inspection ↔ page_backlinks ↔ page_cwv ↔ page_entity. normalize_url shows the key for any URL.
-- query — the literal search term. Joins GSC search_analytics ↔ DataForSEO keyword tools (keyword_volume, search_intent, ranked_keywords rows) ↔ keyword_intent.
-- domain — a bare host (no scheme, no www). Joins the Labs tools (ranked_keywords, domain_visibility, top_pages, competitors_domain, topic_gaps) ↔ backlinks summary.
-
-GRAIN (one line per source):
-- search_analytics: date × query × page (plus device/country when synced with segments). Rows are additive; position must be impression-weighted when aggregated.
-- pages / links: the LATEST crawl only, one row per url_key (history lives in page_snapshots, diffed by detect_changes). Carries title/H1/meta, canonical, schema (json_ld), body_chunks, iPR, click_depth, inlink_count.
-- url_inspection: one row per inspected URL — Google's own view (coverage_state, google_canonical vs user_canonical, last_crawl_time, crawled_as, rich_results).
-- rank_history: month × domain (DataForSEO rank distribution + ETV).
-- page_backlinks: one row per backlinked URL (counts + live HTTP status).
-- Labs tools: keyword × target, or month × target; cached 20 days; each call costs money — never loop them in bulk.
-
-ARCHETYPE CHAINS (compose along these lines):
-1. Demand → reality: a GSC query with impressions but weak rank → the ranking page's crawl fields (title/H1/body_chunks) → does the page actually say what the query asks? → fix on-page or draft content.
-2. Authority → waste: iPR / backlinks flowing into non-200, redirected, or orphaned URLs → recover the equity with 301s or internal links (fix_finding generates them).
-3. Competitor → gap: competitor keyword footprints (ranked_keywords / topic_gaps) minus our GSC + crawled-page footprint → topics to cover, each tied to the nearest existing page.
-
-COST DISCIPLINE (behave like a strategist who knows the margins):
-- Free and instant, use liberally: everything on synced data — query_data, run_audit, query_audit, suggest_pages, list_templates, detect_changes, get_dashboard, serve_dashboard, export_report.
-- Paid but CHEAP and 20-day cached (Labs/Keywords, ~$0.01–0.13 a call): keyword_volume, topic_trend, search_intent, ranked_keywords, serp_features, domain_visibility, top_pages, competitors_domain, page_intersection, topic_gaps. Top-down pulls only — ONE ranked_keywords call answers "what does this domain rank for"; NEVER loop keywords through SERP endpoints to reconstruct what a Labs call returns.
-- Paid per-keyword (SERP): related_terms, youtube_discovery (ranking videos for a topic — pair with a transcript tool), news_discovery (recent coverage / freshness), and AI-Overview CITATION checks. On-demand for a handful of clicked/explicit keywords, never a list.
-- Content research (what to write / what changed): topic_trend (is a topic rising/seasonal) → youtube_discovery + news_discovery (what the winning videos/articles cover) → draft_content.
-- Separate subscription: pull_backlinks (DataForSEO Backlinks — a 40204 error means it isn't activated).
-
-AGENCY MACRO-WORKFLOWS (the engagement arc — each stage feeds the next):
-1. Baseline: refresh_property → run_audit → serve_dashboard (share the URL).
-2. Market: serp_features (feature exposure) + domain_visibility + competitors_domain → topic_gaps vs the named rivals.
-3. Content plan: suggest_pages (demand you already have) + topic_gaps (demand rivals own) → draft_content briefs.
-4. Fix cycle: fix_finding per top finding → re-crawl → detect_changes to prove the fix landed.
-
+const SERVER_INSTRUCTIONS = `SEO Audit Console fuses four data sources into one SQLite database per property: Google Search Console history, a first-party site crawl, GSC URL Inspection, and on-demand DataForSEO (SERP/Labs/Backlinks). Its real power is COMPOSITION — joining sources to answer questions no single tool answers.
+
+JOIN KEYS (memorise these):
+- url_key — one normalised URL form (https, unified www/apex, sorted params, no tracking params/fragments). Joins the crawl (pages, links) ↔ GSC (search_analytics.page_key) ↔ url_inspection ↔ page_backlinks ↔ page_cwv ↔ page_entity. normalize_url shows the key for any URL.
+- query — the literal search term. Joins GSC search_analytics ↔ DataForSEO keyword tools (keyword_volume, search_intent, ranked_keywords rows) ↔ keyword_intent.
+- domain — a bare host (no scheme, no www). Joins the Labs tools (ranked_keywords, domain_visibility, top_pages, competitors_domain, topic_gaps) ↔ backlinks summary.
+
+GRAIN (one line per source):
+- search_analytics: date × query × page (plus device/country when synced with segments). Rows are additive; position must be impression-weighted when aggregated.
+- pages / links: the LATEST crawl only, one row per url_key (history lives in page_snapshots, diffed by detect_changes). Carries title/H1/meta, canonical, schema (json_ld), body_chunks, iPR, click_depth, inlink_count.
+- url_inspection: one row per inspected URL — Google's own view (coverage_state, google_canonical vs user_canonical, last_crawl_time, crawled_as, rich_results).
+- rank_history: month × domain (DataForSEO rank distribution + ETV).
+- page_backlinks: one row per backlinked URL (counts + live HTTP status).
+- Labs tools: keyword × target, or month × target; cached 20 days; each call costs money — never loop them in bulk.
+
+ARCHETYPE CHAINS (compose along these lines):
+1. Demand → reality: a GSC query with impressions but weak rank → the ranking page's crawl fields (title/H1/body_chunks) → does the page actually say what the query asks? → fix on-page or draft content.
+2. Authority → waste: iPR / backlinks flowing into non-200, redirected, or orphaned URLs → recover the equity with 301s or internal links (fix_finding generates them).
+3. Competitor → gap: competitor keyword footprints (ranked_keywords / topic_gaps) minus our GSC + crawled-page footprint → topics to cover, each tied to the nearest existing page.
+
+COST DISCIPLINE (behave like a strategist who knows the margins):
+- Free and instant, use liberally: trend_categories, and everything on synced data — query_data, run_audit, query_audit, suggest_pages, list_templates, detect_changes, get_dashboard, serve_dashboard, export_report.
+- Paid but CHEAP and 20-day cached (Labs/Keywords, ~$0.01–0.13 a call): keyword_volume, topic_trend, search_intent, ranked_keywords, serp_features, domain_visibility, top_pages, competitors_domain, page_intersection, topic_gaps. Top-down pulls only — ONE ranked_keywords call answers "what does this domain rank for"; NEVER loop keywords through SERP endpoints to reconstruct what a Labs call returns.
+- Paid per-keyword (SERP): related_terms, youtube_discovery (ranking videos for a topic — pair with a transcript tool), news_discovery (recent coverage / freshness), and AI-Overview CITATION checks. On-demand for a handful of clicked/explicit keywords, never a list.
+- Content research (what to write / what changed): topic_trend (is a topic rising/seasonal; with a categoryCode from the free trend_categories, is a whole market growing and what is breaking out in it) → youtube_discovery + news_discovery (what the winning videos/articles cover) → draft_content.
+- Separate subscription: pull_backlinks (DataForSEO Backlinks — a 40204 error means it isn't activated).
+
+AGENCY MACRO-WORKFLOWS (the engagement arc — each stage feeds the next):
+1. Baseline: refresh_property → run_audit → serve_dashboard (share the URL).
+2. Market: serp_features (feature exposure) + domain_visibility + competitors_domain → topic_gaps vs the named rivals.
+3. Content plan: suggest_pages (demand you already have) + topic_gaps (demand rivals own) → draft_content briefs.
+4. Fix cycle: fix_finding per top finding → re-crawl → detect_changes to prove the fix landed.
+
 Before planning ANY complex multi-source question, call composition_cookbook — it returns the full data-surface map and worked recipes using these exact tool and table names.`;
-const COOKBOOK_TEXT = `# Composition cookbook — the data surface and how to join it
-
-This server's value is composition: joining Search Console, the crawl, URL Inspection and DataForSEO to answer questions no preset check covers. This page is static (no API calls) — use it to PLAN, then run the tools.
-
-## The data surface
-
-| Source (table) | Grain | Key dimensions | Join keys | Freshness | Cost |
-|---|---|---|---|---|---|
-| search_analytics (GSC) | date × query × page (+device/country with segments) | clicks, impressions, ctr, position | page_key (url_key), query, date | sync_gsc / refresh_property — incremental, GSC lags ~2–3 days | free |
-| pages + links (crawl) | one row per url_key, LATEST crawl | status, title, H1, meta, canonical_key, robots, json_ld, hreflang, redirects, body_chunks, word_count, ipr, click_depth, inlink_count, conditional_304 | url_key | start_crawl / refresh_property (on demand) | free |
-| page_snapshots (drift) | url_key × crawl | field-level SEO snapshot per crawl | url_key, captured_at | every crawl, automatically | free |
-| url_inspection | one row per inspected URL (top pages by clicks, quota-limited) | coverage_state, page_fetch_state, google_canonical, user_canonical, last_crawl_time, crawled_as, rich_results | url_key | inspect_urls | free (GSC quota) |
-| sitemap_urls | one row per sitemap URL | lastmod | url_key | captured at crawl time | free |
-| rank_history | month × domain | rank distribution (1–3/4–10/11–20/21–100), ETV | period | track_ranks | paid, 20-day cache |
-| page_backlinks | one row per backlinked URL | backlinks, referring_domains, live status_code | url_key, domain | pull_backlinks (needs the DataForSEO Backlinks subscription) | paid, 20-day cache |
-| link_prospects | one row per prospect domain (links to competitors, not you) | intersections, domain_trust, spam_score, dofollow, trust_flow, topical_trust_flow | domain | link_intersect (needs the DataForSEO Backlinks subscription; Majestic optional) | paid, 20-day cache |
-| keyword_intent | one row per keyword | intent + probability | query | search_intent (pass siteUrl to persist) | paid (cheap), cached |
-| page_cwv | one row per audited URL | performance, LCP, CLS, TBT | url_key | page_lighthouse (pass siteUrl to persist) | paid, cached |
-| page_entity + entity_edge | one row per page / edge per relation | QID, label, subclass-of / part-of | url_key, qid | resolve_entities (free Wikidata) | free |
-| Labs (ranked_keywords, domain_visibility, top_pages, competitors_domain, page_intersection, topic_gaps) | keyword × target, or month × target | volume, ETV, position, KD, intent, SERP features, AIO citations | domain, query | on demand | paid, 20-day cache |
-| findings (audit_runs) | finding per check × URL | priority, evidence JSON | url_key, check_id | run_audit | free |
-
-Raw access: query_audit runs any single check with full evidence; every table above lives in one SQLite file per property (path via data_location) if you need direct SQL.
-
-## Worked recipes
-
-1. **AI Overview exposure & citation loss.** ranked_keywords target:<your domain> aioOnly:true → keywords you rank for where the SERP shows an AI Overview (exposure). For citation (are YOU a source?) check specific keywords with related_terms/serpOrganic — the ai_overview item's references[] carries domain/url/quoted text. For each exposed keyword's ranking page, pull its per-day clicks from search_analytics (page_key × date). Pages whose clicks fell while the AIO citation appeared = you are feeding the answer without earning the visit.
-2. **Striking distance without body coverage.** query_audit check:striking-distance (GSC rank 11–20) → for each page, check pages.body_chunks for the query's terms. The automated versions: body-missing-top-query, rag-answer-gap, and score_passages for the dense-answer test. Pages ranking 11–20 that never answer the query in one passage are the highest-yield rewrites.
-3. **Not indexed + no equity.** url_inspection.coverage_state ~ 'not indexed' joined to pages.ipr + inlink_count. Low-iPR unindexed pages need internal links, not resubmission; high-iPR unindexed pages are the real anomalies. (Checks: coverage-not-indexed, underlinked-high-demand.)
-4. **Cannibalisation with semantic overlap.** run_audit → keyword-cannibalisation evidence lists the competing URLs per query → compare those pages' body_chunks: heavy chunk overlap = consolidate (301 the loser); light overlap = differentiate the titles/H1s and interlink with distinct anchors.
-5. **Stable rank, falling CTR → SERP feature shift.** In search_analytics find queries where weekly position is flat but ctr declines → related_terms / ranked_keywords serpFeatures for that keyword shows what now sits above you (AIO, featured snippet, shopping). ctr-below-expected is the deterministic starting list.
-6. **Schema vs rich-result reality.** pages.json_ld (declared @types) joined to url_inspection.rich_results (what Google actually detected + issues). The rich-result-issues check automates the per-URL diff; the composition question is per-TEMPLATE (list_templates): which template's schema never earns its rich result?
-7. **Migration signal transfer.** pages.redirects (recorded chains) → url_inspection.google_canonical of the target (has Google accepted the move?) → search_analytics clicks by page_key before/after the migration date. Equity that didn't follow the 301 shows up as a target with no canonical adoption and no click recovery.
-8. **404s with backlinks.** pages.status_code = 404 joined to page_backlinks.backlinks (run pull_backlinks first) → run_audit surfaces backlinks-to-404; fix_finding generates the 301 that recovers the equity.
-9. **Competitor topic gap.** topic_gaps (bounded + cached: competitor ranked_keywords minus your GSC queries and page titles/H1s, clustered and scored) — or do it manually with ranked_keywords per competitor when you want the raw rows.
-10. **Link gap (what links do rivals have that we don't).** link_intersect over the competitor set (or a single company) → link_prospects: domains linking to them but not you, followed-first and sorted by domain trust. DataForSEO domain rank surfaces spam directories at the top; MAJESTIC_API_KEY re-sorts by Trust Flow (a rank-227 domain is often TF 0) and Topical Trust Flow shows whether that authority is on-topic. data_storage flags when a property's prospect set is going stale (competitors keep earning links).
-
-## Novel combinations (nothing else surfaces these)
-
-- **Crawl budget vs equity:** url_inspection.last_crawl_time × pages.ipr — your highest-iPR pages should be recrawled often; a high-iPR page Google rarely revisits is a freshness/priority problem (and vice versa: junk crawled daily = wasted budget).
-- **AIO text vs your content:** the ai_overview items in a SERP call (related_terms' underlying serpOrganic) × pages.body_chunks — is the text Google quotes actually on your page, and in one extractable chunk?
-- **Crawl-to-first-impression latency:** url_inspection.last_crawl_time vs the first date a page appears in search_analytics — how fast does Google turn a crawl into impressions, per template? Slow templates have an indexing-pipeline problem.
-- **Crawled-as vs response times:** url_inspection.crawled_as (mobile/desktop agent) × pages.response_time_ms — slow responses specifically on the agent Google uses against you.
-
-## Agency engagement recipes (the deliverable arc)
-
-- **Week-one baseline:** refresh_property → run_audit → serve_dashboard. Share the dashboard URL; the ranked findings ARE the technical workstream.
-- **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.
-
+const COOKBOOK_TEXT = `# Composition cookbook — the data surface and how to join it
+
+This server's value is composition: joining Search Console, the crawl, URL Inspection and DataForSEO to answer questions no preset check covers. This page is static (no API calls) — use it to PLAN, then run the tools.
+
+## The data surface
+
+| Source (table) | Grain | Key dimensions | Join keys | Freshness | Cost |
+|---|---|---|---|---|---|
+| search_analytics (GSC) | date × query × page (+device/country with segments) | clicks, impressions, ctr, position | page_key (url_key), query, date | sync_gsc / refresh_property — incremental, GSC lags ~2–3 days | free |
+| pages + links (crawl) | one row per url_key, LATEST crawl | status, title, H1, meta, canonical_key, robots, json_ld, hreflang, redirects, body_chunks, word_count, ipr, click_depth, inlink_count, conditional_304 | url_key | start_crawl / refresh_property (on demand) | free |
+| page_snapshots (drift) | url_key × crawl | field-level SEO snapshot per crawl | url_key, captured_at | every crawl, automatically | free |
+| url_inspection | one row per inspected URL (top pages by clicks, quota-limited) | coverage_state, page_fetch_state, google_canonical, user_canonical, last_crawl_time, crawled_as, rich_results | url_key | inspect_urls | free (GSC quota) |
+| sitemap_urls | one row per sitemap URL | lastmod | url_key | captured at crawl time | free |
+| rank_history | month × domain | rank distribution (1–3/4–10/11–20/21–100), ETV | period | track_ranks | paid, 20-day cache |
+| page_backlinks | one row per backlinked URL | backlinks, referring_domains, live status_code | url_key, domain | pull_backlinks (needs the DataForSEO Backlinks subscription) | paid, 20-day cache |
+| link_prospects | one row per prospect domain (links to competitors, not you) | intersections, domain_trust, spam_score, dofollow, trust_flow, topical_trust_flow | domain | link_intersect (needs the DataForSEO Backlinks subscription; Majestic optional) | paid, 20-day cache |
+| keyword_intent | one row per keyword | intent + probability | query | search_intent (pass siteUrl to persist) | paid (cheap), cached |
+| page_cwv | one row per audited URL | performance, LCP, CLS, TBT | url_key | page_lighthouse (pass siteUrl to persist) | paid, cached |
+| page_entity + entity_edge | one row per page / edge per relation | QID, label, subclass-of / part-of | url_key, qid | resolve_entities (free Wikidata) | free |
+| Labs (ranked_keywords, domain_visibility, top_pages, competitors_domain, page_intersection, topic_gaps) | keyword × target, or month × target | volume, ETV, position, KD, intent, SERP features, AIO citations | domain, query | on demand | paid, 20-day cache |
+| findings (audit_runs) | finding per check × URL | priority, evidence JSON | url_key, check_id | run_audit | free |
+
+Raw access: query_audit runs any single check with full evidence; every table above lives in one SQLite file per property (path via data_location) if you need direct SQL.
+
+## Worked recipes
+
+1. **AI Overview exposure & citation loss.** ranked_keywords target:<your domain> aioOnly:true → keywords you rank for where the SERP shows an AI Overview (exposure). For citation (are YOU a source?) check specific keywords with related_terms/serpOrganic — the ai_overview item's references[] carries domain/url/quoted text. For each exposed keyword's ranking page, pull its per-day clicks from search_analytics (page_key × date). Pages whose clicks fell while the AIO citation appeared = you are feeding the answer without earning the visit.
+2. **Striking distance without body coverage.** query_audit check:striking-distance (GSC rank 11–20) → for each page, check pages.body_chunks for the query's terms. The automated versions: body-missing-top-query, rag-answer-gap, and score_passages for the dense-answer test. Pages ranking 11–20 that never answer the query in one passage are the highest-yield rewrites.
+3. **Not indexed + no equity.** url_inspection.coverage_state ~ 'not indexed' joined to pages.ipr + inlink_count. Low-iPR unindexed pages need internal links, not resubmission; high-iPR unindexed pages are the real anomalies. (Checks: coverage-not-indexed, underlinked-high-demand.)
+4. **Cannibalisation with semantic overlap.** run_audit → keyword-cannibalisation evidence lists the competing URLs per query → compare those pages' body_chunks: heavy chunk overlap = consolidate (301 the loser); light overlap = differentiate the titles/H1s and interlink with distinct anchors.
+5. **Stable rank, falling CTR → SERP feature shift.** In search_analytics find queries where weekly position is flat but ctr declines → related_terms / ranked_keywords serpFeatures for that keyword shows what now sits above you (AIO, featured snippet, shopping). ctr-below-expected is the deterministic starting list.
+6. **Schema vs rich-result reality.** pages.json_ld (declared @types) joined to url_inspection.rich_results (what Google actually detected + issues). The rich-result-issues check automates the per-URL diff; the composition question is per-TEMPLATE (list_templates): which template's schema never earns its rich result?
+7. **Migration signal transfer.** pages.redirects (recorded chains) → url_inspection.google_canonical of the target (has Google accepted the move?) → search_analytics clicks by page_key before/after the migration date. Equity that didn't follow the 301 shows up as a target with no canonical adoption and no click recovery.
+8. **404s with backlinks.** pages.status_code = 404 joined to page_backlinks.backlinks (run pull_backlinks first) → run_audit surfaces backlinks-to-404; fix_finding generates the 301 that recovers the equity.
+9. **Competitor topic gap.** topic_gaps (bounded + cached: competitor ranked_keywords minus your GSC queries and page titles/H1s, clustered and scored) — or do it manually with ranked_keywords per competitor when you want the raw rows.
+10. **Link gap (what links do rivals have that we don't).** link_intersect over the competitor set (or a single company) → link_prospects: domains linking to them but not you, followed-first and sorted by domain trust. DataForSEO domain rank surfaces spam directories at the top; MAJESTIC_API_KEY re-sorts by Trust Flow (a rank-227 domain is often TF 0) and Topical Trust Flow shows whether that authority is on-topic. data_storage flags when a property's prospect set is going stale (competitors keep earning links).
+
+## Novel combinations (nothing else surfaces these)
+
+- **Crawl budget vs equity:** url_inspection.last_crawl_time × pages.ipr — your highest-iPR pages should be recrawled often; a high-iPR page Google rarely revisits is a freshness/priority problem (and vice versa: junk crawled daily = wasted budget).
+- **AIO text vs your content:** the ai_overview items in a SERP call (related_terms' underlying serpOrganic) × pages.body_chunks — is the text Google quotes actually on your page, and in one extractable chunk?
+- **Crawl-to-first-impression latency:** url_inspection.last_crawl_time vs the first date a page appears in search_analytics — how fast does Google turn a crawl into impressions, per template? Slow templates have an indexing-pipeline problem.
+- **Crawled-as vs response times:** url_inspection.crawled_as (mobile/desktop agent) × pages.response_time_ms — slow responses specifically on the agent Google uses against you.
+
+## Agency engagement recipes (the deliverable arc)
+
+- **Week-one baseline:** refresh_property → run_audit → serve_dashboard. Share the dashboard URL; the ranked findings ARE the technical workstream.
+- **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.`;
-// The check catalogue rendered as markdown — single source of truth is listChecks();
-// shared by the seo-audit://checks-reference resource (and buildable for any category subset).
 function buildChecksMarkdown(checks) {
     const byCategory = new Map();
     for (const c of checks) {
@@ -200,53 +183,54 @@ function buildChecksMarkdown(checks) {
         list.map(c => `| \`${c.id}\` | ${c.severity} | ${c.labels.join(',')} | ${c.certainty} | ${c.fixType} | ${esc(c.title)} | ${esc(c.fix)} |`).join('\n'));
     return `# Check registry — ${checks.length} checks\n\nLabels: D = deterministic (cites bytes), G = evidence from Google's own data (Search Console / URL Inspection), N = judgement (heuristic, gated behind includeJudgement). Certainty < 1 discounts a finding's priority.\n\n${sections.join('\n\n')}\n`;
 }
-const HELP_TEXT = `# SEO Audit Console — what it can do
-A technical-SEO audit that fuses **Search Console + a site crawl + DataForSEO**, joined on a normalised URL, with evidence on every finding. Typical flow: **refresh → audit → fix → report**.
-
-## 1. Sync the data
-- **refresh_property** — sync everything (GSC → crawl → URL inspection → rank history). _"Refresh sc-domain:example.com"_ · add \`segments:true\` for device/country, \`maxPages\`, \`startDate\`.
-- **sync_gsc / start_crawl / inspect_urls / track_ranks** — run just one part. _"Crawl example.com, 500 pages"_
-- **check_sync_status / check_crawl_status** — poll a job. _"Check sync status"_
-- **list_properties** — _"List my Search Console properties"_
-
-## 2. Audit
-- **run_audit** — score all checks; returns a prioritised markdown report. _"Run an SEO audit on sc-domain:example.com"_ · \`scope:full\`, \`categories\`, \`includeJudgement:true\`.
-- **query_audit** — one named check with evidence (\`columns\`/\`offset\` for big sets). _"Show striking-distance for example.com"_
-- **query_data** — read-only queries over the raw tables; aggregates in the database (counts/percentages/sums), answers not rows. _"How do status codes break down on example.com?"_
-- **list_checks** — _"What does the audit check for?"_
-
-## 3. Fix (the moat)
-- **fix_finding** — paste-ready remediation from your own data: JSON-LD for missing/invalid schema, a 301 rule for broken links, iPR-ranked internal-link suggestions. _"Generate the fix for finding 12"_ or _"fix_finding check:missing-required-fields url:https://example.com/x"_
-- **detect_changes** — what changed since the last crawl (status, canonical, noindex, title, schema), severity-ranked — the regression monitor. _"Detect changes on example.com"_
-- **check_agent_readiness** — is your site ready for AI agents? Scores llms.txt / agents.md / AI-bot rules / Content Signals / MCP server card / Agent Skills / API Catalog / OAuth signals (0–100 + level) with copy-paste fixes. _"Check agent readiness for example.com"_
-
-## 4. Backlinks, keywords & competitive (DataForSEO, on-demand, cached 20 days)
-- **pull_backlinks** — backlink profile + per-page counts + live status → unlocks **backlinks-to-404** (recover lost equity), top-linked pages, true orphans. _"Pull backlinks for example.com"_
-- **link_intersect** — the links your competitors have that you don't - a prioritised outreach prospect list (followed-first, then domain trust, spam filtered). Also answers "what links does company X have that we don't?" for a single company. Set MAJESTIC_API_KEY to re-sort by Trust Flow + Topical Trust Flow (kills directory noise). _"Link intersect for example.com vs rival1.com, rival2.com"_
-- **keyword_volume / related_terms** — volume/CPC, and People-Also-Ask + related searches. _"Search volume for [\\"best widgets\\"]"_
-- **search_intent** — informational/navigational/commercial/transactional per keyword → spot intent mismatch behind low CTR. _"Classify intent for [\\"buy running shoes\\", \\"how to clean shoes\\"]"_
-- **page_lighthouse** — lab Core Web Vitals + opportunities for one URL (~20–120s). _"Run Lighthouse on https://example.com/slow-page"_
-- **competitors_domain** — domains competing for your organic keywords. _"Find competitors for example.com in the UK"_
-- **page_intersection** — keywords competitor pages rank for but yours doesn’t (content gap). _"Content gap: competitorUrls [\\"https://rival.com/guide\\"], excludePages [\\"https://example.com/guide\\"]"_
-- **domain_visibility** — monthly ranking-keyword distribution + ETV trend for ANY domain/subdomain (Semrush-style organic overview). _"Show visibility over time for competitor.com"_
-- **top_pages** — a domain's top organic pages by estimated traffic. _"Top pages on competitor.com"_
-- **ranked_keywords** — keywords a domain / subdomain / URL / subfolder ranks for (+ difficulty, intent, SERP features). _"What does competitor.com/blog/ rank for?"_ · \`scope:url|folder\` · \`aioOnly:true\` = keywords where the target is cited in AI Overviews
-- **topic_gaps** — what related topics should this site cover to be expert in its space: competitor keyword footprints minus everything you already rank or have a page for, clustered into ranked topics with volumes, the owning competitor and your nearest existing page. _"What topics should example.com cover? Compare against rival.com"_
-
-## 5. Templates & opportunities
-- **list_templates** — cluster pages into templates (one fix → N pages) with a representative exemplar. _"List page templates for example.com"_
-- **suggest_pages** — new-page ideas grounded in real GSC demand, minus what you already cover. _"Suggest new pages for example.com"_
-- **resolve_entities** — map pages to Wikidata entities → unlocks entity-internal-link-gap (judgement). _"Resolve entities for example.com"_
-
-## 6. Reports & dashboard
-- **get_dashboard** — interactive dashboard (renders in chat). _"Show the dashboard for example.com"_
-- **export_report** — self-contained shareable HTML to send a client. _"Export the report for example.com"_
-
-## 7. Utilities
-- **data_location** — where DBs are stored (set with a path). · **normalize_url** — the join key for a URL.
-- **data_storage** — per-property disk usage + row counts; prune (vacuum / clear-crawl-history / delete-property, destructive ones need \`confirm:true\`). _"How much disk is my audit data using?"_
-
-_Tip: first time on a property → \`refresh_property\` then \`run_audit\`._
+const HELP_TEXT = `# SEO Audit Console — what it can do
+A technical-SEO audit that fuses **Search Console + a site crawl + DataForSEO**, joined on a normalised URL, with evidence on every finding. Typical flow: **refresh → audit → fix → report**.
+
+## 1. Sync the data
+- **refresh_property** — sync everything (GSC → crawl → URL inspection → rank history). _"Refresh sc-domain:example.com"_ · add \`segments:true\` for device/country, \`maxPages\`, \`startDate\`.
+- **sync_gsc / start_crawl / inspect_urls / track_ranks** — run just one part. _"Crawl example.com, 500 pages"_
+- **check_sync_status / check_crawl_status** — poll a job. _"Check sync status"_
+- **list_properties** — _"List my Search Console properties"_
+
+## 2. Audit
+- **run_audit** — score all checks; returns a prioritised markdown report. _"Run an SEO audit on sc-domain:example.com"_ · \`scope:full\`, \`categories\`, \`includeJudgement:true\`.
+- **query_audit** — one named check with evidence (\`columns\`/\`offset\` for big sets). _"Show striking-distance for example.com"_
+- **query_data** — read-only queries over the raw tables; aggregates in the database (counts/percentages/sums), answers not rows. _"How do status codes break down on example.com?"_
+- **list_checks** — _"What does the audit check for?"_
+
+## 3. Fix (the moat)
+- **fix_finding** — paste-ready remediation from your own data: JSON-LD for missing/invalid schema, a 301 rule for broken links, iPR-ranked internal-link suggestions. _"Generate the fix for finding 12"_ or _"fix_finding check:missing-required-fields url:https://example.com/x"_
+- **detect_changes** — what changed since the last crawl (status, canonical, noindex, title, schema), severity-ranked — the regression monitor. _"Detect changes on example.com"_
+- **check_agent_readiness** — is your site ready for AI agents? Scores llms.txt / agents.md / AI-bot rules / Content Signals / MCP server card / Agent Skills / API Catalog / OAuth signals (0–100 + level) with copy-paste fixes. _"Check agent readiness for example.com"_
+
+## 4. Backlinks, keywords & competitive (DataForSEO, on-demand, cached 20 days)
+- **pull_backlinks** — backlink profile + per-page counts + live status → unlocks **backlinks-to-404** (recover lost equity), top-linked pages, true orphans. _"Pull backlinks for example.com"_
+- **link_intersect** — the links your competitors have that you don't - a prioritised outreach prospect list (followed-first, then domain trust, spam filtered). Also answers "what links does company X have that we don't?" for a single company. Set MAJESTIC_API_KEY to re-sort by Trust Flow + Topical Trust Flow (kills directory noise). _"Link intersect for example.com vs rival1.com, rival2.com"_
+- **keyword_volume / related_terms** — volume/CPC, and People-Also-Ask + related searches. _"Search volume for [\\"best widgets\\"]"_
+- **topic_trend / trend_categories** — Google Trends interest over time for keywords, a whole category (no keyword needed), or a keyword inside a category; \`related:true\` adds rising queries and topics. trend_categories (free) finds the category code. _"Is the Software category rising in the UK? What's breaking out in it?"_
+- **search_intent** — informational/navigational/commercial/transactional per keyword → spot intent mismatch behind low CTR. _"Classify intent for [\\"buy running shoes\\", \\"how to clean shoes\\"]"_
+- **page_lighthouse** — lab Core Web Vitals + opportunities for one URL (~20–120s). _"Run Lighthouse on https://example.com/slow-page"_
+- **competitors_domain** — domains competing for your organic keywords. _"Find competitors for example.com in the UK"_
+- **page_intersection** — keywords competitor pages rank for but yours doesn’t (content gap). _"Content gap: competitorUrls [\\"https://rival.com/guide\\"], excludePages [\\"https://example.com/guide\\"]"_
+- **domain_visibility** — monthly ranking-keyword distribution + ETV trend for ANY domain/subdomain (Semrush-style organic overview). _"Show visibility over time for competitor.com"_
+- **top_pages** — a domain's top organic pages by estimated traffic. _"Top pages on competitor.com"_
+- **ranked_keywords** — keywords a domain / subdomain / URL / subfolder ranks for (+ difficulty, intent, SERP features). _"What does competitor.com/blog/ rank for?"_ · \`scope:url|folder\` · \`aioOnly:true\` = keywords where the target is cited in AI Overviews
+- **topic_gaps** — what related topics should this site cover to be expert in its space: competitor keyword footprints minus everything you already rank or have a page for, clustered into ranked topics with volumes, the owning competitor and your nearest existing page. _"What topics should example.com cover? Compare against rival.com"_
+
+## 5. Templates & opportunities
+- **list_templates** — cluster pages into templates (one fix → N pages) with a representative exemplar. _"List page templates for example.com"_
+- **suggest_pages** — new-page ideas grounded in real GSC demand, minus what you already cover. _"Suggest new pages for example.com"_
+- **resolve_entities** — map pages to Wikidata entities → unlocks entity-internal-link-gap (judgement). _"Resolve entities for example.com"_
+
+## 6. Reports & dashboard
+- **get_dashboard** — interactive dashboard (renders in chat). _"Show the dashboard for example.com"_
+- **export_report** — self-contained shareable HTML to send a client. _"Export the report for example.com"_
+
+## 7. Utilities
+- **data_location** — where DBs are stored (set with a path). · **normalize_url** — the join key for a URL.
+- **data_storage** — per-property disk usage + row counts; prune (vacuum / clear-crawl-history / delete-property, destructive ones need \`confirm:true\`). _"How much disk is my audit data using?"_
+
+_Tip: first time on a property → \`refresh_property\` then \`run_audit\`._
 _Composing your own analysis? Call \`composition_cookbook\` first — the data-surface map (grain + join keys per source) and worked multi-source recipes._`;
 export function createServer() {
     const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { instructions: SERVER_INSTRUCTIONS });
@@ -255,7 +239,7 @@ export function createServer() {
     const gsc = credPath ? new GscClient(credPath) : null;
     const sync = gsc ? new GscSync(gsc, dataDir()) : null;
     const inspector = gsc ? new UrlInspector(gsc, dataDir()) : null;
-    const crawler = new Crawler(dataDir()); // no GSC credentials required
+    const crawler = new Crawler(dataDir());
     const dfsUser = process.env.DATAFORSEO_USERNAME;
     const dfsPass = process.env.DATAFORSEO_PASSWORD;
     const dfsCacheDays = Number(process.env.DATAFORSEO_CACHE_DAYS) || 7;
@@ -264,16 +248,12 @@ export function createServer() {
         : null;
     const rankTracker = dfs ? new RankTracker(dfs, dataDir()) : null;
     const linkIntersect = dfs ? new LinkIntersect(dfs, dataDir()) : null;
-    // Majestic (Trust Flow / Topical Trust Flow) — optional link_intersect + trapped-authority tier.
     const majesticKey = process.env.MAJESTIC_API_KEY;
     const majesticCacheDays = Number(process.env.MAJESTIC_CACHE_DAYS) || 30;
     const majestic = majesticKey ? new MajesticClient(majesticKey, path.join(dataDir(), 'majestic-cache.db'), majesticCacheDays) : null;
-    // Backlinks after Majestic, so pull_backlinks can enrich per-URL pages with Trust Flow.
     const backlinks = dfs ? new Backlinks(dfs, dataDir(), majestic) : 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());
@@ -288,33 +268,21 @@ export function createServer() {
             throw new Error('DATAFORSEO_USERNAME / DATAFORSEO_PASSWORD not set — required for DataForSEO.');
         return v;
     };
-    // Which optional integrations have a key set — drives the dashboard's key-gated tabs
-    // (Links, Content research) and their affiliate-linked upsell states. The data layer has
-    // no env access, so it's injected here onto every dashboard payload surface.
     const apiKeysStatus = () => ({ dataforseo: !!dfs, majestic: !!majestic, firecrawl: !!firecrawl, supadata: !!supadata });
-    // The dashboard webserver's options — one definition shared by serve_dashboard AND the
-    // auto-start at the end of refresh_property / run_audit, so a populated property always has
-    // a live browser link (browserLink() surfaces dashboardServerUrl() once this is running).
     const buildWebOpts = (port) => ({
         dataDir,
         uiHtml: () => readFileSync(path.join(__dirname, 'src', 'ui', 'dashboard.html'), 'utf8'),
         call: buildWebCallHandlers({ dataDir, dfs, apiKeys: apiKeysStatus }),
         ...(port != null ? { port } : {}),
     });
-    // Idempotent auto-start used by refresh_property / run_audit. Best-effort: a served port that
-    // can't bind (e.g. Docker without a published port) must never fail the populate/audit — the
-    // in-chat get_dashboard and export_report still work, and browserLink() falls back to those.
-    // Opt-out with SAC_AUTOSERVE=0 for headless/CI/sandboxed runs where binding a localhost port
-    // is unwanted (default: on, since the whole point is to hand the user a link).
     const autoServeDashboard = async () => {
         if (/^(0|false|no|off)$/i.test(process.env.SAC_AUTOSERVE ?? ''))
             return;
         try {
             await startDashboardServer(buildWebOpts());
         }
-        catch { /* dashboard is a convenience, not a dependency */ }
+        catch { }
     };
-    // ── Introspection (no data / creds required) ────────────────────────────
     server.registerTool('seo_audit_help', {
         title: 'Help — what this audit can do',
         description: 'Overview of every tool/feature with an example prompt for each. Start here.',
@@ -358,8 +326,6 @@ export function createServer() {
         inputSchema: { path: z.string().optional() },
     }, async ({ path: newPath }) => {
         if (newPath) {
-            // Persist an ABSOLUTE path — a relative one resolves against the host process's
-            // cwd, which differs across Claude Desktop launches, so DBs would "disappear".
             newPath = path.resolve(newPath);
             mkdirSync(newPath, { recursive: true });
             writeFileSync(CONFIG_PATH, JSON.stringify({ dataDir: newPath }, null, 2));
@@ -405,10 +371,6 @@ export function createServer() {
         }
         const rows = s.properties.map(p => `| ${p.siteUrl ?? p.file} | ${fmtBytes(p.bytes)} | ${p.searchAnalytics.toLocaleString('en-US')} | ${p.pages.toLocaleString('en-US')} | ${p.links.toLocaleString('en-US')} | ${p.pageSnapshots.toLocaleString('en-US')} | ${p.findings.toLocaleString('en-US')} | ${p.lastSynced?.slice(0, 10) ?? '—'} | ${p.lastCrawl?.slice(0, 10) ?? '—'} |`).join('\n');
         const cacheLines = s.caches.map(c => `- ${c.file}: ${fmtBytes(c.bytes)}`).join('\n');
-        // Link-intersect freshness: prospect data ages as competitors keep earning links, so
-        // flag properties that HAVE link_prospects and roughly how stale it is — a re-run of
-        // link_intersect updates it. (The DataForSEO call is 20-day cached; older than that a
-        // re-run genuinely refetches.)
         const nowMs = Date.now();
         const liProps = s.properties.filter(p => (p.linkProspects ?? 0) > 0);
         const liLines = liProps.map(p => {
@@ -425,7 +387,6 @@ export function createServer() {
             `Prune with data_storage prune:{siteUrl, action:"vacuum" | "clear-crawl-history" | "delete-property"} (destructive actions need confirm:true).`;
         return { content: [{ type: 'text', text: md }], structuredContent: s };
     });
-    // ── Audit engine ────────────────────────────────────────────────────────
     server.registerTool('run_audit', {
         title: 'Run SEO audit',
         description: 'Run the technical-SEO checks against synced data and return scored findings, ranked by expected clicks per dev-hour — Priority = (T × Y × C) / E (T = clicks at stake from real GSC data, Y = expected yield, C = certainty, E = effort hours). Crawl + GSC + URL-inspection checks. Set includeJudgement=true to include heuristic (N) checks.',
@@ -437,7 +398,7 @@ export function createServer() {
         },
     }, async ({ siteUrl, scope, categories, includeJudgement }) => {
         const result = runAudit(dataDir(), siteUrl, { scope, categories, includeJudgement });
-        await autoServeDashboard(); // spin up the browser dashboard so browserLink() hands over a live URL
+        await autoServeDashboard();
         return {
             content: [{ type: 'text', text: buildAuditMarkdown(result, siteUrl) + browserLink(siteUrl) }],
             structuredContent: { ...result, dashboardUrl: dashboardServerUrl() },
@@ -455,8 +416,6 @@ export function createServer() {
         },
     }, async ({ siteUrl, check, limit, offset, columns }) => {
         const r = runSingleCheck(dataDir(), siteUrl, check, limit, offset ?? 0);
-        // Token discipline (mirrors query_data): optional evidence-column selection + loud
-        // 120-char cell truncation, and an explicit offset/total footer.
         const shape = (f) => {
             const src = (f.evidence ?? {});
             const keys = columns?.length ? columns.filter(k => k in src) : Object.keys(src);
@@ -467,9 +426,6 @@ export function createServer() {
         };
         let sc = { ...r, findingsTotal: r.total };
         let findings = r.findings.map(shape);
-        // Hosts cap the model-facing result (~60k chars). On evidence-heavy checks a large
-        // `limit` can blow that ceiling and error the whole call — trim findings (keeping the
-        // true total) instead of failing. Same guard pattern as detect_changes.
         while (findings.length > 25 && JSON.stringify({ ...sc, findings }).length > 45000) {
             findings = findings.slice(0, Math.floor(findings.length / 2));
         }
@@ -540,7 +496,6 @@ export function createServer() {
         const text = `WRITING BRIEF — ${r.url}\nTarget query: “${r.topQuery ?? '(unknown)'}”\nGap: ${r.gap}\n\nTASK\n${r.brief}\n\nVOICE (match this — the page's own writing):\n${voice || '  (no substantial passages)'}\n\nFACTS (ground in these — the page's most query-relevant content; invent nothing beyond them):\n${facts || '  (none)'}`;
         return { content: [{ type: 'text', text }], structuredContent: r };
     });
-    // detect_changes — change-detection / drift: what changed on the site since the last crawl.
     server.registerTool('detect_changes', {
         title: 'Detect changes since the last crawl',
         description: 'Compare the two most recent crawls and report what changed per URL — status code, indexability, canonical, robots/noindex, title, meta, H1, schema, large content swings — each classified by severity (critical → info). This is the monitor: run refresh_property on different days to build history, then this surfaces regressions (a page that went noindex, a canonical that flipped, a 200 that became a 404). Needs at least two crawls.',
@@ -549,9 +504,6 @@ export function createServer() {
         const adb = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
         try {
             const d = diffLatest(adb.db);
-            // Cap the changes array in structuredContent to `limit` — the full diff can be tens of
-            // thousands of rows (e.g. a crawl-methodology change) and blow the MCP token ceiling. The
-            // summary keeps the TRUE totals; markdown is already limited.
             const lim = limit ?? 50;
             const sc = { ...d, changes: d.changes.slice(0, lim), changesReturned: Math.min(lim, d.changes.length), changesTotal: d.changes.length };
             return {
@@ -563,18 +515,16 @@ export function createServer() {
             adb.close();
         }
     });
-    // check_agent_readiness — is the site ready for AI agents? (the agentic-SEO / GEO frontier)
     server.registerTool('check_agent_readiness', {
         title: 'Check agent readiness (AI-agent / GEO signals)',
         description: 'Probe a site for AI-agent readiness — the signals agents use to discover and use it: robots.txt AI-bot rules + Content Signals, sitemap, Link headers, llms.txt, agents.md, Markdown content negotiation, Web Bot Auth, MCP server card, Agent Skills, API Catalog, OAuth discovery. Returns a 0–100 score, a level (Basic web presence → Agent-native), and a per-check checklist with copy-paste fixes. Live HTTP probes of the property origin (no crawl/GSC needed). Modelled on Cloudflare\'s isitagentready.com.',
         inputSchema: { siteUrl: z.string() },
     }, async ({ siteUrl }) => {
         const r = await checkAgentReadiness(siteUrl);
-        // Persist so the dashboard/export can show it (live probe, not crawl-derived).
         try {
             const adb = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
             try {
-                adb.db.prepare(`INSERT INTO agent_readiness (origin,score,level,checks,by_category,checked_at) VALUES (?,?,?,?,?,datetime('now'))
+                adb.db.prepare(`INSERT INTO agent_readiness (origin,score,level,checks,by_category,checked_at) VALUES (?,?,?,?,?,datetime('now'))
             ON CONFLICT(origin) DO UPDATE SET score=excluded.score, level=excluded.level, checks=excluded.checks, by_category=excluded.by_category, checked_at=excluded.checked_at`)
                     .run(r.origin, r.score, r.level, JSON.stringify(r.checks), JSON.stringify(r.byCategory));
             }
@@ -582,13 +532,12 @@ export function createServer() {
                 adb.close();
             }
         }
-        catch { /* persistence is best-effort */ }
+        catch { }
         return {
             content: [{ type: 'text', text: buildAgentReadinessMarkdown(r) }],
             structuredContent: r,
         };
     });
-    // fix_finding — the moat: turn a finding into a concrete, paste-ready remediation.
     server.registerTool('fix_finding', {
         title: 'Generate a fix for a finding',
         description: 'Turn an audit finding into a concrete, paste-ready remediation: JSON-LD for missing structured data, a 301 rule for broken / redirecting internal links, or internal-link suggestions for orphan / striking-distance pages. Other checks return their deterministic fix guidance. Dry-run — returns artifacts, never writes to your site. Identify the finding by findingId (from run_audit) or by check + url.',
@@ -602,7 +551,6 @@ export function createServer() {
     }, async ({ siteUrl, findingId, check, url, redirectFormat }) => {
         const db = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
         try {
-            // Resolve the finding → checkId, affected url_key, evidence.
             let checkId = check;
             let affectedKey = null;
             let evidence = {};
@@ -641,14 +589,12 @@ export function createServer() {
                     break;
                 }
                 case 'redirect-chain': {
-                    // The finding's url_key IS the chain's final page — its row holds the recorded
-                    // hops. Collapse each hop straight to the final URL; never fuzzy-match here.
                     const page = db.db.prepare('SELECT url, redirects FROM pages WHERE url_key = ?').get(affectedKey);
                     let hops = [];
                     try {
                         hops = page?.redirects ? JSON.parse(page.redirects) : [];
                     }
-                    catch { /* malformed chain */ }
+                    catch { }
                     kind = 'redirect';
                     fix = page && hops.length
                         ? { ...collapseChainRules(page.url, hops, redirectFormat ?? 'htaccess'), chain: hops }
@@ -656,8 +602,6 @@ export function createServer() {
                     break;
                 }
                 case 'internal-links-to-redirects': {
-                    // The flagged key is a redirect SOURCE; the crawler recorded where it actually
-                    // goes — find the chain containing it and use that real destination.
                     const hostForm = hostFormForProperty(siteUrl) ?? 'asis';
                     let knownTarget = null;
                     for (const row of db.db.prepare(`SELECT url, redirects FROM pages WHERE redirects IS NOT NULL AND redirects <> ''`).iterate()) {
@@ -668,15 +612,13 @@ export function createServer() {
                                 break;
                             }
                         }
-                        catch { /* skip malformed */ }
+                        catch { }
                     }
                     kind = 'redirect';
                     fix = suggestRedirect(affectedKey ?? '', [], redirectFormat ?? 'htaccess', knownTarget);
                     break;
                 }
                 case 'broken-internal-links': {
-                    // Genuinely dead target (4xx/5xx) — no recorded destination exists, so fall back
-                    // to token-overlap fuzzy matching against live pages.
                     const livePages = db.db
                         .prepare('SELECT url FROM pages WHERE status_code = 200 AND indexable = 1')
                         .all();
@@ -687,11 +629,8 @@ export function createServer() {
                 case 'orphan-with-impressions':
                 case 'striking-distance': {
                     const page = db.db.prepare('SELECT h1, title FROM pages WHERE url_key = ?').get(affectedKey);
-                    // Prefer the GSC query as anchor, but fall back to H1/title when it's a
-                    // boolean/over-long search string (common on job boards) — not usable anchor text.
                     const q = evidence.query;
                     const cleanQuery = q && q.length <= 60 && !/["()]|\bor\b|\bnot\b|\s-\w/i.test(q) ? q : undefined;
-                    // Never fall back to the raw q — it was just rejected as unusable anchor text.
                     const anchor = cleanQuery ?? page?.h1 ?? page?.title ?? '';
                     kind = 'internal-links';
                     fix = suggestInternalLinks(db.db, affectedKey ?? '', anchor);
@@ -721,7 +660,6 @@ export function createServer() {
         const key = urlKey(url, { hostForm });
         return { content: [{ type: 'text', text: key }], structuredContent: { url, key, hostForm } };
     });
-    // ── GSC ─────────────────────────────────────────────────────────────────
     server.registerTool('list_properties', {
         title: 'List GSC properties',
         description: 'List Google Search Console properties accessible to the service account.',
@@ -733,8 +671,6 @@ export function createServer() {
             structuredContent: { properties },
         };
     });
-    // refresh_property — the "sync everything" verb (GSC + crawl + inspection in one job).
-    // Skip flags let the same tool do "just update X".
     registerAppTool(server, 'refresh_property', {
         title: 'Refresh a property (sync + crawl + inspect)',
         description: 'Full refresh for a property in one async job: GSC sync → site crawl → URL inspection → DataForSEO rank history. Opens a live progress widget (phases + counts). Set gsc/crawl/inspect/ranks=false to run just part. GSC sync is "lite" (date×query×page) by default — set segments=true to also pull device/country breakdowns (much heavier on large sites). GSC sync is INCREMENTAL: the first sync pulls the window (default last 90 days; pass startDate to go deeper), later syncs only fetch new days — set full=true to force a full re-pull. Use this for "sync everything"; use the single-purpose tools to update just one thing.',
@@ -756,8 +692,6 @@ export function createServer() {
     }, async ({ siteUrl, gsc: doGsc, crawl, inspect, ranks, segments, full, location, startDate, endDate, maxPages, inspectLimit }) => {
         const jobId = jobs.start('refresh', async (update, signal) => {
             const r = await refresh.run(siteUrl, { gsc: doGsc, crawl, inspect, ranks, segments, full, location, startDate, endDate, maxPages, inspectLimit }, update, signal);
-            // Property is now populated — spin up the browser dashboard and hand back its URL so the
-            // finished job (polled via check_sync_status) carries a one-click link, no extra tool call.
             await autoServeDashboard();
             const dashboardUrl = dashboardServerUrl();
             return dashboardUrl ? { ...r, dashboardUrl, dashboard: `${dashboardUrl}/dashboard?siteUrl=${encodeURIComponent(siteUrl)}` } : r;
@@ -820,7 +754,6 @@ export function createServer() {
             structuredContent: { jobId, status: 'running', siteUrl },
         };
     });
-    // ── Crawl ─────────────────────────────────────────────────────────────────
     server.registerTool('start_crawl', {
         title: 'Crawl a site (just the crawl)',
         description: 'Update just the crawl: fetch the site into the local database (async job — poll with check_crawl_status). HTTP crawl; respects robots.txt; asset file-types are HEAD-only (no body download); internal-search / cart / wp-json / builder junk URLs are skipped by default. For a full refresh use refresh_property. excludePatterns adds extra URL regexes to skip (e.g. ["/author/","/tag/","/page/"]) to keep big crawls light. Grain: one row per url_key, latest crawl. Joins: url_key → GSC/inspection/backlinks.',
@@ -854,7 +787,6 @@ export function createServer() {
         const all = jobs.list();
         return { content: [{ type: 'text', text: `${all.length} jobs` }], structuredContent: { jobs: all } };
     });
-    // ── DataForSEO (cached 20 days, single-worker) ──────────────────────────
     server.registerTool('keyword_volume', {
         title: 'Keyword search volume (DataForSEO)',
         description: '[Paid: Keywords API, cheap, cached 20d | Use for: demand sizing] True monthly search volume + CPC + competition for keywords (DataForSEO KEYWORDS_DATA). Served from a 20-day cache; live calls are serialised. Default location: United States (2840).',
@@ -924,7 +856,6 @@ export function createServer() {
             articles.push(a);
         } };
         let cost = 0, cached = true, googleCount = 0, dfsCount = 0, googleError = null;
-        // Free Google News RSS.
         if (src === 'google' || src === 'both') {
             try {
                 const g = await fetchGoogleNews(keyword, { limit: n });
@@ -936,7 +867,6 @@ export function createServer() {
                 googleError = e instanceof Error ? e.message : 'failed';
             }
         }
-        // Paid DataForSEO Google News SERP (only when explicitly asked, or 'both' AND a key is set).
         if (src === 'dataforseo' || (src === 'both' && !!dfs)) {
             const r = await requireDfs(dfs).serpNews(keyword, location, languageCode, n);
             cost += r.cost;
@@ -945,8 +875,6 @@ export function createServer() {
             for (const a of r.articles)
                 add({ ...a, via: 'dataforseo' });
         }
-        // Top sources: which publishers are covering this topic, ranked by article count — the
-        // "who is talking about X" read. Powers "trending news + sources for X" in one call.
         const sourceCount = new Map();
         for (const a of articles) {
             const s = String(a.source ?? '').trim();
@@ -964,17 +892,22 @@ export function createServer() {
     });
     server.registerTool('topic_trend', {
         title: 'Google Trends interest over time (DataForSEO)',
-        description: '[Paid: Keywords API, cheap, cached 20d | Use for: seasonality + "is this rising or fading" — should we update now, when to publish] Google Trends relative interest (0–100) over time for up to 5 keywords (DataForSEO KEYWORDS_DATA / google_trends). Returns a per-keyword time series plus a rising/falling/flat read, so you can see direction and seasonality. timeRange: past_7_days | past_30_days | past_90_days | past_12_months (default) | past_5_years | 2004_present. type: web (default) | news | youtube | images. Default location: United States.',
+        description: '[Paid: Keywords API, cheap, cached 20d | Use for: seasonality + "is this rising or fading" — should we update now, when to publish; category monitoring — is a whole market growing] Google Trends relative interest (0–100) over time (DataForSEO KEYWORDS_DATA / google_trends). Give up to 5 keywords, a categoryCode (find it with trend_categories), or both: keywords alone search all categories; keywords + categoryCode narrow a term to one industry (e.g. "jaguar" in Autos); categoryCode alone returns interest in the WHOLE category, no keyword needed. related:true adds the top + rising related topics and queries (at most 1 keyword) — the category-only form surfaces what is breaking out across a market. Returns the time series plus a rising/falling/flat read. timeRange: past_7_days | past_30_days | past_90_days | past_12_months (default) | past_5_years | 2004_present. type: web (default) | news | youtube | images | froogle. Default location: United States.',
         inputSchema: {
-            keywords: z.array(z.string()).min(1).max(5),
+            keywords: z.array(z.string()).max(5).optional(),
+            categoryCode: z.number().int().min(1).optional(),
+            related: z.boolean().optional(),
             location: z.union([z.string(), z.number()]).optional(),
             languageCode: z.string().optional(),
             timeRange: z.enum(['past_7_days', 'past_30_days', 'past_90_days', 'past_12_months', 'past_5_years', '2004_present']).optional(),
             type: z.enum(['web', 'news', 'youtube', 'images', 'froogle']).optional(),
         },
-    }, async ({ keywords, location, languageCode, timeRange, type }) => {
+    }, async ({ keywords, categoryCode, related, location, languageCode, timeRange, type }) => {
         const client = requireDfs(dfs);
-        const r = await client.googleTrends(keywords, location, languageCode, { ...(timeRange ? { timeRange } : {}), ...(type ? { type } : {}) });
+        const r = await client.googleTrends(keywords ?? [], location, languageCode, {
+            ...(timeRange ? { timeRange } : {}), ...(type ? { type } : {}),
+            ...(categoryCode ? { categoryCode } : {}), ...(related ? { related } : {}),
+        });
         const summarise = (k) => {
             const vals = r.series.map(s => s.values[k]).filter((v) => typeof v === 'number');
             if (!vals.length)
@@ -986,9 +919,31 @@ export function createServer() {
             return `${k}: ${dir} (${Math.round(first)}→${Math.round(last)}, peak ${Math.max(...vals)})`;
         };
         const txt = r.keywords.map(summarise).join('\n');
+        const fmt = (xs, rising) => xs.slice(0, 10).map(x => `  ${'title' in x ? x.title : x.query} (${x.value == null ? '?' : rising ? `+${x.value}%` : x.value})`).join('\n') || '  none';
+        const relatedTxt = r.queries && r.topics
+            ? `\n\nRising queries:\n${fmt(r.queries.rising, true)}\nTop queries:\n${fmt(r.queries.top, false)}\nRising topics:\n${fmt(r.topics.rising, true)}`
+            : '';
+        const scope = r.categoryCode ? ` in category ${r.categoryCode}` : '';
+        return {
+            content: [{ type: 'text', text: `Trend${scope}, ${r.series.length} points${r.cached ? ' (cached)' : ` (live, $${r.cost.toFixed(4)})`}:\n${txt}${relatedTxt}` }],
+            structuredContent: { keywords: r.keywords, categoryCode: r.categoryCode, series: r.series, topics: r.topics, queries: r.queries, cached: r.cached, cost: r.cost },
+        };
+    });
+    server.registerTool('trend_categories', {
+        title: 'Google Trends category codes (DataForSEO)',
+        description: '[Free | Use before topic_trend with categoryCode] Search the Google Trends category tree (~1,400 categories) by name and get the codes topic_trend takes, with each match\'s parent so you can pick the right level. Omit query to list the top-level categories.',
+        inputSchema: { query: z.string().optional(), limit: z.number().int().min(1).max(100).optional() },
+    }, async ({ query, limit }) => {
+        const client = requireDfs(dfs);
+        const cats = await client.googleTrendsCategories();
+        const byCode = new Map(cats.map(c => [c.code, c]));
+        const q = query?.trim().toLowerCase();
+        const hits = (q ? cats.filter(c => c.name.toLowerCase().includes(q)) : cats.filter(c => c.parent === 0)).slice(0, limit ?? 25);
+        const withParent = hits.map(c => ({ ...c, parentName: c.parent ? byCode.get(c.parent)?.name ?? null : null }));
+        const lines = withParent.map(c => `${c.code}  ${c.parentName ? `${c.parentName} > ` : ''}${c.name}`).join('\n');
         return {
-            content: [{ type: 'text', text: `Trend, ${r.series.length} points${r.cached ? ' (cached)' : ` (live, $${r.cost.toFixed(4)})`}:\n${txt}` }],
-            structuredContent: { keywords: r.keywords, series: r.series, cached: r.cached, cost: r.cost },
+            content: [{ type: 'text', text: `${withParent.length} of ${cats.length} categories${q ? ` matching "${query}"` : ' (top level)'}:\n${lines || 'none'}\n\nPass a code to topic_trend as categoryCode.` }],
+            structuredContent: { categories: withParent, total: cats.length },
         };
     });
     server.registerTool('suggest_pages', {
@@ -1010,8 +965,6 @@ export function createServer() {
             db.close();
         }
     });
-    // content_opportunities — the content marketer's report: everything the stored data
-    // says about what to WRITE, REFRESH and REWRITE, in one free composition.
     server.registerTool('content_opportunities', {
         title: 'Content opportunity report (write / refresh / rewrite)',
         description: 'The content marketer\'s report, composed entirely from stored data - NO paid calls. Four sections: WRITE NEXT (new pages proposed from queries you already earn impressions for but have no winning page - suggest_pages), REFRESH NOW (pages that lost 20%+ of their clicks vs the prior period - content decay), REWRITE SNIPPETS (page-1 rankings earning far below expected CTR - title/meta rewrites, the fastest wins), and STRENGTHEN (keyword clusters where you rank 4-20 - one push from the money positions). Every line traces to real Search Console data. Chain into draft_content for a brief, or keyword_volume to size a cluster against the market.',
@@ -1063,7 +1016,6 @@ 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, plus a small refundable surcharge for loading async AI Overviews), 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, depth 20 organic), 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, competitive-gap, or page-cannot-rank (the crawl says the URL is noindex/canonicalised away, so its GSC history is legacy and the SERP read belongs to another page). Honesty rules baked in: every GSC figure carries its 28-day window; organicRank:null means "absent from the top 20 ORGANIC results", never a position; and an AI Overview whose citations could not be resolved reports aioCitesUs:null (UNKNOWN) rather than "not cited". To-dos are prioritised by OPPORTUNITY (impressions x the CTR gap between where you rank and a realistic target, damped by the verdict), not by raw impressions, and cannibalisation is counted across the whole query cluster. Set scrapeCompetitors:true to also pull the top competitors as content, routed by host: YouTube/video → Supadata transcript (SUPADATA_API_KEY), Reddit → its .json, other pages → Firecrawl (FIRECRAWL_API_KEY) with a free HTTP fallback; competitorLimit (default 5) caps how many are fetched and everything above the cap is listed as skipped. 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. **Async job:** returns a jobId immediately - poll check_sync_status; the finished job carries the per-page verdicts, to-dos and a summary. (Each page is persisted to the ledger as it completes, so recon_todos shows results even mid-run.)',
@@ -1078,10 +1030,8 @@ export function createServer() {
             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, competitorLimit, crawlAs }) => {
-        const client = requireDfs(dfs); // fail fast if no DataForSEO creds, before starting the job
+        const client = requireDfs(dfs);
         const count = urls?.length ?? limit ?? 5;
-        // Async job: N live page-fetches + N serialised SERP calls exceed the ~60s MCP ceiling
-        // past a handful of pages, so return a jobId and poll (like refresh_property).
         const jobId = jobs.start('recon', async (update, signal) => {
             const db = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
             try {
@@ -1092,8 +1042,6 @@ export function createServer() {
                 const ownDomain = dfsHost(siteUrl);
                 const hostForm = hostFormForProperty(siteUrl) ?? 'asis';
                 const SERP_DEPTH = 20;
-                // Every GSC number below is this window and only this window. Undeclared, a 28-day figure
-                // read against an all-time baseline looks exactly like a decline.
                 const windowStart = db.db.prepare(`SELECT date(?, '-27 days') d`).get(fresh.effectiveMax);
                 const gscWindow = { start: windowStart.d, end: fresh.effectiveMax, days: 28, metric: 'Search Console, last 28 days of synced data (not all-time)' };
                 let targets;
@@ -1101,7 +1049,7 @@ export function createServer() {
                     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
+                        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)
@@ -1124,12 +1072,10 @@ export function createServer() {
                     try {
                         own = await fetchOwnPage(t.urlKey, hostForm === 'asis' ? 'asis' : hostForm);
                     }
-                    catch { /* page unreachable — classify on SERP alone */ }
+                    catch { }
                     const serpResp = await client.serpOrganic(t.query, location, 'en', SERP_DEPTH, { loadAsyncAiOverview: true });
                     cost += serpResp.cost;
                     const serp = parseSerpForRecon(serpResp, ownDomain, SERP_DEPTH);
-                    // The crawl row overrides the SERP/GSC read: GSC keeps reporting impressions for URLs
-                    // that have since been canonicalised away or set noindex.
                     const state = pageState(db.db, t.urlKey);
                     const serpVerdict = reconVerdict(serp);
                     const verdict = crawlRealityOverride(serpVerdict, state) ?? serpVerdict;
@@ -1148,10 +1094,6 @@ export function createServer() {
                     let competitorContent = undefined;
                     let competitorFetch = undefined;
                     if (scrapeCompetitors && (firecrawl || supadata)) {
-                        // Build a routed candidate set: organic-above + AI-Overview references + one ranking
-                        // video, deduped, our own domain removed. Each URL routes by HOST (YouTube→supadata,
-                        // Reddit→.json, else→firecrawl). What we don't fetch is REPORTED, not silently dropped
-                        // — an undeclared cap of 3 is what made this look like it returned nothing.
                         const seen = new Set();
                         const candidates = [];
                         const add = (url, from) => {
@@ -1164,8 +1106,6 @@ export function createServer() {
                         serp.aioReferences.slice(0, 6).forEach(r => add(r.url, 'aio-reference'));
                         serp.videoItems.slice(0, 2).forEach(v => add(v.url, 'video-pack'));
                         const lim = competitorLimit ?? 5;
-                        // Organic-above first (the editorial pages actually worth diffing), but keep one slot
-                        // for a ranking video — video is usually what wins these SERPs.
                         const video = candidates.find(c => c.route === 'video');
                         const rest = candidates.filter(c => c !== video);
                         const reserve = video && lim >= 3 ? 1 : 0;
@@ -1235,12 +1175,6 @@ export function createServer() {
                         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);
-                // The poll (check_sync_status) injects this result into the model's context, which the
-                // host caps (~25k tokens). The full per-page detail (heading lists, competitor URL arrays,
-                // full to-do objects, cannibalisation clusters) is already persisted to the ledger and read
-                // back via recon_todos, so the job result returns the readable `summary` plus a SLIM per-page
-                // view — verdict, ranks, opportunity — and keeps only competitorContent (the scraped research
-                // payload, which lives nowhere else). This keeps a 10-page poll well under the cap.
                 const slimTargets = results.map(r => ({
                     urlKey: r.urlKey, query: r.query, window: r.window,
                     impressions: r.impressions, gscPosition: r.gscPosition, priorPosition: r.priorPosition, slipped: r.slipped,
@@ -1262,8 +1196,6 @@ export function createServer() {
             structuredContent: { jobId, status: 'running', siteUrl },
         };
     });
-    // 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.',
@@ -1283,11 +1215,7 @@ export function createServer() {
         try {
             const key = urlKey(rawUrl, { hostForm: hostFormForProperty(siteUrl) ?? 'asis' });
             const page = db.db.prepare(`SELECT query, organic_rank, aio_cites_us, gsc_position, gsc_impressions, verdict FROM recon_page WHERE url_key=?`).get(key);
-            // aio_cites_us is NULL when the AI Overview never resolved — keep that as unknown rather
-            // than coercing it to false, or the outcome diff reads "no → yes" off a missing fetch.
             const baseline = page ? { organicRank: page.organic_rank, aioCitesUs: page.aio_cites_us == null ? null : !!page.aio_cites_us, gscPosition: page.gsc_position, at: new Date().toISOString().slice(0, 10) } : {};
-            // Default priority to the PAGE's opportunity so research to-dos sort on the same scale as
-            // the deterministic ones (a default of 0 buried every judgement finding at the bottom).
             const basis = page ? opportunityBasis(page.gsc_impressions ?? 0, page.organic_rank, page.gsc_position ?? 20, page.verdict) : null;
             const fallbackPriority = basis ? Math.max(1, Math.round(basis.opportunityClicks * basis.verdictFactor)) : 0;
             const drafts = todos.map(t => ({ action: t.action, type: t.type ?? 'content-gap', rationale: t.rationale ?? '', evidence: t.evidence ?? {}, priority: t.priority ?? fallbackPriority }));
@@ -1298,8 +1226,6 @@ export function createServer() {
             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.',
@@ -1325,7 +1251,6 @@ export function createServer() {
                 let outcome = row.outcome;
                 let outcomeNote = '';
                 if (status === 'shipped' && remeasure && dfs) {
-                    // Same depth + async-AIO handling as recon_targets, so before/after are comparable.
                     const serpResp = await dfs.serpOrganic(row.query, location, 'en', 20, { loadAsyncAiOverview: true });
                     const serp = parseSerpForRecon(serpResp, dfsHost(siteUrl), 20);
                     const cited = (v) => (v == null ? 'unknown' : v ? 'yes' : 'no');
@@ -1349,7 +1274,7 @@ export function createServer() {
                 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
+            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: [] } };
@@ -1371,8 +1296,6 @@ export function createServer() {
             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', {
         title: 'Cluster a keyword list into topics with own/weak/absent verdicts',
         description: 'Demand-first keyword clustering from stored data - NO paid calls. Give it a keyword list (or omit keywords to use your top 500 GSC queries) and it clusters them by the page Google ALREADY answers them with (two keywords that rank via the same URL belong together - the strongest clustering signal, free from your own GSC data), then groups non-ranking keywords lexically. Each cluster gets a deterministic verdict: OWN (best position <=3), WEAK (4-20), ABSENT (no ranking page), plus the ranking URL, summed 90-day impressions and clicks. The keyword-research workhorse: paste a client keyword list, get the topic map and where you stand. Chain with keyword_volume for market volumes on the interesting clusters, or draft_content for the absent ones.',
@@ -1421,7 +1344,7 @@ export function createServer() {
         if (siteUrl) {
             const db = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
             try {
-                const up = db.db.prepare(`INSERT INTO keyword_intent (keyword,intent,probability,fetched_at) VALUES (?,?,?,datetime('now'))
+                const up = db.db.prepare(`INSERT INTO keyword_intent (keyword,intent,probability,fetched_at) VALUES (?,?,?,datetime('now'))
             ON CONFLICT(keyword) DO UPDATE SET intent=excluded.intent, probability=excluded.probability, fetched_at=datetime('now')`);
                 db.db.transaction(() => { for (const it of items)
                     if (it.keyword && it.intent) {
@@ -1475,9 +1398,9 @@ export function createServer() {
         if (siteUrl && cats.performance) {
             const db = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
             try {
-                db.db.prepare(`INSERT INTO page_cwv (url_key,url,for_mobile,performance,lcp_ms,cls,tbt_ms,fetched_at)
-            VALUES (?,?,?,?,?,?,?,datetime('now'))
-            ON CONFLICT(url_key) DO UPDATE SET url=excluded.url, for_mobile=excluded.for_mobile, performance=excluded.performance,
+                db.db.prepare(`INSERT INTO page_cwv (url_key,url,for_mobile,performance,lcp_ms,cls,tbt_ms,fetched_at)
+            VALUES (?,?,?,?,?,?,?,datetime('now'))
+            ON CONFLICT(url_key) DO UPDATE SET url=excluded.url, for_mobile=excluded.for_mobile, performance=excluded.performance,
               lcp_ms=excluded.lcp_ms, cls=excluded.cls, tbt_ms=excluded.tbt_ms, fetched_at=datetime('now')`)
                     .run(urlKey(url, { hostForm: hostFormForProperty(siteUrl) }), url, mobile ? 1 : 0, out.scores.performance, numeric('largest-contentful-paint'), numeric('cumulative-layout-shift'), numeric('total-blocking-time'));
                 persisted = true;
@@ -1501,7 +1424,7 @@ export function createServer() {
         const cleaned = target.replace(/^sc-domain:/, '').replace(/^https?:\/\//, '').replace(/^www\./, '').replace(/\/+$/, '');
         const r = await client.competitorsDomain(cleaned, location, languageCode, limit ?? 20);
         const items = (r.tasks[0]?.result?.[0]?.items ?? [])
-            .filter((it) => it.domain && it.domain.replace(/^www\./, '') !== cleaned) // drop the target itself
+            .filter((it) => it.domain && it.domain.replace(/^www\./, '') !== cleaned)
             .map((it) => ({
             domain: it.domain,
             intersections: it.intersections ?? null,
@@ -1529,7 +1452,7 @@ export function createServer() {
         const r = await client.pageIntersection(competitorUrls, excludePages ?? [], location, languageCode, limit ?? 100);
         const items = (r.tasks[0]?.result?.[0]?.items ?? [])
             .map((it) => {
-            const kd = it.keyword_data ?? {}; // actual shape: item.keyword_data.{keyword,keyword_info}
+            const kd = it.keyword_data ?? {};
             return {
                 keyword: kd.keyword ?? null,
                 searchVolume: kd.keyword_info?.search_volume ?? null,
@@ -1540,16 +1463,13 @@ export function createServer() {
                 })),
             };
         })
-            .sort((a, b) => (b.searchVolume ?? 0) - (a.searchVolume ?? 0)); // order_by unsupported on this endpoint
+            .sort((a, b) => (b.searchVolume ?? 0) - (a.searchVolume ?? 0));
         return {
             content: [{ type: 'text', text: `${items.length} gap keywords${r.cached ? ' (cached)' : ` (live, $${r.cost.toFixed(4)})`}` }],
             structuredContent: { gaps: items, cached: r.cached, cost: r.cost },
         };
     });
-    // Strip any scheme/sc-domain:/path down to a bare host for Labs domain targets.
-    // Always strips leading www. — Labs treats www.example.com as a subdomain, not the domain.
     const dfsHost = (t) => t.replace(/^sc-domain:/, '').replace(/^https?:\/\//, '').replace(/\/.*$/, '').replace(/^www\./, '').trim();
-    // Cap a markdown table well under the ~40k model-facing ceiling: keep whole rows, note the rest.
     const capMdRows = (header, rows, footer = '', maxChars = 30000) => {
         let out = header;
         let used = 0;
@@ -1581,7 +1501,6 @@ export function createServer() {
         const r = await client.historicalRankOverview(cleaned, location, 'en', languageName);
         const items = r.tasks[0]?.result?.[0]?.items ?? [];
         const n = (v) => Number(v) || 0;
-        // Guard year/month — a malformed item would emit an "undefined-NaN" period row.
         const series = items
             .filter((it) => Number.isInteger(it?.year) && Number.isInteger(it?.month))
             .map((it) => {
@@ -1641,7 +1560,7 @@ export function createServer() {
             .map((it) => {
             const page = it.page_address ?? it.relative_url ?? null;
             if (!page)
-                return null; // skip malformed rows
+                return null;
             const o = it.metrics?.organic ?? {};
             const top3 = n(o.pos_1) + n(o.pos_2_3);
             return {
@@ -1698,14 +1617,9 @@ export function createServer() {
         const folderPath = mode === 'folder'
             ? (folder.trim().startsWith('/') ? folder.trim() : '/' + folder.trim())
             : null;
-        // aioOnly: only rows where the target's ranked element is an AI Overview citation —
-        // expressed as a serp_item.type filter (item_types is invalid on this Labs endpoint).
         const clauses = [];
         if (folderPath)
             clauses.push(['ranked_serp_element.serp_item.relative_url', 'like', `${folderPath}%`]);
-        // Exposure, not citation: Labs ranked_keywords carries no citation fields (verified via
-        // available_filters) — this filters to keywords whose SERP CONTAINS an AI Overview.
-        // Per-keyword citation checking (are WE a reference?) is the SERP-advanced recipe.
         if (aioOnly)
             clauses.push(['keyword_data.serp_info.serp_item_types', 'has', 'ai_overview']);
         const filters = clauses.length === 0 ? undefined : clauses.length === 1 ? clauses : [clauses[0], 'and', clauses[1]];
@@ -1717,7 +1631,7 @@ export function createServer() {
             const kd = it.keyword_data ?? {};
             const serp = it.ranked_serp_element?.serp_item ?? {};
             if (!kd.keyword)
-                return null; // skip malformed rows
+                return null;
             const serpFeatures = Array.isArray(kd.serp_info?.serp_item_types) ? kd.serp_info.serp_item_types : null;
             return {
                 keyword: kd.keyword,
@@ -1725,7 +1639,6 @@ export function createServer() {
                 searchVolume: kd.keyword_info?.search_volume ?? null,
                 etv: serp.etv != null ? Math.round(Number(serp.etv) * 100) / 100 : null,
                 url: serp.relative_url ?? serp.url ?? null,
-                // Fields we already pay for but previously dropped (plan/data-utilisation.md Part 2 §4):
                 keywordDifficulty: kd.keyword_properties?.keyword_difficulty ?? null,
                 intent: kd.search_intent_info?.main_intent ?? null,
                 serpFeatures,
@@ -1744,7 +1657,6 @@ export function createServer() {
         }
         const totalCount = Number(result.total_count) || kws.length;
         const sumEtv = kws.reduce((s, k) => s + (k.etv ?? 0), 0);
-        // Optional columns — only where the response actually carries the field (older cache entries won't).
         const hasKd = kws.some(k => k.keywordDifficulty != null);
         const hasIntent = kws.some(k => k.intent != null);
         const hasFeatures = kws.some(k => (k.serpFeatures && k.serpFeatures.length) || k.isFeaturedSnippet);
@@ -1767,9 +1679,6 @@ export function createServer() {
             structuredContent: { target: dfsTarget, scope: mode, aioOnly: aioOnly ?? false, totalCount, rowsTotal: kws.length, keywords: kws.slice(0, 100), cached: r.cached, cost: r.cost },
         };
     });
-    // serp_features — the SERP-feature footprint: "how much of my market do AI Overviews,
-    // snippets and other features sit on, and do I already rank page 1 there?" One cached
-    // Labs pull, volume-weighted; persisted so the dashboard can chart it.
     server.registerTool('serp_features', {
         title: 'SERP-feature footprint (AI Overviews, snippets, PAA)',
         description: '[Paid: Labs, ONE cached call | Use for: AI-Overview / zero-click exposure with real numbers] How much of your keyword universe carries each SERP feature - AI Overviews, featured snippets, People Also Ask, shopping, video - weighted by search volume, and how much of that volume you already rank page 1 for. ONE DataForSEO Labs ranked_keywords pull (top-volume sample, cached 20 days, never per-keyword SERP loops). Answers "how exposed are we to AI Overviews / zero-click?" with real numbers. Deterministic: feature PRESENCE (from the Labs index). Judgement proxy: page-1 rank stands in for feature ownership - true ownership needs per-keyword SERP calls (see ranked_keywords aioOnly + the cookbook). Persists to the property DB so the dashboard charts it.',
@@ -1814,8 +1723,6 @@ export function createServer() {
             structuredContent: fp,
         };
     });
-    // market_sizing — Market Sizing and Prioritisation: the organic market read that opens
-    // an engagement. Top-down Labs pulls only (client + <=4 rivals), cached, ~$0.65 worst case.
     server.registerTool('market_sizing', {
         title: 'Market Sizing and Prioritisation (share of voice vs competitors)',
         description: '[Paid: Labs, one cached call per domain (<=5) | Use for: sizing the organic market and who owns it] Build the organic market map: your domain plus up to 4 named competitors, ONE cached Labs ranked_keywords pull each, unioned into a keyword universe. Returns total monthly demand (deduplicated search volume), each domain\'s share of voice (ETV share) overall and per topic cluster, and the leader per cluster - the "here is the market, here is who owns it, here is where to attack" table that opens an engagement. Deterministic: the competitor set and ranked keywords (Labs index). Judgement: ETV is DataForSEO\'s CTR-curve traffic estimate - the SoV percentages inherit that. Persists to the property DB for the dashboard chart. Get the competitor set from competitors_domain first if unsure.',
@@ -1833,7 +1740,7 @@ export function createServer() {
         const inputs = [];
         let cost = 0;
         let cachedAll = true;
-        for (const domain of domains) { // sequential - the client serialises anyway
+        for (const domain of domains) {
             const r = await client.rankedKeywords(domain, location, languageCode ?? 'en', limitPerDomain ?? 1000, 'keyword_data.keyword_info.search_volume,desc');
             cost += r.cost;
             cachedAll = cachedAll && r.cached;
@@ -1899,8 +1806,6 @@ export function createServer() {
             const ourHost = dfsHost(siteUrl);
             let totalCost = 0, liveCalls = 0, cachedCalls = 0;
             const tally = (r) => { totalCost += r.cost; r.cached ? cachedCalls++ : liveCalls++; };
-            // Competitors: explicit (≤3) or derived top-2 by keyword overlap. Total Labs
-            // budget stays ≤4 calls: at most 1 discovery + at most 3 footprint pulls.
             let comps = [...new Set((competitors ?? []).map(dfsHost).filter(c => c && c !== ourHost))].slice(0, 3);
             let derived = false;
             if (!comps.length) {
@@ -1919,7 +1824,6 @@ export function createServer() {
                     };
                 }
             }
-            // One ranked_keywords pull per competitor (top 1000 rows by ETV — their money keywords).
             const rows = [];
             const perCompetitor = {};
             for (const c of comps) {
@@ -1968,8 +1872,6 @@ export function createServer() {
                 `${res.competitorKeywords} distinct competitor keywords → ${res.afterSubtraction} survive subtraction of your footprint (${fmtVol(res.ourQueryCount)} GSC queries + page titles/H1s) → top ${res.clusters.length} topic clusters by volume × competitor coverage.\n\n` +
                 sections.join('\n\n') +
                 `\n\n_${costLine} Competitor rows: ${comps.map(c => `${c} ${perCompetitor[c] ?? 0}`).join(', ')}._`;
-            // structuredContent: keyword lists capped at 10 per cluster with explicit totals
-            // (host ~60k model-facing ceiling) — the counts always state the true size.
             const scClusters = res.clusters.map(c => ({
                 ...c,
                 keywords: c.keywords.slice(0, 10),
@@ -1989,16 +1891,12 @@ export function createServer() {
             db.close();
         }
     });
-    // ── Dashboard (MCP App UI — houtini design + ECharts) ───────────────────
     registerAppTool(server, 'get_dashboard', {
         title: 'SEO dashboard',
         description: 'Interactive dashboard for a property: summary metrics, rank & clicks over time, and top-keyword performance (click a keyword for related terms). Needs synced GSC data — run refresh_property first.',
         inputSchema: { siteUrl: z.string() },
         _meta: { ui: { resourceUri: DASHBOARD_URI } },
     }, async ({ siteUrl }) => {
-        // Return only a TINY model-facing result + the siteUrl; the widget fetches the full
-        // (large) dataset itself via the app-only get_dashboard_data tool, which keeps the
-        // big payload OUT of the model's context/token limit (per the MCP Apps large-data pattern).
         const data = getDashboardData(dataDir(), siteUrl);
         if (data.empty) {
             return { content: [{ type: 'text', text: `No synced data for ${siteUrl} yet — run refresh_property.` }], structuredContent: { siteUrl, empty: true } };
@@ -2008,9 +1906,6 @@ export function createServer() {
             `${data.findings ? `, ${data.findings.total} audit findings` : ''}. Interactive charts + findings render in the widget.` + browserLink(siteUrl);
         return { content: [{ type: 'text', text: summary }], structuredContent: { siteUrl } };
     });
-    // App-only data tool: the dashboard widget calls this via app.callServerTool to fetch its
-    // full dataset. visibility:['app'] hides it from the model; results route to the iframe,
-    // bypassing the model token cap that a large model-facing result would hit.
     registerAppTool(server, 'get_dashboard_data', {
         title: 'Dashboard data (internal)',
         description: 'Full dashboard dataset for the UI widget. App-only — not for direct use.',
@@ -2020,9 +1915,6 @@ export function createServer() {
         const data = { ...getDashboardData(dataDir(), siteUrl), apiKeys: apiKeysStatus() };
         return { content: [{ type: 'text', text: 'ok' }], structuredContent: data };
     });
-    // export_report — the dependable deliverable: a self-contained interactive dashboard
-    // HTML (data inlined) the user opens in any browser / emails to a client. Works
-    // regardless of whether the host renders MCP-App widgets inline.
     server.registerTool('export_report', {
         title: 'Export a shareable dashboard report (HTML)',
         description: 'Write a self-contained, interactive dashboard HTML for a property (all data + charts inlined) to the reports folder, and return the file path. Open it in any browser or send it to a client — no server, no MCP-App host support needed. Run refresh_property (+ run_audit for findings) first.',
@@ -2033,10 +1925,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: `No synced data for ${siteUrl} — run refresh_property first.` }], structuredContent: { error: 'empty', siteUrl } };
         }
         const tpl = readFileSync(path.join(__dirname, 'src', 'ui', 'dashboard.html'), 'utf8');
-        const json = JSON.stringify(data).replace(/</g, '\\u003c'); // prevent </script> breakout
+        const json = JSON.stringify(data).replace(/</g, '\\u003c');
         const inject = `<script>window.__DASH_FIXTURE__=${json};window.__DASH_THEME__=${JSON.stringify(theme ?? 'light')};</script>`;
-        // Replacement FUNCTION, not string — crawl data containing $& / $' would otherwise
-        // be interpreted as String.replace substitution patterns and corrupt the report.
         const html = tpl.replace(/<head([^>]*)>/i, (_m, attrs) => `<head${attrs}>${inject}`);
         const dir = path.join(dataDir(), 'reports');
         mkdirSync(dir, { recursive: true });
@@ -2047,8 +1937,6 @@ export function createServer() {
             structuredContent: { path: file, siteUrl, findings: data.findings?.total ?? 0, bytes: html.length },
         };
     });
-    // serve_dashboard — the local webserver delivery surface: the full dashboard in a real
-    // browser tab (live data, property switcher, native downloads), no MCP-App host needed.
     server.registerTool('serve_dashboard', {
         title: 'Serve the dashboard on a local webserver',
         description: 'Start a localhost-only webserver and return a URL that opens the full interactive dashboard in your browser — live data straight from the local database (always current, unlike export_report snapshots), a property switcher, working CSV downloads, and no host widget limits. The server stays up while the MCP server runs; call again with stop=true to shut it down. Localhost only — nothing is exposed to the network.',
@@ -2072,8 +1960,6 @@ export function createServer() {
             structuredContent: { url: open, base: url },
         };
     });
-    // pull_backlinks — on-demand backlink profile (DataForSEO, paid + 20-day cached). Powers
-    // backlinks-to-404 (the big quick win), top-linked pages, and true-orphan detection.
     server.registerTool('pull_backlinks', {
         title: 'Pull backlink profile (DataForSEO)',
         description: '[Paid: Backlinks subscription (separate - 40204 = not activated), cached 20d | Use for: authority + dead-backlink recovery] Fetch the property’s backlink profile (overall summary — total backlinks, referring domains, Domain Rank, broken backlinks/pages, nofollow share — plus per-page backlink/referring-domain counts) into page_backlinks, and resolve each backlinked page’s live HTTP status so run_audit can flag external backlinks pointing to dead (4xx/5xx) pages. Paid DataForSEO call, 20-day cached, on-demand only. Async job — poll check_sync_status. Grain: one row per backlinked URL. Joins: url_key → pages/GSC; domain → Labs tools.',
@@ -2086,9 +1972,6 @@ export function createServer() {
             structuredContent: { jobId, status: 'running', siteUrl },
         };
     });
-    // link_intersect — "what links do our competitors have that we don't?". One DataForSEO
-    // backlinks/domain_intersection call (paid, ~$0.024, 20-day cached), aggregated + prioritised
-    // client-side. Default sort = the link-builder's: followed links first, then domain trust.
     server.registerTool('link_intersect', {
         title: 'Link intersect — links your competitors have that you don’t (DataForSEO + Majestic)',
         description: '[Paid: Backlinks subscription (separate - 40204 = not activated), one cached call ~$0.024 | Use for: prospect list for link outreach] Answers "what links do our competitors have that we don’t?" - and for a SINGLE company, "what links does company X have that we don’t?" (pass competitors:["companyx.com"]). One DataForSEO domain_intersection call over the target set (excluding your domain), aggregated per prospect domain: how many of the targets it links to, its DataForSEO domain trust (rank 0-1000), worst spam score, whether the link is followed, the anchor/link-type mix. Default sort is the link-builder’s view - FOLLOWED links first, then domain trust - with spam filtered out. When MAJESTIC_API_KEY is set, prospects are enriched with Majestic Trust Flow + Topical Trust Flow and RE-SORTED by Trust Flow (the directory-killer: a DataForSEO rank-227 domain is often Trust Flow 0). Results persist to link_prospects. Pass targets explicitly (max 20) or let it derive the top few via competitors_domain. Grain: one row per prospect domain. Join: domain.',
@@ -2107,8 +1990,6 @@ export function createServer() {
     }, async ({ siteUrl, competitors, location, poolLimit, minIntersections, maxSpamScore, dofollowOnly, topN, sort, enrichLimit }) => {
         const li = requireDfs(linkIntersect);
         const ownHost = dfsHost(siteUrl);
-        // Prior-run awareness: if this property already has link_prospects, frame the run as an
-        // update (the previous set ages as competitors keep earning links). Read-only, cheap.
         let priorNote = '';
         {
             const d = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
@@ -2119,12 +2000,11 @@ export function createServer() {
                     priorNote = ` _(updating a prior intersect of ${prior.n} prospects from ${prior.t.slice(0, 10)}, ${ageDays}d ago)_`;
                 }
             }
-            catch { /* pre-link_intersect DB */ }
+            catch { }
             finally {
                 d.close();
             }
         }
-        // Competitors: explicit (deduped, minus self) or derived top few by keyword overlap.
         let comps = [...new Set((competitors ?? []).map(dfsHost).filter(c => c && c !== ownHost))];
         let derived = false;
         let deriveCost = 0;
@@ -2161,7 +2041,6 @@ export function createServer() {
             ...(enrichLimit != null ? { enrichLimit } : {}),
         }, majestic);
         const enriched = result.majesticEnriched > 0;
-        // With Majestic: show Trust Flow (0-100) + the domain's top topic. Without: DataForSEO domain rank.
         const trustHead = enriched ? 'Trust Flow' : 'Domain trust';
         const rows = result.prospects.map(p => {
             const trust = enriched ? (p.trustFlow ?? '–') : (p.domainTrust ?? '–');
@@ -2193,7 +2072,6 @@ export function createServer() {
             structuredContent: { jobId, status: 'running', siteUrl },
         };
     });
-    // ── Static reference resources (same content the tools return — one source of truth) ──
     server.registerResource('checks-reference', 'seo-audit://checks-reference', {
         title: 'Check registry reference',
         description: 'The full audit check catalogue (the list_checks data) rendered as markdown: every check with category, severity, labels, certainty, fix type and its one-line fix.',