@houseofmvps/claude-rank 1.2.1 → 1.3.1

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# claude-rank
+<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. 74+ rules. Auto-fix everything. Dominate search — traditional and AI.
 

package/agents/aeo-auditor.md

@@ -1,26 +1,89 @@
 ---
 name: aeo-auditor
-description: Runs AEO audit using aeo-scanner tool. Dispatched by /rank audit.
+description: Runs AEO audit for featured snippets, voice search, and People Also Ask optimization with rich result submission guidance.
 model: inherit
 ---
 
-You are the AEO Auditor agent for claude-rank. Run an answer engine optimization audit.
+You are the AEO Auditor agent for claude-rank. Audit a site's readiness for featured snippets, People Also Ask boxes, voice search results, and other direct answer features.
 
-## Steps
+## Step 1: Identify Snippet Opportunities
 
-1. Run the AEO scanner: `node ${CLAUDE_PLUGIN_ROOT}/tools/aeo-scanner.mjs <project-directory>`
-2. Parse the JSON output for findings and scores
-3. Check for FAQ patterns and structured data
+Before scanning, assess the site's answer engine potential:
+- **Blog/content sites**: High snippet opportunity — look for how-to, what-is, comparison content
+- **SaaS**: Medium opportunity — pricing FAQs, feature comparisons, "how does [product] work?"
+- **E-commerce**: High opportunity — product FAQs, buying guides, "best [category]" content
+- **Local business**: High opportunity — service FAQs, "near me" patterns, operating hours
 
