@houseofmvps/claude-rank 1.3.0 → 1.4.0

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. 74+ rules. Auto-fix everything. Dominate search — traditional and AI.
+### The most comprehensive SEO/GEO/AEO plugin for Claude Code. 80+ rules. 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)
@@ -143,7 +143,7 @@ That's not an SEO problem. That's a visibility problem across every search surfa
 /rank audit
 ```
 
-One command. Three scanners run in parallel — SEO, GEO, and AEO. 74+ rules checked. Every finding gets an automated fix. Score tracked over time.
+One command. Three scanners run in parallel — SEO, GEO, and AEO. 80+ rules checked. Every finding gets an automated fix. Score tracked over time.
 
 ```
 SEO Score:   87/100  ████████████░░  (37 rules)
@@ -158,7 +158,7 @@ Overall:     86/100  READY TO RANK
 
 ## What It Does
 
-### SEO Scanner — 37 Rules
+### SEO Scanner — 39 Rules
 
 Traditional search optimization. The foundation.
 
@@ -166,8 +166,8 @@ Traditional search optimization. The foundation.
 |---|---|
 | **Meta** | Title (length, uniqueness), meta description, viewport, charset, canonical URL, lang attribute |
 | **Content** | H1 presence, heading hierarchy, word count, image alt text, thin content detection |
-| **Technical** | robots.txt, sitemap.xml, HTTPS, mobile-friendly viewport, analytics detection |
-| **Structured Data** | JSON-LD presence, schema validation, required fields |
+| **Technical** | robots.txt, sitemap.xml, HTTPS, mobile-friendly viewport, analytics detection, redirect chain detection |
+| **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
@@ -204,6 +204,33 @@ Every finding has a fix. Not "consider adding" — actual file generation:
 | **llms.txt** | AI discoverability file from your package.json |
 | **JSON-LD Schema** | 12 types: Organization, Article, Product, FAQPage, HowTo, LocalBusiness, Person, WebSite, BreadcrumbList, SoftwareApplication, VideoObject, ItemList |
 
+### Core Web Vitals (Lighthouse)
+
+Optional performance scoring powered by Lighthouse. Requires `lighthouse` and `chrome-launcher`:
+
+```bash
+npm install -g lighthouse chrome-launcher
+claude-rank cwv https://example.com
+```
+
+| Metric | What it measures | Good | Poor |
+|---|---|---|---|
+| **LCP** | Largest Contentful Paint | < 2.5s | > 4.0s |
+| **CLS** | Cumulative Layout Shift | < 0.1 | > 0.25 |
+| **FCP** | First Contentful Paint | < 1.8s | > 3.0s |
+| **TBT** | Total Blocking Time (proxy for INP) | < 200ms | > 600ms |
+| **SI** | Speed Index | < 3.4s | > 5.8s |
+
+Graceful fallback: if Lighthouse isn't installed, tells the user how to enable it.
+
+### Post-Audit Action Plans
+
+Every audit now ends with exact step-by-step instructions for:
+
+- **Google Search Console** — submit sitemap, request indexing for money pages, check coverage, validate rich results, monitor Core Web Vitals
+- **Bing Webmaster Tools** — submit URLs, enable IndexNow, verify robots.txt for Copilot/ChatGPT visibility
+- **AI Search Verification** — test visibility in ChatGPT, Perplexity, Gemini, Google AI Overviews
+
 ### Schema Engine — Full CRUD
 
 Not just detection. Full lifecycle management:
@@ -250,6 +277,7 @@ Each audit produces separate SEO, GEO, and AEO scores plus a composite. Same rul
 | `claude-rank geo ./project` | GEO scan — AI search optimization (25 rules) |
 | `claude-rank aeo ./project` | AEO scan — answer engine optimization (12 rules) |
 | `claude-rank schema ./project` | Detect structured data across all HTML |
+| `claude-rank cwv https://example.com` | Core Web Vitals via Lighthouse (optional) |
 | `claude-rank help` | Show available commands |
 
 ## Slash Commands (Claude Code)
@@ -269,13 +297,20 @@ Each audit produces separate SEO, GEO, and AEO scores plus a composite. Same rul
 
 | Feature | claude-rank | claude-seo |
 |---------|:-----------:|:----------:|
-| SEO rules | 37 | ~20 |
+| SEO rules | 39 | ~20 |
 | GEO — AI search (Perplexity, ChatGPT, Gemini) | 25 rules | Basic |
 | AEO — featured snippets, voice search | 12 rules | None |
 | Auto-fix generators | Yes | No |
 | Schema management (detect / validate / generate / inject) | Full CRUD | Detect only |
