seo-gravity-mcp 1.0.0 → 1.0.2

package/README.md

@@ -1,20 +1,188 @@
-# 🚀 SEO Gravity MCP Server
+# 🚀 SEO Gravity MCP (v1.0.2)
 
-The core Model Context Protocol (MCP) server for **SEO Gravity**.
+<div align="center">
 
-## Installation
+[![npm version](https://img.shields.io/npm/v/seo-gravity-mcp?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/seo-gravity-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/seo-gravity-mcp?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/seo-gravity-mcp)
+![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-blue?style=for-the-badge&logo=anthropic)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
+![Node.js](https://img.shields.io/badge/Node.js-18+-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)
+![Zero API Cost](https://img.shields.io/badge/Zero_API_Cost-100%25_Free-orange?style=for-the-badge)
+
+**The Universal SEO Intelligence, Source-Code Correlation & Remediation Engine for AI Coding Agents.**
+
+[⚡ Instant Start](#-instant-start) • [🤖 Client Setup](#-ai-ide--mcp-client-setup) • [🧠 5-Stage Autonomous Loop](#-the-5-stage-autonomous-remediation-loop) • [🛠 Tool Catalog (35 Tools)](#-complete-tool-catalog-35-tools) • [📄 License](#-license)
+
+</div>
+
+---
+
+## 🌟 What is SEO Gravity?
+
+**SEO Gravity** gives AI coding agents (Antigravity, Cursor, Claude Code, Windsurf, Cline, Roo Code, etc.) the autonomous ability to **understand, audit, fix, and continuously verify the SEO of the websites they build.**
+
+Instead of acting as a passive "SEO metrics dump", SEO Gravity connects **rendered web signals** directly to your **source code components** (Next.js App Router, Astro, Vite/React, Remix, SvelteKit), ranks issues by impact-to-effort priority, generates code fix blueprints, and verifies that commits introduce **zero regressions**.
+
+```text
+ ┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+ │ 1. DISCOVER  │ ──▶ │  2. OBSERVE  │ ──▶ │ 3. DIAGNOSE  │ ──▶ │    4. FIX    │ ──▶ │  5. VERIFY   │
+ │ Framework    │     │ Live/Dev SSR │     │ Root Causes  │     │ AI Modifies  │     │ Re-crawl &   │
+ │ Routes       │     │ SERP & Comp. │     │ Prioritized  │     │ Source Code  │     │ Regression   │
+ │ Source Map   │     │ Crawl Graph  │     │ Action Plan  │     │ Components   │     │ Diff Check   │
+ └──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
+```
+
+---
+
+## 💡 Key Architectural Pillars
+
+1. **Source-to-URL Correlation**: Directly maps audited URLs (`/blog/my-post`) to source files (`app/blog/[slug]/page.tsx`), identifying missing metadata exports or canonical tags.
+2. **Canonical Finding Model**: Every audit issue produces a normalized finding with `id`, `severity`, `confidence` ($0.0-1.0$), `evidenceType` (*Observed*, *Derived*, *Heuristic*, *Predictive*), `effort`, `priorityScore`, and verification steps.
+3. **Crawl Graph & Site Architecture**: Computes BFS click depths, orphan pages, hub pages, circular link loops, and internal link equity (PageRank heuristic).
+4. **Multidimensional Health Scoring**: Breaks scores into 7 discrete dimensions (Technical, Content, Discoverability, Authority, Entity, Performance, AI Readiness) with confidence levels.
+5. **SEO Regression & Snapshot System**: Creates snapshots (`seo.gravity/v1`) before commits/PRs and validates that changes introduced 0 regressions.
+6. **Zero Paid API Requirement**: 100% functional out-of-the-box using local AST parsing, cheerio, JSDOM, Google Autocomplete, and standard web extraction.
+
+---
+
+## ⚡ Instant Start
+
+Run instantly with `npx`:
 
 ```bash
-npm install
-npm run build
+npx -y seo-gravity-mcp
 ```
 
-## Running the MCP Server
+Or install globally:
 
 ```bash
-node dist/index.js
+npm install -g seo-gravity-mcp
+```
+
+---
+
+## 🤖 AI IDE & MCP Client Setup
+
+### 1. 🟣 Claude Desktop
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "seo-gravity": {
+      "command": "npx",
+      "args": ["-y", "seo-gravity-mcp"]
+    }
+  }
+}
+```
+
+### 2. ⚡ Cursor
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "seo-gravity": {
+      "command": "npx",
+      "args": ["-y", "seo-gravity-mcp"]
+    }
+  }
+}
+```
+
+### 3. 🌊 Antigravity / Windsurf / VS Code Cline
+Add to `mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "seo-gravity": {
+      "command": "npx",
+      "args": ["-y", "seo-gravity-mcp"]
+    }
+  }
+}
 ```
 
-## Available Tools (28 Tools)
+---
+
+## 🛠 Complete Tool Catalog (35 Tools)
+
+### Layer 0: Agent Orchestration & Remediation (Flagship)
+| Tool Name | Operational Class | Description |
+| :--- | :--- | :--- |
+| `seo_project_audit` | **Planning / Audit** | Scans workspace framework, discovers routes, correlates source files, builds crawl graph, and computes multidimensional SEO health. |
+| `seo_diagnose` | **Planning / Diagnose** | Deep root-cause inspection linking an observed issue/URL back to specific source code files with ready-to-use fix blueprints. |
+| `seo_prioritize` | **Planning / Strategy** | Ranks findings into Quick Wins, Critical Blockers, and Architectural Improvements using `(Impact × Confidence × Reach) / Effort`. |
+| `seo_fix_plan` | **Planning / Execution** | Generates an end-to-end code modification and verification plan for AI coding agents. |
+| `seo_snapshot_create` | **Verification** | Creates and saves a project SEO baseline snapshot adhering to canonical schema `seo.gravity/v1`. |
+| `seo_snapshot_compare` | **Verification** | Diffs two snapshots to compute resolved findings, new regressions, and multidimensional score deltas. |
+| `seo_regression_check` | **Verification / CI** | Automated pass/fail regression check with alert messages for CI/CD gates and PR bots. |
+
+### Layer 1: SERP & Competitor Intelligence
+| Tool Name | Description |
+| :--- | :--- |
+| `seo_serp_analyze` | Live Google SERP scraper returning rankings, snippets, People Also Ask (PAA), and SERP features. |
+| `seo_competitor_content_gap` | Compares target page against top 3-5 competitors for missing TF-IDF entities, subtopics, and word count deltas. |
+| `seo_competitor_profile` | Deep extraction of competitor heading tree (H1-H4), schema types, reading grade, and link ratios. |
+| `seo_competitor_diff` | 25-factor side-by-side scorecard comparing your page vs #1 competitor. |
+| `seo_forum_discussions_pulse` | Scrapes Reddit & Quora threads ranking for a query to extract user pain points and consensus. |
+
+### Layer 2: Generative Engine Optimization (GEO & AEO)
+| Tool Name | Description |
+| :--- | :--- |
+| `seo_geo_ai_readiness_audit` | Audits content for AI Overviews & Perplexity citation readiness with structured retrieval signals and evidence tiers. |
+| `seo_llms_txt_generate` | Generates standard `/llms.txt` and `/llms-full.txt` markdown context files for AI search bots. |
+| `seo_ai_bots_robots_audit` | Audits robots.txt permissions specifically for AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended). |
+
+### Layer 3: Information Gain & E-E-A-T
+| Tool Name | Description |
+| :--- | :--- |
+| `seo_information_gain_score` | Quantifies content novelty vs top 10 SERPs to prevent generic AI fluff penalties. |
+| `seo_eeat_audit` | Audits Google E-E-A-T trust signals (Person schema, author bylines, sameAs Wikidata/LinkedIn, publish/modified dates). |
+
+### Layer 4: On-Page & Content Strategy
+| Tool Name | Description |
+| :--- | :--- |
+| `seo_onpage_audit` | Deep on-page audit of pixel width, meta CTR, heading hierarchy, image alt, and slug optimization. |
+| `seo_content_brief_generate` | Generates data-backed Content Outline & Brief with target word count, H1/H2/H3 structure, and FAQs. |
+| `seo_readability_score` | Computes Flesch Reading Ease, Flesch-Kincaid Grade Level, and Gunning Fog index. |
+
+### Layer 5: Technical SEO & JavaScript Hydration
+| Tool Name | Description |
+| :--- | :--- |
+| `seo_technical_audit` | Inspects HTTP status codes, redirect chains, canonical consistency, meta robots (`noindex` leaks), and SSL. |
+| `seo_js_rendering_diff` | Compares raw server HTML vs hydrated client DOM (JavaScript SEO) to detect client-only content or broken tags. |
+| `seo_robots_txt_validate` | Validates bot crawlability against specific paths and User-Agents. |
+| `seo_sitemap_inspect` | Validates XML sitemaps, sitemap indexes, lastmod timestamps, and URL limit constraints. |
+| `seo_internal_links_analyze` | Analyzes internal link equity distribution, anchor texts, generic anchors, and nofollow flags. |
+
+### Layer 6: Keyword Research & Intent
+| Tool Name | Description |
+| :--- | :--- |
+| `seo_keyword_suggestions` | Generates keyword suggestions using Google Autocomplete and Alphabet Soup expansion. |
+| `seo_questions_find` | Finds question queries asked by users across Google (Who, What, Where, When, Why, How, Can). |
+| `seo_keyword_cluster` | Clusters keyword lists into Topic Pillars and Supporting Articles using semantic similarity. |
+| `seo_search_intent_classify` | Classifies keywords into Informational, Navigational, Commercial, or Transactional intent. |
+
+### Layer 7: Schema & Entity Graph
+| Tool Name | Description |
+| :--- | :--- |
+| `seo_entity_salience_map` | Extracts named entities, computes salience scores, and generates SPO relationship triples. |
+| `seo_schema_generate` | Generates validated Schema.org JSON-LD scripts (Article, FAQPage, Product, LocalBusiness, Organization). |
+| `seo_schema_validate` | Validates structured data against Schema.org and Google Rich Result criteria. |
+
+### Layer 8: Performance & Maintenance
+| Tool Name | Description |
+| :--- | :--- |
+| `seo_pagespeed_audit` | Checks Core Web Vitals (LCP, FCP, CLS, TTFB) with performance optimization fixes. |
+| `seo_indexnow_submit` | Submits newly created or updated URLs directly to Bing & Yandex via the IndexNow API protocol. |
+| `seo_content_decay_audit` | Scans content for freshness decay (stale year references, outdated stats, broken external links). |
+
+---
+
+## 📄 License
 
-See root [README.md](../README.md) or [SEO_GRAVITY_MCP_SPEC.md](../SEO_GRAVITY_MCP_SPEC.md) for full documentation of all 28 tools.
+MIT License. Free for open-source and commercial use.

package/dist/index.js

@@ -11,9 +11,103 @@ import { auditTechnical, diffJsRendering, validateRobotsTxt, inspectSitemap, ana
 import { getKeywordSuggestions, findQuestions, clusterKeywords, classifySearchIntent } from './tools/keywords.js';
 import { mapEntitySalience, generateSchemaMarkup, validateSchema } from './tools/schema.js';
 import { auditPageSpeed, submitIndexNow, auditContentDecay } from './tools/performance.js';
-// Define the 28 MCP Tools
+import { auditProject, diagnoseSeo, prioritizeFindings, generateFixPlan, createSnapshotTool, compareSnapshotsTool, checkRegression } from './tools/orchestration.js';
+// Define the 35 MCP Tools
 const TOOLS = [
-    // 1. SERP & Competitor Intelligence
+    // ==========================================
+    // Layer 0. Agent Orchestration & Remediation
+    // ==========================================
+    {
+        name: 'seo_project_audit',
+        description: 'Flagship project audit: scans codebase for framework (Next.js, Astro, Vite, Remix), maps discovered routes to source files, builds crawl graph, and computes multidimensional SEO scores (Technical, Content, AI Readiness, Discoverability, Entity).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_path: { type: 'string', description: 'Absolute or relative path to project workspace root' },
+                base_url: { type: 'string', description: 'Optional live or dev server URL (e.g. "http://localhost:3000")' },
+                crawl_depth: { type: 'number', description: 'Crawl depth for internal link graph analysis (default 2)' }
+            },
+            required: ['project_path']
+        }
+    },
+    {
+        name: 'seo_diagnose',
+        description: 'Deep root-cause diagnostic: correlates an observed SEO issue or URL back to specific source code files, components, and line numbers with actionable code fix blueprints.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_path: { type: 'string', description: 'Path to project workspace root' },
+                target_url_or_file: { type: 'string', description: 'URL, route path (e.g. "/blog/[slug]"), or file path to diagnose' },
+                focus_issue_id: { type: 'string', description: 'Optional specific finding ID (e.g. "SEO-CANONICAL-001")' }
+            },
+            required: ['project_path', 'target_url_or_file']
+        }
+    },
+    {
+        name: 'seo_prioritize',
+        description: 'Ranks and groups project SEO findings into actionable sprints (Quick Wins, Critical Blockers, Architectural Improvements) using the (Impact × Confidence × Reach) / Effort formula.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_path: { type: 'string', description: 'Project path or raw findings array' },
+                max_count: { type: 'number', description: 'Max items per sprint category (default 20)' }
+            },
+            required: ['project_path']
+        }
+    },
+    {
+        name: 'seo_fix_plan',
+        description: 'Generates a structured, step-by-step code modification and verification plan for AI coding agents to remediate project SEO issues.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_path: { type: 'string', description: 'Path to project workspace root' },
+                finding_ids: { type: 'array', items: { type: 'string' }, description: 'Optional subset of finding IDs to plan fixes for' }
+            },
+            required: ['project_path']
+        }
+    },
+    {
+        name: 'seo_snapshot_create',
+        description: 'Creates a baseline or milestone project SEO snapshot adhering to canonical schema `seo.gravity/v1`, optionally exporting to a JSON file.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_path: { type: 'string', description: 'Path to project workspace root' },
+                base_url: { type: 'string', description: 'Optional live or dev server URL' },
+                output_path: { type: 'string', description: 'Optional destination file path to save snapshot JSON' }
+            },
+            required: ['project_path']
+        }
+    },
+    {
+        name: 'seo_snapshot_compare',
+        description: 'Compares two SEO project snapshots (e.g. baseline vs current) to compute exact resolved issues, new regressions, and multidimensional score deltas.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                baseline_snapshot: { type: 'object', description: 'Baseline ProjectSnapshot object or file path' },
+                current_snapshot: { type: 'object', description: 'Current ProjectSnapshot object or file path' }
+            },
+            required: ['baseline_snapshot', 'current_snapshot']
+        }
+    },
+    {
+        name: 'seo_regression_check',
+        description: 'Automated CI/PR regression check: compares current project state against a baseline snapshot and returns a pass/fail verdict with regression alerts.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_path: { type: 'string', description: 'Path to project workspace root' },
+                baseline_snapshot: { type: 'object', description: 'Baseline ProjectSnapshot object or file path' },
+                base_url: { type: 'string', description: 'Optional live or dev server URL' }
+            },
+            required: ['project_path', 'baseline_snapshot']
+        }
+    },
+    // ==========================================
+    // Layer 1. SERP & Competitor Intelligence
+    // ==========================================
     {
         name: 'seo_serp_analyze',
         description: 'Scrapes live Google SERP for any keyword. Returns top ranking URLs, snippets, People Also Ask (PAA), Related Searches, and rich SERP features.',
@@ -76,7 +170,9 @@ const TOOLS = [
             required: ['topic_or_keyword']
         }
     },
