seo-intel 1.0.0

package/exports/competitive.js

@@ -0,0 +1,186 @@
+import { collectTop, makeAction, normalizeActionType, normalizePriority, sortActions } from './heuristics.js';
+import { getEntityCoverage, getLatestAnalysis, getProjectDomains, getSchemaCoverage } from './queries.js';
+
+function aggregateEntityCoverage(rows) {
+  const target = new Set();
+  const competitors = new Map();
+
+  for (const row of rows) {
+    const parsed = Array.isArray(row.primary_entities) ? row.primary_entities : (() => {
+      try { return JSON.parse(row.primary_entities || '[]'); } catch { return []; }
+    })();
+    for (const entity of parsed) {
+      const key = String(entity || '').trim();
+      if (!key) continue;
+      if (row.role === 'competitor') {
+        if (!competitors.has(key)) competitors.set(key, new Set());
+        competitors.get(key).add(row.domain);
+      } else {
+        target.add(key);
+      }
+    }
+  }
+
+  return { target, competitors };
+}
+
+export function buildCompetitiveActions(db, project, options = {}) {
+  const { vsDomain = null } = options;
+  const analysis = getLatestAnalysis(db, project);
+  const competitorDomains = getProjectDomains(db, project).filter(d => d.role === 'competitor' && (!vsDomain || d.domain === vsDomain));
+  if (!competitorDomains.length) return [];
+
+  const actions = [];
+
+  if (analysis) {
+    for (const gap of analysis.keyword_gaps || []) {
+      actions.push(makeAction({
+        id: `competitive-keyword-${String(gap.keyword || '').toLowerCase().replace(/[^a-z0-9]+/g, '-')}`,
+        type: normalizeActionType(gap.suggested_action === 'new_page' ? 'new_page' : 'improve', 'new_page'),
+        priority: normalizePriority(gap.priority, 'medium'),
+        area: 'content',
+        title: `Close keyword gap: ${gap.keyword}`,
+        why: `${gap.keyword} is covered by ${gap.competitor_count || competitorDomains.length} competitor domains and maps to ${gap.intent || 'search'} intent demand.`,
+        evidence: collectTop([
+          gap.suggested_page ? `Suggested page: ${gap.suggested_page}` : null,
+          gap.difficulty ? `Difficulty: ${gap.difficulty}` : null,
+          gap.intent ? `Intent: ${gap.intent}` : null,
+        ].filter(Boolean), 5),
+        implementationHints: [
+          gap.suggested_page ? `Create or upgrade ${gap.suggested_page} around the target query.` : 'Create a dedicated landing page for this query cluster.',
+          'Benchmark the top competitor pages for headings, examples, proof, and schema coverage.',
+        ],
+      }));
+    }
+
+    for (const gap of analysis.content_gaps || []) {
+      actions.push(makeAction({
+        id: `competitive-content-${String(gap.topic || '').toLowerCase().replace(/[^a-z0-9]+/g, '-')}`,
+        type: gap.format === 'comparison' || gap.format === 'landing' ? 'new_page' : 'improve',
+        priority: 'high',
+        area: 'content',
+        title: `Cover topic gap: ${gap.topic}`,
+        why: gap.why_it_matters || 'Competitors cover this topic and the target site currently does not.',
+        evidence: collectTop([
+          gap.suggested_title ? `Suggested title: ${gap.suggested_title}` : null,
+          Array.isArray(gap.covered_by) && gap.covered_by.length ? `Covered by: ${gap.covered_by.join(', ')}` : null,
+          gap.format ? `Format: ${gap.format}` : null,
+        ].filter(Boolean), 5),
+        implementationHints: [
+          gap.suggested_title ? `Build the piece around: ${gap.suggested_title}` : 'Publish a dedicated piece for this topic.',
+          'Include comparison tables, proof, examples, and intent-matched CTAs.',
+        ],
+      }));
+    }
+
+    for (const gap of analysis.technical_gaps || []) {
+      actions.push(makeAction({
+        id: `competitive-schema-${String(gap.gap || '').toLowerCase().replace(/[^a-z0-9]+/g, '-')}`,
+        type: 'add_schema',
+        priority: 'medium',
+        area: 'schema',
+        title: `Match competitor schema pattern: ${gap.gap}`,
+        why: gap.fix || 'Competitors have richer structured data coverage on relevant templates.',
+        evidence: collectTop([
+          Array.isArray(gap.competitors_with_it) && gap.competitors_with_it.length ? `Used by: ${gap.competitors_with_it.join(', ')}` : null,
+        ].filter(Boolean), 3),
+        implementationHints: [
+          gap.fix || 'Add the schema type to matching target templates.',
+          'Validate rich result eligibility in Google Rich Results Test after rollout.',
+        ],
+      }));
+    }
+  }
+
+  const schemaCoverage = getSchemaCoverage(db, project, vsDomain);
+  const targetSchemaTypes = new Set(schemaCoverage.filter(r => r.role !== 'competitor').map(r => r.schema_type));
+  const competitorSchemaMap = new Map();
+  for (const row of schemaCoverage.filter(r => r.role === 'competitor')) {
+    if (!competitorSchemaMap.has(row.schema_type)) competitorSchemaMap.set(row.schema_type, { domains: new Set(), pages: 0 });
+    competitorSchemaMap.get(row.schema_type).domains.add(row.domain);
+    competitorSchemaMap.get(row.schema_type).pages += row.page_count || 0;
+  }
+
+  for (const [schemaType, info] of competitorSchemaMap.entries()) {
+    if (targetSchemaTypes.has(schemaType)) continue;
+    actions.push(makeAction({
+      id: `competitive-schema-coverage-${String(schemaType).toLowerCase()}`,
+      type: 'add_schema',
+      priority: info.domains.size >= 2 ? 'high' : 'medium',
+      area: 'schema',
+      title: `Add ${schemaType} schema where competitors already do`,
+      why: 'Competitors are enriching equivalent pages with schema types the target site has not deployed.',
+      evidence: collectTop([
+        `Competitors using it: ${[...info.domains].join(', ')}`,
+        `Competitor pages with this schema: ${info.pages}`,
+      ], 5),
+      implementationHints: [
+        `Map ${schemaType} to the closest target template and ship JSON-LD at render time.`,
+        'Prioritize pages where this schema can improve CTR or eligibility for enhanced SERP features.',
+      ],
+    }));
+  }
+
+  const entityCoverage = aggregateEntityCoverage(getEntityCoverage(db, project, vsDomain));
+  const missingEntities = [...entityCoverage.competitors.entries()]
+    .filter(([entity]) => !entityCoverage.target.has(entity))
+    .sort((a, b) => b[1].size - a[1].size)
+    .slice(0, 8);
+
+  for (const [entity, domains] of missingEntities) {
+    actions.push(makeAction({
+      id: `competitive-entity-${String(entity).toLowerCase().replace(/[^a-z0-9]+/g, '-')}`,
+      type: 'improve',
+      priority: domains.size >= 3 ? 'high' : 'medium',
+      area: 'content',
+      title: `Expand entity coverage around “${entity}”`,
+      why: 'Competitors repeatedly mention this entity while the target domain set does not.',
+      evidence: collectTop([
+        `Competitors covering it: ${[...domains].join(', ')}`,
+      ], 4),
+      implementationHints: [
+        'Add the entity to relevant product, docs, or comparison pages with supporting context, examples, and links.',
+        'If the entity deserves dedicated intent coverage, create a focused landing page or guide.',
+      ],
+    }));
+  }
+
+  if (analysis?.new_pages?.length) {
+    for (const page of analysis.new_pages.slice(0, 6)) {
+      actions.push(makeAction({
+        id: `competitive-new-page-${String(page.title || '').toLowerCase().replace(/[^a-z0-9]+/g, '-')}`,
+        type: 'new_page',
+        priority: normalizePriority(page.priority, 'medium'),
+        area: 'content',
+        title: `Build page: ${page.title}`,
+        why: page.why || 'Analysis recommends a dedicated page to win competitor demand.',
+        evidence: collectTop((page.placement || []).map(p => `${p.property}: ${p.url}`), 5),
+        implementationHints: [
+          page.content_angle ? `Angle: ${page.content_angle}` : null,
+          'Use the best-fit property and internal link it from high-authority hub pages.',
+        ].filter(Boolean),
+      }));
+    }
+  }
+
+  if (analysis?.positioning?.open_angle) {
+    actions.push(makeAction({
+      id: 'competitive-positioning-open-angle',
+      type: 'improve',
+      priority: 'medium',
+      area: 'content',
+      title: 'Sharpen positioning around the open market angle',
+      why: analysis.positioning.open_angle,
+      evidence: collectTop([
+        analysis.positioning.target_differentiator ? `Differentiator: ${analysis.positioning.target_differentiator}` : null,
+        analysis.positioning.competitor_map ? `Competitor map: ${analysis.positioning.competitor_map}` : null,
+      ].filter(Boolean), 4),
+      implementationHints: [
+        'Reflect the differentiator in homepage hero copy, solution pages, and comparison pages.',
+        'Use repeated phrasing across title tags, H1s, and product proof sections to build topical association.',
+      ],
+    }));
+  }
+
+  return sortActions(actions);
+}

