gsc-cli 2.0.0

data/lib/gsc/prompts.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module GSC
+  class Prompts
+    PLAYBOOKS = [
+# Master 360° Multi-Horizon Audit
+{
+  id: 0,
+  category: 'master',
+  category_name: '👑 Master 360° Multi-Horizon Audits',
+  title: 'The 360° Multi-Horizon Master SEO & Universal Keyword Audit',
+  impact: 'Maximum Impact (Exhaustive 30d, 90d, 180d audit & action plan)',
+  cli_command: 'gsc performance --days 180 --json',
+  template: "Antigravity, perform an exhaustive 360° SEO, Universal Keyword, and Crawl Health Audit for {{domain}} across 30d, 90d, and 180d horizons.\n\nExecute the following commands with --json and save the final report to both an Antigravity Artifact and to docs/seo/master_audit_report.md:\n\n1. Macro Multi-Horizon Performance & Trends:\n   - `gsc performance --days 30 --json`\n   - `gsc performance --days 90 --json`\n   - `gsc performance --days 180 --json`\n   - `gsc decay --compare 28 --json`\n\n2. Universal Keyword Intelligence (Saved & Unsaved):\n   - Check all saved snapshots: `gsc saved check 1 --json`\n   - Unsaved live search queries: `gsc top-queries --days 180 --limit 500 -s imp --json`\n   - Page 2 striking distance: `gsc opportunities --min-imp 5 --limit 100 --json`\n   - CTR underperformers: `gsc underperformers --limit 50 --json`\n   - Keyword cannibalization conflicts: `gsc cannibalization --json`\n\n3. Google Trends & Autocomplete Velocity:\n   - `gsc trends \"{{seed}}\" --time 12m --json`\n   - `gsc planner \"{{seed}}\" --json`\n\n4. Landing Pages, Post-Click GA4 Behavior & Crawl Budget:\n   - Top traffic landing pages: `gsc top-pages --days 90 --limit 100 --json`\n   - Organic bounce & engagement: `gsc ga4 --organic --days 30 --limit 100 --json`\n   - SERP vs Bounce correlation: `gsc correlation --organic --json`\n   - Sitemap crawl waste: `gsc zombies public/sitemap.xml --json`\n\nGenerate a Master Executive Report containing:\n1. Executive Growth Scorecard (Macro comparison: 30d vs 90d vs 180d clicks, impressions, CTR, pos).\n2. The Universal Keyword Opportunity Matrix (Ranking, Striking Distance, Untargeted Saved Keywords).\n3. Google Trends Seasonal Velocity & Rising Breakouts (+5000% queries).\n4. CTR Optimization Matrix (Title & meta rewrites for low-CTR pages).\n5. Post-Click Leak Audit (High organic impressions with high GA4 bounce).\n6. Technical & Zombie Crawl Waste cleanup plan.\n7. Prioritized 30-Day Sprint (P0, P1, P2 with exact file paths and code edits)."
+},
+
+      # Category: Growth & Striking Distance Opportunities
+      {
+        id: 1,
+        category: 'growth',
+        category_name: '🚀 Growth & Striking Distance',
+        title: 'The Page 2 Striking Distance Leap',
+        impact: 'High Impact (Push Page 2 keywords to Top 3)',
+        cli_command: 'gsc opportunities --min-imp 20 --json',
+        template: 'Antigravity, run `gsc opportunities --min-imp 20 --json` for {{domain}}. Find the top 3 striking-distance queries (positions 8–18 with high impressions). For each query, locate its ranking page in our codebase, identify what content is missing compared to top SERP competitors, expand the page with a targeted FAQ and comparison table, and ping Google Indexing API via `gsc index <url>`.'
+      },
+      {
+        id: 2,
+        category: 'growth',
+        category_name: '🚀 Growth & Striking Distance',
+        title: 'The Untargeted Keyword Goldmine',
+        impact: 'High Impact (Create high-intent new landing pages)',
+        cli_command: 'gsc saved check 1 --json',
+        template: 'Antigravity, inspect our saved keyword research with `gsc saved check 1 --json`. Identify the top 5 keywords with Opportunity Score > 65 that are currently flagged as 🚀 Untargeted. For each keyword, propose a dedicated landing page route, draft high-intent metadata, and generate a semantic content outline.'
+      },
+      {
+        id: 3,
+        category: 'growth',
+        category_name: '🚀 Growth & Striking Distance',
+        title: '5-Year Google Trends Seasonal Surf',
+        impact: 'Medium Impact (Catch seasonal breakout demand)',
+        cli_command: 'gsc trends "{{seed}}" --time 5y --json',
+        template: 'Antigravity, run `gsc trends "{{seed}}" --time 5y --json`. Identify the historical peak search months, extract all rising breakout queries (+5000%), and update our landing page headings and marketing banners to capture the upcoming seasonal search surge.'
+      },
+      {
+        id: 4,
+        category: 'growth',
+        category_name: '🚀 Growth & Striking Distance',
+        title: 'Long-Tail Autocomplete Multiplier',
+        impact: 'Medium Impact (Target long-tail customer questions)',
+        cli_command: 'gsc planner "{{seed}}" --limit 50 --json',
+        template: 'Antigravity, run `gsc planner "{{seed}}" --limit 50 --json`. Group all discovered long-tail queries by search intent (Transactional vs Informational), and generate an interactive FAQ accordion component in our template addressing the top 5 customer questions.'
+      },
+
+      # Category: Conversion & Click-Through Rate (CTR)
+      {
+        id: 5,
+        category: 'ctr',
+        category_name: '🎯 Conversion & CTR Multipliers',
+        title: 'The CTR Underperformer Double',
+        impact: 'High Impact (Double organic clicks with 0 rank changes)',
+        cli_command: 'gsc underperformers --limit 5 --json',
+        template: 'Antigravity, run `gsc underperformers --limit 5 --json` for {{domain}}. For the page with the highest impressions but lowest CTR (<2%), read its current <title> and meta description in our codebase. Rewrite them applying the 50–60 character high-CTR formula (front-loading the exact query, adding bracketed hooks like [2026 Free Tool], and appending brand). Update the file and ping `gsc index <url>`.'
+      },
+      {
+        id: 6,
+        category: 'ctr',
+        category_name: '🎯 Conversion & CTR Multipliers',
+        title: 'Review & FAQ Rich Snippet Enabler',
+        impact: 'High Impact (Win star ratings and expandable FAQs in SERP)',
+        cli_command: 'gsc snippets --json',
+        template: 'Antigravity, run `gsc snippets --json` on {{domain}} to check active search appearances. Then inspect our top traffic pages from `gsc top-pages --json` and inject valid Schema.org JSON-LD structured data (FAQPage or Product) so our Google SERP listings display star ratings and expandable FAQs.'
+      },
+      {
+        id: 7,
+        category: 'ctr',
+        category_name: '🎯 Conversion & CTR Multipliers',
+        title: 'Headline & H1 Alignment Overhaul',
+        impact: 'Medium Impact (Increase on-page conversion rate)',
+        cli_command: 'gsc top-queries --limit 10 --json',
+        template: 'Antigravity, find our top 3 visited landing pages using `gsc ga4 --organic --json`. Audit their <h1> display headings against our copywriting rules (ensure zero trailing periods, strong benefit promise, and strict alignment with high-volume search queries from `gsc top-queries`).'
+      },
+      {
+        id: 8,
+        category: 'ctr',
+        category_name: '🎯 Conversion & CTR Multipliers',
+        title: 'Keyword Cannibalization Consolidator',
+        impact: 'High Impact (Stop competing against your own pages)',
+        cli_command: 'gsc cannibalization --json',
+        template: 'Antigravity, run `gsc cannibalization --json` on {{domain}}. Detect any search queries where 2 or more of our URLs are competing against each other and splitting Google impressions. Recommend which URL should be the authoritative canonical, and add cross-linking or 301 redirects to consolidate ranking power.'
+      },
+
+      # Category: GA4 Behavioral, Ads & Conversion Analytics
+      {
+        id: 9,
+        category: 'analytics',
+        category_name: '📊 GA4 Behavioral & Ad Synergy',
+        title: 'High-Bounce Traffic Leak Plugger',
+        impact: 'High Impact (Rescue lost visitors who bounce in <10s)',
+        cli_command: 'gsc correlation --json',
+        template: 'Antigravity, run `gsc correlation --json`. Correlate high-impression GSC search queries against GA4 bounce rates. Find search queries driving visitors who bounce in under 10 seconds. Audit the page\'s above-the-fold hero section and align the primary value proposition directly to user search intent.'
+      },
+      {
+        id: 10,
+        category: 'analytics',
+        category_name: '📊 GA4 Behavioral & Ad Synergy',
+        title: 'Real-Time Traffic Wave Monitor',
+        impact: 'Medium Impact (Live visitor diagnostic & health check)',
+        cli_command: 'gsc realtime --json',
+        template: 'Antigravity, run `gsc realtime --json`. Check how many live visitors are currently on {{domain}}, which landing pages they are viewing, and verify that our conversion tracking and call-to-actions on those active pages are operating smoothly.'
+      },
+      {
+        id: 11,
+        category: 'analytics',
+        category_name: '📊 GA4 Behavioral & Ad Synergy',
+        title: 'Google Ads & Organic Synergy Optimizer',
+        impact: 'High Impact (Cut wasted ad spend where you rank #1 organically)',
+        cli_command: 'gsc ads --json',
+        template: 'Antigravity, run `gsc ads --json` and `gsc top-queries --json`. Identify expensive Google Ads keywords (high CPC) where our site already ranks in Top 3 organically, and suggest pausing those paid ads to save ad spend while doubling down on organic CTR.'
+      },
+      {
+        id: 12,
+        category: 'analytics',
+        category_name: '📊 GA4 Behavioral & Ad Synergy',
+        title: 'Omni-Channel Attribution & Engagement Audit',
+        impact: 'Medium Impact (Identify top converting traffic channels)',
+        cli_command: 'gsc channels --days 30 --json',
+        template: 'Antigravity, run `gsc channels --days 30 --json`. Compare organic search conversion rates against paid and direct traffic. Highlight which traffic channel has the highest customer engagement rate and recommend channel-specific landing page optimizations.'
+      },
+
+      # Category: Technical SEO, Crawl Health & Indexing
+      {
+        id: 13,
+        category: 'technical',
+        category_name: '🛠️ Technical Health & Crawl Optimization',
+        title: 'The 90-Day Zombie Page Purge',
+        impact: 'High Impact (Reclaim crawl budget and prune dead weight)',
+        cli_command: 'gsc zombies --json',
+        template: 'Antigravity, run `gsc zombies --json` on our sitemap. Identify all low-quality or obsolete pages that have received 0 impressions in the last 90 days. Recommend whether to update them with fresh content or retire them with `gsc remove <url>` to protect crawl budget.'
+      },
+      {
+        id: 14,
+        category: 'technical',
+        category_name: '🛠️ Technical Health & Crawl Optimization',
+        title: 'Sitemap Coverage & Rapid Indexing Blitz',
+        impact: 'High Impact (Force Googlebot to index queued pages)',
+        cli_command: 'gsc inspect-sitemap https://{{domain}}/sitemap.xml --json',
+        template: 'Antigravity, run `gsc inspect-sitemap https://{{domain}}/sitemap.xml --json`. Identify all URLs marked as "Discovered - currently not indexed" or "Crawled - currently not indexed". For any unindexed URL, batch ping Google Indexing API via `gsc index <url>` to accelerate indexing.'
+      },
+      {
+        id: 15,
+        category: 'technical',
+        category_name: '🛠️ Technical Health & Crawl Optimization',
+        title: 'Ranking Decay Early Warning Detection',
+        impact: 'High Impact (Arrest traffic loss before it accelerates)',
+        cli_command: 'gsc decay --days 28 --json',
+        template: 'Antigravity, run `gsc decay --days 28 --json`. Identify queries or pages experiencing period-over-period click or impression drops (>20%). Propose immediate content freshness updates and internal link boosts to reverse the decay.'
+      },
+      {
+        id: 16,
+        category: 'technical',
+        category_name: '🛠️ Technical Health & Crawl Optimization',
+        title: 'Lost Query Resuscitation',
+        impact: 'Medium Impact (Recover queries that fell out of Google)',
+        cli_command: 'gsc decay --json',
+        template: 'Antigravity, run `gsc decay --json` and filter by "lost". Find high-volume keywords that generated traffic last month but completely dropped off this month. Inspect the previous URL and restore missing topical sections.'
+      },
+
+      # Category: Programmatic SEO & Scalable Architecture
+      {
+        id: 17,
+        category: 'programmatic',
+        category_name: '⚡ Programmatic SEO & Directory Scaling',
+        title: 'Programmatic Landing Page Generator',
+        impact: 'High Impact (Build 50+ data-driven landing pages)',
+        cli_command: 'gsc saved check 1 --json',
+        template: 'Antigravity, run `gsc saved check 1 --json`. Extract the top 10 untargeted city or feature keywords. Generate a reusable programmatic template that renders unique, value-dense content for each variation without creating duplicate content.'
+      },
+      {
+        id: 18,
+        category: 'programmatic',
+        category_name: '⚡ Programmatic SEO & Directory Scaling',
+        title: 'Competitor Gap Exploitation via Import',
+        impact: 'High Impact (Steal competitor high-volume terms)',
+        cli_command: 'gsc import clip --json',
+        template: 'Antigravity, run `gsc import clip --json` using our latest competitor export from clipboard. Compare their highest volume keywords against our `gsc top-queries --json`. Identify the 5 most profitable keywords where our competitor ranks but we have zero presence.'
+      },
+      {
+        id: 19,
+        category: 'programmatic',
+        category_name: '⚡ Programmatic SEO & Directory Scaling',
+        title: 'Zero-Click Search & AI Overview Winning Strategy',
+        impact: 'High Impact (Win citations in Google AI Overviews)',
+        cli_command: 'gsc top-queries -s imp --limit 20 --json',
+        template: 'Antigravity, run `gsc top-queries -s imp --limit 20 --json`. Identify informational queries where Google shows AI Overviews or direct answer boxes. Structure our content with concise 40-word definitions, numbered steps, and comparison tables to win the AI Overview citation.'
+      },
+      {
+        id: 20,
+        category: 'programmatic',
+        category_name: '⚡ Programmatic SEO & Directory Scaling',
+        title: 'Mobile vs Desktop SERP Parity Audit',
+        impact: 'Medium Impact (Fix mobile ranking discrepancies)',
+        cli_command: 'gsc devices --json',
+        template: 'Antigravity, run `gsc devices --json`. Compare Mobile CTR vs Desktop CTR for {{domain}}. If mobile CTR lags by more than 30%, inspect our mobile viewport layouts, tap target sizes, and above-the-fold content density.'
+      },
+
+      # Category: Executive Briefings & Daily Standups
+      {
+        id: 21,
+        category: 'executive',
+        category_name: '📋 Executive Briefings & Standups',
+        title: '360° Executive SEO Health Briefing',
+        impact: 'High Impact (Complete C-Suite progress report)',
+        cli_command: 'gsc performance --days 30 --json',
+        template: 'Antigravity, run `gsc performance --days 30 --json`, `gsc decay --json`, and `gsc opportunities --json`. Generate a markdown briefing summarizing: Total Clicks & Growth % MoM, Top 3 Emerging Keywords, Top 3 Striking-Distance Opportunities, and 3 Critical Action Items for this sprint.'
+      },
+      {
+        id: 22,
+        category: 'executive',
+        category_name: '📋 Executive Briefings & Standups',
+        title: 'New Feature Launch Indexing Blitz',
+        impact: 'High Impact (Index new releases within hours)',
+        cli_command: 'gsc index {{url}} --json',
+        template: 'Antigravity, I just launched a new feature/landing page at {{url}}. Inspect its metadata, verify Schema markup, confirm robots.txt accessibility, and immediately submit it to Google Indexing API via `gsc index {{url}}`.'
+      },
+      {
+        id: 23,
+        category: 'executive',
+        category_name: '📋 Executive Briefings & Standups',
+        title: 'Geographic Market Expansion Diagnostic',
+        impact: 'Medium Impact (Find international expansion markets)',
+        cli_command: 'gsc countries --limit 20 --json',
+        template: 'Antigravity, run `gsc countries --limit 20 --json` and `gsc cities --limit 20 --json`. Identify our top 3 international or regional markets outside our primary country. Check if localized currency, language, or shipping details are needed on those landing pages.'
+      },
+      {
+        id: 24,
+        category: 'executive',
+        category_name: '📋 Executive Briefings & Standups',
+        title: 'Title Tag Pixel Width & Truncation Audit',
+        impact: 'Medium Impact (Prevent Google ... truncation on all pages)',
+        cli_command: 'gsc top-pages --limit 25 --json',
+        template: 'Antigravity, crawl our sitemap via `gsc inspect-sitemap --json`, extract all page <title> tags from our repository, and flag any titles under 40 characters (too short) or over 60 characters (truncated by Google with ...). Propose rewritten versions for all flagged titles.'
+      },
+      {
+        id: 25,
+        category: 'executive',
+        category_name: '📋 Executive Briefings & Standups',
+        title: 'The Daily 5-Minute SEO Standup',
+        impact: 'High Impact (Daily check of pulses, wins, and anomalies)',
+        cli_command: 'gsc realtime --json',
+        template: 'Antigravity, run `gsc realtime --json`, `gsc top-queries --limit 5 --json`, and `gsc decay --json`. Give me a 3-bullet standup: (1) Live visitors right now, (2) Yesterday\'s top performing search query, and (3) Any query that saw an unexpected drop requiring attention.'
+      }
+    ].freeze
+
+    def self.all
+      PLAYBOOKS
+    end
+
+    def self.find(id)
+      PLAYBOOKS.find { |p| p[:id] == id.to_i }
+    end
+
+    def self.by_category(cat)
+      PLAYBOOKS.select { |p| p[:category] == cat.to_s.downcase }
+    end
+
+    def self.categories
+      PLAYBOOKS.map { |p| { id: p[:category], name: p[:category_name] } }.uniq { |c| c[:id] }
+    end
+
+    def self.render_prompt(id, domain: nil, seed: nil, url: nil)
+      item = find(id)
+      return nil unless item
+
+      dom = domain || Config.default_domain || 'example.com'
+      s = seed || 'moving boxes'
+      u = url || "https://#{dom}"
+
+      item[:template]
+        .gsub('{{domain}}', dom)
+        .gsub('{{seed}}', s)
+        .gsub('{{url}}', u)
+    end
+  end
+end