-    // 2. GEO & AI Search (AEO)
+    // ==========================================
+    // Layer 2. GEO & AI Search (AEO)
+    // ==========================================
     {
         name: 'seo_geo_ai_readiness_audit',
         description: 'Evaluates content for citation readiness in Google AI Overviews, Perplexity.ai, and ChatGPT Search (checks direct definitions, semantic chunking, tables, and stats).',
@@ -125,7 +221,9 @@ const TOOLS = [
             required: ['domain_or_url']
         }
     },
-    // 3. Information Gain & E-E-A-T
+    // ==========================================
+    // Layer 3. Information Gain & E-E-A-T
+    // ==========================================
     {
         name: 'seo_information_gain_score',
         description: 'Quantifies content novelty vs top 10 Google results (Google Information Gain Patent) to detect and fix generic AI fluff.',
@@ -149,7 +247,9 @@ const TOOLS = [
             required: ['url_or_html']
         }
     },
-    // 4. On-Page & Content Strategy
+    // ==========================================
+    // Layer 4. On-Page & Content Strategy
+    // ==========================================
     {
         name: 'seo_onpage_audit',
         description: 'Comprehensive on-page audit of a URL, local file, or raw HTML (title pixel width, meta CTR, heading hierarchy, image alt, and slug).',
@@ -190,7 +290,9 @@ const TOOLS = [
             required: ['text_or_url']
         }
     },