+| Core Web Vitals / Lighthouse | Yes (optional) | No |
+| Redirect chain detection | Yes | No |
+| Schema validation (Google required fields) | 14 types | No |
+| Post-audit GSC/Bing action plans | Yes | No |
 | Score tracking with history and trends | Yes | None |
 | Cross-page analysis (duplicates, orphans, canonicals) | Yes | No |
+| Multi-page URL crawling (up to 50 pages) | Yes | No |
+| HTML report export (agency-ready) | Yes | No |
+| CI/CD threshold mode | Yes | No |
 | AI bot detection | 9 bots | Basic |
 | llms.txt generation | Yes | No |
 | robots.txt generation | Yes | No |
@@ -302,7 +337,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`. |
-| **85 tests** | Security module, all scanners, CLI, integration tests |
+| **200 tests** | Security module, all scanners, 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.
@@ -313,7 +348,7 @@ See [SECURITY.md](SECURITY.md) for the full vulnerability disclosure policy.
 
 | Category | Count | Highlights |
 |---|---|---|
-| **Tools** | 8 | SEO scanner (37 rules), GEO scanner (25 rules), AEO scanner (12 rules), schema engine, robots analyzer, sitemap analyzer, llms.txt generator, audit history |
+| **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 | /rank, /rank audit, /rank geo, /rank aeo, /rank fix, /rank schema |
 | **Agents** | 4 | SEO auditor, GEO auditor, AEO auditor, Schema auditor |
 | **Commands** | 6 | All slash commands above |
@@ -357,7 +392,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              # 85 tests, node:test
+npm test              # 200 tests, node:test
 node tools/<tool>.mjs # No build step
 ```
 

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

@@ -42,6 +42,7 @@ Commands:
   scan     Run core SEO scanner (default)
   geo      Run GEO (AI search) scanner
   aeo      Run AEO (answer engine) scanner
+  cwv      Run Core Web Vitals / Lighthouse audit (requires: npm i -g lighthouse chrome-launcher)
   schema   Detect and validate structured data
   help     Show this help message
 
@@ -72,6 +73,37 @@ Examples:
   process.exit(0);
 }
 