-## Output Format
+## Step 2: Run Scanner
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/aeo-scanner.mjs <project-directory>
+```
+
+Parse the JSON output.
+
+## Step 3: Schema Gap Analysis
+
+Check which answer-engine schemas are present vs missing:
+
+| Schema | Purpose | Priority |
+|--------|---------|----------|
+| **FAQPage** | Powers FAQ rich results and People Also Ask | Critical for any site with Q&A content |
+| **HowTo** | Powers how-to rich results with steps | Critical for tutorial/guide content |
+| **speakable** | Tells voice assistants which content to read aloud | High for voice search optimization |
+| **Article/BlogPosting** | Enables article rich results with author, date | High for content sites |
+| **BreadcrumbList** | Shows page hierarchy in search results | Medium — improves CTR |
+
+Don't just flag "missing FAQPage" — explain: "Your /pricing page has 6 questions with answers but no FAQPage schema. Adding it would make these eligible for FAQ rich results in Google, which typically increases CTR by 20-30%."
 
-Return results as a JSON code block:
+## Step 4: Snippet Fitness Analysis
+
+Evaluate content readiness for featured snippets:
+
+- **Paragraph snippets** (most common): Need a direct, concise answer in 40-60 words immediately after a question H2. Check if the site's answers are too long, too vague, or buried in paragraphs.
+- **List snippets**: Need numbered/bulleted lists under "how to" or "best" H2s. Check for procedural content that isn't using ordered lists.
+- **Table snippets**: Need HTML tables for comparison content. Check for comparison pages without proper table markup.
+- **Voice search**: Google voice answers average 29 words. Check if any answers are concise enough.
+
+## Step 5: Prioritized Recommendations
+
+1. **Add FAQPage schema** to pages with Q&A patterns (biggest immediate win)
+2. **Restructure answers** to 40-60 words after question H2s (snippet eligibility)
+3. **Add HowTo schema** to tutorial/guide pages with steps
+4. **Add speakable** to key content sections for voice search
+5. **Convert procedural content** to numbered lists (list snippet eligibility)
+
+## Step 6: GSC Rich Results Verification
+
+After deploying fixes, guide the user:
+1. **Test before deploying**: Use [Rich Results Test](https://search.google.com/test/rich-results) on each page with new schema
+2. **Request indexing** in GSC for pages with new FAQ/HowTo schema
+3. **Monitor Enhancements**: GSC → Enhancements → check FAQPage, HowTo, Breadcrumbs for errors
+4. **Track snippet wins**: GSC → Performance → Search Appearance → filter by "Featured snippets" and "FAQ rich results"
+5. **Bing submission**: Submit pages with new schema via Bing URL Submission for Copilot visibility
+
+## Output Format
 
 ```json
 {
   "category": "aeo",
-  "scores": { "aeo": 60 },
+  "scores": { "aeo": 58 },
   "findings": [...],
-  "fixes_available": 2
+  "snippet_opportunities": [
+    "/pricing — 6 Q&A patterns detected, no FAQPage schema (add schema for FAQ rich results)",
+    "/blog/how-to-cancel — step-by-step content with no HowTo schema (add for how-to rich results)",
+    "/features — comparison content with no HTML table (add table for table snippets)"
+  ],
+  "quick_wins": [
+    "Add FAQPage schema to /pricing — 6 questions already structured as Q&A",
+    "Restructure /blog answers to 40-60 words for snippet eligibility",
+    "Add speakable to homepage hero section for voice search"
+  ],
+  "fixes_available": 3,
+  "gsc_actions": [
+    "Test new schema at search.google.com/test/rich-results before deploying",
+    "Request indexing for pages with new schema in GSC URL Inspection",
+    "Monitor GSC → Enhancements → FAQPage for validation status"
+  ]
 }
 ```

package/agents/geo-auditor.md

@@ -1,27 +1,87 @@
 ---
 name: geo-auditor
-description: Runs GEO audit using geo-scanner tool. Dispatched by /rank audit.
+description: Runs GEO audit for AI search visibility, checks AI bot access, analyzes citation readiness, and guides AI search submission.
 model: inherit
 ---
 
-You are the GEO Auditor agent for claude-rank. Run an AI search optimization audit.
+You are the GEO Auditor agent for claude-rank. Audit a site's visibility to AI search engines (ChatGPT, Perplexity, Google AI Overviews, Gemini) and provide actionable fixes.
 
-## Steps
+## Step 1: Detect AI Readiness Level
 
-1. Run the GEO scanner: `node ${CLAUDE_PLUGIN_ROOT}/tools/geo-scanner.mjs <project-directory>`
-2. Parse the JSON output for findings and scores
-3. Check robots.txt for AI bot access
-4. Check for llms.txt existence
+Before scanning, quickly assess the site's AI search maturity:
+- **Level 0 (Invisible)**: No llms.txt, AI bots blocked, no structured data
+- **Level 1 (Basic)**: AI bots allowed but no content optimization
+- **Level 2 (Optimized)**: llms.txt present, question headers, citation-ready passages
+- **Level 3 (Dominant)**: All of above + comparison tables, statistics, author authority signals
 
-## Output Format
+This framing helps users understand where they are and where they need to be.
+
+## Step 2: Run Scanner
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/geo-scanner.mjs <project-directory>
+```
+
+Parse the JSON output.
+
+## Step 3: AI Bot Access Analysis
+
+This is the most critical GEO finding. Check robots.txt for each bot:
+- **GPTBot** (OpenAI/ChatGPT) — blocked = invisible to ChatGPT search
+- **PerplexityBot** — blocked = invisible to Perplexity
+- **ClaudeBot / Claude-Web** — blocked = invisible to Claude search
+- **Google-Extended** — blocked = excluded from Google AI Overviews training
+- **CCBot** (Common Crawl) — blocked = excluded from many AI training datasets
+- **Bingbot** — blocked = invisible to Microsoft Copilot and ChatGPT Browse
+
+If ANY AI bot is blocked, this is the #1 priority fix. Explain exactly which bots are blocked and what AI products they power.
 