data/lib/gsc/site_crawler.rb

@@ -0,0 +1,260 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'fileutils'
+
+module GSC
+  class SiteCrawler
+    attr_reader :target, :options, :results, :broken_links, :missing_alts, :heading_issues, :title_issues, :canonical_issues
+
+    def initialize(target, options = {})
+      @target = target.to_s.strip
+      @options = options
+      @results = []
+      @broken_links = []
+      @missing_alts = []
+      @heading_issues = []
+      @title_issues = []
+      @canonical_issues = []
+    end
+
+    def run(&progress_block)
+      urls = discover_urls(@target)
+      urls = urls.first(@options[:limit]) if @options[:limit] && @options[:limit] > 0
+
+      total = urls.size
+      urls.each_with_index do |url, idx|
+        progress_block.call(url, idx + 1, total) if block_given?
+
+        analyzer = PageAnalyzer.new(url)
+        page_data = analyzer.fetch_and_analyze(
+          check_links: @options[:check_links] || false,
+          gsc_api: @options[:gsc_api],
+          active_domain: @options[:active_domain]
+        )
+
+        @results << page_data
+        categorize_page_issues(page_data)
+      end
+
+      aggregate_summary
+    end
+
+    def generate_markdown_report(filepath)
+      summary = aggregate_summary
+      FileUtils.mkdir_p(File.dirname(File.expand_path(filepath)))
+
+      md = []
+      md << "# 🛠️ Autonomous SEO Site Audit & Broken Link Report"
+      md << ""
+      md << "> **Target**: `#{@target}`  "
+      md << "> **Audit Date**: `#{Time.now.strftime('%Y-%m-%d %H:%M:%S UTC')}`  "
+      md << "> **Pages Audited**: `#{summary[:total_pages]}` | **Total Issues Found**: `#{summary[:total_issues]}`  "
+      md << "> **Broken Links (404/Error)**: `#{summary[:broken_links_count]}` | **Missing Alt Images**: `#{summary[:missing_alts_count]}`  "
+      md << ""
+      md << "---"
+      md << ""
+      md << "## 📊 1. Executive Health Scorecard"
+      md << ""
+      md << "| Metric | Count / Value | Health Status |"
+      md << "| :--- | :---: | :--- |"
+      md << "| **Total Pages Audited** | `#{summary[:total_pages]}` | ℹ️ Crawl Scope |"
+      md << "| **Critical Errors** | `#{summary[:critical_errors_count]}` | #{summary[:critical_errors_count] == 0 ? '🟢 Clean' : '🔴 Action Required'} |"
+      md << "| **Broken Links (404/500)** | `#{summary[:broken_links_count]}` | #{summary[:broken_links_count] == 0 ? '🟢 Zero Broken Links' : '🔴 Broken Links Detected'} |"
+      md << "| **Images Missing Alt** | `#{summary[:missing_alts_count]}` | #{summary[:missing_alts_count] == 0 ? '🟢 100% Accessible' : '🟡 Needs Alt Text'} |"
+      md << "| **Pages with 0 or >1 H1** | `#{summary[:heading_issues_count]}` | #{summary[:heading_issues_count] == 0 ? '🟢 Perfect Hierarchy' : '🟡 Review H1s'} |"
+      md << "| **Title / Meta Flaws** | `#{summary[:title_meta_issues_count]}` | #{summary[:title_meta_issues_count] == 0 ? '🟢 Optimal' : '🟡 Review SERP Truncation'} |"
+      md << ""
+      md << "---"
+      md << ""
+
+      # 2. Broken Links
+      md << "## 🚨 2. Broken Links & Dead Anchors (#{summary[:broken_links_count]} Found)"
+      md << ""
+      if @broken_links.empty?
+        md << "✅ **No broken links detected across all audited pages!**"
+      else
+        md << "The following links returned HTTP errors (404 Not Found, 500 Server Error, or Timeout) and should be updated or removed:"
+        md << ""
+        md << "| Source Page URL | Target Broken URL | Anchor Text | HTTP Status |"
+        md << "| :--- | :--- | :--- | :---: |"
+        @broken_links.each do |b|
+          md << "| `#{b[:source_page]}` | `#{b[:href]}` | #{b[:anchor].empty? ? '*(Empty)*' : b[:anchor]} | **#{b[:status]}** |"
+        end
+      end
+      md << ""
+      md << "---"
+      md << ""
+
+      # 3. Image Alt Tag Fixes
+      md << "## 🖼️ 3. Images Missing Alt Attributes (#{summary[:missing_alts_count]} Found)"
+      md << ""
+      if @missing_alts.empty?
+        md << "✅ **All images on audited pages have descriptive alt text!**"
+      else
+        md << "Search engines and screen readers rely on descriptive `alt` attributes to index visual content:"
+        md << ""
+        md << "| Page URL | Image Source URL | Recommended Fix |"
+        md << "| :--- | :--- | :--- |"
+        @missing_alts.each do |img|
+          md << "| `#{img[:page_url]}` | `#{img[:src]}` | Add descriptive keywords to `alt=\"...\"` |"
+        end
+      end
+      md << ""
+      md << "---"
+      md << ""
+
+      # 4. Heading Hierarchy Flaws
+      md << "## 📑 4. Heading Hierarchy & H1 Flaws (#{summary[:heading_issues_count]} Found)"
+      md << ""
+      if @heading_issues.empty?
+        md << "✅ **All pages have exactly one <h1> and clean structure!**"
+      else
+        md << "| Page URL | Issue Details | Recommended Action |"
+        md << "| :--- | :--- | :--- |"
+        @heading_issues.each do |h|
+          md << "| `#{h[:page_url]}` | #{h[:issue]} | Ensure exactly one <h1> matching primary search query |"
+        end
+      end
+      md << ""
+      md << "---"
+      md << ""
+
+      # 5. Title & Meta Description Flaws
+      md << "## 🏷️ 5. Title & Meta Description Optimizations (#{summary[:title_meta_issues_count]} Found)"
+      md << ""
+      if @title_issues.empty?
+        md << "✅ **All titles and meta descriptions meet 30–60 char and 70–155 char standards!**"
+      else
+        md << "| Page URL | Current Title (Chars) | Current Meta (Chars) | Flaw Detected |"
+        md << "| :--- | :--- | :--- | :--- |"
+        @title_issues.each do |t|
+          md << "| `#{t[:page_url]}` | #{t[:title]} (#{t[:title_chars]}c) | #{t[:meta]} (#{t[:meta_chars]}c) | #{t[:flaw]} |"
+        end
+      end
+      md << ""
+      md << "---"
+      md << ""
+
+      # 6. Prioritized AI Action Sprint
+      md << "## 🤖 6. AI Agent Automated Fix Sprint"
+      md << ""
+      md << "Use these instructions to locate template files and apply fixes:"
+      md << ""
+      md << "1. **P0: Fix Broken Links**: Locate `<a href=\"...\">` tags pointing to dead URLs identified in Section 2."
+      md << "2. **P0: Single <h1> Enforcement**: Ensure all template layouts have exactly one `<h1>`."
+      md << "3. **P1: Image Alt Tag Insertion**: Add descriptive `alt` attributes to all images in Section 3."
+      md << "4. **P1: Title Truncation Fix**: Keep `<title>` under 60 characters and `<meta name=\"description\">` under 155 characters."
+      md << "5. **P2: Googlebot Re-Index**: Ping Google's Indexing API for all updated URLs via `gsc index <url>`."
+      md << ""
+      md << "---\n*Report generated by `gsc site-audit` (On-Page & Off-Page SEO Engine)*"
+
+      File.write(filepath, md.join("\n"), encoding: 'UTF-8')
+      filepath
+    end
+
+    def aggregate_summary
+      critical_errors = @broken_links.size + @results.count { |r| r[:indexability][:noindex] }
+      total_issues = critical_errors + @missing_alts.size + @heading_issues.size + @title_issues.size + @canonical_issues.size
+
+      {
+        total_pages: @results.size,
+        total_issues: total_issues,
+        critical_errors_count: critical_errors,
+        broken_links_count: @broken_links.size,
+        missing_alts_count: @missing_alts.size,
+        heading_issues_count: @heading_issues.size,
+        title_meta_issues_count: @title_issues.size,
+        canonical_issues_count: @canonical_issues.size
+      }
+    end
+
+    private
+
+    def discover_urls(target)
+      if target.end_with?('.xml') || target.include?('sitemap')
+        SitemapLoader.load_urls(target)
+      elsif File.file?(target)
+        [target]
+      else
+        normalized = target.start_with?('http') ? target : "https://#{target}"
+        sitemap_url = "#{normalized.sub(%r{/+$}, '')}/sitemap.xml"
+        urls = SitemapLoader.load_urls(sitemap_url)
+        urls.empty? ? [normalized] : urls
+      end
+    rescue StandardError
+      [target.start_with?('http') ? target : "https://#{target}"]
+    end
+
+    def categorize_page_issues(data)
+      page_url = data[:url]
+
+      # Broken links
+      if data.dig(:links, :verification)
+        data[:links][:verification].each do |link|
+          if !link[:ok]
+            @broken_links << {
+              source_page: page_url,
+              href: link[:href],
+              anchor: link[:anchor],
+              status: link[:status] || 'Error'
+            }
+          end
+        end
+      end
+
+      # Missing alts
+      if data.dig(:images, :missing_alt_images)
+        data[:images][:missing_alt_images].each do |img|
+          @missing_alts << {
+            page_url: page_url,
+            src: img[:src]
+          }
+        end
+      end
+
+      # Headings
+      h1_count = data.dig(:headings, :h1_count) || 0
+      if h1_count == 0
+        @heading_issues << { page_url: page_url, issue: "Missing <h1> tag (0 found)" }
+      elsif h1_count > 1
+        @heading_issues << { page_url: page_url, issue: "Multiple <h1> tags (#{h1_count} found)" }
+      end
+
+      # Title & Meta
+      title_chars = data.dig(:title, :length) || 0
+      meta_chars = data.dig(:meta_description, :length) || 0
+      title_text = data.dig(:title, :text) || ''
+      meta_text = data.dig(:meta_description, :text) || ''
+
+      flaws = []
+      flaws << "Title > 60 chars" if title_chars > 60
+      flaws << "Title < 30 chars" if title_chars > 0 && title_chars < 30
+      flaws << "Missing Title" if title_chars == 0
+      flaws << "Meta > 155 chars" if meta_chars > 155
+      flaws << "Missing Meta" if meta_chars == 0
+
+      if !flaws.empty?
+        @title_issues << {
+          page_url: page_url,
+          title: title_text[0..40],
+          title_chars: title_chars,
+          meta: meta_text[0..40],
+          meta_chars: meta_chars,
+          flaw: flaws.join(', ')
+        }
+      end
+
+      # Canonical
+      if data.dig(:canonical, :url) && !data.dig(:canonical, :self_referencing)
+        @canonical_issues << {
+          page_url: page_url,
+          canonical_url: data[:canonical][:url]
+        }
+      end
+    end
+  end
+end

