@houseofmvps/claude-rank 1.8.0 → 1.9.1

package/.claude-plugin/marketplace.json

@@ -5,13 +5,13 @@
     "email": "houseofmvps2024@gmail.com"
   },
   "metadata": {
-    "description": "The most comprehensive SEO/GEO/AEO plugin for Claude Code. 80+ rules, auto-fix, GSC/Bing action plans."
+    "description": "The most comprehensive SEO/GEO/AEO plugin for Claude Code. 170+ rules, auto-fix, GSC/Bing action plans."
   },
   "plugins": [
     {
       "name": "claude-rank",
-      "description": "SEO/GEO/AEO audit + auto-fix + Core Web Vitals + schema validation + GSC/Bing action plans",
-      "version": "1.5.0",
+      "description": "SEO/GEO/AEO audit + auto-fix + keyword clustering + content briefs + E-E-A-T + Core Web Vitals + schema validation",
+      "version": "1.9.1",
       "source": "./",
       "author": {
         "name": "Houseofmvps",

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.8.0",
+  "version": "1.9.1",
   "author": {
     "name": "Houseofmvps",
     "email": "houseofmvps2024@gmail.com"

package/README.md

@@ -2,8 +2,9 @@
 
 <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. 150+ rules. Competitive X-Ray. Auto-fix everything. Dominate search — traditional and AI.
+### The most comprehensive SEO/GEO/AEO plugin for Claude Code. 170+ rules. Competitive X-Ray. Auto-fix everything. Dominate search — traditional and AI.
 
+[![CI](https://img.shields.io/github/actions/workflow/status/Houseofmvps/claude-rank/ci.yml?style=for-the-badge&logo=github&label=CI)](https://github.com/Houseofmvps/claude-rank/actions/workflows/ci.yml)
 [![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)
 [![npm total](https://img.shields.io/npm/dt/%40houseofmvps%2Fclaude-rank?style=for-the-badge&logo=npm&color=cyan&label=Total%20Downloads)](https://www.npmjs.com/package/@houseofmvps/claude-rank)
@@ -110,14 +111,15 @@ Quick Wins — Close These Gaps:
 
 ### Use as a Claude Code Plugin (recommended)
 
-claude-rank works as a full Claude Code plugin with skills, agents, and slash commands. In any Claude Code session, run:
+claude-rank works as a full Claude Code plugin with skills, agents, and slash commands.
 
+**Option A — Install from GitHub (recommended):**
 ```
 /plugin marketplace add Houseofmvps/claude-rank
 /plugin install claude-rank@Houseofmvps-claude-rank
 ```
 
-Or clone and add locally:
+**Option B — Install from a local clone:**
 ```bash
 git clone https://github.com/Houseofmvps/claude-rank.git
 ```
@@ -152,6 +154,8 @@ npx @houseofmvps/claude-rank geo ./my-project            # AI search audit
 npx @houseofmvps/claude-rank aeo ./my-project            # Answer engine audit
 npx @houseofmvps/claude-rank schema ./my-project         # Structured data
 npx @houseofmvps/claude-rank compete https://competitor.com .  # Competitive X-Ray
+npx @houseofmvps/claude-rank keyword ./my-project         # Keyword clustering
+npx @houseofmvps/claude-rank brief ./my-project "seo"     # Content brief
 npx @houseofmvps/claude-rank scan ./site --json          # Raw JSON output
 npx @houseofmvps/claude-rank scan ./site --report html   # Agency-ready HTML report
 npx @houseofmvps/claude-rank scan ./site --threshold 80  # CI/CD mode
@@ -160,12 +164,15 @@ npx @houseofmvps/claude-rank scan ./site --threshold 80  # CI/CD mode
 ### Install globally
 
 ```bash
-npm install -g @houseofmvps/claude-rank
+npm install -g @houseofmvps/claude-rank    # scoped (official)
+npm install -g claude-rank-seo             # unscoped (shorter)
 claude-rank scan ./my-project
 claude-rank scan https://example.com --pages 20
 claude-rank cwv https://example.com    # Core Web Vitals (just needs Chrome)
 ```
 
+> Both packages are identical. `claude-rank-seo` is an unscoped alias for easier `npx` usage.
+
 ---
 
 ## The Problem
@@ -188,14 +195,14 @@ That's not an SEO problem. That's a visibility problem across every search surfa
 /claude-rank:rank-audit
 ```
 
-One command. Eight scanners run in parallel — SEO, GEO, AEO, AI Citability, Content Intelligence, Performance, Vertical SEO, and Security. 150+ 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. Ten scanners run in parallel — SEO, GEO, AEO, AI Citability, Content Intelligence, Keyword Clustering, Performance, Vertical SEO, Security, and Content Brief. 170+ 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  ████████████░░  (49 rules)
-GEO Score:         92/100  █████████████░  (40 rules)
+SEO Score:         87/100  ████████████░░  (50 rules)
+GEO Score:         92/100  █████████████░  (45 rules + E-E-A-T)
 AEO Score:         78/100  ██████████░░░░  (12 rules)
 Citability Score:  65/100  ████████░░░░░░  (7 dimensions)
-Performance:       90/100  █████████████░  (13 rules)
+Performance:       90/100  █████████████░  (16 rules)
 Security:          80/100  ███████████░░░  (15 rules)
 Overall:           86/100  READY TO RANK
 ```
@@ -206,7 +213,7 @@ Overall:           86/100  READY TO RANK
 
 ## What It Does
 
-### SEO Scanner — 49 Rules
+### SEO Scanner — 50 Rules
 
 Traditional search optimization. The foundation.
 
@@ -216,10 +223,10 @@ Traditional search optimization. The foundation.
 | **Content** | H1 presence, heading hierarchy, word count, image alt text, thin content, readability (Flesch-Kincaid), passive voice, wall-of-text paragraphs |
 | **Technical** | robots.txt, sitemap.xml, HTTPS, mixed content, mobile-friendly viewport, analytics detection (30+ providers), redirect chain detection, lazy loading, hreflang validation |
 | **Structured Data** | JSON-LD presence, schema validation against Google's required fields (14 schema types), dateModified freshness |
-| **Cross-Page** | Duplicate titles, duplicate descriptions, duplicate content (Jaccard similarity >80%), canonical conflicts, orphan pages |
+| **Cross-Page** | Duplicate titles, duplicate descriptions, duplicate content (Jaccard similarity >80%), canonical conflicts, orphan pages, broken internal links (filesystem resolution) |
 | **Keyword Relevance** | Title-content keyword alignment, meta description-content alignment |
 
-### GEO Scanner — 40 Rules
+### GEO Scanner — 45 Rules
 
 Generative Engine Optimization. For AI search engines: ChatGPT, Perplexity, Gemini, Google AI Overviews.
 
@@ -230,6 +237,7 @@ Generative Engine Optimization. For AI search engines: ChatGPT, Perplexity, Gemi
 | **Content Structure** | Question-format H2s (with marketing header filtering), definition patterns, statistics, data tables, lists |
 | **Citation Readiness** | Passage length (134-167 word sweet spot), direct answers in first 40-60 words, source citations to .edu/.gov/.org |
 | **Authority Signals** | Author attribution, organization schema, dateModified freshness, content freshness |
+| **E-E-A-T** | Author bio detection, credentials/expertise signals, about/team page links, review/testimonial trust signals, external authority links (.edu/.gov/.org) |
 
 ### AEO Scanner — 12 Rules
 
@@ -268,8 +276,38 @@ Deep content quality analysis across all pages.
 | **Thin Content** | Pages under 300 words flagged |
 | **Wall of Text** | Paragraphs over 150 words identified |
 | **Internal Linking** | Suggestions for pages sharing H2 topics that should cross-link |
+| **Orphan Content** | Pages with zero incoming internal links |
+| **Hub Pages** | Identifies pillar pages with 5+ outgoing internal links |
+| **Topic Clusters** | Groups pages by shared keywords, suggests missing cross-links |
+
+### Keyword Clustering (NEW)
+
+TF-IDF keyword analysis across all pages.
+
+| Category | What it analyzes |
+|---|---|
+| **Primary Keyword** | Highest-weighted keyword per page (from H1/title) |
+| **TF-IDF Scoring** | Term frequency / inverse document frequency across your content |
+| **Topic Clusters** | Pages grouped by 3+ shared significant keywords |
+| **Keyword Cannibalization** | Multiple pages targeting the same primary keyword |
+| **Content Gaps** | Keywords only covered by 1 page — opportunity for more content |
+| **Pillar Suggestions** | When 3+ pages share a theme, suggests creating a pillar page |
+
+### Content Brief Generator (NEW)
+
+Generate SEO-optimized writing briefs from your existing content.
+
+| Category | What it generates |
+|---|---|
+| **Suggested Title** | H1 based on target keyword and existing content patterns |
+| **Word Count Target** | Based on avg of related pages + 20% to outperform |
+| **H2 Outline** | From analyzing related content structure |
+| **Questions to Answer** | Extracted from existing FAQ patterns and question headings |
+| **Internal Links** | Pages to link to/from for topical authority |
+| **Related Keywords** | Extracted from related pages via TF-IDF |
+| **GEO Tips** | Statistics to include, expert quotes, citation opportunities |
 
-### Performance Risk Assessment — 13 Rules (NEW)
+### Performance Risk Assessment — 16 Rules (NEW)
 
 Performance risk detection from static HTML — no Chrome or Lighthouse needed.
 
@@ -282,6 +320,7 @@ Performance risk detection from static HTML — no Chrome or Lighthouse needed.
 | **Fonts** | Web fonts without font-display: swap (FOIT/FOUT risk) |
 | **Resource Hints** | Missing preload/prefetch, missing preconnect |
 | **Security** | Mixed content (HTTP resources on HTTPS pages) |
+| **Images** | Responsive images (srcset/sizes), modern formats (WebP/AVIF), decorative image handling (alt="" valid per WCAG) |
 
 ### Vertical SEO — 20 Rules (NEW)
 
@@ -445,13 +484,15 @@ Each audit produces separate SEO, GEO, and AEO scores plus a composite. Same rul
 
 | Command | Description |
 |---------|-------------|
-| `claude-rank scan ./project` | Full SEO scan (49 rules) |
+| `claude-rank scan ./project` | Full SEO scan (50 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 (40 rules) |
+| `claude-rank geo ./project` | GEO scan — AI search optimization (45 rules + E-E-A-T) |
 | `claude-rank aeo ./project` | AEO scan — answer engine optimization (12 rules) |
 | `claude-rank citability ./project` | AI Citability Score — 7-dimension analysis |
 | `claude-rank content ./project` | Content intelligence — readability, duplicates, linking |
-| `claude-rank perf ./project` | Performance risk assessment (13 rules, no Chrome needed) |
+| `claude-rank keyword ./project` | Keyword clustering — TF-IDF, cannibalization, content gaps |
+| `claude-rank brief ./project "keyword"` | Content brief generator — SEO-optimized writing outline |
+| `claude-rank perf ./project` | Performance risk assessment (16 rules, no Chrome needed) |
 | `claude-rank vertical ./project` | Vertical SEO — e-commerce + local business (20 rules) |
 | `claude-rank security ./project` | Security headers audit (15 rules) |
 | `claude-rank compete https://competitor.com .` | Competitive X-Ray — side-by-side comparison |
@@ -485,8 +526,8 @@ Each audit produces separate SEO, GEO, and AEO scores plus a composite. Same rul
 
 | Feature | claude-rank | claude-seo |
 |---------|:-----------:|:----------:|
-| SEO rules | 49 | ~20 |
-| GEO — AI search (Perplexity, ChatGPT, Gemini) | 40 rules | Basic |
+| SEO rules | 50 | ~20 |
+| GEO — AI search (Perplexity, ChatGPT, Gemini) | 45 rules | Basic |
 | AEO — featured snippets, voice search | 12 rules | None |
 | Core Web Vitals / Lighthouse | Yes (optional) | No |
 | Redirect chain detection | Yes | No |
@@ -504,6 +545,11 @@ Each audit produces separate SEO, GEO, and AEO scores plus a composite. Same rul
 | Performance Risk Assessment | Yes (no Chrome needed) | No |
 | Vertical SEO (e-commerce + local) | Yes — auto-detection | No |
 | Security Headers Audit | Yes | No |
+| Keyword Clustering (TF-IDF) | Yes | No |
+| Content Brief Generator | Yes | No |
+| E-E-A-T Scoring | Yes — 5 rules | No |
+| Broken Link Detection | Yes — filesystem resolution | No |
+| Image Optimization Audit | Yes — srcset, WebP/AVIF | No |
 | Competitive analysis (X-Ray) | Yes — side-by-side comparison | No |
 | Tech stack detection (50+ patterns) | Yes | No |
 | AI bot detection | 11 bots | Basic |
@@ -532,7 +578,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`. |
-| **332 tests** | Security module, all scanners, competitive X-Ray, CLI, integration tests |
+| **372 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.
@@ -543,10 +589,10 @@ See [SECURITY.md](SECURITY.md) for the full vulnerability disclosure policy.
 
 | Category | Count | Highlights |
 |---|---|---|
-| **Tools** | 15 | SEO scanner (49 rules), GEO scanner (40 rules), AEO scanner (12 rules), AI Citability scorer (7 dimensions), Content analyzer, Performance scanner (13 rules), Vertical scanner (20 rules), Security scanner (15 rules), Competitive X-Ray (50+ tech patterns), Lighthouse/CWV scanner, schema engine, robots analyzer, sitemap analyzer, llms.txt generator, audit history |
+| **Tools** | 17 | SEO scanner (50 rules), GEO scanner (45 rules + E-E-A-T), AEO scanner (12 rules), AI Citability scorer (7 dimensions), Content analyzer + keyword clustering, Content brief generator, Performance scanner (16 rules), Vertical scanner (20 rules), Security scanner (15 rules), Competitive X-Ray (50+ tech patterns), Lighthouse/CWV scanner, schema engine, robots analyzer, sitemap analyzer, llms.txt generator, audit history, formatter |
 | **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** | 12 | All slash commands above |
+| **Agents** | 9 | SEO auditor, GEO auditor, AEO auditor, Schema auditor, Citability auditor, Content auditor, Performance auditor, Vertical auditor, Security auditor |
+| **Commands** | 14 | All slash commands + keyword, brief |
 | **Research** | 3 | SEO benchmarks, GEO research, schema catalog |
 
 ---
@@ -567,7 +613,7 @@ Optional for Core Web Vitals: `lighthouse` + `chrome-launcher`
 
 I built claude-rank alone — nights and weekends, between building my own SaaS products. No VC funding. No team. Just one person who got tired of being invisible to AI search and decided to fix it for everyone.
 
-This plugin is **free forever.** No pro tier. No paywalls. No "upgrade to unlock." Every feature you just read about — all 9 tools, 6 skills, 4 agents — is yours, completely free.
+This plugin is **free forever.** No pro tier. No paywalls. No "upgrade to unlock." Every feature you just read about — all 17 tools, 7 skills, 9 agents — is yours, completely free.
 
 But building and maintaining something this comprehensive takes real time. Every scanner rule I add, every false positive I fix, every new AI crawler I track — that's time I'm not spending on my own products.
 
@@ -589,7 +635,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              # 332 tests, node:test
+npm test              # 372 tests, node:test
 node tools/<tool>.mjs # No build step
 ```
 

package/agents/citability-auditor.md

@@ -0,0 +1,93 @@
+---
+name: citability-auditor
+description: Runs AI citability audit, analyzes 7-dimension breakdown, and provides actionable recommendations to increase AI citation probability.
+model: inherit
+---
+
+You are the Citability Auditor agent for claude-rank. Analyze a site's likelihood of being cited by AI search engines (ChatGPT, Perplexity, Gemini, Google AI Overviews) and provide specific recommendations per dimension.
+
+## Step 1: Detect Content Profile
+
+Before scanning, assess the site's citation potential:
+- **Authority signals**: Does the site have author bios, credentials, citations to sources?
+- **Data density**: Does the content include statistics, percentages, research findings?
+- **Structure quality**: Are answers front-loaded? Are passages self-contained and quotable?
+- **Freshness**: Is content dated and regularly updated?
+
+## Step 2: Run Scanner
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/citability-scorer.mjs <project-directory>
+```
+
+Parse the JSON output for the 7-dimension breakdown and per-page scores.
+
+## Step 3: Analyze Each Dimension
+
+Interpret results across all 7 citability dimensions:
+
+1. **Factual Density** — Does the content contain verifiable facts, numbers, and data?
+   - Fix: Add a statistic or data point every 200 words. Use specific numbers over vague claims.
+   - Example: Change "many users prefer X" to "73% of users prefer X (Source, 2025)."
+
+2. **Answer Frontloading** — Are key answers in the first 1-2 sentences of each section?
+   - Fix: Start each section with a direct answer before elaborating. AI engines extract the first sentence.
+   - Example: "What is X? X is [definition]." not "In order to understand X, we must first consider..."
+
+3. **Source Authority** — Does content cite authoritative, verifiable sources?
+   - Fix: Link to primary sources (research papers, official docs, gov data). Name the source inline.
+   - Example: "According to Google's Search Central documentation..." not "According to experts..."
+
+4. **Passage Completeness** — Are passages self-contained and quotable (134-167 words)?
+   - Fix: Write paragraphs that make sense without surrounding context. Each passage = one complete idea.
+
+5. **Structural Clarity** — Are headings questions? Are definitions formatted as "X is Y"?
+   - Fix: Rewrite H2s as questions users actually ask. Use "What is", "How does", "Why should" format.
+
+6. **Uniqueness** — Does the content offer original insights, data, or perspectives?
+   - Fix: Add original research, case studies, proprietary data, or unique frameworks. Avoid rehashing common knowledge.
+
+7. **Entity Consistency** — Is the brand/product name used consistently with clear definitions?
+   - Fix: Define your product in the first paragraph of every key page. Use consistent naming throughout.
+
+## Step 4: Per-Page Recommendations
+
+For each page scanned, provide:
+- The overall citability score (0-100)
+- The weakest 2-3 dimensions with specific rewrite suggestions
+- A sample rewritten passage demonstrating the improvement
+
+Prioritize pages by importance: homepage > pricing > product pages > blog posts.
+
+## Step 5: Quick Wins
+
+Identify the 3 fastest improvements across the entire site:
+1. The single dimension dragging down the most pages
+2. Template-level fixes (e.g., all pages missing author attribution)
+3. The highest-traffic page with the lowest citability score
+
+## Output Format
+
+```json
+{
+  "category": "citability",
+  "scores": { "citability": 45 },
+  "dimension_scores": {
+    "factual_density": 40,
+    "answer_frontloading": 55,
+    "source_authority": 30,
+    "passage_completeness": 50,
+    "structural_clarity": 60,
+    "uniqueness": 35,
+    "entity_consistency": 45
+  },
+  "findings": [...],
+  "quick_wins": [
+    "Add statistics to your top 5 pages — factual density is your weakest dimension at 40/100",
+    "Front-load answers in H2 sections — AI engines extract the first sentence",
+    "Cite authoritative sources by name — 'According to [Source]' increases citation probability"
+  ],
+  "fixes_available": 7,
+  "lowest_dimensions": ["source_authority", "uniqueness", "factual_density"]
+}
+```

package/agents/content-auditor.md

@@ -0,0 +1,102 @@
+---
+name: content-auditor
+description: Runs content quality audit, reviews readability, identifies duplicate and thin content, and suggests internal linking improvements.
+model: inherit
+---
+
+You are the Content Auditor agent for claude-rank. Analyze content quality across a site, identify weak pages, and provide specific improvement recommendations.
+
+## Step 1: Detect Content Strategy
+
+Before scanning, identify the content architecture:
+- **Content volume**: How many pages have substantive content?
+- **Content types**: Blog posts, landing pages, documentation, product pages?
+- **Update frequency**: Are dates present? Is content stale?
+- **Internal linking**: Do pages link to each other effectively?
+
+## Step 2: Run Scanner
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/content-analyzer.mjs <project-directory>
+```
+
+Parse the JSON output for readability scores, duplicate content flags, and thin page warnings.
+
+## Step 3: Readability Analysis
+
+Interpret readability metrics for each page:
+- **Flesch-Kincaid Grade Level**: Target 6-8 for general audiences, 10-12 for technical content
+- **Average sentence length**: Flag sentences over 25 words for simplification
+- **Paragraph length**: Flag paragraphs over 150 words for splitting
+- **Passive voice ratio**: Target under 10%. Flag pages above 20%.
+- **Transition word usage**: Recommend adding transitions where flow is choppy
+
+For each page with poor readability, provide:
+- The specific metric that failed
+- A sample sentence rewrite demonstrating the fix
+- Whether it is a page-level or template-level issue
+
+## Step 4: Duplicate Content Detection
+
+Identify content duplication issues:
+- **Internal duplicates**: Pages with >60% content overlap (common with category/tag pages)
+- **Near-duplicates**: Pages covering the same topic with slightly different wording
+- **Boilerplate ratio**: Flag pages where >40% of content is repeated header/footer/sidebar text
+
+For each duplicate found, recommend:
+- Canonical tag pointing to the primary version
+- Content consolidation (merge two thin pages into one comprehensive page)
+- noindex for pure duplicate pages (tag archives, paginated lists)
+
+## Step 5: Thin Content Identification
+
+Flag pages with insufficient content:
+- **Under 300 words**: Critical — likely to be seen as thin content by Google
+- **300-600 words**: Warning — may underperform for competitive keywords
+- **No unique value**: Pages that exist but add nothing (empty category pages, stub pages)
+
+For each thin page, provide specific expansion recommendations:
+- What subtopics to add (based on heading gaps)
+- Target word count based on the keyword's competition level
+- Whether to expand the page or merge it with a related page
+
+## Step 6: Internal Linking Opportunities
+
+Identify pages that should link to each other:
+- **Orphan pages**: Pages with zero internal links pointing to them
+- **Hub pages**: Pages that should serve as topic hubs linking to related content
+- **Anchor text**: Suggest descriptive anchor text (not "click here" or "read more")
+- **Link depth**: Flag important pages more than 3 clicks from homepage
+
+## Step 7: Quick Wins
+
+Identify the 3 highest-impact content improvements:
+1. The thinnest page that targets a valuable keyword
+2. The most-duplicated content pattern (template fix)
+3. The highest-authority page with the worst readability score
+
+## Output Format
+
+```json
+{
+  "category": "content",
+  "scores": { "content": 58 },
+  "findings": [...],
+  "thin_pages": [
+    { "file": "about.html", "word_count": 120, "recommendation": "Expand with team bios, mission, and company story — target 800+ words" }
+  ],
+  "duplicate_groups": [
+    { "pages": ["blog/tag/seo.html", "blog/category/seo.html"], "overlap": "78%", "fix": "Add canonical on tag page pointing to category page" }
+  ],
+  "readability_issues": [
+    { "file": "pricing.html", "grade_level": 14.2, "fix": "Simplify feature descriptions — current reading level is graduate-level" }
+  ],
+  "orphan_pages": ["docs/api-reference.html"],
+  "quick_wins": [
+    "Expand about.html from 120 to 800+ words — currently flagged as thin content",
+    "Add canonical tags to 5 tag pages duplicating category pages",
+    "Simplify pricing.html — grade level 14.2, target 8"
+  ],
+  "fixes_available": 8
+}
+```

package/agents/performance-auditor.md

@@ -0,0 +1,107 @@
+---
+name: performance-auditor
+description: Runs performance risk audit, identifies CLS/LCP issues, blocking resources, and provides specific optimization recommendations.
+model: inherit
+---
+
+You are the Performance Auditor agent for claude-rank. Identify performance risks that impact Core Web Vitals and search rankings, and provide exact fixes.
+
+## Step 1: Assess Performance Profile
+
+Before scanning, identify performance-critical factors:
+- **Page type**: Landing pages need sub-2s LCP. Blog posts are more forgiving.
+- **Asset inventory**: How many images, scripts, stylesheets, fonts?
+- **Third-party load**: Analytics, chat widgets, ad scripts?
+- **Framework**: Static HTML is fastest. SPAs need SSR/SSG assessment.
+
+## Step 2: Run Scanner
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/perf-scanner.mjs <project-directory>
+```
+
+Parse the JSON output for CLS risks, blocking resources, image issues, and font loading problems.
+
+## Step 3: CLS Risk Analysis
+
+Cumulative Layout Shift directly affects rankings. Identify causes:
+
+- **Images without dimensions**: List every `<img>` missing `width`/`height` attributes. Provide the exact tag and the fix:
+  - Before: `<img src="hero.jpg" alt="Hero">`
+  - After: `<img src="hero.jpg" alt="Hero" width="1200" height="630">`
+- **Dynamic content injection**: Ads, embeds, or lazy-loaded elements that push content down
+- **Font swapping without reserve**: Web fonts that cause text reflow on load
+- **Unsized iframes/embeds**: YouTube, maps, or widget embeds without dimensions
+
+For each CLS risk, estimate the severity (minor shift vs major layout jump).
+
+## Step 4: Render-Blocking Resources
+
+Identify scripts and styles that delay first paint:
+
+- **Blocking scripts**: List each `<script>` without `async` or `defer`. Recommend:
+  - `defer` for scripts that need DOM (analytics, UI libraries)
+  - `async` for independent scripts (tracking pixels, third-party widgets)
+  - Move to bottom of `<body>` as a fallback
+- **Blocking stylesheets**: Large CSS files loaded in `<head>` without media queries
+  - Recommend critical CSS inlining for above-fold styles
+  - Add `media="print"` with `onload` swap for non-critical CSS
+- **Render chain depth**: Flag chains where resource A loads B which loads C
+
+## Step 5: Image Optimization
+
+Identify image performance issues:
+- **Missing lazy loading**: Images below the fold without `loading="lazy"`
+- **LCP image priority**: The hero/above-fold image should have `fetchpriority="high"` and must NOT have `loading="lazy"`
+- **Missing preconnect**: Third-party image CDNs without `<link rel="preconnect">` hints
+- **Oversized images**: Images served at dimensions much larger than their display size
+- **Missing modern formats**: Images that could benefit from WebP/AVIF conversion
+
+For each image issue, provide the exact element and the fix.
+
+## Step 6: Font Loading
+
+Identify font performance issues:
+- **Missing font-display**: `@font-face` without `font-display: swap` causes invisible text
+- **Too many font files**: Loading more than 4 font files impacts performance
+- **Missing preload**: Critical fonts (used above fold) should have `<link rel="preload" as="font">`
+- **Missing preconnect**: Font CDNs (fonts.googleapis.com, fonts.gstatic.com) without preconnect hints
+
+## Step 7: Third-Party Script Impact
+
+Assess third-party scripts by impact:
+- **High impact**: Analytics (GA4, GTM), chat widgets (Intercom, Drift), ad scripts
+- **Recommendation**: Defer all third-party scripts, load after user interaction where possible
+- **Preconnect**: Add `<link rel="preconnect">` for each third-party origin
+
+## Step 8: Quick Wins
+
+Identify the 3 fixes with the biggest performance impact:
+1. The single largest CLS risk (usually images without dimensions)
+2. The most impactful blocking resource (usually a large JS bundle)
+3. The LCP image optimization (fetchpriority + preconnect)
+
+## Output Format
+
+```json
+{
+  "category": "performance",
+  "scores": { "performance": 62 },
+  "findings": [...],
+  "cls_risks": [
+    { "file": "index.html", "element": "<img src='hero.jpg'>", "fix": "Add width='1200' height='630'" }
+  ],
+  "blocking_resources": [
+    { "file": "index.html", "resource": "analytics.js", "fix": "Add defer attribute" }
+  ],
+  "image_issues": [
+    { "file": "index.html", "element": "<img src='logo.png'>", "fix": "Add loading='lazy' (below fold)" }
+  ],
+  "quick_wins": [
+    "Add dimensions to 12 images — eliminates CLS risk on all pages",
+    "Add defer to 3 blocking scripts — reduces time to first paint by ~800ms",
+    "Add fetchpriority='high' to hero image — improves LCP"
+  ],
+  "fixes_available": 15
+}
+```