seo-intel 1.5.45 → 1.5.50

package/mcp/server.js

@@ -32,8 +32,17 @@ import { readProgress } from '../lib/progress.js';
 import { getProblems, getProblemCounts, markProblemStatus, getActiveStatusMap, PROBLEM_CATEGORIES, PROBLEM_STATUSES } from '../lib/problems.js';
 
 import { runAeoAnalysis, persistAeoScores, upsertCitabilityInsights } from '../analyses/aeo/index.js';
+import { fetchAiAccessForDomains } from '../analyses/aeo/ai-access.js';
+import { runTechnicalAudit } from '../analysis/technical-audit.js';
+// NOTE: model-suggestion helpers (setup/models.js, setup/checks.js) are loaded
+// lazily inside the suggest_models handler, NOT imported at top level — to keep
+// the setup subtree (and anything it transitively pulls) off the MCP boot path.
 import { prescore, extractDraftTopic } from '../analyses/blog-draft/prescorer.js';
-import { lightCrawl } from '../crawler/light.js';
+// NOTE: lightCrawl (crawler/light.js) is loaded lazily inside the crawl_site
+// handler, NOT imported at top level. Its chain pulls turndown
+// (light.js → html-extract.js → sanitize.js → turndown), and a slow/hanging
+// turndown import would otherwise block the entire MCP stdio boot — no tools,
+// no banner, no handshake. Keep the crawler subtree off the boot path.
 import { runContentLoop } from '../analyses/loop/orchestrator.js';
 import { gatherBlogDraftContext, buildBlogDraftPrompt } from '../analyses/blog-draft/index.js';
 
