@houseofmvps/claude-rank 1.0.0

package/research/schema-catalog.md

@@ -0,0 +1,170 @@
+# Schema Catalog — 25 Critical Schema Types (2026)
+
+*All schemas use JSON-LD format. Fields marked REQUIRED are critical for validation; RECOMMENDED for AI visibility.*
+
+## Content & Publishing
+
+### 1. Article / BlogPosting / NewsArticle
+**Use**: Blog posts, news, long-form content
+- REQUIRED: headline, image, datePublished, author
+- RECOMMENDED: dateModified, articleBody, wordCount, articleSection
+
+### 2. NewsArticle
+**Use**: Breaking news, journalism
+- REQUIRED: headline, datePublished, author, body
+- RECOMMENDED: dateline, printSection, printEdition
+
+### 3. ScholarlyArticle
+**Use**: Research papers, academic content
+- REQUIRED: headline, author, datePublished
+- RECOMMENDED: abstract, author.affiliation, citation
+
+### 4. BreadcrumbList
+**Use**: Navigation hierarchy on all pages
+- REQUIRED: itemListElement[].name, itemListElement[].item
+- RECOMMENDED: position
+
+### 5. FAQPage
+**Use**: FAQ sections, Q&A content
+- REQUIRED: mainEntity[].question, mainEntity[].acceptedAnswer.text
+- RECOMMENDED: acceptedAnswer.url
+
+## E-Commerce & Products
+
+### 6. Product
+**Use**: Product pages, catalog listings
+- REQUIRED: name, image, description
+- RECOMMENDED: offers, aggregateRating, brand
+
+### 7. Offer / AggregateOffer
+**Use**: Pricing, availability, deals
+- REQUIRED: price, priceCurrency, availability
+- RECOMMENDED: url, priceValidUntil, seller
+
+### 8. AggregateRating
+**Use**: User reviews, ratings
+- REQUIRED: ratingValue, ratingCount
+- RECOMMENDED: bestRating, worstRating, reviewCount
+
+### 9. Review / AggregateRating
+**Use**: Customer reviews, testimonials
+- REQUIRED: reviewRating.ratingValue, author, reviewBody
+- RECOMMENDED: datePublished, reviewRating.ratingCount
+
+## Local & Events
+
+### 10. LocalBusiness
+**Use**: Service businesses, locations
+- REQUIRED: name, address, telephone
+- RECOMMENDED: openingHours, geo, areaServed
+
+### 11. Organization
+**Use**: Company info, brand identity
+- REQUIRED: name, url, logo
+- RECOMMENDED: sameAs (social links), contact, description
+
+### 12. Person
+**Use**: Author bios, employee directories
+- REQUIRED: name, image, url
+- RECOMMENDED: jobTitle, affiliation, sameAs
+
+### 13. Event
+**Use**: Webinars, conferences, workshops
+- REQUIRED: name, startDate, location
+- RECOMMENDED: description, offers, performer, endDate
+
+## Services & Expertise
+
+### 14. Service
+**Use**: Service pages, skill listings
+- REQUIRED: name, description, areaServed
+- RECOMMENDED: provider, offers, serviceType
+
+### 15. ProfessionalService
+**Use**: Consulting, legal, medical services
+- REQUIRED: name, image, areaServed
+- RECOMMENDED: hasCredential, makesOffer, serviceArea
+
+### 16. MedicalBusiness
+**Use**: Health, fitness, wellness
+- REQUIRED: name, address, medicalSpecialty
+- RECOMMENDED: hasCredential, knowsLanguage
+
+## Knowledge & How-To
+
+### 17. HowTo
+**Use**: Step-by-step guides, tutorials, recipes
+- REQUIRED: name, step[].name, step[].text
+- RECOMMENDED: image, estimatedCost, totalTime
+
+### 18. HowToStep
+**Use**: Individual steps in guides
+- REQUIRED: name, text
+- RECOMMENDED: image, url
+
+### 19. WebContent
+**Use**: Generic web pages, landing pages
+- REQUIRED: name, headline
+- RECOMMENDED: datePublished, author, image
+
+## Media & Creative
+
+### 20. ImageObject
+**Use**: Standalone images, galleries
+- REQUIRED: url, name
+- RECOMMENDED: caption, creditText, contentLocation
+
+### 21. VideoObject
+**Use**: Embedded videos, tutorials
+- REQUIRED: name, description, thumbnailUrl, uploadDate
+- RECOMMENDED: contentUrl, duration, transcript
+
+### 22. Podcast / PodcastEpisode
+**Use**: Audio content, podcasts
+- REQUIRED: name, description, url
+- RECOMMENDED: author, datePublished, audio
+
+## Navigation & Lists
+
+### 23. ItemList / CollectionPage
+**Use**: Category pages, archives, collections
+- REQUIRED: itemListElement[].name
+- RECOMMENDED: itemListElement[].position, itemListElement[].url
+
+### 24. SearchAction
+**Use**: Site search integration
+- REQUIRED: target (with {search_term_string})
+- RECOMMENDED: query-input
+
+## Q&A & Community
+
+### 25. Question / Answer
+**Use**: Q&A sites, forums, knowledge bases
+- REQUIRED: name (question text), acceptedAnswer
+- RECOMMENDED: author, dateCreated, upvoteCount
+
+---
+
+## Quick Implementation Priority
+
+**High Impact** (do first):
+- Article / BlogPosting
+- Product
+- Organization
+- LocalBusiness
+- BreadcrumbList
+
+**Medium Impact** (recommended):
+- AggregateRating / Review
+- HowTo
+- Event
+- FAQPage
+
+**Niche/Conditional**:
+- NewsArticle, ScholarlyArticle
+- MedicalBusiness, ProfessionalService
+- Podcast, VideoObject
+
+---
+
+*Reference: schema.org, Google Search Central, Search Engine Journal*