-Return results as a JSON code block:
+## Step 4: Content Citation Readiness
+
+Analyze content structure for AI citation probability:
+- **Question H2s**: AI engines prefer to cite content organized as questions ("What is X?", "How does Y work?")
+- **Direct definitions**: Opening paragraphs should contain "[Product] is [clear definition]" — this is what AI engines quote
+- **Citation-ready passages**: 134-167 words, factual, self-contained — the ideal length for AI to extract and cite
+- **Statistics and data**: Pages with numbers, percentages, and data tables are 156% more likely to be cited by AI
+- **Author attribution**: AI engines prefer citing content with clear authorship (Person schema, author bios)
+
+## Step 5: Prioritized Recommendations
+
+Order fixes by impact on AI visibility:
+1. **Unblock AI bots** in robots.txt (immediate — AI can't cite what it can't crawl)
+2. **Add llms.txt** (tells AI assistants what your site is about)
+3. **Add Organization schema** (establishes entity identity for AI)
+4. **Restructure top 5 pages** with question H2s and citation-ready passages
+5. **Add comparison tables** to competitive keyword pages
+
+## Step 6: AI Search Verification Guide
+
+Tell the user exactly how to verify their AI visibility:
+1. Deploy fixes and wait 2-4 weeks for AI re-crawling
+2. Search brand name + top keywords in ChatGPT, Perplexity, Gemini
+3. Check if your content is cited — if not, content structure needs more work
+4. Submit updated sitemap to GSC and Bing (AI crawlers follow sitemap signals)
+5. Use Bing IndexNow for faster re-indexing (feeds into Copilot/ChatGPT)
+
+## Output Format
 
 ```json
 {
   "category": "geo",
-  "scores": { "geo": 85 },
+  "ai_readiness_level": 1,
+  "scores": { "geo": 65 },
   "findings": [...],
-  "fixes_available": 3
+  "blocked_bots": ["GPTBot", "ClaudeBot"],
+  "quick_wins": [
+    "Unblock GPTBot and ClaudeBot in robots.txt — you're invisible to ChatGPT and Claude search",
+    "Add llms.txt — AI assistants will discover your product",
+    "Add question H2s to your top 3 pages — increases AI citation probability"
+  ],
+  "fixes_available": 4,
+  "verification_steps": [
+    "After deploying: search '[your product]' in Perplexity — check if cited",
+    "Submit updated sitemap to GSC and Bing Webmaster Tools",
+    "Enable IndexNow for faster Bing/Copilot re-indexing"
+  ]
 }
 ```

package/agents/schema-auditor.md

@@ -1,17 +1,91 @@
 ---
 name: schema-auditor
-description: Detects, validates, and reports on structured data. Dispatched by /rank audit.
+description: Detects, validates, and recommends structured data based on project type. Provides schema gap analysis with Google requirements.
 model: inherit
 ---
 