data/lib/gsc/sitemap_loader.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'zlib'
+require 'stringio'
+
+module GSC
+  class SitemapLoader
+    def self.fetch_content(path_or_url)
+      if path_or_url.start_with?('http://', 'https://')
+        uri = URI(path_or_url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == 'https')
+        http.open_timeout = 10
+        http.read_timeout = 20
+        req = Net::HTTP::Get.new(uri.request_uri)
+        req['User-Agent'] = 'Mozilla/5.0 (compatible; GSC-SEO-Auditor/1.0)'
+        req['Accept-Encoding'] = 'gzip'
+
+        res = http.request(req)
+        raise "HTTP #{res.code} fetching sitemap: #{path_or_url}" unless res.is_a?(Net::HTTPSuccess)
+
+        raw = res.body || ''
+        decompressed = if res['content-encoding'] =~ /gzip/i && !raw.empty?
+                         Zlib::GzipReader.new(StringIO.new(raw)).read
+                       else
+                         raw
+                       end
+        decompressed.to_s.dup.force_encoding('UTF-8').scrub
+      else
+        raise "Local file not found: #{path_or_url}" unless File.exist?(path_or_url)
+        File.read(path_or_url, encoding: 'UTF-8').scrub
+      end
+    end
+
+    def self.load_urls(input, default_origin = nil)
+      resolve_urls(input, default_origin, quiet: true)
+    end
+
+    def self.resolve_urls(input, default_origin = nil, quiet: false)
+      target_input = input
+      if target_input.nil? || target_input.empty?
+        candidates = [
+          'public/sitemap.xml',
+          'public/sitemap-0.xml',
+          'public/sitemap-index.xml',
+          'dist/sitemap.xml',
+          'dist/sitemap-index.xml'
+        ]
+        found = candidates.find { |f| File.exist?(f) }
+        if found
+          target_input = found
+          puts Color.c("📄 Auto-detected local sitemap: #{found}", Color::GRAY) unless quiet
+        elsif default_origin
+          target_input = "#{default_origin.chomp('/')}/sitemap.xml"
+          puts Color.c("🌐 Using remote sitemap URL: #{target_input}", Color::GRAY) unless quiet
+        else
+          raise 'No sitemap file or URL provided, and no local sitemap found.'
+        end
+      end
+
+      xml = fetch_content(target_input)
+      urls = []
+
+      # Parse child sitemaps if this is a sitemap index
+      sitemap_locs = xml.scan(/<sitemap>\s*<loc>([^<]+)<\/loc>/m).flatten
+      if sitemap_locs.any?
+        puts "📑 Found #{sitemap_locs.size} nested sitemaps in index..." unless quiet
+        sitemap_locs.each do |child_url|
+          child_url = child_url.strip
+          unless child_url.start_with?('http://', 'https://')
+            puts Color.c("   ⚠️ Skipping non-HTTP child sitemap location: #{child_url}", Color::YELLOW) unless quiet
+            next
+          end
+          puts "   ↳ Loading child sitemap: #{child_url}" unless quiet
+          begin
+            child_xml = fetch_content(child_url)
+            urls.concat(child_xml.scan(/<url>\s*<loc>([^<]+)<\/loc>/m).flatten.map(&:strip))
+          rescue StandardError => e
+            puts Color.c("   ⚠️ Warning: Could not load child sitemap #{child_url}: #{e.message}", Color::YELLOW) unless quiet
+          end
+        end
+      else
+        urls.concat(xml.scan(/<loc>([^<]+)<\/loc>/m).flatten.map(&:strip))
+      end
+
+      urls.uniq
+    end
+  end
+end

data/lib/gsc/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GSC
+  VERSION = '2.0.0'
+end