seo-intel 1.5.2 → 1.5.21

package/Start SEO Intel.command

@@ -5,4 +5,14 @@ echo ""
 echo "  Starting SEO Intel..."
 echo "  Dashboard will open in your browser."
 echo ""
+
+# Kill any stale server on the same port so new code is always loaded
+PORT="${SEO_INTEL_PORT:-3000}"
+OLD_PID=$(lsof -ti :"$PORT" 2>/dev/null)
+if [ -n "$OLD_PID" ]; then
+  echo "  Restarting server (killing stale PID $OLD_PID on port $PORT)..."
+  kill "$OLD_PID" 2>/dev/null
+  sleep 1
+fi
+
 node cli.js serve --open

package/analyses/blog-draft/index.js

@@ -89,9 +89,10 @@ export function gatherBlogDraftContext(db, project, topic = null) {
 
 // ── Prompt Builder ──────────────────────────────────────────────────────────
 
-export function buildBlogDraftPrompt(context, { config, lang = 'en', topic = null }) {
+export function buildBlogDraftPrompt(context, { config, lang = 'en', topic = null, contentType = 'blog' }) {
   const { longTails, keywordGaps, citabilityGaps, entityRows, topCitablePages, kwInventor, contentGaps, insights } = context;
   const isFi = lang === 'fi';
+  const langName = isFi ? 'Finnish' : 'English';
 
   // Extract unique entities from extraction data
   const allEntities = new Set();
@@ -103,11 +104,19 @@ export function buildBlogDraftPrompt(context, { config, lang = 'en', topic = nul
   }
   const topEntities = [...allEntities].slice(0, 15);
 
-  // ── Section 1: Role ──
+  // ── Section 1: Role — adapts to content type ──
+  const typeInstructions = {
+    blog: `Your task: write a complete, publish-ready blog post draft in ${langName}.
+The post must score 70+ on the AEO citability scale (entity authority, structured claims, answer density, Q&A proximity, freshness signals, schema coverage).`,
+    docs: `Your task: write a complete, publish-ready documentation page in ${langName}.
+The page must be technically precise, well-structured, and scannable. Use step-by-step instructions where applicable. Optimise for developers and technical users searching for how-to answers.`,
+    social: `Your task: write a set of social media posts in ${langName}.
+Create 5-7 distinct posts suitable for LinkedIn/X/Twitter. Each should be self-contained, engaging, and drive traffic to the site. Include hashtag suggestions. Vary formats: thread opener, hot take, stat-based, question-based, listicle.`,
+  };
+
   let prompt = `You are an expert content strategist and copywriter specialising in AEO (Answer Engine Optimisation).
 
-Your task: write a complete, publish-ready blog post draft in ${isFi ? 'Finnish' : 'English'}.
-The post must score 70+ on the AEO citability scale (entity authority, structured claims, answer density, Q&A proximity, freshness signals, schema coverage).
+${typeInstructions[contentType] || typeInstructions.blog}
 
 `;
 
@@ -183,12 +192,46 @@ The post must score 70+ on the AEO citability scale (entity authority, structure
     }
   }
 
-  // ── Section 5: AEO structural requirements ──
-  prompt += `
+  // ── Section 5: Structural requirements — adapts to content type ──
+  const siteName = config.context?.siteName || config.target?.domain;
+  const today = new Date().toISOString().slice(0, 10);
+
+  if (contentType === 'social') {
+    prompt += `
+## Social Media Requirements
+
+1. Create 5-7 distinct posts, each separated by ---
+2. Each post must be self-contained (not a thread unless marked as such)
+3. Include a mix of: hot takes, statistics/data, questions, listicles, how-to snippets
+4. Optimise for engagement: hooks in the first line, clear value proposition
+5. Include 3-5 relevant hashtags per post
+6. Keep posts under 280 characters for X/Twitter variants; LinkedIn variants can be longer (600-1,200 chars)
+7. Reference ${siteName} naturally where appropriate (not in every post)
+8. Include one thread idea (3-5 connected posts) marked with [THREAD]
+9. Language: ${isFi ? 'Finnish' : 'English'}
+`;
+  } else if (contentType === 'docs') {
+    prompt += `
+## Documentation Requirements
+
+The page MUST include:
+1. YAML frontmatter with: title, slug, description (155 chars max), primary_keyword, secondary_keywords[], date (${today}), lang (${lang}), tags[]
+2. An H1 that clearly states what this page covers
+3. A 1-2 sentence overview immediately after the H1
+4. Prerequisites section (if applicable)
+5. Step-by-step instructions with numbered lists
+6. Code examples with language-tagged fenced code blocks
+7. At least one table for reference data (parameters, options, etc.)
+8. A "Troubleshooting" or "Common Issues" section at the end
+9. Word count: 800-2,000 words
+10. Internal link suggestions: include 2-3 \`[anchor text](URL)\` links to related pages
+`;
+  } else {
+    prompt += `
 ## AEO Structural Requirements
 
 The draft MUST include:
-1. YAML frontmatter with: title, slug, description (155 chars max), primary_keyword, secondary_keywords[], date (${new Date().toISOString().slice(0, 10)}), updated (same), lang (${lang}), tags[]${!topic ? ', topic_selection_rationale' : ''}
+1. YAML frontmatter with: title, slug, description (155 chars max), primary_keyword, secondary_keywords[], date (${today}), updated (same), lang (${lang}), tags[]${!topic ? ', topic_selection_rationale' : ''}
 2. An H1 that contains the primary keyword
 3. A 2-3 sentence summary immediately after the H1 (answer-first structure — inverted pyramid). This paragraph will be cited by AI assistants.
 4. Minimum 6 H2 subheadings
@@ -196,10 +239,11 @@ The draft MUST include:
 6. At least one numbered or bulleted list with 4+ items
 7. At least one "X is Y because Z" definitional sentence per major concept
 8. A FAQ section at the end with minimum 4 Q&A pairs (### H3 questions, 2-4 sentence answers)
-9. A closing CTA paragraph referencing ${config.context?.siteName || config.target?.domain}
+9. A closing CTA paragraph referencing ${siteName}
 10. Word count: 1,200-2,000 words
 11. Internal link suggestions: include 2-3 \`[anchor text](URL)\` links back to the site where natural
 `;
+  }
 
   // ── Section 6: Language ──
   if (isFi) {
@@ -217,11 +261,19 @@ Write in clear, direct international English. No filler phrases. No "in today's
   }
 
   // ── Section 7: Output format ──
-  prompt += `
+  if (contentType === 'social') {
+    prompt += `
+## Output Format
+
+Respond with ONLY the social media posts. Separate each post with ---. No explanation before or after. No triple backticks wrapping the response.
+`;
+  } else {
+    prompt += `
 ## Output Format
 
-Respond with ONLY the complete markdown document. Start with --- (YAML frontmatter open fence). End with the FAQ section and CTA. No explanation before or after. No triple backticks wrapping the response.
+Respond with ONLY the complete markdown document. Start with --- (YAML frontmatter open fence). End with the ${contentType === 'docs' ? 'Troubleshooting section' : 'FAQ section and CTA'}. No explanation before or after. No triple backticks wrapping the response.
 `;
+  }
 
   return prompt;
 }

package/cli.js

@@ -4439,6 +4439,7 @@ program
   .description('Generate an AEO-optimised blog post draft from Intelligence Ledger data')
   .option('--topic <keyword>', 'Focus the post on a specific topic')
   .option('--lang <code>', 'Language: en or fi', 'en')
+  .option('--type <type>', 'Content type: blog, docs, or social', 'blog')
   .option('--model <name>', 'Model to use for generation (gemini, claude, gpt, deepseek)', 'gemini')
   .option('--save', 'Save the generated draft to reports/')
   .action(async (project, opts) => {
@@ -4480,6 +4481,7 @@ program
       config,
       lang: opts.lang,
       topic: opts.topic || null,
+      contentType: opts.type || 'blog',
     });
     console.log(chalk.gray(`    Prompt size: ${(prompt.length / 1024).toFixed(1)}KB`));
 
@@ -4771,6 +4773,243 @@ program.hook('preAction', async () => {
   }
 });
 
+// ── SCAN — One-shot full audit ────────────────────────────────────────────────
+program
+  .command('scan <domain>')
+  .description('One-shot full audit: crawl → extract → analyze → export (no config needed)')
+  .option('--pages <n>', 'Max pages to crawl', '100')
+  .option('--no-ai', 'Skip AI-enriched export (deterministic only)')
+  .option('--model <name>', 'Model for analysis + AI export (gemini, claude, gpt)', 'gemini')
+  .option('--no-stealth', 'Disable stealth browser mode')
+  .action(async (domainInput, opts) => {
+    if (!requirePro('scan')) return;
+
+    // ── Parse domain ──
+    const domain = domainInput.replace(/^https?:\/\//, '').replace(/\/.*$/, '').replace(/^www\./, '');
+    const projectSlug = '_scan-' + domain.replace(/[^a-z0-9]/gi, '-').toLowerCase();
+    const siteUrl = defaultSiteUrl(domain);
+    const useStealth = opts.stealth !== false;
+    const useAi = opts.ai !== false;
+    const maxPages = Math.min(parseInt(opts.pages) || 100, capPages(9999));
+
+    console.log(chalk.bold.hex('#d4af37')(`\n${'═'.repeat(60)}`));
+    console.log(chalk.bold.hex('#d4af37')(`  ⚡ SCAN — Full SEO Audit`));
+    console.log(chalk.bold.hex('#d4af37')(`${'═'.repeat(60)}`));
+    console.log('');
+    console.log(chalk.white(`  Target:    ${chalk.bold(domain)}`));
+    console.log(chalk.white(`  Pages:     ${maxPages}`));
+    console.log(chalk.white(`  Stealth:   ${useStealth ? chalk.green('yes') : chalk.gray('no')}`));
+    console.log(chalk.white(`  AI Export: ${useAi ? chalk.green('yes') : chalk.gray('no')}`));
+    console.log(chalk.white(`  Model:     ${opts.model}`));
+    console.log('');
+
+    const scanStart = Date.now();
+    const db = getDb();
+
+    // ── Ephemeral config ──
+    const config = {
+      project: projectSlug,
+      context: { siteName: domain, industry: '', audience: '', goal: '' },
+      target: { domain, url: siteUrl, maxPages, crawlMode: 'standard' },
+      competitors: [],
+      owned: [],
+    };
+    // Save config so dashboard/export functions work
+    const configPath = join(__dirname, `config/${projectSlug}.json`);
+    writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+
+    applyExtractionRuntimeConfig(config);
+
+    // ── Step 1: Crawl + Extract ──
+    console.log(chalk.bold.cyan('  ⏱  Step 1/3 — Crawl + Extract'));
+    console.log('');
+
+    // Check extraction availability
+    let doExtract = true;
+    const ollamaAvailable = await checkOllamaAvailability(config);
+    if (!ollamaAvailable) {
+      console.log(chalk.yellow('  ⚠  No AI extraction available (Ollama unreachable)'));
+      console.log(chalk.gray('  → Crawl-only mode — body text still captured for analysis'));
+      console.log('');
+      doExtract = false;
+    }
+
+    upsertDomain(db, { domain, project: projectSlug, role: 'target' });
+    const domainId = db.prepare('SELECT id FROM domains WHERE domain = ? AND project = ?').get(domain, projectSlug)?.id;
+
+    let pageCount = 0, extracted = 0, failed = 0;
+    const tag = chalk.cyan(`[${domain.split('.')[0]}]`);
+
+    for await (const page of crawlDomain(siteUrl, { maxPages, stealth: useStealth, tiered: true })) {
+      if (page._blocked) {
+        console.log(chalk.bold.red(`  ${tag} ⛔ BLOCKED: ${page._blockReason}`));
+        break;
+      }
+
+      const pageRes = upsertPage(db, {
+        domainId, url: page.url, statusCode: page.status,
+        wordCount: page.wordCount, loadMs: page.loadMs,
+        isIndexable: page.isIndexable, clickDepth: page.depth ?? 0,
+        publishedDate: page.publishedDate || null, modifiedDate: page.modifiedDate || null,
+        contentHash: page.contentHash || null, title: page.title || null,
+        metaDesc: page.metaDesc || null, bodyText: page.fullBodyText || page.bodyText || null,
+      });
+      const pageId = pageRes?.id;
+
+      upsertTechnical(db, { pageId, hasCanonical: page.hasCanonical, hasOgTags: page.hasOgTags, hasSchema: page.hasSchema, hasRobots: page.hasRobots });
+      insertHeadings(db, pageId, page.headings);
+      insertLinks(db, pageId, page.links);
+      if (page.parsedSchemas?.length) insertPageSchemas(db, pageId, page.parsedSchemas);
+
+      if (doExtract) {
+        process.stdout.write(chalk.gray(`  ${tag} [${pageCount + 1}] d${page.depth ?? 0} ${page.url.slice(0, 60)} → extracting...`));
+        try {
+          const extractFn = await getExtractPage();
+          const extraction = await extractFn(page);
+          insertExtraction(db, { pageId, data: extraction });
+          insertKeywords(db, pageId, extraction.keywords);
+          process.stdout.write(chalk.green(` ✓\n`));
+          extracted++;
+        } catch (err) {
+          process.stdout.write(chalk.red(` ✗ ${err.message}\n`));
+          failed++;
+        }
+      } else {
+        process.stdout.write(chalk.gray(`  ${tag} [${pageCount + 1}] d${page.depth ?? 0} ${page.url.slice(0, 65)} ✓\n`));
+      }
+      pageCount++;
+    }
+
+    const crawlSec = ((Date.now() - scanStart) / 1000).toFixed(1);
+    console.log(chalk.green(`\n  ✅ Crawl done: ${pageCount} pages, ${extracted} extracted (${crawlSec}s)\n`));
+
+    // ── Step 2: Analyze ──
+    console.log(chalk.bold.cyan('  ⏱  Step 2/3 — Analyze'));
+    console.log('');
+
+    const summary = getCompetitorSummary(db, projectSlug);
+    const target = summary.find(s => s.role === 'target');
+
+    if (!target) {
+      console.log(chalk.yellow('  ⚠  No target data found — skipping analysis'));
+    } else {
+      target.domain = domain;
+      const keywordMatrix = getKeywordMatrix(db, projectSlug);
+      const headings = getHeadingStructure(db, projectSlug);
+
+      const buildPromptFn = await getBuildAnalysisPrompt();
+      const prompt = buildPromptFn({
+        project: projectSlug, target, competitors: [],
+        keywordMatrix, headingStructure: headings, context: config.context,
+      });
+
+      console.log(chalk.gray(`  Prompt: ~${Math.round(prompt.length / 4)} tokens → ${opts.model}...`));
+      process.env._SEO_INTEL_PROJECT = projectSlug;
+      const result = await callAnalysisModel(prompt, opts.model);
+
+      if (result) {
+        try {
+          const jsonMatch = result.match(/\{[\s\S]*\}/);
+          const analysis = JSON.parse(jsonMatch[0]);
+
+          // Save to DB
+          const analysisTs = Date.now();
+          db.prepare(`
+            INSERT INTO analyses (project, generated_at, model, keyword_gaps, long_tails, quick_wins, new_pages, content_gaps, positioning, technical_gaps, raw)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          `).run(
+            projectSlug, analysisTs, opts.model,
+            JSON.stringify(analysis.keyword_gaps || []),
+            JSON.stringify(analysis.long_tails || []),
+            JSON.stringify(analysis.quick_wins || []),
+            JSON.stringify(analysis.new_pages || []),
+            JSON.stringify(analysis.content_gaps || []),
+            JSON.stringify(analysis.positioning || {}),
+            JSON.stringify(analysis.technical_gaps || []),
+            result,
+          );
+          const analysisRowId = db.prepare('SELECT last_insert_rowid() as id').get().id;
+          upsertInsightsFromAnalysis(db, projectSlug, analysisRowId, analysis, analysisTs);
+
+          printAnalysisSummary(analysis, projectSlug);
+        } catch (parseErr) {
+          console.log(chalk.yellow(`  ⚠  Could not parse analysis: ${parseErr.message}`));
+          const rawPath = join(__dirname, `reports/${projectSlug}-raw-${new Date().toISOString().slice(0, 10)}.md`);
+          writeFileSync(rawPath, result, 'utf8');
+          console.log(chalk.gray(`  Raw output saved: ${rawPath}`));
+        }
+      } else {
+        console.log(chalk.yellow('  ⚠  No response from model — skipping analysis'));
+      }
+    }
+
+    // ── Step 3: Export ──
+    console.log(chalk.bold.cyan('\n  ⏱  Step 3/3 — Export Report'));
+    console.log('');
+
+    // Generate dashboard (so gatherProjectData works)
+    try {
+      const allConfigs = loadAllConfigs();
+      generateMultiDashboard(db, allConfigs);
+    } catch { /* ok if this fails */ }
+
+    // Build export markdown via the server's export logic
+    const { gatherProjectData } = await import('./reports/generate-html.js');
+    const dash = gatherProjectData(db, projectSlug, config);
+
+    // Inline the deterministic markdown builder from server.js
+    const { buildScanMarkdown } = await import('./lib/scan-export.js');
+    let md = buildScanMarkdown(dash, projectSlug, domain);
+
+    // AI enrichment
+    if (useAi) {
+      console.log(chalk.gray(`  Enriching with AI (${opts.model})...`));
+      const aiPrompt = `You are an SEO strategist reviewing a data export report. Your job is to ENRICH this report, NOT rewrite it.
+
+Rules:
+- Keep ALL existing data, tables, headers, and instruction blocks exactly as they are
+- Fill any empty table cells (marked with empty | | columns) with concise, actionable content
+- For empty "Parent" cells: infer the parent keyword cluster
+- For empty "Opportunity" cells: classify as how-to guide, comparison, tutorial, landing page, etc.
+- For empty "Gap"/"Suggestion"/"Rationale"/"Potential" cells: fill with concise actionable content
+- After the last section, add "## AI Action Plan" with a numbered top-10 highest-impact actions
+- Keep markdown format — tables, headers, blockquotes
+- Be concise — table cells under 80 chars
+- Do NOT add commentary outside the report
+
+Here is the report:
+
+${md}`;
+      const aiResult = await callAnalysisModel(aiPrompt, opts.model);
+      if (aiResult && aiResult.trim().length > md.length * 0.5) {
+        md = aiResult;
+        console.log(chalk.green('  ✓ AI enrichment applied'));
+      } else {
+        console.log(chalk.yellow('  ⚠  AI enrichment failed — using deterministic export'));
+      }
+    }
+
+    // Save
+    const dateStr = new Date().toISOString().slice(0, 10);
+    const fileName = `scan-${domain.replace(/[^a-z0-9]/gi, '-')}-${dateStr}.md`;
+    const outPath = join(__dirname, 'reports', fileName);
+    writeFileSync(outPath, md, 'utf8');
+
+    const totalSec = ((Date.now() - scanStart) / 1000).toFixed(1);
+    console.log('');
+    console.log(chalk.bold.hex('#d4af37')(`${'═'.repeat(60)}`));
+    console.log(chalk.bold.hex('#d4af37')(`  ✅ Scan Complete — ${totalSec}s`));
+    console.log(chalk.bold.hex('#d4af37')(`${'═'.repeat(60)}`));
+    console.log('');
+    console.log(chalk.white(`  Report: ${chalk.bold(outPath)}`));
+    console.log(chalk.white(`  Pages:  ${pageCount} crawled, ${extracted} extracted`));
+    console.log(chalk.white(`  Export: ${useAi ? 'AI-enriched' : 'deterministic'} markdown`));
+    console.log('');
+
+    // Clean up ephemeral config (keep the report)
+    try { unlinkSync(configPath); } catch { /* fine if already gone */ }
+  });
+
 // ── BUG-002: No-args getting-started handler ─────────────────────────────────
 // When run with no command, show a friendly entry point instead of generic help
 if (process.argv.length <= 2) {

package/lib/scan-export.js

@@ -0,0 +1,180 @@
+/**
+ * Scan Export — Deterministic markdown builder for the `scan` command.
+ * Mirrors the dashboardToMarkdown logic from server.js but works standalone.
+ */
+
+function inferLongTailParent(phrase, keywordGaps) {
+  const lower = phrase.toLowerCase();
+  let best = null, bestScore = 0;
+  for (const g of (keywordGaps || [])) {
+    const kw = (g.keyword || '').toLowerCase();
+    if (!kw || kw.length < 3) continue;
+    const words = kw.split(/\s+/);
+    const score = words.filter(w => lower.includes(w)).length / words.length;
+    if (score > bestScore && score >= 0.5) { bestScore = score; best = g.keyword; }
+  }
+  return best;
+}
+
+function inferLongTailOpportunity(item) {
+  const p = (item.phrase || '').toLowerCase();
+  const intent = item.intent || '';
+  const pageType = item.page_type || '';
+  if (p.startsWith('how to ') || p.includes(' tutorial')) return `How-to ${pageType || 'guide'} — ${intent || 'informational'} intent`;
+  if (p.includes(' vs ') || p.includes(' comparison')) return `Comparison ${pageType || 'article'} — captures decision-stage traffic`;
+  if (p.includes('best ') || p.includes('top ')) return `Listicle / roundup — high commercial intent`;
+  if (p.includes('what is ') || p.includes('explained')) return `Explainer ${pageType || 'page'} — top-of-funnel awareness`;
+  if (p.includes(' api ') || p.includes(' sdk ')) return `Technical docs ${pageType || 'page'} — developer intent`;
+  if (p.includes(' price') || p.includes(' cost') || p.includes(' pricing')) return `Pricing / comparison page — transactional intent`;
+  if (intent) return `${pageType || 'Content'} page — ${intent} intent`;
+  return pageType ? `${pageType} page` : '';
+}
+
+function inferPotential(item) {
+  const p = (item.priority || '').toLowerCase();
+  if (p === 'high' || p === 'critical') return 'High';
+  if (p === 'medium') return 'Medium';
+  if (p === 'low') return 'Low';
+  const phrase = (item.phrase || '').toLowerCase();
+  if (phrase.startsWith('how') || phrase.includes(' vs ') || phrase.includes('best ')) return 'High';
+  if (item.type === 'question' || item.type === 'comparison') return 'High';
+  if (item.type === 'ai_query') return 'Medium';
+  return 'Medium';
+}
+
+export function buildScanMarkdown(dash, projectSlug, domain) {
+  const date = new Date().toISOString().slice(0, 10);
+  const a = dash.latestAnalysis || {};
+  const s = {};
+
+  // Map dashboard data to sections
+  const target = dash.technicalScores?.find(d => d.isTarget);
+  if (target) {
+    s.technical = { score: target.score, h1_coverage: target.h1Pct + '%', meta_coverage: target.metaPct + '%', schema_coverage: target.schemaPct + '%', title_coverage: target.titlePct + '%' };
+  }
+  if (a.technical_gaps?.length) s.technical_gaps = a.technical_gaps;
+  if (a.quick_wins?.length) s.quick_wins = a.quick_wins;
+  if (a.keyword_gaps?.length) s.keyword_gaps = a.keyword_gaps;
+  if (dash.keywordGaps?.length) s.top_keyword_gaps = dash.keywordGaps.slice(0, 50);
+  if (a.long_tails?.length) s.long_tails = a.long_tails;
+  if (a.new_pages?.length) s.new_pages = a.new_pages;
+  if (a.content_gaps?.length) s.content_gaps = a.content_gaps;
+  if (a.positioning) s.positioning = a.positioning;
+  if (a.keyword_inventor?.length) s.keyword_inventor = a.keyword_inventor;
+  if (dash.internalLinks) {
+    s.internal_links = { total_links: dash.internalLinks.totalLinks, orphan_pages: dash.internalLinks.orphanCount, top_pages: dash.internalLinks.topPages };
+  }
+  if (dash.crawlStats) s.crawl_stats = dash.crawlStats;
+
+  // Build markdown
+  let md = `# SEO Scan Report — ${domain}\n\n- Date: ${date}\n- Mode: One-shot audit (no competitors)\n\n`;
+
+  if (s.technical) {
+    md += `## Technical Scorecard\n\n`;
+    md += `- Overall: **${s.technical.score}/100**\n`;
+    md += `- H1: ${s.technical.h1_coverage} | Meta: ${s.technical.meta_coverage} | Schema: ${s.technical.schema_coverage} | Title: ${s.technical.title_coverage}\n\n`;
+  }
+
+  if (s.technical_gaps?.length) {
+    md += `## Technical Gaps (${s.technical_gaps.length})\n\n`;
+    md += `> Implement these schema and markup fixes to qualify for rich results. Start with FAQ and HowTo schema.\n\n`;
+    md += `| Issue | Affected | Fix |\n|-------|----------|-----|\n`;
+    for (const g of s.technical_gaps) md += `| ${g.gap || g.issue || ''} | ${g.affected || g.pages || ''} | ${g.recommendation || g.fix || ''} |\n`;
+    md += '\n';
+  }
+
+  if (s.quick_wins?.length) {
+    const highCount = s.quick_wins.filter(w => w.impact === 'high').length;
+    md += `## Quick Wins (${s.quick_wins.length})\n\n`;
+    md += `> **${highCount} high-impact items.** Pick the top 3 and implement this week — each takes <30 min.\n\n`;
+    md += `| Page | Issue | Fix | Impact |\n|------|-------|-----|--------|\n`;
+    for (const w of s.quick_wins) md += `| ${w.page || ''} | ${w.issue || ''} | ${w.fix || ''} | ${w.impact || ''} |\n`;
+    md += '\n';
+  }
+
+  if (s.internal_links) {
+    md += `## Internal Links\n\n- Total links: ${s.internal_links.total_links}\n- Orphan pages: ${s.internal_links.orphan_pages}\n`;
+    if (s.internal_links.top_pages?.length) {
+      md += '\n| Page | Depth Score |\n|------|-------------|\n';
+      for (const p of s.internal_links.top_pages) md += `| ${p.url || p.label} | ${p.count} |\n`;
+    }
+    md += '\n';
+  }
+
+  if (s.keyword_gaps?.length) {
+    md += `## Keyword Opportunities (${s.keyword_gaps.length})\n\n`;
+    md += `> Keywords identified from your content that could be targeted more aggressively.\n\n`;
+    md += `| Keyword | Coverage | Priority |\n|---------|----------|----------|\n`;
+    for (const g of s.keyword_gaps) md += `| ${g.keyword || ''} | ${g.your_coverage || g.target_count || 'low'} | ${g.priority || ''} |\n`;
+    md += '\n';
+  }
+
+  if (s.top_keyword_gaps?.length) {
+    md += `## Top Keyword Gaps\n\n`;
+    md += `| Keyword | Frequency | Your Count | Gap |\n|---------|-----------|------------|-----|\n`;
+    for (const g of s.top_keyword_gaps) {
+      const freq = g.total || g.competitor_count || '';
+      const tgt = g.target || 0;
+      const gap = freq ? (Number(freq) - Number(tgt)) || freq : '';
+      md += `| ${g.keyword || ''} | ${freq} | ${tgt} | ${gap} |\n`;
+    }
+    md += '\n';
+  }
+
+  if (s.long_tails?.length) {
+    md += `## Long-tail Opportunities (${s.long_tails.length})\n\n`;
+    md += `> Lower competition, higher conversion. Each maps to a parent cluster and content type.\n\n`;
+    md += `| Phrase | Parent | Opportunity |\n|-------|--------|-------------|\n`;
+    for (const l of s.long_tails) {
+      const parent = l.parent || l.keyword || inferLongTailParent(l.phrase, s.keyword_gaps) || '';
+      const opportunity = l.opportunity || l.rationale || inferLongTailOpportunity(l) || '';
+      md += `| ${l.phrase || ''} | ${parent} | ${opportunity} |\n`;
+    }
+    md += '\n';
+  }
+
+  if (s.new_pages?.length) {
+    md += `## New Pages to Create (${s.new_pages.length})\n\n`;
+    md += `> Each targets a keyword gap. Create with proper H1, schema, and internal links.\n\n`;
+    md += `| Title | Target Keyword | Rationale |\n|-------|----------------|----------|\n`;
+    for (const p of s.new_pages) {
+      md += `| ${p.title || ''} | ${p.target_keyword || ''} | ${p.rationale || p.why || p.content_angle || ''} |\n`;
+    }
+    md += '\n';
+  }
+
+  if (s.content_gaps?.length) {
+    md += `## Content Gaps (${s.content_gaps.length})\n\n`;
+    md += `> Topics you should cover but currently don't.\n\n`;
+    md += `| Topic | Gap | Suggestion |\n|-------|-----|------------|\n`;
+    for (const g of s.content_gaps) {
+      const gap = g.gap || (g.covered_by?.length ? `Covered by ${g.covered_by.join(', ')}` : '') || g.why_it_matters || '';
+      const suggestion = g.suggestion || g.suggested_title || (g.format ? `Create a ${g.format} covering this topic` : '') || '';
+      md += `| ${g.topic || ''} | ${gap} | ${suggestion} |\n`;
+    }
+    md += '\n';
+  }
+
+  if (s.keyword_inventor?.length) {
+    md += `## Keyword Ideas (${s.keyword_inventor.length})\n\n`;
+    md += `| Phrase | Cluster | Potential |\n|-------|---------|----------|\n`;
+    for (const k of s.keyword_inventor.slice(0, 50)) {
+      md += `| ${k.phrase || ''} | ${k.cluster || ''} | ${k.potential || k.volume || inferPotential(k) || ''} |\n`;
+    }
+    if (s.keyword_inventor.length > 50) md += `\n_...and ${s.keyword_inventor.length - 50} more._\n`;
+    md += '\n';
+  }
+
+  if (s.positioning) {
+    md += `## Positioning Strategy\n\n`;
+    if (s.positioning.open_angle) md += `**Open angle:** ${s.positioning.open_angle}\n\n`;
+    if (s.positioning.target_differentiator) md += `**Differentiator:** ${s.positioning.target_differentiator}\n\n`;
+    if (s.positioning.competitor_map) md += `**Competitor map:** ${s.positioning.competitor_map}\n\n`;
+  }
+
+  if (s.crawl_stats) {
+    md += `## Crawl Info\n\n- Last crawl: ${s.crawl_stats.lastCrawl || date}\n- Extracted pages: ${s.crawl_stats.extractedPages || 0}\n`;
+  }
+
+  return md;
+}

package/package.json

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