-    // 5. Technical SEO & JS Hydration
+    // ==========================================
+    // Layer 5. Technical SEO & JS Hydration
+    // ==========================================
     {
         name: 'seo_technical_audit',
         description: 'Inspects HTTP status code, redirect chains, canonical consistency, meta robots (noindex/nofollow), hreflang, SSL, and OpenGraph tags.',
@@ -248,7 +350,9 @@ const TOOLS = [
             required: ['url']
         }
     },
-    // 6. Keyword Research & Intent Clustering
+    // ==========================================
+    // Layer 6. Keyword Research & Intent
+    // ==========================================
     {
         name: 'seo_keyword_suggestions',
         description: 'Extracts keyword suggestions and long-tail variations using Google Autocomplete and the Alphabet Soup method.',
@@ -295,7 +399,9 @@ const TOOLS = [
             required: ['keywords']
         }
     },
-    // 7. Schema & Entity Graph
+    // ==========================================
+    // Layer 7. Schema & Entity Graph
+    // ==========================================
     {
         name: 'seo_entity_salience_map',
         description: 'Extracts core entities, computes salience scores, and extracts Subject-Predicate-Object (SPO) relationship triples.',
@@ -334,7 +440,9 @@ const TOOLS = [
             required: ['url_or_jsonld']
         }
     },