+// Handle CWV command separately (requires URL, optional dependency)
+if (command === 'cwv') {
+  const url = dir.startsWith('http://') || dir.startsWith('https://') ? dir : null;
+  if (!url) {
+    console.error('The cwv command requires a URL. Usage: claude-rank cwv https://example.com');
+    process.exit(1);
+  }
+
+  // Clear argv before importing
+  process.argv = process.argv.slice(0, 2);
+
+  const { runLighthouse, isAvailable } = await import(new URL('../tools/lighthouse-scanner.mjs', import.meta.url));
+  const check = isAvailable();
+  if (!check.available) {
+    console.log(`\n  Core Web Vitals scanner requires Lighthouse.\n`);
+    console.log(`  Install: npm install -g lighthouse chrome-launcher\n`);
+    console.log(`  Then run: claude-rank cwv ${url}\n`);
+    process.exit(0);
+  }
+
+  const result = await runLighthouse(url);
+  if (jsonFlag) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    // Pretty output is handled inside lighthouse-scanner.mjs CLI
+    // For programmatic use, just output JSON
+    console.log(JSON.stringify(result, null, 2));
+  }
+  process.exit(0);
+}
+
 const toolPath = commands[command];
 if (!toolPath) {
   console.error(`Unknown command: ${command}. Run "claude-rank help" for usage.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houseofmvps/claude-rank",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "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

package/skills/rank-audit/SKILL.md

@@ -73,6 +73,94 @@ Advise on content optimizations the scanner cannot automate:
 
 Guide link building: create link-worthy assets, guest posting, broken link building, HARO.
 
-## Phase 8: Next Steps
-
-Recommend which /rank sub-commands to run next based on lowest scores.
+## Phase 8: Search Console Action Plan
+
+After fixing issues, guide the user through submitting their improved site to search engines. This is the critical bridge between "audit complete" and "actually ranking."
+
+### Google Search Console (GSC)
+
+1. **Submit Sitemap**
+   - Go to [Google Search Console](https://search.google.com/search-console)
+   - Select your property → Sitemaps → Enter `sitemap.xml` → Submit
+   - If sitemap was just generated by `/rank fix`, confirm the file is deployed first
+
+2. **Request Indexing for Money Pages**
+   - Go to URL Inspection → Paste each high-priority page URL
+   - Click "Request Indexing" for pages that were fixed (new title, meta description, schema added)
+   - Priority order for indexing requests:
+     - Homepage
+     - Pricing / signup page
+     - Top landing pages (highest revenue/conversion)
+     - Blog posts targeting competitive keywords
+   - Google allows ~10-12 indexing requests per day — prioritize your money pages
+
+3. **Check Index Coverage**
+   - Go to Pages → review "Not indexed" list
+   - "Crawled - currently not indexed" → page needs content improvements or more internal links
+   - "Discovered - currently not indexed" → page needs stronger internal links pointing to it
+   - Verify any `noindex` pages found by scanner are intentional
+
+4. **Validate Robots.txt**
+   - Go to Settings → Crawling → Open robots.txt report
+   - Verify updated robots.txt (AI bots unblocked) is live and valid
+   - Test specific URLs to confirm they're crawlable
+
+5. **Check Rich Results**
+   - Go to Enhancements → review each schema type (FAQ, HowTo, Product, etc.)
+   - If `/rank fix` generated new JSON-LD, check for validation errors here
+   - Use [Rich Results Test](https://search.google.com/test/rich-results) to test individual pages
+   - Common issues: missing `image` field in Article, missing `price` in Product
+
+6. **Monitor Core Web Vitals**
+   - Go to Experience → Core Web Vitals
+   - Note any "Poor" or "Needs Improvement" URLs — these directly affect rankings
+   - Focus on: LCP (Largest Contentful Paint), CLS (Cumulative Layout Shift), INP (Interaction to Next Paint)
+
+### Bing Webmaster Tools
+
+1. **Submit Sitemap**
+   - Go to [Bing Webmaster Tools](https://www.bing.com/webmasters)
+   - Configure Sitemaps → Submit your sitemap.xml URL
+   - Bing also reads the `Sitemap:` directive in robots.txt (already added by `/rank fix`)
+
+2. **Submit URLs for Fast Indexing**
+   - Go to URL Submission → submit your top 10 money pages
+   - Bing allows up to 10,000 URL submissions per day (far more generous than Google)
+   - Submit ALL pages that had SEO fixes applied
+
+3. **Enable IndexNow** (instant indexing)
+   - Bing supports [IndexNow](https://www.indexnow.org/) for near-instant indexing
+   - Generate an API key at indexnow.org → place key file at your domain root
+   - If using Next.js/WordPress, install IndexNow plugin for automatic ping on publish
+   - This feeds into Bing, Yandex, and Seznam simultaneously
+
+4. **Verify Robots.txt**
+   - Go to Configure My Site → Block URLs → Robots.txt Tester
+   - Important: Bingbot feeds into Microsoft Copilot and ChatGPT Browse — keeping it unblocked is critical for AI visibility
+
+### AI Search Verification
+
+After deploying fixes, verify your site is visible to AI search engines:
+
+1. **Test AI Visibility** (wait 2-4 weeks after robots.txt changes)
+   - Search your brand name + top 3 keywords in:
+     - ChatGPT (chat.openai.com)
+     - Perplexity (perplexity.ai)
+     - Google Gemini (gemini.google.com)
+     - Google AI Overviews (google.com — check the AI summary box)
+   - Screenshot results as baseline for tracking improvement
+
+2. **Verify llms.txt**
+   - Visit `https://yourdomain.com/llms.txt` — confirm it returns content
+   - Check that it accurately describes your product and links to key pages
+
+3. **Monitor AI Citations Weekly**
+   - Search your niche keywords in Perplexity and ChatGPT every week
+   - Track which pages get cited vs competitors
+   - Focus content improvements on topics where competitors are cited but you're not
+   - Add comparison tables, statistics, and direct definitions to boost citation probability
+
+## Phase 9: Next Steps
+
+Recommend which `/rank` sub-commands to run next based on lowest scores.
+Present the user with a prioritized action checklist they can track.

package/skills/rank-geo/SKILL.md

@@ -33,10 +33,23 @@ Present GEO findings grouped by:
 
 Re-run geo-scanner. Show before/after GEO score.
 
-## Phase 5: Advanced Guidance
+## Phase 5: Search Console Submission
 
-Advise user to:
-1. Search top 5 keywords in ChatGPT, Perplexity, Google AI Overviews
-2. Note which competitors are cited
-3. Create citation-ready content for each gap (134-167 word passages)
+After deploying GEO fixes, submit to search engines so AI crawlers pick up the changes:
+
+### Google Search Console
+1. **Resubmit sitemap** — Sitemaps → Resubmit `sitemap.xml` (triggers recrawl)
+2. **Request indexing** for pages where you unblocked AI bots or added schema — URL Inspection → Request Indexing
+3. **Check robots.txt** — Settings → Crawling → verify your updated robots.txt is live (AI bots unblocked)
+
+### Bing Webmaster Tools
+1. **Submit URLs** — URL Submission → submit pages with new schema/content structure
+2. **Verify robots.txt** — Bingbot feeds Microsoft Copilot and ChatGPT Browse — keeping it unblocked is essential
+3. **Enable IndexNow** — Near-instant indexing for Bing, Yandex, Seznam. Generate key at indexnow.org
+
+### 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)
+5. Set up weekly monitoring — track your AI citation rate vs competitors

package/tools/lib/crawler.mjs

@@ -220,6 +220,7 @@ export async function crawlSite(startUrl, options = {}) {
           url: result.finalUrl,
           html: result.html,
           statusCode: result.statusCode,
+          redirectChain: result.redirectChain || [],
         });
 
         if (onPage) {

package/tools/lib/url-fetcher.mjs

@@ -5,8 +5,9 @@
 
 import { validateUrl, createResponseAccumulator } from './security.mjs';
 
-const USER_AGENT = 'claude-rank/1.1.0 (https://github.com/Houseofmvps/claude-rank)';
+const USER_AGENT = 'claude-rank/1.3.1 (https://github.com/Houseofmvps/claude-rank)';
 const TIMEOUT_MS = 15_000;
+const MAX_REDIRECTS = 10;
 
 /**
  * Fetch a page by URL with SSRF protection and response size limits.
@@ -20,34 +21,67 @@ export async function fetchPage(url) {
     throw new Error(`URL blocked: ${validation.reason}`);
   }
 
-  // 2. Abort controller for timeout
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
-
+  // 2. Follow redirects manually to detect chains
+  const redirectChain = [];
+  let currentUrl = url;
   let response;
-  try {
-    response = await fetch(url, {
-      signal: controller.signal,
-      headers: {
-        'User-Agent': USER_AGENT,
-        'Accept': 'text/html,application/xhtml+xml,*/*',
-      },
-      redirect: 'follow',
-    });
-  } catch (err) {
+
+  for (let i = 0; i <= MAX_REDIRECTS; i++) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+    try {
+      response = await fetch(currentUrl, {
+        signal: controller.signal,
+        headers: {
+          'User-Agent': USER_AGENT,
+          'Accept': 'text/html,application/xhtml+xml,*/*',
+        },
+        redirect: 'manual',
+      });
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err.name === 'AbortError') {
+        throw new Error(`Request timed out after ${TIMEOUT_MS / 1000}s: ${currentUrl}`);
+      }
+      throw new Error(`Fetch failed for ${currentUrl}: ${err.message}`);
+    }
+
     clearTimeout(timeoutId);