package/research/seo-benchmarks.md

@@ -0,0 +1,75 @@
+# SEO Benchmarks 2026
+
+## Title & Meta Tags
+- **Title length**: 50-60 characters (optimal CTR)
+- **Meta description**: 140-160 characters (155 chars = full SERP width)
+- **H1 per page**: 1 (critical for semantic clarity)
+- **Focus keyword density**: 1-2% (natural language first)
+
+## Page Word Count by Type
+- **Homepage**: 500+ words (authority signal)
+- **Blog post**: 1500+ words (top-3 correlation)
+- **Product page**: 300+ words (conversion intent)
+- **Service page**: 800+ words (expertise depth)
+- **Category page**: 1000+ words (topical authority)
+- **Landing page**: 600+ words (engagement signal)
+
+## Core Web Vitals Targets (Ranking Factors)
+- **LCP (Largest Contentful Paint)**: < 2.5 seconds (good)
+- **INP (Interaction to Next Paint)**: < 200 milliseconds (good)
+- **CLS (Cumulative Layout Shift)**: < 0.1 (good)
+- Mobile TTL (Time To Interactive): < 4 seconds
+
+## SERP Click-Through Rate by Position
+- **Position 1**: 39.8% average CTR
+- **Position 2**: 18.7% average CTR
+- **Position 3**: 10.2% average CTR
+- **Position 4**: 6.1% average CTR
+- **Position 10**: 1.9% average CTR
+- **Title/description quality**: Can increase CTR 20-30% at same position
+
+## Featured Snippet Capture Rates
+- **Listicle format (ordered/unordered)**: 52% capture rate
+- **Paragraph format (40-60 words)**: 38% capture rate
+- **Table format (structured data)**: 68% capture rate
+- **Definition format (100-150 words)**: 44% capture rate
+- **Step-by-step format (numbered)**: 61% capture rate
+- **Optimal snippet length**: 40-60 words (40% of captures)
+
+## Backlinks & Authority
+- **Domain authority vs ranking**: Correlation 0.38 (moderate)
+- **Backlink quality > quantity**: 10 high-authority links > 100 low-authority
+- **Link anchor text diversity**: 80% branded, 15% variations, 5% exact match
+- **Topical relevance**: 3x more important than domain authority
+- **Link velocity**: 3-5 new links/month for established sites
+
+## Page Performance Benchmarks
+- **Median page load time**: 2.4 seconds (desktop), 5.9 seconds (mobile)
+- **Images as % of page size**: 50-60% typical (optimize to < 40%)
+- **JavaScript bundle size**: Target < 300KB (gzipped)
+- **CSS bundle size**: Target < 50KB (gzipped)
+- **First Input Delay**: < 100ms target (critical for UX)
+
+## Content Freshness
+- **Optimal update frequency**: 30-90 days for top rankings
+- **E-E-A-T signals**: Experience, Expertise, Authoritativeness, Trustworthiness
+- **Author entity**: Name + topic authority + credentials
+- **Publication date**: Display publicly (correlates with trust)
+
+## Indexability & Crawlability
+- **Sitemaps**: < 50,000 URLs per sitemap.xml
+- **Robots.txt**: Whitelist critical paths, crawl budget awareness
+- **Internal linking**: 3-5 links per page minimum
+- **Orphaned pages**: < 2% of total (discoverable from sitemap)
+- **Redirect chains**: 0 (direct 301/302, max 1 hop)
+
+## Mobile-First Indexing
+- **Mobile viewport**: Required (responsive or mobile-specific)
+- **Mobile load time**: Critical (target < 3 seconds)
+- **Touch targets**: 48x48 pixels minimum
+- **Readability**: Font size 16px+, line spacing 1.5+
+- **Mobile CTR boost**: Up to 25% higher for mobile-optimized sites
+
+---
+
+*Data sources: Google Search Central, Ahrefs, SEMrush, Moz 2026 studies*