@@ -383,6 +392,9 @@ server.registerTool(
   },
   async ({ url, max_pages, include_citability, same_origin }) => {
     try {
+      // Lazy-load the crawler subtree (pulls turndown) only when crawl_site is
+      // actually invoked — keeps it off the MCP boot path. See note at top.
+      const { lightCrawl } = await import('../crawler/light.js');
       const r = await lightCrawl(url, {
         maxPages: max_pages ?? 10,
         includeCitability: include_citability ?? false,
@@ -502,21 +514,31 @@ server.registerTool(
 server.registerTool(
   'run_citability_audit',
   {
-    description: 'Run AEO citability scoring across all crawled pages (6 signals: entity authority, structured claims, answer density, Q&A proximity, freshness, schema coverage). Persists scores to citability_scores and upserts citability_gap insights into the ledger. Pure function — fast, no LLM calls. Free tier — analysis of your own site is free.',
+    description: 'Run AEO citability scoring across all crawled pages (7 signals: entity authority, structured claims, answer density, Q&A proximity, freshness, schema coverage, and AI-crawler access). Also checks robots.txt per target domain — if it blocks answer-engine crawlers (ClaudeBot / GPTBot / PerplexityBot / Google-Extended), affected pages are gated low because AI assistants literally cannot read them. Persists scores to citability_scores and upserts citability_gap insights into the ledger. Free tier — analysis of your own site is free.',
     inputSchema: {
       project: z.string(),
       include_competitors: z.boolean().optional().describe('Score competitor pages too (default true)'),
+      check_ai_access: z.boolean().optional().describe('Fetch robots.txt per target domain to score AI-crawler access (default true). The only network call this tool makes; set false to keep it fully offline.'),
     },
   },
-  async ({ project, include_competitors = true }) => {
+  async ({ project, include_competitors = true, check_ai_access = true }) => {
     if (!loadProjectConfig(project)) {
       return { content: [{ type: 'text', text: `Project "${project}" not found. Use list_projects to discover.` }], isError: true };
     }
     try {
       const db = getDb();
-      const results = runAeoAnalysis(db, project, { includeCompetitors: include_competitors, log: () => {} });
+      let aiAccessByDomain = null;
+      if (check_ai_access) {
+        const targetDomains = db
+          .prepare("SELECT DISTINCT domain FROM domains WHERE project = ? AND role IN ('target','owned')")
+          .all(project).map(r => r.domain);
+        if (targetDomains.length) {
+          try { aiAccessByDomain = await fetchAiAccessForDomains(targetDomains); } catch { /* best-effort */ }
+        }
+      }
+      const results = runAeoAnalysis(db, project, { includeCompetitors: include_competitors, aiAccessByDomain, log: () => {} });
       persistAeoScores(db, results);
-      upsertCitabilityInsights(db, project, results.target);
+      upsertCitabilityInsights(db, project, results.target, results.summary.aiAccess);
       const competitorPageCount = [...results.competitors.values()].reduce((a, list) => a + list.length, 0);
       const avgTargetScore = results.target.length
         ? Math.round(results.target.reduce((s, p) => s + p.score, 0) / results.target.length)
@@ -532,6 +554,8 @@ server.registerTool(
         target_pages_scored: results.target.length,
         competitor_pages_scored: competitorPageCount,
         avg_target_score: avgTargetScore,
+        ai_access: results.summary.aiAccess,
+        ai_access_gated_pages: results.summary.gatedPages,
         low_score_target_pages: lowScorePages,
         hint: 'Scores persisted to DB. Call get_intel(project, for=audit) to see the full citability matrix + insights ledger.',
       };
@@ -545,6 +569,226 @@ server.registerTool(
   }
 );
 
+// ── Tool: tech_audit (FREE) ───────────────────────────────────────────────
+server.registerTool(
+  'tech_audit',
+  {
+    description: [
+      'Run the technical SEO audit on already-crawled data for a project — titles, meta descriptions, noindex/robots conflicts, redirect chains, canonical issues, and sitemap-vs-crawl diff. Returns severity-sorted findings (error / warn / info) with the affected URL and a description each.',
+      '',
+      'Reads from the local DB (no re-crawl). Optionally runs live HEAD checks against sitemap URLs (network) to catch broken/redirected entries. Free tier — covers your own target/owned domains.',
+    ].join('\n'),
+    inputSchema: {
+      project: z.string().describe('Project slug. Use list_projects to discover.'),
+      domain: z.string().optional().describe('Audit a single domain. Omit to audit all target/owned domains in the project.'),
+      sitemap_head: z.boolean().optional().describe('Also run live HEAD checks against sitemap URLs (network-heavy). Default false.'),
+      limit: z.number().int().positive().max(200).optional().describe('Max findings to return per domain (default 60).'),
+    },
+  },
+  async ({ project, domain, sitemap_head, limit = 60 }) => {
+    if (!loadProjectConfig(project)) {
+      return { content: [{ type: 'text', text: `Project "${project}" not found. Use list_projects to discover.` }], isError: true };
+    }
+    try {
+      const db = getDb();
+      const domainRows = domain
+        ? [{ domain }]
+        : db.prepare("SELECT domain FROM domains WHERE project = ? AND role IN ('target','owned')").all(project);
+      if (!domainRows.length) {
+        return { content: [{ type: 'text', text: `No target/owned domains found for project "${project}".` }], isError: true };
+      }
+      const order = { error: 0, warn: 1, info: 2 };
+      const domains = [];
+      for (const { domain: d } of domainRows) {
+        const res = await runTechnicalAudit(db, { project, domain: d, runSitemapHead: !!sitemap_head });
+        if (res.error) { domains.push({ domain: d, error: res.error }); continue; }
+        const findings = [...(res.findings || [])]
+          .sort((a, b) => (order[a.severity] ?? 3) - (order[b.severity] ?? 3))
+          .slice(0, limit)
+          .map(f => ({ severity: f.severity, type: f.type, url: f.url || null, details: f.details }));
+        domains.push({ domain: d, stats: res.stats, findings, findings_truncated: (res.findings || []).length > limit });
+      }
+      const out = {
+        ok: true,
+        project,
+        domains,
+        hint: 'Findings read from the local crawl DB. Re-run `run_crawl` then this tool to verify fixes cleared. For AI-citability gaps, use run_citability_audit; for the prioritized fix queue, use list_problems.',
+      };
+      return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }], structuredContent: out };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `seo-intel error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// ── Tool: suggest_models (FREE) ───────────────────────────────────────────
+server.registerTool(
+  'suggest_models',
+  {
+    description: [
+      'Suggest LOCAL extraction models for the user\'s machine — the small models seo-intel runs once per crawled page to pull structured SEO data. Detects GPU/VRAM and which models are already in Ollama, then recommends from the curated set (Gemma 4 E2B / E4B / 12B, Qwen 3.5 4B / 9B).',
+      '',
+      'IMPORTANT: extraction should be done with a LOCAL model. The response always includes a cloud disclaimer — surface it to the user. Cloud extraction sends every page off-machine, costs money at scale, and rate-limits; a 4–8B local model handles this task well, offline. Free tier.',
+    ].join('\n'),
+    inputSchema: {
+      vram_gb: z.number().positive().optional().describe('Override detected VRAM (GB). Omit to auto-detect the host GPU/unified memory.'),
+    },
+  },
+  async ({ vram_gb }) => {
+    try {
+      const { suggestExtractionModels, CLOUD_EXTRACTION_DISCLAIMER } = await import('../setup/models.js');
+      let vramMB = 0, gpuName = null;
+      if (vram_gb) { vramMB = Math.round(vram_gb * 1024); gpuName = 'user-specified'; }
+      else { try { const { detectVRAM } = await import('../setup/checks.js'); const v = detectVRAM(); vramMB = v.vramMB || 0; gpuName = v.gpuName || null; } catch { /* unknown */ } }
+
+      let installed = [];
+      try {
+        const c = new AbortController();
+        const t = setTimeout(() => c.abort(), 1500);
+        const r = await fetch('http://localhost:11434/api/tags', { signal: c.signal });
+        clearTimeout(t);
+        if (r.ok) { const d = await r.json(); installed = (d.models || []).map(m => m.name); }
+      } catch { /* Ollama not reachable */ }
+
+      const { suggestions, recommendedId } = suggestExtractionModels(vramMB, installed);
+      const out = {
+        hardware: { gpu: gpuName, vram_gb: vramMB ? +(vramMB / 1024).toFixed(1) : null },
+        recommended: recommendedId,
+        install_hint: recommendedId ? `ollama pull ${recommendedId}` : null,
+        suggestions,
+        cloud_disclaimer: CLOUD_EXTRACTION_DISCLAIMER,
+        note: 'Extraction should be done with a LOCAL model — show cloud_disclaimer to the user before suggesting any cloud option.',
+      };
+      return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }], structuredContent: out };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `seo-intel error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// ── Tool: setup_project (FREE — project creation from chat) ───────────────
+// Closes the "setting up" gap: before this, projects could only be created via
+// the CLI/web wizard. An agent can now take a user from zero → configured →
+// crawled → audited entirely in chat.
+server.registerTool(
+  'setup_project',
+  {
+    description: [
+      'Create (or update) a SEO Intel project from chat — no CLI wizard needed. Writes the project config that run_crawl / run_citability_audit / tech_audit / get_intel operate on.',
+      '',
+      'Minimum: project_name + target_url. Add competitors to unlock the Solo competitive surface later. Industry/audience/goal feed the analysis prompts — better context, better insights. Use suggest_models first to pick a local extraction model for the user\'s hardware.',
+      '',
+      'Refuses to overwrite an existing project unless overwrite=true. Free tier.',
+    ].join('\n'),
+    inputSchema: {
+      project_name: z.string().describe('Human name — slugified for the project id (e.g. "Carbium Docs" → carbium-docs).'),
+      target_url: z.string().describe('The site to optimize (scheme optional).'),
+      site_name: z.string().optional().describe('Brand/site display name (defaults to project_name).'),
+      industry: z.string().optional().describe('What the site/business does — feeds analysis context.'),
+      audience: z.string().optional().describe('Who the site serves — feeds analysis context.'),
+      goal: z.string().optional().describe('What success looks like — feeds analysis context.'),
+      competitors: z.array(z.string()).optional().describe('Competitor URLs/domains to track (Solo features use these).'),
+      owned: z.array(z.string()).optional().describe('Other owned domains/subdomains to include.'),
+      pages_per_domain: z.number().int().positive().optional().describe('Max pages per domain per crawl (default 50).'),
+      extraction_model: z.string().optional().describe('Local extraction model tag (e.g. gemma4:e4b). Get a recommendation from suggest_models.'),
+      overwrite: z.boolean().optional().describe('Allow overwriting an existing project config (default false).'),
+    },
+  },
+  async ({ project_name, target_url, site_name, industry, audience, goal, competitors = [], owned = [], pages_per_domain, extraction_model, overwrite = false }) => {
+    try {
+      const { buildProjectConfig, writeProjectConfig, validateConfig, slugify } = await import('../setup/config-builder.js');
+      const slug = slugify(project_name);
+      const existing = join(CONFIG_DIR, `${slug}.json`);
+      if (existsSync(existing) && !overwrite) {
+        return { content: [{ type: 'text', text: `Project "${slug}" already exists. Pass overwrite=true to replace it, or use list_projects to see what's configured.` }], isError: true };
+      }
+
+      const config = buildProjectConfig({
+        projectName: project_name,
+        targetUrl: target_url,
+        siteName: site_name || project_name,
+        industry: industry || '',
+        audience: audience || '',
+        goal: goal || '',
+        competitors: competitors.map(u => ({ url: u })),
+        owned: owned.map(u => ({ url: u })),
+        pagesPerDomain: pages_per_domain || 50,
+        extractionModel: extraction_model,
+      });
+
+      const validation = validateConfig(config);
+      if (!validation.valid) {
+        return { content: [{ type: 'text', text: `Config validation failed: ${validation.errors.join('; ')}` }], isError: true };
+      }
+
+      const written = writeProjectConfig(config, ROOT);
+      const out = {
+        ok: true,
+        project: config.project,
+        config_path: written.path,
+        overwritten: written.overwritten,
+        target: config.target?.domain,
+        competitors: (config.competitors || []).map(c => c.domain),
+        owned: (config.owned || []).map(o => o.domain),
+        extraction_model: config.crawl?.extractionModel || '(default)',
+        hint: `Project ready. Next: run_crawl("${config.project}") to crawl, then run_citability_audit + tech_audit + list_problems. For a local extraction model, see suggest_models.`,
+      };
+      return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }], structuredContent: out };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `seo-intel error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// ── Tool: scan_site (PAID — one-shot full audit, no config) ───────────────
+// Mirrors `seo-intel scan <domain>`: crawl → extract → analyze → export. It is
+// heavyweight (browser crawl + extraction + cloud analysis), so it runs as a
+// detached subprocess like run_crawl and returns the report path to poll.
+server.registerTool(
+  'scan_site',
+  {
+    description: [
+      'One-shot full SEO audit of any domain with no project setup — crawl → extract → analyze → export. Spawns a detached background job (like run_crawl) and returns immediately with the report path; poll get_crawl_status for progress.',
+      '',
+      'Heavyweight: full browser crawl, local extraction, and cloud analysis. For a fast, ephemeral, offline read of a single URL use crawl_site instead. Paid tier (Solo).',
+    ].join('\n'),
+    inputSchema: {
+      domain: z.string().describe('Domain or URL to audit (e.g. "docs.carbium.sh").'),
+      pages: z.number().int().positive().max(500).optional().describe('Max pages to crawl (default 100).'),
+      stealth: z.boolean().optional().describe('Enable stealth browser mode for JS-heavy / anti-bot sites.'),
+      no_ai: z.boolean().optional().describe('Skip the AI-enriched export (deterministic markdown only).'),
+      model: z.enum(['gemini', 'claude', 'gpt']).optional().describe('Model for analysis + AI export (default gemini).'),
+    },
+  },
+  async ({ domain, pages, stealth, no_ai, model }) => {
+    if (!isPro()) return paidGate('scan_site');
+    const progress = readProgress();
+    if (progress?.status === 'running') {
+      return { content: [{ type: 'text', text: `A seo-intel job is already running (command="${progress.command}", pid=${progress.pid}). Wait or call get_crawl_status.` }], isError: true };
+    }
+    const bare = domain.replace(/^https?:\/\//, '').replace(/\/.*$/, '').replace(/^www\./, '');
+    const args = ['cli.js', 'scan', bare];
+    if (pages) args.push('--pages', String(pages));
+    if (stealth) args.push('--stealth');
+    if (no_ai) args.push('--no-ai');
+    if (model) args.push('--model', model);
+
+    const child = spawn(process.execPath, args, { cwd: ROOT, detached: true, stdio: 'ignore' });
+    child.unref();
+
+    const reportPath = join(ROOT, 'reports', `scan-${bare.replace(/[^a-z0-9]/gi, '-').toLowerCase()}-${new Date().toISOString().slice(0, 10)}.md`);
+    const result = {
+      started: true,
+      pid: child.pid,
+      domain: bare,
+      command: `node ${args.join(' ')}`,
+      report_path: reportPath,
+      hint: 'Scan is running detached (crawl → extract → analyze → export). Poll get_crawl_status; when status="completed" read the markdown at report_path. The ephemeral project is "_scan-<domain>" — tech_audit/run_citability_audit can be run against it once the crawl lands.',
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: result };
+  }
+);
+
 // ── Tool: get_competitor_positioning (PAID) ───────────────────────────────
 server.registerTool(
   'get_competitor_positioning',
@@ -989,7 +1233,7 @@ async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   // stderr is fine; the host typically surfaces this in its MCP logs panel.
-  console.error(`[seo-intel-mcp] v${VERSION} ready on stdio. 17 tools — free: crawl_site (ad-hoc, any URL, no config), run_content_loop (gap→draft→close), list_projects, list_problems, mark_problem_status, get_intel(raw/audit/blog), get_pages, list_keywords, get_headings, run_crawl, get_crawl_status, ingest_insight, run_citability_audit, prescore_draft, draft_blog_prompt, export_intel (own-site tables); Solo (competitor synthesis): get_competitor_positioning, get_intel(competitor), export_intel (analyses table).`);
+  console.error(`[seo-intel-mcp] v${VERSION} ready on stdio. 21 tools — free: setup_project (zero→configured from chat), crawl_site (ad-hoc, any URL, no config), run_content_loop (gap→draft→close), list_projects, list_problems, mark_problem_status, get_intel(raw/audit/blog), get_pages, list_keywords, get_headings, run_crawl, get_crawl_status, ingest_insight, run_citability_audit (now with AI-crawler access), tech_audit, suggest_models (local-first), prescore_draft, draft_blog_prompt, export_intel (own-site tables); Solo: scan_site (one-shot full audit), get_competitor_positioning, get_intel(competitor), export_intel (analyses table).`);
 }
 
 main().catch(err => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seo-intel",
-  "version": "1.5.45",
+  "version": "1.5.50",
   "description": "Local Ahrefs-style SEO competitor intelligence. Crawl → SQLite → cloud analysis.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/server.js

@@ -140,11 +140,55 @@ function getProjects() {
     .filter(Boolean);
 }
 
+// ── Security: loopback-only gate (anti DNS-rebinding + cross-origin/CSRF) ──
+//
+// This server binds 127.0.0.1, but any web page you visit can still fire
+// requests at localhost. Two checks close that whole class:
+//   • Host  — a DNS-rebinding request arrives carrying the ATTACKER's domain as
+//     Host (not localhost), so requiring a loopback Host defeats it.
+//   • Origin — a cross-origin page sends its own Origin; requiring a loopback
+//     Origin (when present) blocks cross-origin reads and CSRF.
+// Same-origin dashboard use is unaffected: same-origin GET/SSE either sends no
+// Origin or sends our own loopback Origin.
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1']);
+
+function normHost(h) {
+  if (!h) return '';
+  h = String(h).trim().toLowerCase();
+  if (h.startsWith('[')) { const i = h.indexOf(']'); return i > 0 ? h.slice(1, i) : h.slice(1); } // [::1]:port → ::1
+  return h.split(':')[0]; // host:port → host
+}
+
+function isLocalRequest(req) {
+  const host = normHost(req.headers.host);
+  if (!host || !LOCAL_HOSTS.has(host)) return false;            // defeats DNS rebinding
+  const origin = req.headers.origin;
+  if (origin && origin !== 'null') {                            // defeats cross-origin / CSRF
+    try { if (!LOCAL_HOSTS.has(normHost(new URL(origin).host))) return false; }
+    catch { return false; }
+  }
+  return true;
+}
+
 // ── Request handler ──
 async function handleRequest(req, res) {
   const url = new URL(req.url, `http://localhost:${PORT}`);
   const path = url.pathname;
 
+  // Security headers on every response (clickjacking + MIME-sniffing). The
+  // frame-ancestors directive only governs who may iframe us — it does NOT
+  // restrict the dashboard's own CDN resources, so it is safe to set globally.
+  res.setHeader('X-Frame-Options', 'DENY');
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+  res.setHeader('Content-Security-Policy', "frame-ancestors 'none'");
+
+  // Loopback-only gate — reject anything not local before any routing happens.
+  if (!isLocalRequest(req)) {
+    res.writeHead(403, { 'Content-Type': 'text/plain' });
+    res.end('Forbidden: SEO Intel only accepts requests from localhost.');
+    return;
+  }
+
   // ─── Setup wizard routes ───
   if (path.startsWith('/setup') || path.startsWith('/api/setup/')) {
     try {
@@ -1162,12 +1206,13 @@ ${md}`;
       args.push('--save');
     }
 
-    // SSE headers
+    // SSE headers — no CORS: the dashboard is same-origin, and the loopback
+    // gate already blocks cross-origin callers. (Removed Access-Control-Allow-Origin:*
+    // which previously let any website read this command-execution stream.)
     res.writeHead(200, {
       'Content-Type': 'text/event-stream',
       'Cache-Control': 'no-cache',
       'Connection': 'keep-alive',
-      'Access-Control-Allow-Origin': '*',
     });
 
     const send = (type, data) => {

package/setup/engine.js

@@ -35,6 +35,9 @@ export {
   recommendExtractionModel,
   recommendAnalysisModel,
   getModelRecommendations,
+  suggestExtractionModels,
+  CLOUD_EXTRACTION_DISCLAIMER,
+  CLOUD_EXTRACTION_DISCLAIMER_SHORT,
 } from './models.js';
 
 // Auto-installers

package/setup/models.js

@@ -42,6 +42,18 @@ export const EXTRACTION_MODELS = [
     description: 'Default recommendation. MoE (8B total, 4.5B active) — excellent extraction quality at edge-model speed. Best quality/speed ratio.',
     recommended: true,
   },
+  {
+    id: 'gemma4:12b',
+    name: 'Gemma 4 12B',
+    family: 'gemma4',
+    tier: 'quality',
+    vram: '~10 GB',
+    minVramMB: 8500,
+    speed: '~3s/page',
+    quality: 'excellent',
+    description: 'Dense 12B — a clear quality step up from E4B for tricky pages, still fast. Needs RTX 3080+/M-series 16GB+.',
+    recommended: false,
+  },
   {
     id: 'gemma4:26b',
     name: 'Gemma 4 26B',
@@ -261,8 +273,8 @@ export const ANALYSIS_MODELS = [
     description: 'Google\'s latest frontier model. Massive 2M context handles the largest competitive datasets. Best value for cloud analysis.',
   },
   {
-    id: 'claude-opus-4.6',
-    name: 'Claude Opus 4.6',
+    id: 'claude-opus-4-8',
+    name: 'Claude Opus 4.8',
     family: 'claude',
     type: 'cloud',
     provider: 'anthropic',
@@ -430,6 +442,82 @@ export function recommendAnalysisModel(availableModels = [], vramMB = 0) {
   };
 }
 
+// ── Cloud-extraction disclaimer ─────────────────────────────────────────────
+//
+// Extraction runs once per crawled page. At scale (thousands of pages) a cloud
+// provider means every page's content leaves the machine, costs real money, and
+// hits rate limits — for a task a small local model handles well. Surface this
+// EVERYWHERE a cloud model is offered/selected for extraction. Non-negotiable.
+
+export const CLOUD_EXTRACTION_DISCLAIMER =
+  'Extraction should be done with a LOCAL model. Cloud is a fallback, not the default: ' +
+  'it sends every page\'s content to a third-party API, costs money at scale (a 10k-page ' +
+  'site is real spend), and hits rate limits — all for a task a 4–8B local model does well, ' +
+  'offline, with your data never leaving the machine. Use cloud only if you have no local ' +
+  'GPU/Ollama and accept those tradeoffs.';
+
+// Short one-liner for tight UIs (status bars, JSON `notice` fields).
+export const CLOUD_EXTRACTION_DISCLAIMER_SHORT =
+  '⚠ Use a LOCAL model for extraction — cloud sends page content off-machine, costs money at scale, and rate-limits. Local is private, free, and offline.';
+
+// ── Curated extraction suggestions ──────────────────────────────────────────
+//
+// The headline "what should I run locally" set — the families we actually
+// recommend, smallest → largest. Drawn from EXTRACTION_MODELS so VRAM/speed/
+// quality stay in one place. Used by `seo-intel models` and the suggest_models
+// MCP tool so an agent in chat can recommend a model without the full wizard.
+
+const SUGGESTED_EXTRACTION_IDS = [
+  'gemma4:e2b',   // laptop / low VRAM
+  'qwen3.5:4b',   // budget alt
+  'gemma4:e4b',   // default — best quality/speed
+  'qwen3.5:9b',   // ~8B-class alt
+  'gemma4:12b',   // step-up quality, still fast
+];
+
+/**
+ * Curated local extraction-model suggestions, annotated for the detected
+ * hardware. Always returns the local set; the cloud disclaimer is attached so
+ * callers can surface it alongside.
+ *
+ * @param {number} [vramMB] - detected VRAM in MB (0/unknown = show all, no fit filter)
+ * @param {string[]} [installed] - model tags currently in Ollama
+ * @returns {{ suggestions: object[], recommendedId: string|null, vramMB: number, disclaimer: string }}
+ */
+export function suggestExtractionModels(vramMB = 0, installed = []) {
+  const isInstalled = (id) => {
+    const [fam, size] = id.split(':');
+    return installed.some(m => m.startsWith(fam) && (!size || m.includes(size)));
+  };
+
+  const suggestions = SUGGESTED_EXTRACTION_IDS
+    .map(id => EXTRACTION_MODELS.find(m => m.id === id))
+    .filter(Boolean)
+    .map(m => ({
+      id: m.id,
+      name: m.name,
+      tier: m.tier,
+      vram: m.vram,
+      speed: m.speed,
+      quality: m.quality,
+      fitsVram: !vramMB || vramMB >= m.minVramMB,
+      installed: isInstalled(m.id),
+      note: m.description,
+    }));
+
+  // Recommend the largest suggested model that fits VRAM (or the default if VRAM unknown).
+  let recommendedId = 'gemma4:e4b';
+  if (vramMB) {
+    const fitting = suggestions.filter(s => s.fitsVram);
+    recommendedId = fitting.length ? fitting[fitting.length - 1].id : (suggestions[0]?.id ?? null);
+  }
+  // Prefer an already-installed fitting model if there is one.
+  const installedFitting = suggestions.find(s => s.installed && s.fitsVram);
+  if (installedFitting) recommendedId = installedFitting.id;
+
+  return { suggestions, recommendedId, vramMB, disclaimer: CLOUD_EXTRACTION_DISCLAIMER };
+}
+
 /**
  * Get all model recommendations for display.
  *