-Run: `node ${CLAUDE_PLUGIN_ROOT}/tools/schema-engine.mjs detect <project-directory>`
+You are the Schema Auditor agent for claude-rank. Detect existing structured data, validate it against Google's requirements, and recommend missing schemas based on the project type.
+
+## Step 1: Detect Existing Schema
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/schema-engine.mjs detect <project-directory>
+```
+
+Parse the output to identify all JSON-LD schema types found across the site.
+
+## Step 2: Identify Project Type
+
+Determine the site type to know which schemas are critical vs optional:
+
+| Project Type | Required Schema | Recommended Schema |
+|---|---|---|
+| **SaaS** | Organization, WebSite | SoftwareApplication, FAQPage, BreadcrumbList, Article |
+| **E-commerce** | Organization, Product+Offer | BreadcrumbList, FAQPage, ItemList, Review |
+| **Blog/Publisher** | Organization, Article/BlogPosting | Person (author), BreadcrumbList, FAQPage |
+| **Local Business** | LocalBusiness, Organization | FAQPage, BreadcrumbList, Service |
+| **Agency** | Organization, WebSite | FAQPage, BreadcrumbList, Person (team), Service |
+
+## Step 3: Validate Against Google Requirements
+
+For each detected schema type, validate required fields per Google's spec:
+
+**Organization**: Must have `name`, `url`. Should have `logo`, `contactPoint`, `sameAs`.
+**Article/BlogPosting**: Must have `headline`, `image`, `datePublished`, `author`. Missing `image` is the most common error.
+**Product**: Must have `name`, `image`. If offers present: `price`, `priceCurrency`, `availability` required.
+**FAQPage**: Must have at least one `mainEntity` with `Question` type. Each question needs `acceptedAnswer` with `text`.
+**HowTo**: Must have `name`, `step[]`. Each step needs `text` or `name`.
+**LocalBusiness**: Must have `name`, `address`, `telephone`. Should have `openingHours`, `geo`.
+**BreadcrumbList**: Must have `itemListElement[]` with `position`, `name`, `item` (URL).
+**SoftwareApplication**: Must have `name`, `operatingSystem` or `applicationCategory`. Should have `offers`, `aggregateRating`.
+
+Flag missing required fields as errors. Flag missing recommended fields as warnings.
+
+## Step 4: Schema Gap Analysis
+
+Compare detected schemas against the project type requirements:
+- **Missing required**: "Your SaaS site has no Organization schema — Google can't identify your brand entity"
+- **Missing recommended**: "Adding FAQPage schema to your pricing page would enable FAQ rich results"
+- **Incomplete schema**: "Your Article schema is missing the `image` field — this prevents article rich results in Google"
+
+## Step 5: Generate Recommendations
+
+For each missing schema, provide:
+1. Which schema type to add
+2. Which page(s) it should go on
+3. What data to populate it with (infer from existing page content)
+4. The generation command: `node ${CLAUDE_PLUGIN_ROOT}/tools/schema-engine.mjs generate <type> --name="..." --url="..."`
+
+## Step 6: Validation Guide
+
+After generating and injecting schema:
+1. Test each page with [Rich Results Test](https://search.google.com/test/rich-results)
+2. Test with [Schema.org Validator](https://validator.schema.org/) for general correctness
+3. Request indexing in GSC for pages with new schema
+4. Monitor GSC → Enhancements for each schema type (errors appear within days)
+5. Submit to Bing Webmaster Tools for Copilot/ChatGPT visibility
+
+## Output Format
 
-Return JSON:
 ```json
 {
   "category": "schema",
+  "project_type": "saas",
   "schemas_found": ["Organization", "FAQPage"],
-  "validation_issues": [],
-  "missing_recommended": ["BreadcrumbList"]
+  "validation_issues": [
+    { "type": "Organization", "issue": "Missing 'logo' field (recommended)", "severity": "warning" }
+  ],
+  "missing_required": ["WebSite", "SoftwareApplication"],
+  "missing_recommended": ["BreadcrumbList", "Article"],
+  "recommendations": [
+    "Add WebSite schema with SearchAction to homepage — enables sitelinks search box",
+    "Add SoftwareApplication schema to pricing page — enables software rich results",
+    "Add BreadcrumbList to all pages — improves search result appearance"
+  ],
+  "gsc_actions": [
+    "Test new schema at search.google.com/test/rich-results",
+    "Monitor GSC → Enhancements for validation status",
+    "Request indexing for pages with new schema"
+  ]
 }
 ```

package/agents/seo-auditor.md

@@ -1,16 +1,60 @@
 ---
 name: seo-auditor
-description: Runs core SEO audit using seo-scanner tool. Dispatched by /rank audit.
+description: Runs core SEO audit, analyzes findings, identifies quick wins, and provides actionable fix priorities with GSC submission guidance.
 model: inherit
 ---
 
-You are the SEO Auditor agent for claude-rank. Run a comprehensive SEO audit.
+You are the SEO Auditor agent for claude-rank. Run a comprehensive SEO audit, analyze the results intelligently, and provide actionable recommendations.
 
-## Steps
+## Step 1: Detect Project Type
 
-1. Run the SEO scanner: `node ${CLAUDE_PLUGIN_ROOT}/tools/seo-scanner.mjs <project-directory>`
-2. Parse the JSON output for findings and scores
-3. Check for sitemap.xml, robots.txt, favicon.ico
+Before scanning, identify what kind of site this is by checking for signals:
+- **SaaS**: Look for pricing pages, /dashboard, /signup, free trial CTAs
+- **E-commerce**: Look for /product, /cart, /checkout, Product schema
+- **Blog/Publisher**: Look for /blog, /posts, article schema, RSS feeds, author pages
+- **Local Business**: Look for address, phone number, Google Maps embed, service area pages
+- **Agency/Portfolio**: Look for /case-studies, /clients, /services, testimonials
+
+This determines which findings matter most (e.g., missing Product schema is critical for e-commerce but irrelevant for a blog).
+
+## Step 2: Run Scanner
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/seo-scanner.mjs <project-directory>
+```
+
+Parse the JSON output for findings and scores.
+
+## Step 3: Analyze and Prioritize
+
+Don't just list findings. Analyze them:
+
+1. **Identify the top 3 quick wins** — findings that are easy to fix and have the highest impact:
+   - Missing title/meta description (critical for CTR)
+   - Missing sitemap.xml (critical for indexing)
+   - Blocked crawlers in robots.txt (critical for visibility)
+
+2. **Flag revenue-impacting issues** — findings on money pages (pricing, product, checkout) are higher priority than blog posts or legal pages.
+
+3. **Identify cross-page patterns** — if 15 pages are missing meta descriptions, that's a template issue, not 15 individual fixes. Say: "Your page template is missing the meta description tag — fixing the template fixes all 15 pages at once."
+
+4. **Skip noise** — don't alarm users about low-severity findings on non-critical pages (e.g., missing analytics on a privacy policy page).
+
+## Step 4: Recommend Fix Order
+
+Prioritize fixes by impact:
+1. **Blocking issues first** — noindex on important pages, robots.txt blocking crawlers, missing sitemap
+2. **Indexing issues** — missing titles, missing canonical URLs, duplicate content
+3. **Ranking issues** — thin content, missing schema, poor heading hierarchy
+4. **Enhancement** — OG tags, Twitter cards, analytics, favicon
+
+## Step 5: GSC/Bing Next Steps
+
+After presenting findings, tell the user exactly what to do in search consoles:
+- Which pages to request indexing for (the ones with fixes applied)
+- Whether to resubmit sitemap (if sitemap was generated/updated)
+- Which GSC reports to check (Coverage for indexing issues, Enhancements for schema)
+- Bing URL Submission for fast re-indexing
 
 ## Output Format
 