package/skills/rank/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: rank
+description: "Main orchestrator for claude-rank SEO/GEO/AEO toolkit. Routes to specialized sub-skills."
+---
+
+# Rank — SEO/GEO/AEO Toolkit
+
+## Routing
+
+| Command | Skill | Description |
+|---|---|---|
+| `/rank` or `/rank status` | (inline) | Quick health check — show all scores |
+| `/rank audit [dir]` | rank-audit | Full audit + auto-fix |
+| `/rank geo [dir]` | rank-geo | AI search optimization |
+| `/rank aeo [dir]` | rank-aeo | Answer engine optimization |
+| `/rank fix [dir]` | rank-fix | Auto-fix all findings |
+| `/rank schema [dir]` | rank-schema | Schema detect/validate/generate |
+| `/rank technical [dir]` | rank-technical | Technical SEO (Phase 2) |
+| `/rank content [dir]` | rank-content | E-E-A-T content analysis (Phase 2) |
+| `/rank speed [dir]` | rank-speed | Core Web Vitals (Phase 2) |
+| `/rank local [dir]` | rank-local | Local SEO (Phase 3) |
+| `/rank images [dir]` | rank-images | Image optimization (Phase 3) |
+| `/rank competitor [dir]` | rank-competitor | Competitive intelligence (Phase 4) |
+| `/rank keywords [dir]` | rank-keywords | Keyword research (Phase 4) |
+| `/rank report [dir]` | rank-report | Client report generation (Phase 5) |
+| `/rank plan [type]` | rank-plan | Strategic SEO roadmap (Phase 5) |
+
+## Quick Health Check (bare /rank)
+
+1. Run available scanners in parallel:
+   - `node ${CLAUDE_PLUGIN_ROOT}/tools/seo-scanner.mjs <dir>`
+   - `node ${CLAUDE_PLUGIN_ROOT}/tools/geo-scanner.mjs <dir>`
+   - `node ${CLAUDE_PLUGIN_ROOT}/tools/aeo-scanner.mjs <dir>`
+2. Display scores table with grades (SEO, GEO, AEO; Technical and Content show "—" until Phase 2)
+3. **Overall Rank Score** = weighted average: SEO (40%), GEO (40%), AEO (20%)
+4. Show top 3 quick wins (highest-impact fixes)
+5. Show trend vs last scan (if history exists)
+
+**Grade thresholds:** A (90-100), B (80-89), C (70-79), D (60-69), F (<60)
+
+## Project Type Detection
+
+Scan for signals to auto-detect:
+- **SaaS**: pricing page, free trial CTA, /dashboard route
+- **E-commerce**: product pages, cart, checkout, Product schema
+- **Local business**: service area, phone, address, Google Maps embed
+- **Publisher/Blog**: /blog, article schema, author bios, RSS feed
+- **Agency**: client testimonials, case studies, service pages