-    if (err.name === 'AbortError') {
-      throw new Error(`Request timed out after ${TIMEOUT_MS / 1000}s: ${url}`);
+
+    // Check for redirect (3xx status)
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get('location');
+      if (!location) break;
+
+      // Resolve relative redirects
+      const nextUrl = new URL(location, currentUrl).href;
+      redirectChain.push({ from: currentUrl, to: nextUrl, statusCode: response.status });
+
+      // SSRF check the redirect target
+      const nextValidation = validateUrl(nextUrl);
+      if (!nextValidation.valid) {
+        throw new Error(`Redirect target blocked: ${nextValidation.reason}`);
+      }
+
+      currentUrl = nextUrl;
+
+      if (i === MAX_REDIRECTS) {
+        throw new Error(`Too many redirects (>${MAX_REDIRECTS}): ${url}`);
+      }
+      continue;
     }
-    throw new Error(`Fetch failed for ${url}: ${err.message}`);
+
+    break;
   }
 
-  clearTimeout(timeoutId);
+  const finalUrl = currentUrl;
+  const redirected = redirectChain.length > 0;
 
   // 3. Check Content-Type — only scan HTML responses
   const contentType = response.headers.get('content-type') || '';
   if (!contentType.includes('text/html') && !contentType.includes('application/xhtml+xml')) {
-    throw new Error(`Not an HTML page (Content-Type: ${contentType}): ${url}`);
+    throw new Error(`Not an HTML page (Content-Type: ${contentType}): ${finalUrl}`);
   }
 
   // 4. Read body with size limits using response accumulator
