@houseofmvps/claude-rank 1.7.0 → 1.7.2

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.7.0",
+  "version": "1.7.2",
   "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. Competitive X-Ray. Auto-fix everything. Dominate search — traditional and AI.
+### The most comprehensive SEO/GEO/AEO plugin for Claude Code. 85+ 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)
@@ -188,11 +188,11 @@ That's not an SEO problem. That's a visibility problem across every search surfa
 /claude-rank:rank-audit
 ```
 
-One command. Three scanners run in parallel — SEO, GEO, and AEO. 80+ rules checked. Every finding gets an automated fix. Score tracked over time. **Then it tells you exactly what to do in Google Search Console and Bing Webmaster Tools.**
+One command. Three scanners run in parallel — SEO, GEO, and AEO. 85+ rules checked. Every finding gets an automated fix. Score tracked over time. **Then it tells you exactly what to do in Google Search Console and Bing Webmaster Tools.**
 
 ```
 SEO Score:   87/100  ████████████░░  (39 rules)
-GEO Score:   92/100  █████████████░  (25 rules)
+GEO Score:   92/100  █████████████░  (34 rules)
 AEO Score:   78/100  ██████████░░░░  (12 rules)
 Overall:     86/100  READY TO RANK
 ```
@@ -215,7 +215,7 @@ Traditional search optimization. The foundation.
 | **Structured Data** | JSON-LD presence, schema validation against Google's required fields (14 schema types) |
 | **Cross-Page** | Duplicate titles across pages, duplicate descriptions, canonical conflicts, orphan pages |
 
-### GEO Scanner — 25 Rules
+### GEO Scanner — 34 Rules
 
 Generative Engine Optimization. For AI search engines: ChatGPT, Perplexity, Gemini, Google AI Overviews.
 
@@ -382,7 +382,7 @@ Each audit produces separate SEO, GEO, and AEO scores plus a composite. Same rul
 |---------|-------------|
 | `claude-rank scan ./project` | Full SEO scan (39 rules) |
 | `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 geo ./project` | GEO scan — AI search optimization (34 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) |
@@ -411,7 +411,7 @@ Each audit produces separate SEO, GEO, and AEO scores plus a composite. Same rul
 | Feature | claude-rank | claude-seo |
 |---------|:-----------:|:----------:|
 | SEO rules | 39 | ~20 |
-| GEO — AI search (Perplexity, ChatGPT, Gemini) | 25 rules | Basic |
+| GEO — AI search (Perplexity, ChatGPT, Gemini) | 34 rules | Basic |
 | AEO — featured snippets, voice search | 12 rules | None |
 | Core Web Vitals / Lighthouse | Yes (optional) | No |
 | Redirect chain detection | Yes | No |
@@ -452,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`. |
-| **260 tests** | Security module, all scanners, competitive X-Ray, CLI, integration tests |
+| **265 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.
@@ -463,7 +463,7 @@ See [SECURITY.md](SECURITY.md) for the full vulnerability disclosure policy.
 
 | Category | Count | Highlights |
 |---|---|---|
