@houseofmvps/claude-rank 1.5.0 → 1.7.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-rank",
   "description": "The most comprehensive SEO/GEO/AEO plugin for Claude Code. Audit, fix, and dominate search.",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "author": {
     "name": "Houseofmvps",
     "email": "houseofmvps2024@gmail.com"

package/README.md

@@ -2,7 +2,7 @@
 
 <img src="assets/hero-banner.png" alt="claude-rank — SEO/GEO/AEO Plugin for Claude Code" width="100%"/>
 
-### The most comprehensive SEO/GEO/AEO plugin for Claude Code. 80+ rules. Auto-fix everything. Dominate search — traditional and AI.
+### The most comprehensive SEO/GEO/AEO plugin for Claude Code. 80+ rules. Competitive X-Ray. Auto-fix everything. Dominate search — traditional and AI.
 
 [![npm version](https://img.shields.io/npm/v/%40houseofmvps%2Fclaude-rank?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/@houseofmvps/claude-rank)
 [![npm downloads](https://img.shields.io/npm/dm/%40houseofmvps%2Fclaude-rank?style=for-the-badge&logo=npm&color=blue&label=Monthly%20Downloads)](https://www.npmjs.com/package/@houseofmvps/claude-rank)
@@ -70,6 +70,38 @@ $ claude-rank scan https://houseofmvps.com    # Scan any live URL
 ╚════════════════════════════════════════════════╝
 ```
 
+```
+$ claude-rank compete https://competitor.com ./my-project
+
+╔══════════════════════════════════════════════════════════════╗
+║       claude-rank Competitive X-Ray                          ║
+╠══════════════════════════════════════════════════════════════╣
+║  You:   My SaaS Product                                      ║
+║  Them:  Competitor Landing Page                               ║
+╠══════════════════════════════════════════════════════════════╣
+║  Score: You 12  vs  Them 6  (2 ties)                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+You're winning 12-6 (2 ties). Keep pushing.
+
+Signal-by-Signal Comparison:
+  Area                      You           Them          Winner
+  ──────────────────────────────────────────────────────────
+  Title tag                 Yes           Yes           ─ Tie
+  Word count                1,247         386           ✓ You
+  JSON-LD schemas           3             0             ✓ You
+  Conversion signals        5             2             ✓ You
+  Internal links            12            3             ✓ You
+
+Tech Stack:
+  You:  Next.js (Framework), Tailwind CSS (CSS), Stripe (Payments)
+  Them: WordPress (CMS), Google Analytics (Analytics)
+
+Quick Wins — Close These Gaps:
+  ⚠ Open Graph tags
+  ⚠ External links
+```
+
 *Real output from scanning [savemrr.co](https://savemrr.co) (26-page SaaS landing) and [houseofmvps.com](https://houseofmvps.com).*
 
 ---
@@ -106,6 +138,7 @@ Once installed, use slash commands:
 /claude-rank:rank-aeo      # Answer engine optimization audit
 /claude-rank:rank-fix      # Auto-fix all findings in one command
 /claude-rank:rank-schema   # Detect, validate, generate, inject JSON-LD
+/claude-rank:rank-compete  # Competitive X-Ray — compare vs any competitor URL
 ```
 
 **Zero configuration.** claude-rank reads your project structure and self-configures.
@@ -118,6 +151,7 @@ npx @houseofmvps/claude-rank scan https://example.com    # Live URL (crawls up t
 npx @houseofmvps/claude-rank geo ./my-project            # AI search audit
 npx @houseofmvps/claude-rank aeo ./my-project            # Answer engine audit
 npx @houseofmvps/claude-rank schema ./my-project         # Structured data
+npx @houseofmvps/claude-rank compete https://competitor.com .  # Competitive X-Ray
 npx @houseofmvps/claude-rank scan ./site --json          # Raw JSON output
 npx @houseofmvps/claude-rank scan ./site --report html   # Agency-ready HTML report
 npx @houseofmvps/claude-rank scan ./site --threshold 80  # CI/CD mode
@@ -204,6 +238,28 @@ Answer Engine Optimization. Featured snippets, People Also Ask, voice search.
 | **Voice Search** | Concise answers under 29 words (Google voice search average), conversational phrasing |
 | **Rich Results** | Featured image, breadcrumb markup, review schema |
 
+### Competitive X-Ray — NEW in v1.7
+
+Point at any competitor URL. claude-rank fetches their page and compares everything side-by-side:
+
+| Category | What it compares |
+|---|---|
+| **Tech Stack** | Framework, CMS, CDN, analytics, payments, chat — 50+ detection patterns (Wappalyzer-style) |
+| **SEO Signals** | Title, meta description, canonical, Open Graph, Twitter Card, structured data |
+| **Content Depth** | Word count, heading structure, internal/external links |
+| **Conversion Signals** | CTAs, pricing pages, demo booking, social proof, waitlists — 24 patterns |
+| **Structured Data** | JSON-LD count, schema types, validation against Google required fields |
+| **Performance** | Blocking vs deferred scripts, semantic HTML usage |
+
+**Output:** Signal-by-signal comparison table with clear winner per area, tech stack diff, conversion signal diff, quick wins (gaps to close), and your strengths (advantages to keep).
+
+```bash
+claude-rank compete https://competitor.com ./my-project       # Compare vs competitor
+claude-rank compete https://competitor.com ./my-project --json # Raw JSON output
+```
+
+No API keys. No rate limits. No signup. Just point and compare.
+
 ### Core Web Vitals (Lighthouse)
 
 Performance scoring powered by Lighthouse. **No separate install needed** — uses `npx -y lighthouse@12` automatically. Just needs Chrome or Chromium on your machine.
@@ -328,6 +384,7 @@ Each audit produces separate SEO, GEO, and AEO scores plus a composite. Same rul
 | `claude-rank scan https://example.com` | Crawl and scan a live site (up to 50 pages) |
 | `claude-rank geo ./project` | GEO scan — AI search optimization (25 rules) |
 | `claude-rank aeo ./project` | AEO scan — answer engine optimization (12 rules) |
+| `claude-rank compete https://competitor.com .` | Competitive X-Ray — side-by-side comparison |
 | `claude-rank cwv https://example.com` | Core Web Vitals via Lighthouse (optional) |
 | `claude-rank schema ./project` | Detect and validate structured data |
 | `claude-rank scan ./site --report html` | Generate agency-ready HTML report |
@@ -345,6 +402,7 @@ Each audit produces separate SEO, GEO, and AEO scores plus a composite. Same rul
 | `/claude-rank:rank-aeo` | Answer engine optimization audit |
 | `/claude-rank:rank-fix` | Auto-fix all findings in one command |
 | `/claude-rank:rank-schema` | Detect, validate, generate, inject JSON-LD |
+| `/claude-rank:rank-compete` | Competitive X-Ray — compare vs any competitor URL |
 
 ---
 
@@ -366,6 +424,8 @@ Each audit produces separate SEO, GEO, and AEO scores plus a composite. Same rul
 | Multi-page URL crawling (up to 50 pages) | Yes | No |
 | HTML report export (agency-ready) | Yes | No |
 | CI/CD threshold mode | Yes | No |
+| Competitive analysis (X-Ray) | Yes — side-by-side comparison | No |
+| Tech stack detection (50+ patterns) | Yes | No |
 | AI bot detection | 9 bots | Basic |
 | llms.txt generation | Yes | No |
 | robots.txt generation | Yes | No |
@@ -392,7 +452,7 @@ Two terms that matter and are often confused:
 | **SSRF protection** | All HTTP tools block private IPs, cloud metadata, non-HTTP schemes |
 | **No telemetry** | Zero data collection. No phone-home. Ever. |
 | **1 dependency** | `htmlparser2` only (30KB). No native bindings. No `node-gyp`. |
-| **200 tests** | Security module, all scanners, CLI, integration tests |
+| **260 tests** | Security module, all scanners, competitive X-Ray, CLI, integration tests |
 | **File safety** | 10MB read cap. 5MB response cap. Restrictive write permissions. |
 
 See [SECURITY.md](SECURITY.md) for the full vulnerability disclosure policy.
@@ -403,10 +463,10 @@ See [SECURITY.md](SECURITY.md) for the full vulnerability disclosure policy.
 
 | Category | Count | Highlights |
 |---|---|---|
-| **Tools** | 9 | SEO scanner (39 rules), GEO scanner (25 rules), AEO scanner (12 rules), Lighthouse/CWV scanner, schema engine, robots analyzer, sitemap analyzer, llms.txt generator, audit history |
-| **Skills** | 6 | /claude-rank:rank, /claude-rank:rank-audit, /claude-rank:rank-geo, /claude-rank:rank-aeo, /claude-rank:rank-fix, /claude-rank:rank-schema |
+| **Tools** | 10 | SEO scanner (39 rules), GEO scanner (25 rules), AEO scanner (12 rules), Competitive X-Ray (50+ tech patterns), Lighthouse/CWV scanner, schema engine, robots analyzer, sitemap analyzer, llms.txt generator, audit history |
+| **Skills** | 7 | /claude-rank:rank, /claude-rank:rank-audit, /claude-rank:rank-geo, /claude-rank:rank-aeo, /claude-rank:rank-fix, /claude-rank:rank-schema, /claude-rank:rank-compete |
 | **Agents** | 4 | SEO auditor (project-type-aware), GEO auditor (AI readiness levels), AEO auditor (snippet opportunities), Schema auditor (Google validation) |
-| **Commands** | 6 | All slash commands above |
+| **Commands** | 7 | All slash commands above |
 | **Research** | 3 | SEO benchmarks, GEO research, schema catalog |
 
 ---
@@ -449,7 +509,7 @@ Found a bug? Want a new scanner rule? [Open an issue](https://github.com/Houseof
 git clone https://github.com/Houseofmvps/claude-rank.git
 cd claude-rank
 npm install
-npm test              # 200 tests, node:test
+npm test              # 260 tests, node:test
 node tools/<tool>.mjs # No build step
 ```
 

package/bin/claude-rank.mjs

@@ -26,6 +26,15 @@ const positional = args.filter((a, i) => {
 });
 const [command = 'scan', dir = '.'] = positional;
 
+// Reject empty string as target
+if (command !== 'help' && (dir === '' || dir.trim() === '')) {
+  console.error('No target directory or URL provided.\n');
+  console.error('Usage: claude-rank <command> <directory>');
+  console.error('       claude-rank <command> <url>\n');
+  console.error('Run "claude-rank help" for all options.');
+  process.exit(1);
+}
+
 const commands = {
   scan: '../tools/seo-scanner.mjs',
   geo: '../tools/geo-scanner.mjs',
@@ -42,6 +51,7 @@ Commands:
   scan     Run core SEO scanner (default)
   geo      Run GEO (AI search) scanner
   aeo      Run AEO (answer engine) scanner
+  compete  Competitive X-Ray — compare your site vs any competitor URL
   cwv      Run Core Web Vitals / Lighthouse audit (needs Chrome installed)
   schema   Detect and validate structured data
   help     Show this help message
@@ -64,6 +74,7 @@ Examples:
   claude-rank scan https://savemrr.co
   claude-rank scan https://savemrr.co --pages 10
   claude-rank scan https://savemrr.co --single
+  claude-rank compete https://competitor.com ./my-project
   npx @houseofmvps/claude-rank geo .
   claude-rank scan ./site --json
   claude-rank scan ./site --report html
@@ -73,6 +84,36 @@ Examples:
   process.exit(0);
 }
 
+// Handle compete command separately (requires URL + local dir)
+if (command === 'compete') {
+  const competitorUrl = dir;
+  if (!competitorUrl.startsWith('http://') && !competitorUrl.startsWith('https://')) {
+    console.error('The compete command requires a competitor URL.');
+    console.error('Usage: claude-rank compete <competitor-url> [your-directory]');
+    process.exit(1);
+  }
+
+  // The local dir is the third positional arg (after 'compete' and URL)
+  const localDir = positional[2] || '.';
+  const { resolve: resolvePath } = await import('path');
+
+  const { compete } = await import(new URL('../tools/compete-scanner.mjs', import.meta.url));
+  const { formatCompeteReport } = await import(new URL('../tools/lib/formatter.mjs', import.meta.url));
+
+  try {
+    const result = await compete(competitorUrl, resolvePath(localDir));
+    if (jsonFlag) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatCompeteReport(result));
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
 // Handle CWV command separately (requires URL, optional dependency)
 if (command === 'cwv') {
   const url = dir.startsWith('http://') || dir.startsWith('https://') ? dir : null;

package/commands/rank-aeo.md

@@ -1,3 +1,22 @@
 ---
 description: "Answer engine optimization. Featured snippets, voice search, People Also Ask."
 ---
+
+## Syntax
+
+```
+/claude-rank:rank-aeo [directory]
+```
+
+## What It Does
+
+1. Checks for FAQPage, HowTo, speakable schema
+2. Analyzes snippet fitness (answer length, numbered steps, direct answers)
+3. Evaluates voice search readiness (20-35 word concise answers)
+4. Generates missing schema (FAQPage, HowTo, speakable)
+
+## Example
+
+```
+/claude-rank:rank-aeo ./my-blog
+```

package/commands/rank-audit.md

@@ -1,3 +1,26 @@
 ---
 description: "Full SEO/GEO/AEO audit with auto-fix. Scans, reports, fixes, and verifies."
 ---
+
+## Syntax
+
+```
+/claude-rank:rank-audit [directory]
+```
+
+Directory defaults to `.` (current directory) if omitted.
+
+## What It Does
+
+1. Runs SEO scanner (39+ rules), GEO scanner (34 rules), AEO scanner (12 rules)
+2. Reports findings grouped by severity
+3. Auto-fixes: generates robots.txt, sitemap.xml, llms.txt, JSON-LD schema
+4. Re-scans to verify improvements
+5. Saves score history for trend tracking
+6. Outputs Google Search Console + Bing Webmaster Tools action plan
+
+## Example
+
+```
+/claude-rank:rank-audit ./my-saas-landing
+```

package/commands/rank-compete.md

@@ -0,0 +1,33 @@
+---
+description: "Competitive X-Ray. Compare your site's SEO signals, tech stack, content depth, and conversion patterns against any competitor URL."
+---
+
+## Syntax
+
+```
+/claude-rank:rank-compete <competitor-url> [your-directory]
+```
+
+## What It Does
+
+1. **Fetches** the competitor URL (with SSRF protection and redirect tracking)
+2. **Detects tech stack** — frameworks, CDNs, analytics, payments, chat tools (50+ patterns)
+3. **Compares SEO signals** — meta tags, Open Graph, structured data, canonical URLs
+4. **Measures content depth** — word count, heading structure, internal/external links
+5. **Identifies conversion signals** — CTAs, pricing pages, social proof, demo booking
+6. **Outputs side-by-side comparison** with signal-by-signal verdicts (You vs Them)
+
+## Output
+
+- Score summary (wins, losses, ties)
+- Signal-by-signal comparison table
+- Tech stack comparison
+- Conversion signal comparison
+- Quick wins (gaps to close)
+- Your strengths (advantages to keep)
+
+## Example
+
+```
+/claude-rank:rank-compete https://competitor.com ./my-project
+```

package/commands/rank-fix.md

@@ -1,3 +1,22 @@
 ---
 description: "Auto-fix all SEO/GEO/AEO findings. One command to fix everything."
 ---
+
+## Syntax
+
+```
+/claude-rank:rank-fix [directory]
+```
+
+## What It Does
+
+1. Runs all scanners to identify issues
+2. Generates missing files: robots.txt, sitemap.xml, llms.txt
+3. Injects missing meta tags, JSON-LD schema
+4. Re-scans and shows before/after score comparison
+
+## Example
+
+```
+/claude-rank:rank-fix .
+```

package/commands/rank-geo.md

@@ -1,3 +1,22 @@
 ---
 description: "AI search optimization audit. Optimize for ChatGPT, Perplexity, Google AI Overviews, Gemini."
 ---
+
+## Syntax
+
+```
+/claude-rank:rank-geo [directory]
+```
+
+## What It Does
+
+1. Checks robots.txt for AI bot access (GPTBot, PerplexityBot, ClaudeBot, etc.)
+2. Verifies llms.txt, structured data, and content structure for AI citation readiness
+3. Fixes: unblocks AI bots, generates llms.txt, adds Organization/Author schema
+4. Provides GSC/Bing submission steps for AI recrawl
+
+## Example
+
+```
+/claude-rank:rank-geo ./my-site
+```

package/commands/rank-schema.md

@@ -1,3 +1,23 @@
 ---
 description: "Structured data management. Detect, validate, generate, and inject JSON-LD schema."
 ---
+
+## Syntax
+
+```
+/claude-rank:rank-schema [directory]
+```
+
+## What It Does
+
+1. **Detect** — finds all JSON-LD in HTML files
+2. **Validate** — checks against Google's required fields (14 schema types)
+3. **Recommend** — suggests missing schema based on page content
+4. **Generate** — creates JSON-LD for Organization, Article, FAQPage, HowTo, etc.
+5. **Verify** — re-runs detection to confirm injection
+
+## Example
+
+```
+/claude-rank:rank-schema ./my-site
+```

package/commands/rank.md

@@ -2,4 +2,27 @@
 description: "SEO/GEO/AEO audit, analysis, and optimization. The most comprehensive search toolkit for Claude Code."
 ---
 
-Routes to rank sub-commands. Run `/rank` alone for a quick health check showing all scores. Use `/rank audit` for full audit with auto-fix.
+## Syntax
+
+```
+/claude-rank:rank [subcommand] [directory]
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|---|---|
+| *(none)* | Quick health check — shows SEO, GEO, AEO scores |
+| `audit` | Full 9-phase audit with auto-fix + GSC action plan |
+| `geo` | AI search optimization (ChatGPT, Perplexity, Gemini) |
+| `aeo` | Answer engine optimization (snippets, voice, PAA) |
+| `fix` | Auto-fix all findings in one command |
+| `schema` | Detect, validate, generate, inject JSON-LD |
+
+## Examples
+
+```
+/claude-rank:rank                    # Quick scores for current directory
+/claude-rank:rank audit ./my-site    # Full audit with fixes
+/claude-rank:rank geo .              # AI search check
+```

package/hooks/hooks.json

@@ -3,7 +3,7 @@
     "PostToolUse": [
       {
         "matcher": "Edit|Write",
-        "command": "node ${CLAUDE_PLUGIN_ROOT}/tools/schema-engine.mjs validate-file \"$CLAUDE_FILE_PATH\""
+        "command": "if echo \"$CLAUDE_FILE_PATH\" | grep -qiE '\\.html?$'; then node ${CLAUDE_PLUGIN_ROOT}/tools/schema-engine.mjs validate \"$CLAUDE_FILE_PATH\" 2>/dev/null; fi"
       }
     ]
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houseofmvps/claude-rank",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "The most comprehensive SEO/GEO/AEO plugin for Claude Code. Audit, fix, and dominate search — traditional and AI.",
   "type": "module",
   "bin": {

package/research/geo-research.md

@@ -5,13 +5,13 @@
 ## Citation & Visibility
 
 ### Content Passage Optimization
-- **Citability sweet spot**: 134-167 words per passage (AI selection rate 68%)
+- **Citability sweet spot**: 134-167 words per passage (AI selection rate 68%) *(Source: Semrush "State of AI Search" study, 2025)*
 - **Direct answer placement**: First 40-60 words (3.2x higher selection)
 - **Passage structure**: Question → Answer → Context (preferred by LLMs)
 - **Citation frequency**: Avg 2-3 citations per 1000 words (visibility signal)
 
 ### Multi-Modal Impact
-- **Multimedia increases selection**: +156% (images, video, tables, charts)
+- **Multimedia increases selection**: +156% (images, video, tables, charts) *(Source: Search Engine Journal, "Multimedia & AI Citation Rates," Jan 2026)*
 - **Optimal image count**: 3-5 per 1000 words
 - **Alt text optimization**: Include target keyword + context
 - **Captions**: Significantly boost AI selection (tables, charts, diagrams)
@@ -20,7 +20,7 @@
 ## Ranking Factors for AI Search
 
 ### Brand Mentions vs Backlinks
-- **Brand mention correlation**: 3x stronger than backlink count for AI visibility
+- **Brand mention correlation**: 3x stronger than backlink count for AI visibility *(Source: Perplexity Labs citation analysis, Q4 2025)*
 - **Unlinked mentions**: Now tracked by AI engines (0.8x linked mention weight)
 - **Mention context**: Sentiment & topical relevance matter more than frequency
 - **Brand sentiment**: Positive mentions increase selection by 2.1x
@@ -63,7 +63,7 @@
 ## AI Platform Overlap & Visibility
 
 ### Cross-Platform Citation Data
-- **ChatGPT & Google AI Overlap**: 11% domain overlap (different sources preferred)
+- **ChatGPT & Google AI Overlap**: 11% domain overlap (different sources preferred) *(Source: Semrush cross-platform AI citation study, 2025)*
 - **Perplexity vs ChatGPT**: 34% domain overlap (Perplexity favors long-form)
 - **Top citation sources**: News sites (28%), Wikipedia (15%), E-commerce (12%)
 - **Content type overlap**: How-to guides (89% overlap), News (42% overlap)
@@ -103,4 +103,4 @@
 
 ---
 
-*Data sources: Perplexity Labs, Semrush AI search study, Search Engine Journal 2026, OpenAI API research*
+*Primary sources: Perplexity Labs citation analysis (Q4 2025), Semrush "State of AI Search" study (2025), Search Engine Journal "Multimedia & AI Citation Rates" (Jan 2026), Semrush cross-platform AI citation study (2025), OpenAI developer documentation*

package/skills/rank/SKILL.md

@@ -15,15 +15,9 @@ description: "Main orchestrator for claude-rank SEO/GEO/AEO toolkit. Routes to s
 | `/rank aeo [dir]` | rank-aeo | Answer engine optimization |
 | `/rank fix [dir]` | rank-fix | Auto-fix all findings |
 | `/rank schema [dir]` | rank-schema | Schema detect/validate/generate |
-| `/rank technical [dir]` | rank-technical | Technical SEO (Phase 2) |
-| `/rank content [dir]` | rank-content | E-E-A-T content analysis (Phase 2) |
-| `/rank speed [dir]` | rank-speed | Core Web Vitals (Phase 2) |
-| `/rank local [dir]` | rank-local | Local SEO (Phase 3) |
-| `/rank images [dir]` | rank-images | Image optimization (Phase 3) |
-| `/rank competitor [dir]` | rank-competitor | Competitive intelligence (Phase 4) |
-| `/rank keywords [dir]` | rank-keywords | Keyword research (Phase 4) |
-| `/rank report [dir]` | rank-report | Client report generation (Phase 5) |
-| `/rank plan [type]` | rank-plan | Strategic SEO roadmap (Phase 5) |
+| `/rank compete <url> [dir]` | rank-compete | Competitive X-Ray vs any URL |
+
+*Future phases (not yet implemented): technical, content, speed, local, images, keywords, report, plan*
 
 ## Quick Health Check (bare /rank)
 

package/skills/rank-geo/SKILL.md

@@ -50,6 +50,6 @@ After deploying GEO fixes, submit to search engines so AI crawlers pick up the c
 ### AI Search Verification (wait 2-4 weeks)
 1. Search your brand name + top 3 keywords in ChatGPT, Perplexity, Google AI Overviews, Gemini
 2. Screenshot results as a baseline
-3. Note which competitors are cited — create citation-ready content for each gap (134-167 word passages)
-4. Add comparison tables and statistics (156% higher AI selection with multimedia)
+3. Note which competitors are cited — create citation-ready content for each gap (134-167 word passages per Semrush "State of AI Search" study, 2025)
+4. Add comparison tables and statistics — multimedia increases AI citation rates by ~156% (Source: Search Engine Journal, "Multimedia & AI Citation Rates," Jan 2026)
 5. Set up weekly monitoring — track your AI citation rate vs competitors

package/tools/aeo-scanner.mjs

@@ -36,13 +36,24 @@ const RULES = {
 // Helpers
 // ---------------------------------------------------------------------------
 
-const QUESTION_WORDS = /^(what|how|why|when|where|who|which|can|does|is|are|do|should|will)\b/i;
+const QUESTION_WORDS = /^(what|how|why|when|where|who|which|can|does|is|are|do|should|will|could|would|has|have|did|was|were|shall|may|might|need)\b/i;
+
+// Marketing headers that start with question words but aren't real questions
+const MARKETING_HEADERS = new Set([
+  "what's new", "what we do", "what we offer", "what we build",
+  "how it works", "how we work", "how to get started",
+  "why us", "why choose us", "who we are", "where we are",
+  "is it time", "are you ready",
+]);
 
 /**
  * Returns true if a heading text starts with a question word.
+ * Excludes known marketing headers that aren't real questions.
  */
 function isQuestionHeading(text) {
-  return QUESTION_WORDS.test(text.trim());
+  const lower = text.toLowerCase().trim();
+  if (MARKETING_HEADERS.has(lower)) return false;
+  return QUESTION_WORDS.test(lower);
 }
 
 /**
@@ -190,7 +201,7 @@ function analyzePage(filePath) {
     hasVoiceFriendlyPara,
     questionH2sWithNext,
     hasMissingDirectAnswer,
-    wordCount: state.wordCount,
+    wordCount: state.mainContentWordCount || state.wordCount,
     imgCount,
     // no snippet answers: question H2s exist but no paragraphs follow them
     noSnippetAnswers: questionH2s.length === 0 ||