package/skills/rank-aeo/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: rank-aeo
+description: Answer engine optimization. Optimize for featured snippets, voice search, People Also Ask.
+---
+
+# AEO Audit — Answer Engine Optimization
+
+## Phase 1: Scan
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/aeo-scanner.mjs <project-directory>
+```
+
+## Phase 2: Report
+
+Present AEO findings:
+- **Schema** — FAQPage, HowTo, speakable, Article/BlogPosting
+- **Snippet Readiness** — direct answers, numbered steps, concise paragraphs
+- **Voice Search** — conversational patterns, 29-word answer targets
+
+## Phase 3: Fix
+
+- Missing FAQPage → detect Q&A patterns in content, generate schema: `node ${CLAUDE_PLUGIN_ROOT}/tools/schema-engine.mjs generate FAQPage`
+- Missing speakable → add speakable schema targeting key answer sections
+- Long answers → restructure to 40-60 word direct answers after question H2s
+- No numbered steps → convert procedural content to ordered lists
+- Missing featured image → flag for user to add hero image
+
+## Phase 4: Verify
+
+Re-run aeo-scanner. Show before/after AEO score.
+
+## Phase 5: Voice Search Guidance
+
+- 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

package/skills/rank-audit/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: rank-audit
+description: Full SEO/GEO/AEO audit with auto-fix. Scans, reports, fixes, and verifies.
+---
+
+# Full Audit
+
+Comprehensive search optimization audit. Finds issues AND fixes them.
+
+## Phase 1: Parallel Scan
+
+Run all three scanners:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/seo-scanner.mjs <project-directory>
+node ${CLAUDE_PLUGIN_ROOT}/tools/geo-scanner.mjs <project-directory>
+node ${CLAUDE_PLUGIN_ROOT}/tools/aeo-scanner.mjs <project-directory>
+```
+
+Parse JSON output from each for findings and scores.
+
+## Phase 2: Report
+
+Present findings grouped by category (SEO / GEO / AEO) with severity.
+Show scores table: SEO, GEO, AEO, Overall Rank Score.
+Show summary: X critical, Y high, Z medium, W low.
+
+## Phase 3: Auto-Fix
+
+For each finding, apply the appropriate fix:
+
+**SEO fixes** (Edit tool on HTML files):
+- Missing title → add `<title>` in `<head>`
+- Missing meta description → add `<meta name="description">`
+- Missing OG tags → generate from page content
+- Missing H1 → add heading from page content
+- Missing alt text → add descriptive alt attributes
+- Missing canonical → add `<link rel="canonical">`
+- Missing sitemap → run: `node ${CLAUDE_PLUGIN_ROOT}/tools/sitemap-analyzer.mjs generate <dir> <url>`
+- Missing robots.txt → run: `node ${CLAUDE_PLUGIN_ROOT}/tools/robots-analyzer.mjs generate <dir> <url>`
+
+**GEO fixes**:
+- Missing llms.txt → run: `node ${CLAUDE_PLUGIN_ROOT}/tools/llms-txt-generator.mjs <dir>`
+- Missing structured data → run: `node ${CLAUDE_PLUGIN_ROOT}/tools/schema-engine.mjs generate <type> --out=<path>`
+- Blocked AI bots → update robots.txt to allow GPTBot, PerplexityBot, ClaudeBot, Google-Extended
+- Improve content structure: add question-based H2s, TL;DR summaries, definition patterns
+
+**AEO fixes**:
+- Missing FAQ schema → generate FAQPage from Q&A content on page
+- Missing speakable → add speakable schema for key content sections
+- Snippet optimization → restructure answers to 40-60 word direct answers
+
+## Phase 4: Verify
+
+Re-run all three scanners. Show before/after score comparison.
+
+## Phase 5: Save History
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/audit-history.mjs save <dir> seo <score>
+node ${CLAUDE_PLUGIN_ROOT}/tools/audit-history.mjs save <dir> geo <score>
+node ${CLAUDE_PLUGIN_ROOT}/tools/audit-history.mjs save <dir> aeo <score>
+```
+
+## Phase 6: Content Strategy
+
+Advise on content optimizations the scanner cannot automate:
+- Rewrite H2 headers as questions for AI citation
+- Add concise TL;DR summaries under key sections
+- Write in citation-ready format: factual, quotable, 134-167 word passages
+- Create comparison tables, statistics pages, glossaries
+
+## Phase 7: Backlink Strategy
+
+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.

package/skills/rank-fix/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: rank-fix
+description: Auto-fix all SEO/GEO/AEO findings in one command. Scan, fix, verify.
+---
+
+# Auto-Fix All
+
+Fix everything that can be automated in one pass.
+
+## Step 1: Scan
+
+Run all scanners to get current findings:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/seo-scanner.mjs <dir>
+node ${CLAUDE_PLUGIN_ROOT}/tools/geo-scanner.mjs <dir>
+node ${CLAUDE_PLUGIN_ROOT}/tools/aeo-scanner.mjs <dir>
+```
+
+## Step 2: Fix
+
+For each finding, apply automated fix:
+
+**File generation** (create missing files):
+- robots.txt → `node ${CLAUDE_PLUGIN_ROOT}/tools/robots-analyzer.mjs generate <dir> <url>`
+- sitemap.xml → `node ${CLAUDE_PLUGIN_ROOT}/tools/sitemap-analyzer.mjs generate <dir> <url>`
+- llms.txt → `node ${CLAUDE_PLUGIN_ROOT}/tools/llms-txt-generator.mjs <dir>`
+- JSON-LD schema → `node ${CLAUDE_PLUGIN_ROOT}/tools/schema-engine.mjs generate <type> --out=<path>`
+
+**HTML edits** (use Edit tool):
+- Missing title, meta description, OG tags, canonical, viewport, charset, lang
+- Missing H1, alt text on images, semantic landmarks (main, nav, footer)
+- Inject generated schema into head before closing tag
+
+**robots.txt edits** (use Edit tool):
+- Unblock AI bots (GPTBot, PerplexityBot, ClaudeBot, Google-Extended)
+- Add Sitemap directive
+
+## Step 3: Verify
+
+Re-run all scanners. Report:
+- Issues found: X
+- Auto-fixed: Y
+- Remaining (manual): Z
+- Score improvement: before → after
+
+## Step 4: Save History
+
+Save new scores via audit-history tool.