-| **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 |
+| **Tools** | 10 | SEO scanner (39 rules), GEO scanner (34 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** | 7 | All slash commands above |
@@ -509,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              # 260 tests, node:test
+npm test              # 265 tests, node:test
 node tools/<tool>.mjs # No build step
 ```
 

package/bin/claude-rank.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Standalone CLI: npx claude-rank <command> <directory>
-// Commands: scan, geo, aeo, schema, fix
+// Commands: scan, geo, aeo, compete, cwv, schema
 
 const args = process.argv.slice(2);
 const jsonFlag = args.includes('--json');
@@ -97,6 +97,9 @@ if (command === 'compete') {
   const localDir = positional[2] || '.';
   const { resolve: resolvePath } = await import('path');
 
+  // Clear argv before importing so compete-scanner's inline CLI guard doesn't fire
+  process.argv = process.argv.slice(0, 2);
+
   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));
 

package/package.json

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

package/skills/rank-audit/SKILL.md

@@ -71,7 +71,7 @@ Advise on content optimizations the scanner cannot automate:
 
 ## Phase 7: Backlink Strategy
 
-Guide link building: create link-worthy assets, guest posting, broken link building, HARO.
+Guide link building: create link-worthy assets, guest posting, broken link building, digital PR, expert roundups.
 
 ## Phase 8: Search Console Action Plan
 

package/tools/lib/formatter.mjs

@@ -1,46 +1,180 @@
 /**
- * formatter.mjs — Pretty terminal output for claude-rank CLI reports.
+ * formatter.mjs — Professional terminal output for claude-rank CLI reports.
  * No external dependencies — uses raw ANSI escape codes.
  */
 
+// ---------------------------------------------------------------------------
+// ANSI helpers
+// ---------------------------------------------------------------------------
+
 const c = {
   red: s => `\x1b[31m${s}\x1b[0m`,
-  yellow: s => `\x1b[33m${s}\x1b[0m`,
   green: s => `\x1b[32m${s}\x1b[0m`,
+  yellow: s => `\x1b[33m${s}\x1b[0m`,
+  blue: s => `\x1b[34m${s}\x1b[0m`,
+  magenta: s => `\x1b[35m${s}\x1b[0m`,
   cyan: s => `\x1b[36m${s}\x1b[0m`,
+  white: s => `\x1b[37m${s}\x1b[0m`,
   bold: s => `\x1b[1m${s}\x1b[0m`,
   dim: s => `\x1b[2m${s}\x1b[0m`,
+  underline: s => `\x1b[4m${s}\x1b[0m`,
+  bgRed: s => `\x1b[41m\x1b[37m${s}\x1b[0m`,
+  bgYellow: s => `\x1b[43m\x1b[30m${s}\x1b[0m`,
+  bgGreen: s => `\x1b[42m\x1b[30m${s}\x1b[0m`,
+  bgBlue: s => `\x1b[44m\x1b[37m${s}\x1b[0m`,
+  bgCyan: s => `\x1b[46m\x1b[30m${s}\x1b[0m`,
 };
 
-const BAR_WIDTH = 15;
+/** Strip ANSI codes for accurate length measurement */
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+/** Pad string to exact visual width (ANSI-aware) */
+function pad(str, len) {
+  const visible = stripAnsi(str).length;
+  return str + ' '.repeat(Math.max(0, len - visible));
+}
+
+
+// ---------------------------------------------------------------------------
+// Score display
+// ---------------------------------------------------------------------------
+
+function gradeFor(score) {
+  if (score >= 90) return { letter: 'A', color: c.bgGreen };
+  if (score >= 80) return { letter: 'B', color: c.bgGreen };
+  if (score >= 70) return { letter: 'C', color: c.bgYellow };
+  if (score >= 60) return { letter: 'D', color: c.bgYellow };
+  return { letter: 'F', color: c.bgRed };
+}
 
 function scoreLabel(score) {
-  if (score >= 90) return c.green('EXCELLENT');
-  if (score >= 80) return c.green('GOOD');
-  if (score >= 60) return c.yellow('NEEDS WORK');
-  return c.red('POOR');
+  if (score >= 90) return c.green('Excellent');
+  if (score >= 80) return c.green('Good');
+  if (score >= 70) return c.yellow('Needs Work');
+  if (score >= 60) return c.yellow('Below Average');
+  return c.red('Poor');
 }
 
 function scoreBar(score) {
-  const filled = Math.round((score / 100) * BAR_WIDTH);
-  const empty = BAR_WIDTH - filled;
-  return '\u2588'.repeat(filled) + '\u2591'.repeat(empty);
+  const width = 20;
+  const filled = Math.round((score / 100) * width);
+  const empty = width - filled;
+  const barChar = '\u2501'; // heavy horizontal line
+  const emptyChar = '\u2500'; // light horizontal line
+
+  let bar;
+  if (score >= 80) {
+    bar = c.green(barChar.repeat(filled)) + c.dim(emptyChar.repeat(empty));
+  } else if (score >= 60) {
+    bar = c.yellow(barChar.repeat(filled)) + c.dim(emptyChar.repeat(empty));
+  } else {
+    bar = c.red(barChar.repeat(filled)) + c.dim(emptyChar.repeat(empty));
+  }
+  return bar;
 }
 
-function severityColor(severity) {
-  if (severity === 'critical' || severity === 'high') return c.red;
-  if (severity === 'medium') return c.yellow;
-  return c.dim;
+// ---------------------------------------------------------------------------
+// Severity helpers
+// ---------------------------------------------------------------------------
+
+const SEVERITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
+
+function severityBadge(severity) {
+  switch (severity) {
+    case 'critical': return c.bgRed(' CRITICAL ');
+    case 'high':     return c.bgRed('   HIGH   ');
+    case 'medium':   return c.bgYellow(' MEDIUM  ');
+    case 'low':      return c.dim('   LOW    ');
+    default:         return c.dim(`  ${severity.toUpperCase()}  `);
+  }
 }
 
-function pad(str, len) {
-  const stripped = str.replace(/\x1b\[[0-9;]*m/g, '');
-  return str + ' '.repeat(Math.max(0, len - stripped.length));
+function severityIcon(severity) {
+  switch (severity) {
+    case 'critical': return c.red('\u2718'); // heavy X
+    case 'high':     return c.red('\u2716'); // heavy X
+    case 'medium':   return c.yellow('\u25CB'); // circle
+    case 'low':      return c.dim('\u2022'); // bullet
+    default:         return ' ';
+  }
 }
 
-/**
- * Group findings by rule, aggregating affected files and using the first message.
- */
+// ---------------------------------------------------------------------------
+// Fix suggestions for common rules
+// ---------------------------------------------------------------------------
+
+const FIX_HINTS = {
+  // SEO
+  'missing-title':             'Add <title>Your Page Title</title> in <head>',
+  'missing-meta-description':  'Add <meta name="description" content="..."> in <head>',
+  'missing-h1':                'Add one <h1> heading per page',
+  'thin-content':              'Expand main content to 300+ words',
+  'missing-viewport':          'Add <meta name="viewport" content="width=device-width, initial-scale=1">',
+  'missing-og-title':          'Add <meta property="og:title" content="...">',
+  'missing-og-description':    'Add <meta property="og:description" content="...">',
+  'missing-og-image':          'Add <meta property="og:image" content="https://...">',
+  'missing-og-url':            'Add <meta property="og:url" content="https://...">',
+  'missing-canonical':         'Add <link rel="canonical" href="...">',
+  'missing-json-ld':           'Add JSON-LD structured data — run /claude-rank:rank-schema',
+  'missing-favicon':           'Add <link rel="icon" href="/favicon.ico">',
+  'no-analytics':              'Add Google Analytics, Plausible, or PostHog',
+  'missing-twitter-card':      'Add <meta name="twitter:card" content="summary_large_image">',
+  'missing-twitter-image':     'Add <meta name="twitter:image" content="https://...">',
+  'missing-lang':              'Add lang="en" to your <html> tag',
+  'missing-charset':           'Add <meta charset="utf-8"> in <head>',
+  'no-manifest':               'Add <link rel="manifest" href="/manifest.json">',
+  'missing-main-landmark':     'Wrap main content in <main>...</main>',
+  'missing-nav-landmark':      'Wrap navigation in <nav>...</nav>',
+  'missing-footer-landmark':   'Wrap footer in <footer>...</footer>',
+  'images-missing-alt':        'Add descriptive alt="" to all <img> tags',
+  'images-missing-dimensions': 'Add width/height to <img> tags (prevents CLS)',
+  'viewport-not-responsive':   'Use width=device-width in viewport meta',
+  'has-noindex':               'Remove noindex from robots meta (unless intentional)',
+  'schema-invalid':            'Fix JSON-LD schema — run /claude-rank:rank-schema',
+  'multiple-h1':               'Use only one <h1> per page',
+  'title-too-long':            'Shorten title to under 60 characters',
+  'title-too-short':           'Expand title to at least 20 characters',
+  'all-scripts-blocking':      'Add async or defer to <script> tags',
+  'title-content-mismatch':    'Align page content with title keywords',
+  'meta-content-mismatch':     'Align page content with meta description keywords',
+  'duplicate-title':           'Make each page title unique',
+  'duplicate-meta-description':'Make each meta description unique',
+
+  // GEO
+  'missing-robots-txt':        'Create robots.txt allowing AI crawlers',
+  'missing-sitemap':           'Create sitemap.xml and reference in robots.txt',
+  'missing-llms-txt':          'Create llms.txt for AI discoverability',
+  'bot-blocked':               'Unblock AI bots in robots.txt (GPTBot, ClaudeBot, etc.)',
+  'no-ai-bot-rules':           'Add explicit Allow rules for AI bots in robots.txt',
+  'missing-org-schema':        'Add Organization JSON-LD schema',
+  'missing-author-schema':     'Add author attribution to article content',
+  'thin-content-ai':           'Expand content to 300+ words per page for AI citation',
+  'no-question-headers':       'Add question-format H2 headings (What is...? How to...?)',
+  'no-definition-patterns':    'Add clear definition patterns for AI extraction',
+  'no-data-tables':            'Add data tables to support AI citation',
+  'content-not-citation-ready':'Write 120-167 word passages for AI citation fitness',
+  'no-direct-answer':          'Start with a direct answer in the first 40-60 words',
+  'no-statistics':             'Add statistics and data points to support claims',
+
+  // AEO
+  'missing-faq-schema':        'Add FAQPage JSON-LD for People Also Ask',
+  'missing-howto-schema':      'Add HowTo JSON-LD for step-by-step content',
+  'missing-speakable-schema':  'Add speakable schema for voice search',
+  'no-snippet-answers':        'Add 40-60 word answer paragraphs after H2 questions',
+  'missing-content-schema':    'Add Article or WebPage JSON-LD schema',
+  'missing-llms-txt-aeo':      'Create llms.txt for answer engine discovery',
+  'answers-too-long':          'Trim answer paragraphs to 40-60 words',
+  'no-numbered-steps':         'Add numbered/ordered lists for featured snippets',
+  'no-voice-friendly-content': 'Add 20-35 word concise answers for voice search',
+  'no-paa-patterns':           'Add "People Also Ask" style Q&A sections',
+};
+
+// ---------------------------------------------------------------------------
+// Grouping and formatting
+// ---------------------------------------------------------------------------
+
 function groupFindings(findings) {
   const groups = new Map();
   for (const f of findings) {
@@ -62,208 +196,290 @@ function groupFindings(findings) {
 
 function formatFileList(files, max = 3) {
   if (files.length === 0) return '';
+  if (files.length === 1) return files[0];
   const shown = files.slice(0, max);
   const rest = files.length - max;
   let out = shown.join(', ');
-  if (rest > 0) out += `, +${rest} more`;
+  if (rest > 0) out += c.dim(` +${rest} more`);
   return out;
 }
 
-const SEVERITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
+// ---------------------------------------------------------------------------
+// Main report formatter
+// ---------------------------------------------------------------------------
 
-/**
- * Format a scanner report (SEO, GEO, or AEO) with a box header and grouped findings.
- */
-function formatReport(result, title, scoreKey) {
+function formatReport(result, title, scoreKey, scannerType) {
   if (result.skipped) {
-    return c.yellow(`Skipped: ${result.reason}`);
+    return `\n  ${c.yellow('\u26A0')} ${c.bold('Skipped:')} ${result.reason}\n`;
   }
 
   const score = result.scores[scoreKey];
   const { findings, summary } = result;
-  const files_scanned = result.files_scanned ?? result.pages_scanned ?? 1;
+  const filesScanned = result.files_scanned ?? result.pages_scanned ?? 1;
   const groups = groupFindings(findings);
   groups.sort((a, b) => (SEVERITY_ORDER[a.severity] ?? 9) - (SEVERITY_ORDER[b.severity] ?? 9));
 
-  const W = 48;
-  const hr = '\u2550'.repeat(W);
+  const grade = gradeFor(score);
   const lines = [];
 
-  lines.push(`\u2554${hr}\u2557`);
-  lines.push(`\u2551${pad(c.bold(`          ${title}`), W + 9)}\u2551`);
-  lines.push(`\u2560${hr}\u2563`);
-
-  const barStr = `  Score:  ${score}/100  ${scoreBar(score)}  ${scoreLabel(score)}`;
-  lines.push(`\u2551${pad(barStr, W + 22)}\u2551`);
-  lines.push(`\u2560${hr}\u2563`);
+  // ── Header ──────────────────────────────────────────────
+  lines.push('');
+  lines.push(`  ${c.bold(c.cyan('claude-rank'))} ${c.dim('/')} ${c.bold(title)}`);
+  lines.push(c.dim('  ' + '\u2500'.repeat(50)));
 
-  lines.push(`\u2551${pad(`  Files scanned: ${files_scanned}`, W)}\u2551`);
-  lines.push(`\u2551${pad(`  Findings: ${findings.length}`, W)}\u2551`);
-  const countsLine = `    Critical: ${summary.critical}  High: ${summary.high}  Medium: ${summary.medium}  Low: ${summary.low}`;
-  lines.push(`\u2551${pad(countsLine, W)}\u2551`);
-  lines.push(`\u255A${hr}\u255D`);
+  // ── Score ───────────────────────────────────────────────
   lines.push('');
+  lines.push(`  ${grade.color(` ${score} `)}  ${scoreBar(score)}  ${scoreLabel(score)}`);
+  lines.push('');
+  lines.push(`  ${c.dim('Files scanned:')} ${filesScanned}    ${c.dim('Findings:')} ${findings.length}    ${summary.critical > 0 ? c.red(`Critical: ${summary.critical}`) : c.dim(`Critical: ${summary.critical}`)}  ${summary.high > 0 ? c.red(`High: ${summary.high}`) : c.dim(`High: ${summary.high}`)}  ${summary.medium > 0 ? c.yellow(`Medium: ${summary.medium}`) : c.dim(`Medium: ${summary.medium}`)}  ${c.dim(`Low: ${summary.low}`)}`);
 
+  // ── No findings ─────────────────────────────────────────
   if (groups.length === 0) {
-    lines.push(c.green('No findings — looking great!'));
+    lines.push('');
+    lines.push(`  ${c.green('\u2714')} ${c.bold(c.green('All checks passed!'))} No issues found.`);
+    lines.push('');
     return lines.join('\n');
   }
 
-  lines.push(c.bold('Findings:'));
-  {
-    for (const g of groups) {
-      const colorFn = severityColor(g.severity);
-      const tag = pad(colorFn(g.severity.toUpperCase()), 10 + 9);
-      const countSuffix = g.files.length > 1 ? ` (${g.files.length} pages)` : '';
-      lines.push(`  ${tag}${c.bold(g.rule)}${c.dim(countSuffix)}`);
-      lines.push(`           ${g.message}`);
+  // ── Critical & High (must fix) ──────────────────────────
+  const critical = groups.filter(g => g.severity === 'critical' || g.severity === 'high');
+  const medium = groups.filter(g => g.severity === 'medium');
+  const low = groups.filter(g => g.severity === 'low');
+
+  if (critical.length > 0) {
+    lines.push('');
+    lines.push(c.dim('  ' + '\u2500'.repeat(50)));
+    lines.push(`  ${c.bold(c.red('\u2718 Must Fix'))} ${c.dim(`(${critical.length} issues)`)}`);
+    lines.push('');
+    for (const g of critical) {
+      const badge = severityBadge(g.severity);
+      const hint = FIX_HINTS[g.rule];
+      const pageCount = g.files.length > 1 ? c.dim(` (${g.files.length} pages)`) : '';
+      lines.push(`  ${badge}  ${c.bold(g.rule)}${pageCount}`);
+      lines.push(`              ${g.message}`);
+      if (hint) {
+        lines.push(`              ${c.cyan('\u2192')} ${c.cyan(hint)}`);
+      }
       if (g.files.length > 0) {
-        lines.push(`           ${c.dim('Files: ' + formatFileList(g.files))}`);
+        lines.push(`              ${c.dim(formatFileList(g.files))}`);
+      }
+      lines.push('');
+    }
+  }
+
+  // ── Medium (should fix) ─────────────────────────────────
+  if (medium.length > 0) {
+    lines.push(c.dim('  ' + '\u2500'.repeat(50)));
+    lines.push(`  ${c.bold(c.yellow('\u25CB Should Fix'))} ${c.dim(`(${medium.length} issues)`)}`);
+    lines.push('');
+    for (const g of medium) {
+      const hint = FIX_HINTS[g.rule];
+      const pageCount = g.files.length > 1 ? c.dim(` (${g.files.length} pages)`) : '';
+      lines.push(`  ${severityIcon(g.severity)}  ${c.bold(g.rule)}${pageCount}`);
+      lines.push(`     ${g.message}`);
+      if (hint) {
+        lines.push(`     ${c.cyan('\u2192')} ${c.cyan(hint)}`);
+      }
+      if (g.files.length > 1) {
+        lines.push(`     ${c.dim(formatFileList(g.files))}`);
+      }
+      lines.push('');
+    }
+  }
+
+  // ── Low (nice to have) ─────────────────────────────────
+  if (low.length > 0) {
+    lines.push(c.dim('  ' + '\u2500'.repeat(50)));
+    lines.push(`  ${c.dim('\u2022 Nice to Have')} ${c.dim(`(${low.length} issues)`)}`);
+    lines.push('');
+    for (const g of low) {
+      const hint = FIX_HINTS[g.rule];
+      const pageCount = g.files.length > 1 ? c.dim(` (${g.files.length} pages)`) : '';
+      lines.push(`  ${severityIcon(g.severity)}  ${c.dim(g.rule)}${pageCount}`);
+      lines.push(`     ${c.dim(g.message)}`);
+      if (hint) {
+        lines.push(`     ${c.dim('\u2192 ' + hint)}`);
       }
       lines.push('');
     }
   }
 
+  // ── Next steps ──────────────────────────────────────────
+  lines.push(c.dim('  ' + '\u2500'.repeat(50)));
+  lines.push(`  ${c.bold('Next Steps')}`);
+  lines.push('');
+  if (critical.length > 0) {
+    lines.push(`  ${c.red('1.')} Fix ${c.bold(`${critical.length} critical/high`)} issues first — they have the biggest impact`);
+  }
+  if (medium.length > 0) {
+    const step = critical.length > 0 ? '2.' : '1.';
+    lines.push(`  ${c.yellow(step)} Address ${c.bold(`${medium.length} medium`)} issues for a solid foundation`);
+  }
+  if (scannerType === 'seo') {
+    lines.push(`  ${c.cyan('\u2192')} Run ${c.bold('claude-rank geo .')} to check AI search readiness`);
+    lines.push(`  ${c.cyan('\u2192')} Run ${c.bold('claude-rank compete <url> .')} to compare vs competitors`);
+  } else if (scannerType === 'geo') {
+    lines.push(`  ${c.cyan('\u2192')} Run ${c.bold('claude-rank aeo .')} to optimize for featured snippets`);
+  } else if (scannerType === 'aeo') {
+    lines.push(`  ${c.cyan('\u2192')} Run ${c.bold('/claude-rank:rank-fix')} to auto-fix all findings`);
+  }
+  lines.push('');
+
   return lines.join('\n');
 }
 
+// ---------------------------------------------------------------------------
+// Public exports — scanner reports
+// ---------------------------------------------------------------------------
+
 export function formatSeoReport(result) {
-  return formatReport(result, 'claude-rank SEO Audit', 'seo');
+  return formatReport(result, 'SEO Audit', 'seo', 'seo');
 }
 
 export function formatGeoReport(result) {
-  return formatReport(result, 'claude-rank GEO Audit', 'geo');
+  return formatReport(result, 'GEO Audit', 'geo', 'geo');
 }
 
 export function formatAeoReport(result) {
-  return formatReport(result, 'claude-rank AEO Audit', 'aeo');
+  return formatReport(result, 'AEO Audit', 'aeo', 'aeo');
 }
 
-/**
- * Format schema detection results.
- */
-/**
- * Format competitive analysis comparison report.
- */
+// ---------------------------------------------------------------------------
+// Competitive X-Ray report
+// ---------------------------------------------------------------------------
+
 export function formatCompeteReport(result) {
   if (result.error) {
-    return c.red(`Error: ${result.error}`);
+    return `\n  ${c.red('\u2718')} ${result.error}\n`;
   }
 
   const lines = [];
-  const W = 62;
-  const hr = '\u2550'.repeat(W);
-
-  // Header
-  lines.push(`\u2554${hr}\u2557`);
-  lines.push(`\u2551${pad(c.bold('       claude-rank Competitive X-Ray'), W + 9)}\u2551`);
-  lines.push(`\u2560${hr}\u2563`);
-  lines.push(`\u2551${pad(`  ${c.bold('You:')}   ${result.you.title || result.you.directory}`, W + 9)}\u2551`);
-  lines.push(`\u2551${pad(`  ${c.bold('Them:')}  ${result.competitor.title || result.competitor.url}`, W + 9)}\u2551`);
-  lines.push(`\u2560${hr}\u2563`);
-
-  // Score summary
   const { youWins, themWins, ties } = result.summary;
-  const summaryText = `  Score: ${c.green(`You ${youWins}`)}  vs  ${c.red(`Them ${themWins}`)}  (${ties} ties)`;
-  lines.push(`\u2551${pad(summaryText, W + 31)}\u2551`);
-  lines.push(`\u255A${hr}\u255D`);
+
+  // ── Header ──────────────────────────────────────────────
   lines.push('');
+  lines.push(`  ${c.bold(c.cyan('claude-rank'))} ${c.dim('/')} ${c.bold('Competitive X-Ray')}`);
+  lines.push(c.dim('  ' + '\u2500'.repeat(56)));
+  lines.push('');
+  lines.push(`  ${c.bold('You:')}   ${result.you.title || result.you.directory}`);
+  lines.push(`  ${c.bold('Them:')}  ${result.competitor.title || result.competitor.url}`);
 
-  // Headline
-  lines.push(c.bold(result.headline));
+  // ── Score ───────────────────────────────────────────────
+  lines.push('');
+  const youColor = youWins >= themWins ? c.green : c.red;
+  const themColor = themWins >= youWins ? c.red : c.green;
+  lines.push(`  ${youColor(`You ${youWins}`)}  ${c.dim('vs')}  ${themColor(`Them ${themWins}`)}  ${c.dim(`(${ties} ties)`)}`);
   lines.push('');
+  lines.push(`  ${c.bold(result.headline)}`);
 
-  // Verdicts table
-  lines.push(c.bold('Signal-by-Signal Comparison:'));
-  lines.push(`  ${pad(c.dim('Area'), 26)}  ${pad(c.dim('You'), 12)}  ${pad(c.dim('Them'), 12)}  ${c.dim('Winner')}`);
-  lines.push(c.dim('  ' + '\u2500'.repeat(58)));
+  // ── Signal comparison table ─────────────────────────────
+  lines.push('');
+  lines.push(c.dim('  ' + '\u2500'.repeat(56)));
+  lines.push(`  ${pad(c.bold('Signal'), 26)} ${pad(c.bold('You'), 12)} ${pad(c.bold('Them'), 12)} ${c.bold('Result')}`);
+  lines.push(c.dim('  ' + '\u2500'.repeat(56)));
 
   for (const v of result.verdicts) {
-    const winIcon = v.winner === 'you' ? c.green('\u2713') :
-                    v.winner === 'them' ? c.red('\u2717') : c.dim('\u2500');
-    const winLabel = v.winner === 'you' ? c.green('You') :
-                     v.winner === 'them' ? c.red('Them') : c.dim('Tie');
-    lines.push(`  ${pad(v.area, 24)}  ${pad(String(v.you), 10)}  ${pad(String(v.them), 10)}  ${winIcon} ${winLabel}`);
+    const icon = v.winner === 'you'  ? c.green('\u2714') :
+                 v.winner === 'them' ? c.red('\u2718') :
+                 c.dim('\u2500');
+    const label = v.winner === 'you'  ? c.green('You') :
+                  v.winner === 'them' ? c.red('Them') :
+                  c.dim('Tie');
+    lines.push(`  ${pad(v.area, 24)} ${pad(String(v.you), 10)} ${pad(String(v.them), 10)} ${icon} ${label}`);
   }
-  lines.push('');
+  lines.push(c.dim('  ' + '\u2500'.repeat(56)));
 
-  // Tech stack comparison
+  // ── Tech stack ──────────────────────────────────────────
   if (result.competitor.techStack.length > 0 || result.you.techStack.length > 0) {
-    lines.push(c.bold('Tech Stack:'));
+    lines.push('');
+    lines.push(`  ${c.bold('Tech Stack')}`);
+    lines.push('');
     if (result.you.techStack.length > 0) {
-      lines.push(`  ${c.green('You:')}  ${result.you.techStack.map(t => `${t.tech} ${c.dim(`(${t.category})`)}`).join(', ')}`);
+      for (const t of result.you.techStack) {
+        lines.push(`  ${c.green('\u2022')} ${t.tech} ${c.dim(`(${t.category})`)}`);
+      }
     } else {
-      lines.push(`  ${c.green('You:')}  ${c.dim('None detected')}`);
+      lines.push(`  ${c.dim('  No technologies detected in your project')}`);
     }
+    lines.push('');
+    lines.push(`  ${c.bold('Competitor:')}`);
     if (result.competitor.techStack.length > 0) {
-      lines.push(`  ${c.red('Them:')} ${result.competitor.techStack.map(t => `${t.tech} ${c.dim(`(${t.category})`)}`).join(', ')}`);
+      for (const t of result.competitor.techStack) {
+        lines.push(`  ${c.red('\u2022')} ${t.tech} ${c.dim(`(${t.category})`)}`);
+      }
     } else {
-      lines.push(`  ${c.red('Them:')} ${c.dim('None detected')}`);
+      lines.push(`  ${c.dim('  No technologies detected')}`);
     }
-    lines.push('');
   }
 
-  // Conversion signals
+  // ── Conversion signals ──────────────────────────────────
   if (result.competitor.conversionSignals.length > 0 || result.you.conversionSignals.length > 0) {
-    lines.push(c.bold('Conversion Signals:'));
+    lines.push('');
+    lines.push(c.dim('  ' + '\u2500'.repeat(56)));
+    lines.push(`  ${c.bold('Conversion Signals')}`);
+    lines.push('');
     if (result.you.conversionSignals.length > 0) {
-      lines.push(`  ${c.green('You:')}  ${result.you.conversionSignals.join(', ')}`);
+      lines.push(`  ${c.green('You:')}  ${result.you.conversionSignals.join(' \u2022 ')}`);
     } else {
       lines.push(`  ${c.green('You:')}  ${c.dim('None detected')}`);
     }
     if (result.competitor.conversionSignals.length > 0) {
-      lines.push(`  ${c.red('Them:')} ${result.competitor.conversionSignals.join(', ')}`);
+      lines.push(`  ${c.red('Them:')} ${result.competitor.conversionSignals.join(' \u2022 ')}`);
     } else {
       lines.push(`  ${c.red('Them:')} ${c.dim('None detected')}`);
     }
-    lines.push('');
   }
 
-  // Quick wins
+  // ── Action items ────────────────────────────────────────
   if (result.summary.theirAdvantages.length > 0) {
-    lines.push(c.bold('Quick Wins — Close These Gaps:'));
-    for (const gap of result.summary.theirAdvantages.slice(0, 5)) {
-      lines.push(`  ${c.yellow('\u26A0')} ${gap}`);
-    }
     lines.push('');
+    lines.push(c.dim('  ' + '\u2500'.repeat(56)));
+    lines.push(`  ${c.bold(c.yellow('Gaps to Close'))}`);
+    lines.push('');
+    for (const gap of result.summary.theirAdvantages) {
+      lines.push(`  ${c.yellow('\u2192')} ${gap}`);
+    }
   }
 
-  // Your strengths
   if (result.summary.yourAdvantages.length > 0) {
-    lines.push(c.bold('Your Strengths — Keep These:'));
-    for (const adv of result.summary.yourAdvantages.slice(0, 5)) {
-      lines.push(`  ${c.green('\u2713')} ${adv}`);
-    }
     lines.push('');
+    lines.push(c.dim('  ' + '\u2500'.repeat(56)));
+    lines.push(`  ${c.bold(c.green('Your Advantages'))}`);
+    lines.push('');
+    for (const adv of result.summary.yourAdvantages) {
+      lines.push(`  ${c.green('\u2714')} ${adv}`);
+    }
   }
 
+  lines.push('');
   return lines.join('\n');
 }
 
+// ---------------------------------------------------------------------------
+// Schema report
+// ---------------------------------------------------------------------------
+
 export function formatSchemaReport(results) {
   if (!results || results.length === 0) {
-    return c.yellow('No structured data (JSON-LD, Microdata, RDFa) detected.');
+    return `\n  ${c.yellow('\u26A0')} No structured data (JSON-LD) detected.\n  ${c.cyan('\u2192')} Run ${c.bold('/claude-rank:rank-schema')} to generate schema.\n`;
   }
 
   const lines = [];
-  const W = 48;
-  const hr = '\u2550'.repeat(W);
-
-  lines.push(`\u2554${hr}\u2557`);
-  lines.push(`\u2551${pad(c.bold('       claude-rank Schema Report'), W + 9)}\u2551`);
-  lines.push(`\u2560${hr}\u2563`);
-  lines.push(`\u2551${pad(`  Files with schemas: ${results.length}`, W)}\u2551`);
   const totalSchemas = results.reduce((n, r) => n + r.schemas.length, 0);
-  lines.push(`\u2551${pad(`  Total schemas found: ${totalSchemas}`, W)}\u2551`);
-  lines.push(`\u255A${hr}\u255D`);
+
+  lines.push('');
+  lines.push(`  ${c.bold(c.cyan('claude-rank'))} ${c.dim('/')} ${c.bold('Schema Report')}`);
+  lines.push(c.dim('  ' + '\u2500'.repeat(50)));
+  lines.push('');
+  lines.push(`  ${c.dim('Files with schemas:')} ${results.length}    ${c.dim('Total schemas:')} ${totalSchemas}`);
   lines.push('');
 
   for (const r of results) {
-    lines.push(c.bold(r.file));
+    lines.push(`  ${c.bold(r.file)}`);
     for (const s of r.schemas) {
       const type = s.type || s['@type'] || 'Unknown';
       const format = s.format || 'JSON-LD';
-      lines.push(`  ${c.cyan(type)} ${c.dim(`(${format})`)}`);
+      lines.push(`    ${c.green('\u2714')} ${c.cyan(type)} ${c.dim(`(${format})`)}`);
     }
     lines.push('');
   }