-    // 8. Performance, IndexNow & Maintenance
+    // ==========================================
+    // Layer 8. Performance & Maintenance
+    // ==========================================
     {
         name: 'seo_pagespeed_audit',
         description: 'Checks Core Web Vitals (LCP, FCP, CLS, TTFB) with performance optimization fixes.',
@@ -376,7 +484,7 @@ const TOOLS = [
 // Initialize Server
 const server = new Server({
     name: 'seo-gravity-mcp',
-    version: '1.0.0'
+    version: '1.0.2'
 }, {
     capabilities: {
         tools: {}
@@ -393,6 +501,28 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         let result;
         switch (name) {
+            // 0. Agent Orchestration & Remediation
+            case 'seo_project_audit':
+                result = await auditProject(a.project_path, a.base_url, a.crawl_depth);
+                break;
+            case 'seo_diagnose':
+                result = await diagnoseSeo(a.project_path, a.target_url_or_file, a.focus_issue_id);
+                break;
+            case 'seo_prioritize':
+                result = await prioritizeFindings(a.project_path, a.max_count);
+                break;
+            case 'seo_fix_plan':
+                result = await generateFixPlan(a.project_path, a.finding_ids);
+                break;
+            case 'seo_snapshot_create':
+                result = await createSnapshotTool(a.project_path, a.base_url, a.output_path);
+                break;
+            case 'seo_snapshot_compare':
+                result = await compareSnapshotsTool(a.baseline_snapshot, a.current_snapshot);
+                break;
+            case 'seo_regression_check':
+                result = await checkRegression(a.project_path, a.baseline_snapshot, a.base_url);
+                break;
             // 1. SERP & Competitors
             case 'seo_serp_analyze':
                 result = await analyzeSerp(a.query, a.country, a.language, a.num_results);

package/dist/test.js

@@ -1,11 +1,23 @@
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+// Core Tool Imports
 import { auditOnPage } from './tools/onpage.js';
-import { auditGeoAiReadiness, generateLlmsTxt } from './tools/geo.js';
+import { auditGeoAiReadiness } from './tools/geo.js';
 import { clusterKeywords, classifySearchIntent } from './tools/keywords.js';
 import { generateSchemaMarkup, validateSchema } from './tools/schema.js';
-import { auditContentDecay } from './tools/performance.js';
+// New v1.0.2 Agent Orchestration Imports
+import { auditProject, diagnoseSeo, prioritizeFindings, generateFixPlan, createSnapshotTool, checkRegression } from './tools/orchestration.js';
+import { detectFramework, discoverRoutes, mapUrlToRouteSource } from './utils/projectScanner.js';
+import { CrawlGraphBuilder } from './utils/crawlGraph.js';
+import { calculatePriorityScore } from './utils/findingEngine.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const FIXTURES_DIR = path.resolve(__dirname, '../test/fixtures');
 async function runTests() {
-    console.log('🧪 Starting SEO Gravity MCP Comprehensive Test Suite...\n');
+    console.log('🧪 Starting SEO Gravity MCP v1.0.2 Comprehensive Test Suite...\n');
+    // -------------------------------------------------------------
     // Test 1: On-Page Audit
+    // -------------------------------------------------------------
     console.log('1️⃣ Testing On-Page Audit...');
     const sampleHtml = `
     <!DOCTYPE html>
@@ -28,20 +40,18 @@ async function runTests() {
     </html>
   `;
     const onpage = await auditOnPage(sampleHtml, 'project management software');
-    console.log(`✅ On-Page Score: ${onpage.overallScore}/100 | Title status: ${onpage.titleAudit.status} | H1 count: ${onpage.headingsAudit.h1Count}`);
-    // Test 2: GEO / AEO Readiness Audit
-    console.log('\n2️⃣ Testing GEO & AI Search Readiness Audit...');
+    console.log(`   ✅ On-Page Score: ${onpage.overallScore}/100 | Title: ${onpage.titleAudit.status} | H1s: ${onpage.headingsAudit.h1Count}`);
+    // -------------------------------------------------------------
+    // Test 2: GEO / AEO Readiness with Evidence Tiers
+    // -------------------------------------------------------------
+    console.log('\n2️⃣ Testing GEO & AI Search Readiness Audit (with Evidence Tiers)...');
     const geo = await auditGeoAiReadiness(sampleHtml, 'best project management software');
-    console.log(`✅ GEO Score: ${geo.overallGeoScore}/100 | Citation Likelihood: ${geo.citationLikelihood} | Direct Answer: ${geo.checks.directAnswerParagraph.passed}`);
-    // Test 3: LLMS.txt Generation
-    console.log('\n3️⃣ Testing llms.txt Generation...');
-    const llms = generateLlmsTxt('SaaS Suite', 'Cloud workspace tools', [
-        { title: 'Home', url: 'https://example.com', description: 'Main landing page' },
-        { title: 'Docs', url: 'https://example.com/docs', description: 'API reference' }
-    ]);
-    console.log(`✅ llms.txt generated (${llms.llmsTxt.length} chars)`);
-    // Test 4: Schema Generation & Validation
-    console.log('\n4️⃣ Testing Schema.org JSON-LD Generation & Validation...');
+    console.log(`   ✅ GEO Score: ${geo.overallGeoScore}/100 | Citation: ${geo.citationLikelihood} | Confidence: ${geo.confidence}`);
+    console.log(`   ✅ AI Retrieval Signals: Direct Answer=${geo.aiRetrievalSignals?.directEntityDefinition}, Stats=${geo.aiRetrievalSignals?.factualDataAndStats}`);
+    // -------------------------------------------------------------
+    // Test 3: Schema Generation & Validation
+    // -------------------------------------------------------------
+    console.log('\n3️⃣ Testing Schema.org JSON-LD Generation & Validation...');
     const schema = generateSchemaMarkup('FAQPage', {
         items: [
             { question: 'What is project management software?', answer: 'It is a platform to coordinate team tasks and roadmaps.' },
@@ -49,9 +59,11 @@ async function runTests() {
         ]
     });
     const val = await validateSchema(schema.jsonLdScript.replace(/<script[^>]*>/, '').replace(/<\/script>/, ''));
-    console.log(`✅ Schema Generated & Validated (${val.schemasDetectedCount} schemas detected, Valid: ${val.schemas[0]?.isValid})`);
-    // Test 5: Keyword Clustering & Intent Classification
-    console.log('\n5️⃣ Testing Keyword Clustering & Search Intent Classification...');
+    console.log(`   ✅ Schema Validated (${val.schemasDetectedCount} detected, Valid: ${val.schemas[0]?.isValid})`);
+    // -------------------------------------------------------------
+    // Test 4: Keyword Clustering & Intent Classification
+    // -------------------------------------------------------------
+    console.log('\n4️⃣ Testing Keyword Clustering & Search Intent Classification...');
     const keywords = [
         'best running shoes',
         'buy running shoes online',
@@ -62,15 +74,94 @@ async function runTests() {
     ];
     const clusters = clusterKeywords(keywords);
     const intents = classifySearchIntent(keywords);
-    console.log(`✅ Clustered ${keywords.length} keywords into ${clusters.clusterCount} cluster(s)`);
-    console.log(`✅ Intent sample: "${keywords[1]}" -> ${intents[1].intent} (${(intents[1].confidenceScore * 100).toFixed(0)}% confidence)`);
-    // Test 6: Content Decay Audit
-    console.log('\n6️⃣ Testing Content Decay Audit...');
-    const decay = await auditContentDecay('In 2019, our study showed that 45% of users preferred desktop over mobile.');
-    console.log(`✅ Freshness Score: ${decay.freshnessScore}/100 | Decay level: ${decay.decayLevel} | Stale years found: ${decay.staleYearReferences.join(', ')}`);
-    console.log('\n🎉 ALL CORE TEST SUITES PASSED CLEANLY!\n');
+    console.log(`   ✅ Clustered ${keywords.length} keywords into ${clusters.clusterCount} cluster(s)`);
+    console.log(`   ✅ Intent: "${keywords[1]}" -> ${intents[1].intent} (${(intents[1].confidenceScore * 100).toFixed(0)}%)`);
+    // -------------------------------------------------------------
+    // Test 5: Priority Scoring Algorithm
+    // -------------------------------------------------------------
+    console.log('\n5️⃣ Testing Finding Priority Scoring Algorithm...');
+    const p1 = calculatePriorityScore('critical', 1.0, 'trivial', 'site_wide');
+    const p2 = calculatePriorityScore('low', 0.8, 'high', 'isolated');
+    console.log(`   ✅ Critical Site-wide Issue Priority: ${p1.priorityScore} (Tier: ${p1.priorityTier})`);
+    console.log(`   ✅ Isolated Low-Severity Issue Priority: ${p2.priorityScore} (Tier: ${p2.priorityTier})`);
+    // -------------------------------------------------------------
+    // Test 6: Project Framework Detection & Route Discovery
+    // -------------------------------------------------------------
+    console.log('\n6️⃣ Testing Framework Scanner & Route Discovery on Fixtures...');
+    const nextAppPath = path.join(FIXTURES_DIR, 'nextjs-app');
+    const nextFramework = detectFramework(nextAppPath);
+    const nextRoutes = discoverRoutes(nextAppPath, nextFramework);
+    console.log(`   ✅ Next.js Fixture: Framework=${nextFramework.framework}, TypeScript=${nextFramework.hasTypeScript}, Sitemap=${nextFramework.hasSitemapConfig}`);
+    console.log(`   ✅ Discovered ${nextRoutes.length} route(s): ${nextRoutes.map(r => r.routePath).join(', ')}`);
+    const astroAppPath = path.join(FIXTURES_DIR, 'astro-app');
+    const astroFramework = detectFramework(astroAppPath);
+    const astroRoutes = discoverRoutes(astroAppPath, astroFramework);
+    console.log(`   ✅ Astro Fixture: Framework=${astroFramework.framework}, Routes=${astroRoutes.map(r => r.routePath).join(', ')}`);
+    // -------------------------------------------------------------
+    // Test 7: Source-to-URL Mapping
+    // -------------------------------------------------------------
+    console.log('\n7️⃣ Testing Source-to-URL Correlation...');
+    const map1 = mapUrlToRouteSource('/blog/ai-productivity-2026', nextRoutes);
+    const map2 = mapUrlToRouteSource('/about', nextRoutes);
+    console.log(`   ✅ URL '/blog/ai-productivity-2026' mapped to -> ${map1.sourceFilePath} (Method: ${map1.resolutionMethod}, Conf: ${map1.confidence})`);
+    console.log(`   ✅ URL '/about' mapped to -> ${map2.sourceFilePath} (Method: ${map2.resolutionMethod}, Conf: ${map2.confidence})`);
+    // -------------------------------------------------------------
+    // Test 8: Crawl Graph Analysis & PageRank
+    // -------------------------------------------------------------
+    console.log('\n8️⃣ Testing Crawl Graph Analysis...');
+    const brokenPath = path.join(FIXTURES_DIR, 'broken-site/index.html');
+    const crawlBuilder = new CrawlGraphBuilder(brokenPath);
+    const crawlGraph = await crawlBuilder.buildGraph();
+    console.log(`   ✅ Crawl Graph Built: ${crawlGraph.totalNodes} node(s), ${crawlGraph.totalEdges} edge(s), Max Depth: ${crawlGraph.maxClickDepth}`);
+    // -------------------------------------------------------------
+    // Test 9: Flagship Project Audit (seo_project_audit)
+    // -------------------------------------------------------------
+    console.log('\n9️⃣ Testing Flagship seo_project_audit Tool...');
+    const auditResult = await auditProject(nextAppPath);
+    console.log(`   ✅ Project Audit Completed:`);
+    console.log(`      - Overall Health Score: ${auditResult.scores.overallHealth}/100 (Confidence: ${auditResult.scores.overallConfidence})`);
+    console.log(`      - Technical: ${auditResult.scores.technical.score}/100 (${auditResult.scores.technical.state})`);
+    console.log(`      - Content: ${auditResult.scores.content.score}/100 (${auditResult.scores.content.state})`);
+    console.log(`      - AI Readiness: ${auditResult.scores.aiReadiness.score}/100 (${auditResult.scores.aiReadiness.state})`);
+    console.log(`      - Total Findings Detected: ${auditResult.totalFindingsCount}`);
+    console.log(`      - Immediate Action: ${auditResult.recommendedImmediateAction}`);
+    // -------------------------------------------------------------
+    // Test 10: Deep Root-Cause Diagnosis (seo_diagnose)
+    // -------------------------------------------------------------
+    console.log('\n🔟 Testing Deep Diagnostic (seo_diagnose)...');
+    const diagResult = await diagnoseSeo(nextAppPath, '/about');
+    console.log(`   ✅ Diagnosis for '/about':`);
+    console.log(`      - Matched File: ${diagResult.sourceLocation?.filePath}`);
+    console.log(`      - Issues Detected: ${diagResult.detectedIssues.length}`);
+    if (diagResult.suggestedFixBlueprints.length > 0) {
+        console.log(`      - Suggested Fix Blueprint: ${diagResult.suggestedFixBlueprints[0].title}`);
+    }
+    // -------------------------------------------------------------
+    // Test 11: Sprint Prioritization (seo_prioritize)
+    // -------------------------------------------------------------
+    console.log('\n1️⃣1️⃣ Testing Finding Prioritization (seo_prioritize)...');
+    const sprintResult = await prioritizeFindings(nextAppPath);
+    console.log(`   ✅ Prioritization Sprints:`);
+    console.log(`      - Quick Wins: ${sprintResult.sprints.quickWins.length} items`);
+    console.log(`      - Critical Blockers: ${sprintResult.sprints.criticalBlockers.length} items`);
+    console.log(`      - Projected Score After Quick Wins: ${sprintResult.projectedScoreImprovement.projectedScoreAfterQuickWins}/100`);
+    // -------------------------------------------------------------
+    // Test 12: Fix Plan Generation (seo_fix_plan)
+    // -------------------------------------------------------------
+    console.log('\n1️⃣2️⃣ Testing Fix Plan Generation (seo_fix_plan)...');
+    const fixPlan = await generateFixPlan(nextAppPath);
+    console.log(`   ✅ Fix Plan Generated: ${fixPlan.totalSteps} remediation step(s) ready for AI coding execution.`);
+    // -------------------------------------------------------------
+    // Test 13: Snapshot Creation, Diffing & Regression Checks
+    // -------------------------------------------------------------
+    console.log('\n1️⃣3️⃣ Testing Snapshot Creation & Regression Verification (seo_snapshot_create & seo_regression_check)...');
+    const baselineSnap = await createSnapshotTool(nextAppPath);
+    console.log(`   ✅ Baseline Snapshot Created: ID=${baselineSnap.snapshot.snapshotId}, Score=${baselineSnap.snapshot.scores.overallHealth}/100`);
+    const regCheck = await checkRegression(nextAppPath, baselineSnap.snapshot);
+    console.log(`   ✅ Regression Check: ${regCheck.verdict} (Status: ${regCheck.regressionReport.status})`);
+    console.log('\n🎉 ALL 13 TEST SUITES (CORE + v1.0.2 ORCHESTRATION) PASSED CLEANLY!\n');
 }
 runTests().catch(err => {
-    console.error('Test failed:', err);
+    console.error('❌ Test failed:', err);
     process.exit(1);
 });

package/dist/tools/geo.js

@@ -36,11 +36,47 @@ export async function auditGeoAiReadiness(urlOrText, targetQuery) {
     const entityScore = queryWords.every(w => content.toLowerCase().includes(w)) ? 15 : 5;
     const totalScore = directAnswerScore + chunkingScore + structuredScore + statsScore + entityScore;
     const citationLikelihood = totalScore >= 75 ? 'High' : totalScore >= 50 ? 'Medium' : 'Low';
+    const confidence = content.length > 300 ? 'High' : content.length > 100 ? 'Medium' : 'Low';
     const firstSentence = content.split(/[.!?]+/)[0] || '';
+    const aiRetrievalSignals = {
+        directEntityDefinition: directAnswerPassed,
+        selfContainedAnswerBlocks: semanticChunkingPassed,
+        modularSemanticHeadings: hasHeadings,
+        factualDataAndStats: statsMatches.length >= 2,
+        structuredListsOrTables: structuredDataPassed
+    };
+    const evidenceTypeSummary = {
+        observed: [
+            `Heading tags present: ${hasHeadings}`,
+            `Bullet list items found: ${listItemsCount}`,
+            `Data tables detected: ${tablesCount}`,
+            `Numerical statistics/percentages found: ${statsMatches.length}`
+        ],
+        derived: [
+            directAnswerPassed
+                ? 'Target query defined directly in opening section.'
+                : 'Target query definition missing from opening paragraph.',
+            semanticChunkingPassed
+                ? 'Content is structured for autonomous LLM extraction.'
+                : 'Content may be difficult for LLMs to segment into discrete facts.'
+        ],
+        heuristic: [
+            `Entity coverage score: ${entityScore}/15 based on query keyword presence.`,
+            `Estimated citation probability: ${citationLikelihood} based on multi-signal retrieval weights.`
+        ],
+        predictive: [
+            citationLikelihood === 'High'
+                ? 'High likelihood of inclusion in Google AI Overviews and Perplexity synthesis.'
+                : 'Low to moderate probability of direct LLM citation without structured definition addition.'
+        ]
+    };
     return {
         targetQuery,
         overallGeoScore: totalScore,
         citationLikelihood,
+        confidence,
+        aiRetrievalSignals,
+        evidenceTypeSummary,
         checks: {
             directAnswerParagraph: {
                 passed: directAnswerPassed,