@@ -73,7 +107,8 @@ export async function fetchPage(url) {
     html,
     url,
     statusCode: response.status,
-    redirected: response.redirected,
-    finalUrl: response.url,
+    redirected,
+    finalUrl,
+    redirectChain,
   };
 }

package/tools/lighthouse-scanner.mjs

@@ -0,0 +1,280 @@
+/**
+ * lighthouse-scanner.mjs — Core Web Vitals scanner using Lighthouse.
+ * Optional dependency: works when `lighthouse` and Chrome are available.
+ * Gracefully returns unavailable status when not installed.
+ *
+ * Usage:
+ *   node tools/lighthouse-scanner.mjs <url>
+ *   node tools/lighthouse-scanner.mjs <url> --json
+ */
+
+// ---------------------------------------------------------------------------
+// Try to import lighthouse (optional dependency)
+// ---------------------------------------------------------------------------
+
+let lighthouse = null;
+let chromeLauncher = null;
+
+try {
+  lighthouse = (await import('lighthouse')).default;
+  chromeLauncher = await import('chrome-launcher');
+} catch {
+  // lighthouse not installed — will return unavailable status
+}
+
+// ---------------------------------------------------------------------------
+// CWV thresholds (Google's current thresholds as of 2026)
+// ---------------------------------------------------------------------------
+
+const CWV_THRESHOLDS = {
+  LCP: { good: 2500, poor: 4000 },    // Largest Contentful Paint (ms)
+  CLS: { good: 0.1, poor: 0.25 },     // Cumulative Layout Shift
+  INP: { good: 200, poor: 500 },       // Interaction to Next Paint (ms)
+  FCP: { good: 1800, poor: 3000 },     // First Contentful Paint (ms)
+  TBT: { good: 200, poor: 600 },       // Total Blocking Time (ms)
+  SI:  { good: 3400, poor: 5800 },     // Speed Index (ms)
+};
+
+function rateMetric(value, thresholds) {
+  if (value <= thresholds.good) return 'good';
+  if (value <= thresholds.poor) return 'needs-improvement';
+  return 'poor';
+}
+
+// ---------------------------------------------------------------------------
+// Rule definitions
+// ---------------------------------------------------------------------------
+
+const RULES = {
+  'cwv-lcp-poor':       { severity: 'high', deduction: 10 },
+  'cwv-lcp-needs-work': { severity: 'medium', deduction: 5 },
+  'cwv-cls-poor':       { severity: 'high', deduction: 10 },
+  'cwv-cls-needs-work': { severity: 'medium', deduction: 5 },
+  'cwv-fcp-poor':       { severity: 'medium', deduction: 5 },
+  'cwv-fcp-needs-work': { severity: 'low', deduction: 2 },
+  'cwv-tbt-poor':       { severity: 'high', deduction: 10 },
+  'cwv-tbt-needs-work': { severity: 'medium', deduction: 5 },
+  'cwv-si-poor':        { severity: 'medium', deduction: 5 },
+  'cwv-si-needs-work':  { severity: 'low', deduction: 2 },
+  'perf-score-poor':    { severity: 'high', deduction: 10 },
+  'perf-score-needs-work': { severity: 'medium', deduction: 5 },
+};
+
+// ---------------------------------------------------------------------------
+// isAvailable — check if Lighthouse can run
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if Lighthouse is available (installed + Chrome present).
+ * @returns {{ available: boolean, reason?: string }}
+ */
+export function isAvailable() {
+  if (!lighthouse || !chromeLauncher) {
+    return {
+      available: false,
+      reason: 'Lighthouse not installed. Run: npm install -g lighthouse chrome-launcher',
+    };
+  }
+  return { available: true };
+}
+
+// ---------------------------------------------------------------------------
+// runLighthouse — run audit and extract CWV metrics
+// ---------------------------------------------------------------------------
+
+/**
+ * Run Lighthouse audit on a URL and return Core Web Vitals metrics.
+ * @param {string} url — the URL to audit
+ * @returns {Promise<object>} { url, available, metrics, findings, scores, summary }
+ */
+export async function runLighthouse(url) {
+  const check = isAvailable();
+  if (!check.available) {
+    return {
+      url,
+      available: false,
+      reason: check.reason,
+      metrics: null,
+      findings: [],
+      scores: { performance: null },
+      summary: { critical: 0, high: 0, medium: 0, low: 0 },
+    };
+  }
+
+  // Launch Chrome headless
+  const chrome = await chromeLauncher.launch({
+    chromeFlags: ['--headless', '--no-sandbox', '--disable-gpu'],
+  });
+
+  try {
+    const result = await lighthouse(url, {
+      port: chrome.port,
+      output: 'json',
+      onlyCategories: ['performance'],
+      formFactor: 'mobile',
+      screenEmulation: {
+        mobile: true,
+        width: 412,
+        height: 823,
+        deviceScaleFactor: 1.75,
+      },
+    });
+
+    const lhr = result.lhr;
+    const audits = lhr.audits;
+
+    // Extract metrics
+    const metrics = {
+      performanceScore: Math.round((lhr.categories.performance?.score || 0) * 100),
+      LCP: audits['largest-contentful-paint']?.numericValue || null,
+      CLS: audits['cumulative-layout-shift']?.numericValue || null,
+      FCP: audits['first-contentful-paint']?.numericValue || null,
+      TBT: audits['total-blocking-time']?.numericValue || null,
+      SI: audits['speed-index']?.numericValue || null,
+    };
+
+    // Generate findings
+    const findings = [];
+
+    function addFinding(rule, message) {
+      const def = RULES[rule];
+      if (def) {
+        findings.push({ rule, severity: def.severity, file: url, message });
+      }
+    }
+
+    // Performance score
+    if (metrics.performanceScore < 50) {
+      addFinding('perf-score-poor', `Lighthouse performance score is ${metrics.performanceScore}/100 (poor, target: 90+)`);
+    } else if (metrics.performanceScore < 90) {
+      addFinding('perf-score-needs-work', `Lighthouse performance score is ${metrics.performanceScore}/100 (target: 90+)`);
+    }
+
+    // LCP
+    if (metrics.LCP !== null) {
+      const rating = rateMetric(metrics.LCP, CWV_THRESHOLDS.LCP);
+      const lcpSec = (metrics.LCP / 1000).toFixed(1);
+      if (rating === 'poor') {
+        addFinding('cwv-lcp-poor', `LCP is ${lcpSec}s (poor — should be under ${CWV_THRESHOLDS.LCP.good / 1000}s)`);
+      } else if (rating === 'needs-improvement') {
+        addFinding('cwv-lcp-needs-work', `LCP is ${lcpSec}s (needs improvement — target: under ${CWV_THRESHOLDS.LCP.good / 1000}s)`);
+      }
+      metrics.LCP_rating = rating;
+    }
+
+    // CLS
+    if (metrics.CLS !== null) {
+      const rating = rateMetric(metrics.CLS, CWV_THRESHOLDS.CLS);
+      if (rating === 'poor') {
+        addFinding('cwv-cls-poor', `CLS is ${metrics.CLS.toFixed(3)} (poor — should be under ${CWV_THRESHOLDS.CLS.good})`);
+      } else if (rating === 'needs-improvement') {
+        addFinding('cwv-cls-needs-work', `CLS is ${metrics.CLS.toFixed(3)} (needs improvement — target: under ${CWV_THRESHOLDS.CLS.good})`);
+      }
+      metrics.CLS_rating = rating;
+    }
+
+    // FCP
+    if (metrics.FCP !== null) {
+      const rating = rateMetric(metrics.FCP, CWV_THRESHOLDS.FCP);
+      const fcpSec = (metrics.FCP / 1000).toFixed(1);
+      if (rating === 'poor') {
+        addFinding('cwv-fcp-poor', `FCP is ${fcpSec}s (poor — should be under ${CWV_THRESHOLDS.FCP.good / 1000}s)`);
+      } else if (rating === 'needs-improvement') {
+        addFinding('cwv-fcp-needs-work', `FCP is ${fcpSec}s (needs improvement — target: under ${CWV_THRESHOLDS.FCP.good / 1000}s)`);
+      }
+      metrics.FCP_rating = rating;
+    }
+
+    // TBT (proxy for INP in lab data)
+    if (metrics.TBT !== null) {
+      const rating = rateMetric(metrics.TBT, CWV_THRESHOLDS.TBT);
+      if (rating === 'poor') {
+        addFinding('cwv-tbt-poor', `TBT is ${Math.round(metrics.TBT)}ms (poor — should be under ${CWV_THRESHOLDS.TBT.good}ms)`);
+      } else if (rating === 'needs-improvement') {
+        addFinding('cwv-tbt-needs-work', `TBT is ${Math.round(metrics.TBT)}ms (needs improvement — target: under ${CWV_THRESHOLDS.TBT.good}ms)`);
+      }
+      metrics.TBT_rating = rating;
+    }
+
+    // Speed Index
+    if (metrics.SI !== null) {
+      const rating = rateMetric(metrics.SI, CWV_THRESHOLDS.SI);
+      const siSec = (metrics.SI / 1000).toFixed(1);
+      if (rating === 'poor') {
+        addFinding('cwv-si-poor', `Speed Index is ${siSec}s (poor — should be under ${CWV_THRESHOLDS.SI.good / 1000}s)`);
+      } else if (rating === 'needs-improvement') {
+        addFinding('cwv-si-needs-work', `Speed Index is ${siSec}s (needs improvement — target: under ${CWV_THRESHOLDS.SI.good / 1000}s)`);
+      }
+      metrics.SI_rating = rating;
+    }
+
+    // Calculate CWV score
+    const triggeredRules = new Set(findings.map(f => f.rule));
+    let score = 100;
+    for (const rule of triggeredRules) {
+      const def = RULES[rule];
+      if (def) score -= def.deduction;
+    }
+    score = Math.max(0, score);
+
+    const summary = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const f of findings) {
+      if (summary[f.severity] !== undefined) summary[f.severity]++;
+    }
+
+    return {
+      url,
+      available: true,
+      metrics,
+      findings,
+      scores: { performance: score, lighthouseScore: metrics.performanceScore },
+      summary,
+    };
+  } finally {
+    await chrome.kill();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+if (args.length > 0 && args[0] !== 'detect' && args[0] !== 'generate') {
+  const url = args[0];
+  const jsonFlag = args.includes('--json');
+
+  const result = await runLighthouse(url);
+
+  if (jsonFlag || !process.stdout.isTTY) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    if (!result.available) {
+      console.log(`\n  Lighthouse not available: ${result.reason}\n`);
+      process.exit(0);
+    }
+
+    const m = result.metrics;
+    console.log('');
+    console.log('  Core Web Vitals Report');
+    console.log('  ═══════════════════════');
+    console.log(`  Performance Score: ${m.performanceScore}/100`);
+    console.log('');
+    console.log(`  LCP  (Largest Contentful Paint):  ${(m.LCP / 1000).toFixed(1)}s  [${m.LCP_rating}]`);
+    console.log(`  CLS  (Cumulative Layout Shift):   ${m.CLS.toFixed(3)}   [${m.CLS_rating}]`);
+    console.log(`  FCP  (First Contentful Paint):    ${(m.FCP / 1000).toFixed(1)}s  [${m.FCP_rating}]`);
+    console.log(`  TBT  (Total Blocking Time):       ${Math.round(m.TBT)}ms  [${m.TBT_rating}]`);
+    console.log(`  SI   (Speed Index):               ${(m.SI / 1000).toFixed(1)}s  [${m.SI_rating}]`);
+    console.log('');
+
+    if (result.findings.length > 0) {
+      console.log('  Findings:');
+      for (const f of result.findings) {
+        console.log(`    ${f.severity.toUpperCase().padEnd(8)} ${f.message}`);
+      }
+    } else {
+      console.log('  All Core Web Vitals are good!');
+    }
+    console.log('');
+  }
+}