package/exports/heuristics.js

@@ -0,0 +1,67 @@
+function slugify(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'item';
+}
+
+export function makeAction(overrides = {}) {
+  const base = {
+    id: overrides.id || `${overrides.area || 'general'}-${overrides.type || 'fix'}-${slugify(overrides.title)}`,
+    type: 'fix',
+    priority: 'medium',
+    area: 'content',
+    title: '',
+    why: '',
+    evidence: [],
+    implementationHints: [],
+  };
+
+  return {
+    ...base,
+    ...overrides,
+    evidence: Array.isArray(overrides.evidence) ? overrides.evidence.filter(Boolean) : [],
+    implementationHints: Array.isArray(overrides.implementationHints) ? overrides.implementationHints.filter(Boolean) : [],
+  };
+}
+
+export function priorityWeight(priority) {
+  return ({ critical: 4, high: 3, medium: 2, low: 1 })[priority] || 0;
+}
+
+export function summarizeActions(actions) {
+  return actions.reduce((acc, action) => {
+    acc[action.priority] = (acc[action.priority] || 0) + 1;
+    return acc;
+  }, { critical: 0, high: 0, medium: 0, low: 0 });
+}
+
+export function sortActions(actions) {
+  return [...actions].sort((a, b) => {
+    const priorityDelta = priorityWeight(b.priority) - priorityWeight(a.priority);
+    if (priorityDelta !== 0) return priorityDelta;
+    return a.title.localeCompare(b.title);
+  });
+}
+
+export function normalizePriority(priority, fallback = 'medium') {
+  const value = String(priority || '').toLowerCase();
+  return ['critical', 'high', 'medium', 'low'].includes(value) ? value : fallback;
+}
+
+export function normalizeActionType(type, fallback = 'improve') {
+  const value = String(type || '').toLowerCase();
+  return ['fix', 'new_page', 'improve', 'add_schema'].includes(value) ? value : fallback;
+}
+
+export function inferPriorityFromCount(count, thresholds = { critical: 20, high: 10, medium: 3 }) {
+  if (count >= thresholds.critical) return 'critical';
+  if (count >= thresholds.high) return 'high';
+  if (count >= thresholds.medium) return 'medium';
+  return 'low';
+}
+
+export function collectTop(values, limit = 5) {
+  return [...values].slice(0, limit);
+}