package/skills/rank-geo/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: rank-geo
+description: AI search optimization audit. Optimize content for ChatGPT, Perplexity, Google AI Overviews.
+---
+
+# GEO Audit — AI Search Optimization
+
+## Phase 1: Scan
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/geo-scanner.mjs <project-directory>
+```
+
+## Phase 2: Report
+
+Present GEO findings grouped by:
+- **AI Bot Access** — which bots are allowed/blocked in robots.txt
+- **Structured Data** — JSON-LD quality for AI extraction
+- **Content Structure** — question headers, definitions, citation-ready passages
+- **Discoverability** — llms.txt, sitemap, breadcrumbs
+
+## Phase 3: Fix
+
+- Blocked AI bots → update robots.txt: `node ${CLAUDE_PLUGIN_ROOT}/tools/robots-analyzer.mjs generate <dir> <url>`
+- Missing llms.txt → generate: `node ${CLAUDE_PLUGIN_ROOT}/tools/llms-txt-generator.mjs <dir>`
+- Missing Organization schema → generate: `node ${CLAUDE_PLUGIN_ROOT}/tools/schema-engine.mjs generate Organization --name="..." --url="..."`
+- Missing Author schema → generate Person schema with credentials
+- No question H2s → rewrite key H2 headers as "What is...", "How does...", "Why..."
+- No TL;DR patterns → add 1-2 sentence summaries under important H2 sections
+- No definition patterns → add "[Product] is [clear definition]" in opening paragraphs
+
+## Phase 4: Verify
+
+Re-run geo-scanner. Show before/after GEO score.
+
+## Phase 5: Advanced Guidance
+
+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)
+4. Add comparison tables and statistics (156% higher AI selection with multimedia)

package/skills/rank-schema/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: rank-schema
+description: Structured data management. Detect, validate, generate, and inject JSON-LD schema.
+---
+
+# Schema Management
+
+## Phase 1: Detect
+
+Scan all HTML files for existing JSON-LD:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/schema-engine.mjs detect <dir>
+```
+
+Report: which schema types found, which files contain them.
+
+## Phase 2: Validate
+
+For each detected schema, validate against Google's requirements. Report: missing required fields, deprecated types, invalid values.
+
+## Phase 3: Recommend
+
+Based on project type detection:
+- SaaS → Organization, WebSite+SearchAction, SoftwareApplication, FAQPage
+- E-commerce → Product+Offer, Organization, BreadcrumbList, FAQPage
+- Local → LocalBusiness, Organization, FAQPage, BreadcrumbList
+- Publisher → Article/BlogPosting, Person (author), Organization, BreadcrumbList
+
+Flag missing recommended types.
+
+## Phase 4: Generate + Inject
+
+For each missing schema:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/tools/schema-engine.mjs generate <type> --name="..." --url="..."
+```
+
+Inject into HTML: add script tag before closing head using Edit tool.
+
+## Phase 5: Verify
+
+Re-run detect to confirm all schema is present and valid.