package/tools/seo-scanner.mjs

@@ -7,6 +7,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseHtml, findHtmlFiles, detectPageType } from './lib/html-parser.mjs';
 import { checkFileSize } from './lib/security.mjs';
+import { validateSchema } from './schema-engine.mjs';
 
 // ---------------------------------------------------------------------------
 // Backend framework detection
@@ -80,6 +81,7 @@ const RULES = {
   'images-missing-dimensions': { severity: 'medium', deduction: 5 },
   'missing-main-landmark':     { severity: 'medium', deduction: 5 },
   'missing-json-ld':           { severity: 'medium', deduction: 5 },
+  'schema-invalid':            { severity: 'medium', deduction: 5 },
   'missing-favicon':           { severity: 'medium', deduction: 5 },
   'no-analytics':              { severity: 'medium', deduction: 5 },
 
@@ -243,6 +245,21 @@ function checkFile(state, filePath, rootDir, opts = {}) {
     add('missing-json-ld', 'Page has no JSON-LD structured data');
   }
 
+  // Validate JSON-LD schema against Google's required fields
+  if (state.jsonLdContent && state.jsonLdContent.length > 0) {
+    for (const raw of state.jsonLdContent) {
+      try {
+        const data = JSON.parse(raw);
+        const issues = validateSchema(data);
+        if (issues.length > 0) {
+          add('schema-invalid', `JSON-LD ${data['@type'] || 'unknown'} schema has issues: ${issues.join('; ')}`);
+        }
+      } catch {
+        // Malformed JSON-LD — already handled by missing-json-ld if count is 0
+      }
+    }
+  }
+
   if (!state.hasFavicon) {
     add('missing-favicon', 'Page is missing a favicon link');
   }

package/tools/url-scanner.mjs

@@ -8,6 +8,7 @@
 import { parseHtml, detectPageType } from './lib/html-parser.mjs';
 import { fetchPage } from './lib/url-fetcher.mjs';
 import { crawlSite } from './lib/crawler.mjs';
+import { validateSchema } from './schema-engine.mjs';
 
 // ---------------------------------------------------------------------------
 // Rule definitions (same as seo-scanner, minus cross-page-only rules)
@@ -42,6 +43,7 @@ const RULES = {
   'images-missing-dimensions': { severity: 'medium', deduction: 5 },
   'missing-main-landmark':     { severity: 'medium', deduction: 5 },
   'missing-json-ld':           { severity: 'medium', deduction: 5 },
+  'schema-invalid':            { severity: 'medium', deduction: 5 },
   'missing-favicon':           { severity: 'medium', deduction: 5 },
   'no-analytics':              { severity: 'medium', deduction: 5 },
 
@@ -62,6 +64,7 @@ const RULES = {
   // HTTP-level rules (URL-scan only)
   'http-error':                { severity: 'critical', deduction: 20 },
   'redirect-detected':         { severity: 'low', deduction: 2 },
+  'redirect-chain':            { severity: 'medium', deduction: 5 },
 };
 
 // ---------------------------------------------------------------------------
@@ -203,6 +206,21 @@ function checkPage(state, pageUrl) {
     add('missing-json-ld', 'Page has no JSON-LD structured data');
   }
 
+  // Validate JSON-LD schema against Google's required fields
+  if (state.jsonLdContent && state.jsonLdContent.length > 0) {
+    for (const raw of state.jsonLdContent) {
+      try {
+        const data = JSON.parse(raw);
+        const issues = validateSchema(data);
+        if (issues.length > 0) {
+          add('schema-invalid', `JSON-LD ${data['@type'] || 'unknown'} schema has issues: ${issues.join('; ')}`);
+        }
+      } catch {
+        // Malformed JSON-LD
+      }
+    }
+  }
+
   if (!state.hasFavicon) {
     add('missing-favicon', 'Page is missing a favicon link');
   }
@@ -325,6 +343,20 @@ export async function scanUrl(url) {
       file: url,
       message: `URL redirected: ${url} → ${page.finalUrl}`,
     });
+
+    // Redirect chain detection: flag chains with 2+ hops
+    if (page.redirectChain && page.redirectChain.length > 1) {
+      const chainDef = RULES['redirect-chain'];
+      const hops = page.redirectChain.map(r => `${r.from} (${r.statusCode})`).join(' → ');
+      findings.push({
+        rule: 'redirect-chain',
+        severity: chainDef.severity,
+        file: url,
+        message: `Redirect chain with ${page.redirectChain.length} hops: ${hops} → ${page.finalUrl}`,
+        chainLength: page.redirectChain.length,
+        chain: page.redirectChain,
+      });
+    }
   }
 
   const seoScore = calculateScore(findings);
@@ -345,6 +377,7 @@ export async function scanUrl(url) {
       statusCode: page.statusCode,
       redirected: page.redirected,
       finalUrl: page.finalUrl,
+      redirectChain: page.redirectChain || [],
     },
   };
 }
@@ -463,6 +496,20 @@ export async function scanSite(startUrl, options = {}) {
       });
     }
 
+    // Redirect chain detection
+    if (page.redirectChain && page.redirectChain.length > 1) {
+      const chainDef = RULES['redirect-chain'];
+      const hops = page.redirectChain.map(r => `${r.from} (${r.statusCode})`).join(' → ');
+      pageFindings.push({
+        rule: 'redirect-chain',
+        severity: chainDef.severity,
+        file: page.url,
+        message: `Redirect chain with ${page.redirectChain.length} hops: ${hops} → ${page.url}`,
+        chainLength: page.redirectChain.length,
+        chain: page.redirectChain,
+      });
+    }
+
     perPageFindings.push(...pageFindings);
   }