package/exports/queries.js

@@ -0,0 +1,197 @@
+const SAFE_JSON_FALLBACK = [];
+
+export function parseJson(value, fallback = SAFE_JSON_FALLBACK) {
+  if (value == null || value === '') return Array.isArray(fallback) ? [...fallback] : fallback;
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return Array.isArray(fallback) ? [...fallback] : fallback;
+  }
+}
+
+export function getProjectDomains(db, project) {
+  return db.prepare(`
+    SELECT id, domain, role
+    FROM domains
+    WHERE project = ?
+    ORDER BY CASE role WHEN 'target' THEN 0 WHEN 'owned' THEN 1 ELSE 2 END, domain
+  `).all(project);
+}
+
+export function getTargetDomains(domains) {
+  return domains.filter(d => d.role === 'target' || d.role === 'owned');
+}
+
+export function getCompetitorDomains(domains, vsDomain = null) {
+  return domains.filter(d => d.role === 'competitor' && (!vsDomain || d.domain === vsDomain));
+}
+
+export function getProjectPageCount(db, project) {
+  return db.prepare(`
+    SELECT COUNT(*) AS count
+    FROM pages p
+    JOIN domains d ON d.id = p.domain_id
+    WHERE d.project = ?
+  `).get(project)?.count || 0;
+}
+
+export function assertHasCrawlData(db, project) {
+  const count = getProjectPageCount(db, project);
+  if (!count) {
+    const err = new Error('No crawl data found. Run `crawl` first.');
+    err.code = 'NO_CRAWL_DATA';
+    throw err;
+  }
+  return count;
+}
+
+export function getLatestAnalysis(db, project) {
+  const row = db.prepare(`
+    SELECT *
+    FROM analyses
+    WHERE project = ?
+    ORDER BY generated_at DESC
+    LIMIT 1
+  `).get(project);
+
+  if (!row) return null;
+
+  return {
+    ...row,
+    keyword_gaps: parseJson(row.keyword_gaps, []),
+    content_gaps: parseJson(row.content_gaps, []),
+    technical_gaps: parseJson(row.technical_gaps, []),
+    new_pages: parseJson(row.new_pages, []),
+    positioning: parseJson(row.positioning, null),
+  };
+}
+
+export function getTechnicalDataset(db, project) {
+  return db.prepare(`
+    SELECT
+      p.id,
+      p.url,
+      p.status_code,
+      p.word_count,
+      p.click_depth,
+      p.is_indexable,
+      d.domain,
+      d.role,
+      COALESCE(e.meta_desc, '') AS meta_desc,
+      COALESCE(e.h1, '') AS h1,
+      COALESCE(t.has_canonical, 0) AS has_canonical,
+      COALESCE(t.has_og_tags, 0) AS has_og_tags,
+      COALESCE(t.has_schema, 0) AS has_schema,
+      COALESCE((SELECT COUNT(*) FROM page_schemas ps WHERE ps.page_id = p.id), 0) AS schema_count,
+      COALESCE((SELECT COUNT(*) FROM page_schemas ps WHERE ps.page_id = p.id AND LOWER(ps.schema_type) = 'breadcrumblist'), 0) AS breadcrumb_count,
+      COALESCE((SELECT COUNT(*) FROM headings h WHERE h.page_id = p.id AND h.level = 1), 0) AS h1_count,
+      COALESCE((
+        SELECT COUNT(*)
+        FROM links l
+        JOIN pages src ON src.id = l.source_id
+        JOIN domains srcd ON srcd.id = src.domain_id
+        WHERE srcd.project = d.project
+          AND l.is_internal = 1
+          AND l.target_url = p.url
+      ), 0) AS inbound_internal_links,
+      COALESCE((
+        SELECT COUNT(*)
+        FROM pages child
+        JOIN domains childd ON childd.id = child.domain_id
+        WHERE childd.project = d.project
+          AND child.status_code BETWEEN 300 AND 399
+          AND EXISTS (
+            SELECT 1 FROM links l2 WHERE l2.source_id = p.id AND l2.target_url = child.url
+          )
+      ), 0) AS redirects_linked_from_page
+    FROM pages p
+    JOIN domains d ON d.id = p.domain_id
+    LEFT JOIN technical t ON t.page_id = p.id
+    LEFT JOIN extractions e ON e.page_id = p.id
+    WHERE d.project = ?
+      AND d.role IN ('target', 'owned')
+    ORDER BY d.role, d.domain, p.click_depth, p.url
+  `).all(project);
+}
+
+export function getSchemaCoverage(db, project, vsDomain = null) {
+  const params = [project];
+  let competitorFilter = '';
+  if (vsDomain) {
+    competitorFilter = ' AND (d.role != \'competitor\' OR d.domain = ?)';
+    params.push(vsDomain);
+  }
+
+  return db.prepare(`
+    SELECT
+      ps.schema_type,
+      d.domain,
+      d.role,
+      COUNT(*) AS count,
+      COUNT(DISTINCT p.id) AS page_count
+    FROM page_schemas ps
+    JOIN pages p ON p.id = ps.page_id
+    JOIN domains d ON d.id = p.domain_id
+    WHERE d.project = ?
+      ${competitorFilter}
+    GROUP BY ps.schema_type, d.domain, d.role
+    ORDER BY ps.schema_type, d.role, count DESC
+  `).all(...params);
+}
+
+export function getEntityCoverage(db, project, vsDomain = null) {
+  const params = [project];
+  let competitorFilter = '';
+  if (vsDomain) {
+    competitorFilter = ' AND (d.role != \'competitor\' OR d.domain = ?)';
+    params.push(vsDomain);
+  }
+
+  return db.prepare(`
+    SELECT e.primary_entities, p.url, d.domain, d.role
+    FROM extractions e
+    JOIN pages p ON p.id = e.page_id
+    JOIN domains d ON d.id = p.domain_id
+    WHERE d.project = ?
+      ${competitorFilter}
+  `).all(...params);
+}
+
+export function getHeadingClusterDataset(db, project, vsDomain = null) {
+  const params = [project];
+  let competitorFilter = '';
+  if (vsDomain) {
+    competitorFilter = ' AND (d.role != \'competitor\' OR d.domain = ?)';
+    params.push(vsDomain);
+  }
+
+  return db.prepare(`
+    SELECT h.level, h.text, p.url, p.word_count, d.domain, d.role
+    FROM headings h
+    JOIN pages p ON p.id = h.page_id
+    JOIN domains d ON d.id = p.domain_id
+    WHERE d.project = ?
+      AND h.level IN (1, 2, 3)
+      ${competitorFilter}
+    ORDER BY d.role, d.domain, p.url, h.level
+  `).all(...params);
+}
+
+export function getPagePatternDataset(db, project, vsDomain = null) {
+  const params = [project];
+  let competitorFilter = '';
+  if (vsDomain) {
+    competitorFilter = ' AND (d.role != \'competitor\' OR d.domain = ?)';
+    params.push(vsDomain);
+  }
+
+  return db.prepare(`
+    SELECT p.url, p.word_count, p.click_depth, d.domain, d.role
+    FROM pages p
+    JOIN domains d ON d.id = p.domain_id
+    WHERE d.project = ?
+      ${competitorFilter}
+    ORDER BY d.role, d.domain, p.url
+  `).all(...params);
+}