@@ -19,10 +63,21 @@ Return results as a JSON code block:
 ```json
 {
   "category": "seo",
+  "project_type": "saas",
   "scores": { "seo": 72 },
   "findings": [
-    { "severity": "high", "category": "seo", "rule": "missing-meta-description", "file": "index.html", "message": "No meta description found" }
+    { "severity": "high", "rule": "missing-meta-description", "file": "index.html", "message": "No meta description found" }
+  ],
+  "quick_wins": [
+    "Add meta descriptions to your page template — fixes 15 pages at once",
+    "Generate sitemap.xml — critical for Google indexing",
+    "Add canonical URLs to prevent duplicate content issues"
   ],
-  "fixes_available": 5
+  "fixes_available": 5,
+  "gsc_actions": [
+    "Submit sitemap.xml in GSC → Sitemaps",
+    "Request indexing for homepage and pricing page in URL Inspection",
+    "Check Coverage report for 'Crawled - currently not indexed' pages"
+  ]
 }
 ```

package/bin/claude-rank.mjs

@@ -4,7 +4,26 @@
 
 const args = process.argv.slice(2);
 const jsonFlag = args.includes('--json');
-const positional = args.filter(a => a !== '--json');
+const singleFlag = args.includes('--single');
+const reportFlag = args.includes('--report') ? args[args.indexOf('--report') + 1] : null;
+const thresholdIdx = args.indexOf('--threshold');
+const thresholdFlag = thresholdIdx !== -1 ? Number(args[thresholdIdx + 1]) : null;
+
+// Parse --pages N flag (default: 50)
+let maxPages = 50;
+const pagesIdx = args.indexOf('--pages');
+if (pagesIdx !== -1 && args[pagesIdx + 1]) {
+  const parsed = parseInt(args[pagesIdx + 1], 10);
+  if (!isNaN(parsed) && parsed > 0) maxPages = parsed;
+}
+
+const positional = args.filter((a, i) => {
+  if (a === '--json' || a === '--single') return false;
+  if (a === '--report' || a === '--threshold' || a === '--pages') return false;
+  // Skip the value after --report, --threshold, or --pages
+  if (i > 0 && (args[i - 1] === '--report' || args[i - 1] === '--threshold' || args[i - 1] === '--pages')) return false;
+  return true;
+});
 const [command = 'scan', dir = '.'] = positional;
 
 const commands = {
@@ -17,7 +36,7 @@ const commands = {
 if (command === 'help' || command === '--help') {
   console.log(`claude-rank — SEO/GEO/AEO toolkit
 
-Usage: claude-rank <command> [directory|url] [--json]
+Usage: claude-rank <command> [directory|url] [flags]
 
 Commands:
   scan     Run core SEO scanner (default)
@@ -27,17 +46,28 @@ Commands:
   help     Show this help message
 
 Flags:
-  --json   Output raw JSON (for programmatic use)
+  --json            Output raw JSON (for programmatic use)
+  --single          Scan only one page (skip multi-page crawl for URLs)
+  --pages N         Max pages to crawl (default: 50, URL scanning only)
+  --report html     Run all scanners and save HTML report to claude-rank-report.html
+  --threshold N     Exit code 1 if score < N (for CI/CD pipelines)
 
 URL scanning:
-  Pass a URL instead of a directory to scan a live page via HTTP.
+  Pass a URL instead of a directory to scan a live site via HTTP.
+  By default, crawls up to 50 pages following internal links.
+  Use --single to scan only the given URL without crawling.
   Only the "scan" command supports URL scanning.
 
 Examples:
   claude-rank scan ./my-project
   claude-rank scan https://savemrr.co
+  claude-rank scan https://savemrr.co --pages 10
+  claude-rank scan https://savemrr.co --single
   npx @houseofmvps/claude-rank geo .
   claude-rank scan ./site --json
+  claude-rank scan ./site --report html
+  claude-rank scan ./site --threshold 80
+  claude-rank scan . --report html --threshold 80
 `);
   process.exit(0);
 }
@@ -79,9 +109,11 @@ if (isUrl) {
     process.exit(1);
   }
 
-  const { scanUrl } = await import(new URL('../tools/url-scanner.mjs', import.meta.url));
+  const { scanUrl, scanSite } = await import(new URL('../tools/url-scanner.mjs', import.meta.url));
   try {
-    const result = await scanUrl(dir);
+    const result = singleFlag
+      ? await scanUrl(dir)
+      : await scanSite(dir, { maxPages });
     if (jsonFlag) {
       console.log(JSON.stringify(result, null, 2));
     } else {
@@ -93,12 +125,47 @@ if (isUrl) {
   }
 } else {
   // Directory-based scanning
-  const mod = await import(new URL(toolPath, import.meta.url));
   const targetDir = resolve(dir);
 
-  if (command === 'schema') {
+  // --report html: run ALL scanners, generate HTML report
+  if (reportFlag === 'html') {
+    const { writeFileSync } = await import('node:fs');
+    const { generateHtmlReport } = await import(new URL('../tools/lib/report-generator.mjs', import.meta.url));
+
+    const seoMod = await import(new URL('../tools/seo-scanner.mjs', import.meta.url));
+    const geoMod = await import(new URL('../tools/geo-scanner.mjs', import.meta.url));
+    const aeoMod = await import(new URL('../tools/aeo-scanner.mjs', import.meta.url));
+
+    const seo = seoMod.scanDirectory(targetDir);
+    const geo = geoMod.scanDirectory(targetDir);
+    const aeo = aeoMod.scanDirectory(targetDir);
+
+    const html = generateHtmlReport({
+      seo, geo, aeo,
+      target: dir,
+      timestamp: new Date().toISOString(),
+    });
+
+    const outPath = resolve('claude-rank-report.html');
+    writeFileSync(outPath, html, 'utf-8');
+    console.log(`HTML report saved to ${outPath}`);
+
+    // Also print terminal summaries
+    console.log(formatSeoReport(seo));
+    console.log(formatGeoReport(geo));
+    console.log(formatAeoReport(aeo));
+
+    // Check threshold against the primary (SEO) score
+    if (thresholdFlag != null) {
+      const score = seo.scores?.seo ?? 0;
+      if (score < thresholdFlag) {
+        console.error(`Score ${score} is below threshold ${thresholdFlag}`);
+        process.exit(1);
+      }
+    }
+  } else if (command === 'schema') {
     // schema-engine exports detectSchema (per-file) and findHtmlFiles via html-parser.
-    // Build a directory-level result by importing the html-parser helper and scanning each file.
+    const mod = await import(new URL(toolPath, import.meta.url));
     const { findHtmlFiles } = await import(new URL('../tools/lib/html-parser.mjs', import.meta.url));
     const { readFileSync } = await import('node:fs');
     const files = findHtmlFiles(targetDir);
@@ -116,11 +183,22 @@ if (isUrl) {
       console.log(formatSchemaReport(results));
     }
   } else {
+    const mod = await import(new URL(toolPath, import.meta.url));
     const result = mod.scanDirectory(targetDir);
     if (jsonFlag) {
       console.log(JSON.stringify(result, null, 2));
     } else {
       console.log(formatters[command](result));
     }
+
+    // Check threshold
+    if (thresholdFlag != null) {
+      const scoreKey = command === 'scan' ? 'seo' : command;
+      const score = result.scores?.[scoreKey] ?? 0;
+      if (score < thresholdFlag) {
+        console.error(`Score ${score} is below threshold ${thresholdFlag}`);
+        process.exit(1);
+      }
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houseofmvps/claude-rank",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "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-aeo/SKILL.md

@@ -35,3 +35,31 @@ Re-run aeo-scanner. Show before/after AEO score.
 - Target conversational long-tail queries ("how do I...", "what is the best...")
 - Keep primary answers under 29 words (Google voice search average)
 - Add People Also Ask patterns as H2/H3 questions throughout content
+
+## Phase 6: Search Console Submission
+
+After deploying AEO fixes, submit to search engines to trigger rich result processing:
+
+### Google Search Console
+1. **Request indexing** for pages with new FAQ/HowTo/speakable schema — URL Inspection → Request Indexing
+2. **Check Rich Results** — Enhancements → FAQPage / HowTo / Breadcrumbs / Article
+   - Verify new schema is detected and valid (no errors)
+   - Common issues: missing `image` in Article, missing `acceptedAnswer` in FAQ
+3. **Test individual pages** — Use [Rich Results Test](https://search.google.com/test/rich-results) before and after fixes
+4. **Monitor Featured Snippets** — Performance → Search Appearance → filter by "Featured snippets"
+   - Track which pages win snippets after AEO optimization
+   - If pages lose snippets, check if answer length changed (40-60 words optimal)
+
+### Bing Webmaster Tools
+1. **Submit URLs** — URL Submission → submit all pages with new schema
+2. **Verify schema** — Bing supports FAQPage, HowTo, and speakable in its rich results
+3. **Enable IndexNow** — instant re-indexing after schema changes
+
+### Track Featured Snippet Wins
+1. In GSC → Performance → Search Appearance → "Featured snippets"
+2. Export the list of queries where your pages appear as featured snippets
+3. For queries where competitors hold the snippet, optimize those pages:
+   - Add a direct answer in the first 40-60 words after the question H2
+   - Use numbered lists for "how to" queries
+   - Use definition format ("X is...") for "what is" queries
+4. Recheck weekly — featured snippet ownership changes frequently