package/exports/suggestive.js

@@ -0,0 +1,230 @@
+import { collectTop, makeAction, sortActions } from './heuristics.js';
+import { getEntityCoverage, getHeadingClusterDataset, getPagePatternDataset, getSchemaCoverage } from './queries.js';
+
+function getUrlPath(url) {
+  try {
+    return new URL(url).pathname || '/';
+  } catch {
+    return '/';
+  }
+}
+
+function classifyPath(pathname) {
+  const path = pathname.toLowerCase();
+  if (path === '/' || !path) return 'homepage';
+  if (/docs|documentation|api|reference/.test(path)) return 'docs';
+  if (/pricing|security|status|sla|compliance|trust|rate-limit/.test(path)) return 'trust';
+  if (/dashboard|studio|app|console|portal/.test(path)) return 'dashboards';
+  if (/compare|alternative|vs-/.test(path)) return 'comparison';
+  if (/guide|tutorial|how-to|learn|academy/.test(path)) return 'tutorials';
+  if (/product|products|platform|solutions|use-cases|features/.test(path)) return 'product-pages';
+  if (/onboarding|get-started|quickstart|start-here|sign-up|signup/.test(path)) return 'onboarding';
+  return 'other';
+}
+
+function normalizeHeadingTopic(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .replace(/\b(what|why|how|when|where|best|your|with|for|the|and|from|into|using|guide|tutorial|overview|introduction)\b/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function buildEntitySets(rows) {
+  const target = new Set();
+  const competitors = new Map();
+  for (const row of rows) {
+    let values = [];
+    try { values = JSON.parse(row.primary_entities || '[]'); } catch { values = []; }
+    for (const entity of values) {
+      const key = String(entity || '').trim();
+      if (!key) continue;
+      if (row.role === 'competitor') {
+        if (!competitors.has(key)) competitors.set(key, new Set());
+        competitors.get(key).add(row.domain);
+      } else {
+        target.add(key);
+      }
+    }
+  }
+  return { target, competitors };
+}
+
+export function buildSuggestiveActions(db, project, options = {}) {
+  const { vsDomain = null, scope = 'all' } = options;
+  const actions = [];
+  const pages = getPagePatternDataset(db, project, vsDomain);
+  const headings = getHeadingClusterDataset(db, project, vsDomain);
+  const schemas = getSchemaCoverage(db, project, vsDomain);
+  const entities = buildEntitySets(getEntityCoverage(db, project, vsDomain));
+
+  const targetCategories = new Set();
+  const competitorCategories = new Map();
+  const targetPaths = new Set();
+
+  for (const page of pages) {
+    const path = getUrlPath(page.url);
+    const category = classifyPath(path);
+    if (page.role === 'competitor') {
+      if (!competitorCategories.has(category)) competitorCategories.set(category, []);
+      competitorCategories.get(category).push(page);
+    } else {
+      targetCategories.add(category);
+      targetPaths.add(path.toLowerCase());
+    }
+  }
+
+  const categoryScopeMap = {
+    docs: new Set(['docs', 'tutorials']),
+    'product-pages': new Set(['product-pages', 'comparison', 'trust']),
+    dashboards: new Set(['dashboards']),
+    onboarding: new Set(['onboarding', 'trust']),
+    all: null,
+  };
+  const allowedCategories = categoryScopeMap[scope] || null;
+
+  for (const [category, compPages] of competitorCategories.entries()) {
+    if (category === 'homepage' || category === 'other') continue;
+    if (allowedCategories && !allowedCategories.has(category)) continue;
+    if (targetCategories.has(category)) continue;
+
+    const samplePaths = compPages.slice(0, 4).map(p => `${p.domain}${getUrlPath(p.url)}`);
+    const titleMap = {
+      docs: 'Create documentation/reference pages competitors already use',
+      trust: 'Publish trust pages competitors rely on for conversion',
+      comparison: 'Launch competitor comparison pages',
+      tutorials: 'Build tutorial and guide content clusters',
+      'product-pages': 'Add dedicated product or solution landing pages',
+      dashboards: 'Expose dashboards/console entry pages to capture tool intent',
+      onboarding: 'Create onboarding and quickstart paths',
+    };
+
+    actions.push(makeAction({
+      id: `suggestive-category-${category}`,
+      type: 'new_page',
+      priority: compPages.length >= 5 ? 'high' : 'medium',
+      area: 'structure',
+      title: titleMap[category] || `Add ${category} page type coverage`,
+      why: `Competitors have ${compPages.length} ${category} pages while the target domain set has none in this pattern.`,
+      evidence: collectTop(samplePaths, 6),
+      implementationHints: [
+        'Start with the highest commercial-intent template competitors repeat most often.',
+        'Link the new section from navigation, footer, and relevant hub pages so it becomes crawlable fast.',
+      ],
+    }));
+  }
+
+  const competitorTopics = new Map();
+  const targetTopics = new Set();
+  for (const row of headings) {
+    const topic = normalizeHeadingTopic(row.text);
+    if (!topic || topic.length < 10) continue;
+    if (row.role === 'competitor') {
+      if (!competitorTopics.has(topic)) competitorTopics.set(topic, { domains: new Set(), pages: [] });
+      competitorTopics.get(topic).domains.add(row.domain);
+      competitorTopics.get(topic).pages.push(`${row.domain}${getUrlPath(row.url)}`);
+    } else {
+      targetTopics.add(topic);
+    }
+  }
+
+  for (const [topic, info] of [...competitorTopics.entries()].sort((a, b) => b[1].domains.size - a[1].domains.size).slice(0, 10)) {
+    if (targetTopics.has(topic)) continue;
+    actions.push(makeAction({
+      id: `suggestive-topic-${topic.replace(/[^a-z0-9]+/g, '-')}`,
+      type: 'new_page',
+      priority: info.domains.size >= 3 ? 'high' : 'medium',
+      area: 'content',
+      title: `Cover missing topic cluster: ${topic}`,
+      why: 'Competitors repeatedly organize content around this heading cluster and the target site does not.',
+      evidence: collectTop([
+        `Competitors: ${[...info.domains].join(', ')}`,
+        ...info.pages.slice(0, 4),
+      ], 5),
+      implementationHints: [
+        'Turn this topic into a guide, docs page, or landing page depending on user intent.',
+        'Reuse the subtopics competitors surface in H2/H3 structure, but add stronger proof and differentiation.',
+      ],
+    }));
+  }
+
+  for (const [entity, domains] of [...entities.competitors.entries()].filter(([entity]) => !entities.target.has(entity)).sort((a, b) => b[1].size - a[1].size).slice(0, 6)) {
+    actions.push(makeAction({
+      id: `suggestive-entity-${entity.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`,
+      type: 'improve',
+      priority: domains.size >= 3 ? 'high' : 'medium',
+      area: 'content',
+      title: `Add use-case coverage around entity: ${entity}`,
+      why: 'Competitor pages keep referencing this entity, which suggests buyer or developer demand the target has not served yet.',
+      evidence: collectTop([
+        `Competitors mentioning it: ${[...domains].join(', ')}`,
+      ], 4),
+      implementationHints: [
+        'Decide whether this belongs in docs, a comparison page, a feature page, or a tutorial.',
+        'Add concrete examples, code snippets, or workflows tied to the entity.',
+      ],
+    }));
+  }
+
+  const targetSchemaTypes = new Set(schemas.filter(s => s.role !== 'competitor').map(s => s.schema_type));
+  const missingSchemaTypes = new Map();
+  for (const row of schemas.filter(s => s.role === 'competitor')) {
+    if (targetSchemaTypes.has(row.schema_type)) continue;
+    if (!missingSchemaTypes.has(row.schema_type)) missingSchemaTypes.set(row.schema_type, new Set());
+    missingSchemaTypes.get(row.schema_type).add(row.domain);
+  }
+
+  for (const [schemaType, domains] of [...missingSchemaTypes.entries()].slice(0, 5)) {
+    actions.push(makeAction({
+      id: `suggestive-schema-${schemaType.toLowerCase()}`,
+      type: 'add_schema',
+      priority: domains.size >= 2 ? 'medium' : 'low',
+      area: 'schema',
+      title: `Plan content/templates that support ${schemaType} schema`,
+      why: 'Competitors use this schema type on pages or features the target site likely has not built yet.',
+      evidence: collectTop([
+        `Competitors using it: ${[...domains].join(', ')}`,
+      ], 3),
+      implementationHints: [
+        `Identify which future page template should emit ${schemaType} schema.`,
+        'Design the page structure so the schema fields are naturally supported in the content model.',
+      ],
+    }));
+  }
+
+  const targetAvgWords = average(pages.filter(p => p.role !== 'competitor').map(p => p.word_count || 0));
+  const competitorInvestments = new Map();
+  for (const page of pages.filter(p => p.role === 'competitor')) {
+    const category = classifyPath(getUrlPath(page.url));
+    if (!competitorInvestments.has(category)) competitorInvestments.set(category, []);
+    competitorInvestments.get(category).push(page.word_count || 0);
+  }
+
+  for (const [category, words] of competitorInvestments.entries()) {
+    if (allowedCategories && !allowedCategories.has(category)) continue;
+    const avg = average(words);
+    if (avg < 300 || avg <= targetAvgWords * 1.5) continue;
+    actions.push(makeAction({
+      id: `suggestive-depth-${category}`,
+      type: 'improve',
+      priority: avg > 1200 ? 'high' : 'medium',
+      area: 'content',
+      title: `Invest in deeper ${category} content`,
+      why: `Competitors average ${Math.round(avg)} words on ${category} pages versus about ${Math.round(targetAvgWords || 0)} words across the target domain set.`,
+      evidence: collectTop(pages.filter(p => p.role === 'competitor' && classifyPath(getUrlPath(p.url)) === category).slice(0, 4).map(p => `${p.domain}${getUrlPath(p.url)} (${p.word_count || 0} words)`), 4),
+      implementationHints: [
+        'Add examples, implementation details, FAQs, trust proof, and comparisons instead of pure feature fluff.',
+        'Prioritize page types that map to high-intent keywords or repeated competitor templates.',
+      ],
+    }));
+  }
+
+  return sortActions(actions);
+}
+
+function average(values) {
+  const filtered = values.filter(v => Number.isFinite(v) && v > 0);
+  if (!filtered.length) return 0;
+  return filtered.reduce((sum, value) => sum + value, 0) / filtered.length;
+}