gsc-cli 2.0.1 → 2.1.0

data/bin/gsc

@@ -3,7 +3,7 @@
 
 # ==============================================================================
 # Google Search Console & Indexing API CLI Tool (Pure Ruby - Zero Gem Dependencies)
-# Standalone Single-File Distribution (Built from lib/gsc v2.0.1)
+# Standalone Single-File Distribution (Built from lib/gsc v2.1.0)
 # ==============================================================================
 
 require 'net/http'
@@ -17,13 +17,19 @@ require 'date'
 require 'fileutils'
 require 'zlib'
 require 'stringio'
+require 'csv'
+require 'set'
 
-# --- version.rb ---
 module GSC
-  VERSION = '2.0.1'
 end
 
-# --- color.rb ---
+# --- Begin version.rb ---
+module GSC
+  VERSION = '2.1.0'
+end
+# --- End version.rb ---
+
+# --- Begin color.rb ---
 module GSC
   module Color
     RESET     = "\e[0m"
@@ -44,17 +50,23 @@ module GSC
     end
   end
 end
+# --- End color.rb ---
 
-# --- config.rb ---
-require 'fileutils'
-require 'json'
-require 'time'
-
+# --- Begin config.rb ---
 module GSC
   class Config
     CONFIG_DIR  = File.expand_path('~/.config/gsc')
     CONFIG_FILE = File.join(CONFIG_DIR, 'config.json')
 
+def self.get(key)
+  load[key.to_s]
+end
+
+def self.set(key, value)
+  save(key.to_s => value)
+  value
+end
+
     def self.load
       return {} unless File.exist?(CONFIG_FILE)
       JSON.parse(File.read(CONFIG_FILE))
@@ -221,8 +233,9 @@ end
 
   end
 end
+# --- End config.rb ---
 
-# --- auth.rb ---
+# --- Begin auth.rb ---
 module GSC
   class Auth
     OAUTH_TOKEN_URI = URI('https://oauth2.googleapis.com/token')
@@ -313,14 +326,9 @@ module GSC
     end
   end
 end
+# --- End auth.rb ---
 
-# --- client.rb ---
-require 'net/http'
-require 'uri'
-require 'json'
-require 'zlib'
-require 'stringio'
-
+# --- Begin client.rb ---
 module GSC
   class Client
     def initialize(token:)
@@ -392,8 +400,9 @@ module GSC
     end
   end
 end
+# --- End client.rb ---
 
-# --- api.rb ---
+# --- Begin api.rb ---
 module GSC
   class API
     def initialize(client)
@@ -692,13 +701,9 @@ end
     end
   end
 end
+# --- End api.rb ---
 
-# --- sitemap_loader.rb ---
-require 'net/http'
-require 'uri'
-require 'zlib'
-require 'stringio'
-
+# --- Begin sitemap_loader.rb ---
 module GSC
   class SitemapLoader
     def self.fetch_content(path_or_url)
@@ -783,8 +788,9 @@ module GSC
     end
   end
 end
+# --- End sitemap_loader.rb ---
 
-# --- google_trends.rb ---
+# --- Begin google_trends.rb ---
 module GSC
 class GoogleTrends
   TRENDS_HOST = 'trends.google.com'
@@ -970,8 +976,9 @@ class GoogleTrends
   end
 end
 end
+# --- End google_trends.rb ---
 
-# --- keyword_planner.rb ---
+# --- Begin keyword_planner.rb ---
 module GSC
 class KeywordPlanner
   SUGGEST_HOST = 'suggestqueries.google.com'
@@ -1226,8 +1233,9 @@ end
   end
 end
 end
+# --- End keyword_planner.rb ---
 
-# --- keywords_everywhere.rb ---
+# --- Begin keywords_everywhere.rb ---
 module GSC
 class KeywordsEverywhere
   API_HOST = "api.keywordseverywhere.com"
@@ -1370,8 +1378,9 @@ class KeywordsEverywhere
   end
 end
 end
+# --- End keywords_everywhere.rb ---
 
-# --- prompts.rb ---
+# --- Begin prompts.rb ---
 module GSC
   class Prompts
     PLAYBOOKS = [
@@ -1655,15 +1664,9 @@ module GSC
     end
   end
 end
+# --- End prompts.rb ---
 
-# --- page_analyzer.rb ---
-require 'net/http'
-require 'uri'
-require 'zlib'
-require 'stringio'
-require 'json'
-require 'time'
-
+# --- Begin page_analyzer.rb ---
 module GSC
   class PageAnalyzer
     attr_reader :url, :html, :http_status, :response_time_ms, :headers, :error
@@ -2086,14 +2089,9 @@ module GSC
     end
   end
 end
+# --- End page_analyzer.rb ---
 
-# --- site_crawler.rb ---
-# encoding: utf-8
-require 'net/http'
-require 'uri'
-require 'json'
-require 'fileutils'
-
+# --- Begin site_crawler.rb ---
 module GSC
   class SiteCrawler
     attr_reader :target, :options, :results, :broken_links, :missing_alts, :heading_issues, :title_issues, :canonical_issues
@@ -2159,195 +2157,1932 @@ module GSC
       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]}** |"
+      # 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
+# --- End site_crawler.rb ---
+
+# --- Begin google_suggest.rb ---
+module GSC
+  class GoogleSuggest
+    SUGGEST_URL = 'https://suggestqueries.google.com/complete/search'
+
+    attr_reader :query, :options
+
+    def initialize(query, options = {})
+      @query = query.to_s.strip
+      @options = options
+    end
+
+    def fetch(alphabet: false, questions: false)
+      if questions
+        fetch_questions
+      elsif alphabet
+        fetch_alphabet_soup
+      else
+        fetch_single(@query)
+      end
+    end
+
+    def fetch_single(search_term)
+      uri = URI("#{SUGGEST_URL}?client=chrome&q=#{URI.encode_www_form_component(search_term)}")
+      req = Net::HTTP::Get.new(uri)
+      req['User-Agent'] = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36'
+      req['Accept'] = 'application/json, text/javascript, */*; q=0.01'
+
+      res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: 5, read_timeout: 10) do |http|
+        http.request(req)
+      end
+
+      return [] unless res.code == '200'
+
+      parsed = JSON.parse(res.body.force_encoding('UTF-8'))
+      terms = parsed[1] || []
+      types = parsed[4] ? parsed[4]['google:suggesttype'] || [] : []
+
+      terms.map.with_index do |term, idx|
+        {
+          term: term,
+          type: types[idx] || 'QUERY',
+          root: search_term
+        }
+      end
+    rescue StandardError => e
+      []
+    end
+
+    def fetch_alphabet_soup
+      results = {}
+      base = @query.strip
+
+      # Root query first
+      results['root'] = fetch_single(base)
+
+      # A-Z permutations
+      ('a'..'z').each do |letter|
+        term = "#{base} #{letter}"
+        items = fetch_single(term)
+        results[letter] = items unless items.empty?
+        sleep(0.05) # Polite throttle
+      end
+
+      # 0-9 permutations if requested
+      if @options[:numbers]
+        ('0'..'9').each do |num|
+          term = "#{base} #{num}"
+          items = fetch_single(term)
+          results[num] = items unless items.empty?
+          sleep(0.05)
+        end
+      end
+
+      results
+    end
+
+    def fetch_questions
+      prefixes = [
+        'how to',
+        'how do',
+        'why do',
+        'why does',
+        'what is',
+        'what are',
+        'can you',
+        'best',
+        'where to',
+        'which'
+      ]
+
+      results = {}
+      prefixes.each do |pfx|
+        term = "#{pfx} #{@query}"
+        items = fetch_single(term)
+        results[pfx] = items unless items.empty?
+        sleep(0.05)
+      end
+
+      results
+    end
+  end
+end
+# --- End google_suggest.rb ---
+
+# --- Begin open_page_rank.rb ---
+module GSC
+  class OpenPageRank
+    API_URL = 'https://openpagerank.com/api/v1.0/getPageRank'
+
+    attr_reader :api_key
+
+    def initialize(api_key = nil)
+      @api_key = api_key || ENV['OPENPAGERANK_API_KEY'] || GSC::Config.get('opr_api_key')
+    end
+
+    def configured?
+      !@api_key.nil? && !@api_key.strip.empty?
+    end
+
+    def check_domains(domains)
+      domains = Array(domains).map { |d| clean_domain(d) }.reject(&:empty?).uniq
+      return { error: 'No valid domains provided' } if domains.empty?
+      return { error: 'OpenPageRank API key not configured. Set via `gsc config set opr_api_key <key>` or OPENPAGERANK_API_KEY env (Get free 300k calls/mo at openpagerank.com)' } unless configured?
+
+      # Construct query params: domains[0]=a.com&domains[1]=b.com
+      params = domains.map.with_index { |d, idx| "domains%5B#{idx}%5D=#{URI.encode_www_form_component(d)}" }.join('&')
+      uri = URI("#{API_URL}?#{params}")
+
+      req = Net::HTTP::Get.new(uri)
+      req['API-OPR'] = @api_key
+      req['User-Agent'] = 'gsc-cli/2.1'
+
+      res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: 5, read_timeout: 15) do |http|
+        http.request(req)
+      end
+
+      if res.code == '200'
+        data = JSON.parse(res.body)
+        records = (data['response'] || []).map do |r|
+          {
+            domain: r['domain'],
+            page_rank_decimal: r['page_rank_decimal'] || 0.0,
+            page_rank_integer: r['page_rank_integer'] || 0,
+            rank: r['rank'],
+            status_code: r['status_code']
+          }
+        end
+        {
+          status: 'success',
+          status_code: data['status_code'],
+          records: records
+        }
+      else
+        {
+          status: 'error',
+          code: res.code.to_i,
+          message: res.body
+        }
+      end
+    rescue StandardError => e
+      { status: 'error', message: e.message }
+    end
+
+    def clean_domain(input)
+      d = input.to_s.strip.downcase
+      d = d.sub(%r{^https?://}, '').sub(%r{/.*$}, '').sub(/^www\./, '')
+      d
+    end
+  end
+end
+# --- End open_page_rank.rb ---
+
+# --- Begin page_speed.rb ---
+module GSC
+  class PageSpeed
+    API_URL = 'https://www.googleapis.com/pagespeedonline/v5/runPagespeed'
+
+    attr_reader :url, :strategy, :api_key
+
+    def initialize(url, strategy: 'mobile', api_key: nil)
+      @url = url.to_s.strip
+      @strategy = strategy.to_s.downcase == 'desktop' ? 'desktop' : 'mobile'
+      @api_key = api_key || ENV['PAGESPEED_API_KEY'] || GSC::Config.get('pagespeed_api_key')
+    end
+
+    def run
+      query_params = [
+        "url=#{URI.encode_www_form_component(@url)}",
+        "strategy=#{@strategy}",
+        "category=performance",
+        "category=seo"
+      ]
+      query_params << "key=#{URI.encode_www_form_component(@api_key)}" if @api_key && !@api_key.empty?
+
+      uri = URI("#{API_URL}?#{query_params.join('&')}")
+      req = Net::HTTP::Get.new(uri)
+      req['User-Agent'] = 'gsc-cli/2.1'
+
+      res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30) do |http|
+        http.request(req)
+      end
+
+      if res.code == '200'
+        parse_response(JSON.parse(res.body))
+      else
+        {
+          error: true,
+          status_code: res.code.to_i,
+          message: res.body
+        }
+      end
+    rescue StandardError => e
+      { error: true, message: e.message }
+    end
+
+    private
+
+    def parse_response(data)
+      lhr = data['lighthouseResult'] || {}
+      categories = lhr['categories'] || {}
+      perf_score = ((categories.dig('performance', 'score') || 0) * 100).round
+      seo_score = ((categories.dig('seo', 'score') || 0) * 100).round
+
+      audits = lhr['audits'] || {}
+
+      # Core Web Vitals
+      fcp = audits.dig('first-contentful-paint', 'displayValue')
+      lcp = audits.dig('largest-contentful-paint', 'displayValue')
+      cls = audits.dig('cumulative-layout-shift', 'displayValue')
+      tbt = audits.dig('total-blocking-time', 'displayValue')
+      si  = audits.dig('speed-index', 'displayValue')
+
+      # CrUX Field Data (if available)
+      crux_metrics = {}
+      crux = data.dig('loadingExperience', 'metrics') || {}
+      crux.each do |k, v|
+        crux_metrics[k] = {
+          percentile: v['percentile'],
+          category: v['category']
+        }
+      end
+
+      # Opportunities
+      opportunities = []
+      audits.each do |k, v|
+        next unless v['details'] && v['details']['type'] == 'opportunity'
+        next unless v['numericValue'] && v['numericValue'] > 100
+
+        opportunities << {
+          id: k,
+          title: v['title'],
+          savings_ms: v['numericValue'] ? v['numericValue'].round : 0,
+          display: v['displayValue']
+        }
+      end
+      opportunities.sort_by! { |o| -o[:savings_ms] }
+
+      {
+        url: @url,
+        strategy: @strategy,
+        fetch_time: lhr['fetchTime'],
+        performance_score: perf_score,
+        seo_score: seo_score,
+        metrics: {
+          fcp: fcp,
+          lcp: lcp,
+          cls: cls,
+          tbt: tbt,
+          speed_index: si
+        },
+        field_data: crux_metrics,
+        opportunities: opportunities.first(5)
+      }
+    end
+  end
+end
+# --- End page_speed.rb ---
+
+# --- Begin page_comparator.rb ---
+module GSC
+  class PageComparator
+    attr_reader :url1, :url2, :data1, :data2
+
+    def initialize(url1, url2)
+      @url1 = url1
+      @url2 = url2
+    end
+
+    def compare
+      pa1 = GSC::PageAnalyzer.new(@url1)
+      pa2 = GSC::PageAnalyzer.new(@url2)
+
+      @data1 = pa1.fetch_and_analyze
+      @data2 = pa2.fetch_and_analyze
+
+      diffs = {
+        meta: compare_meta,
+        headings: compare_headings,
+        images: compare_images,
+        links: compare_links,
+        performance: compare_perf,
+        structured_data: compare_schema
+      }
+
+      {
+        page1: { url: @url1, status: @data1[:http_status] },
+        page2: { url: @url2, status: @data2[:http_status] },
+        comparison: diffs
+      }
+    end
+
+    private
+
+    def compare_meta
+      t1 = @data1.dig(:title, :text) || ''
+      t2 = @data2.dig(:title, :text) || ''
+      m1 = @data1.dig(:meta_description, :text) || ''
+      m2 = @data2.dig(:meta_description, :text) || ''
+
+      {
+        title: {
+          page1: { text: t1, length: t1.length, optimal: t1.length.between?(30, 60) },
+          page2: { text: t2, length: t2.length, optimal: t2.length.between?(30, 60) }
+        },
+        meta_description: {
+          page1: { text: m1, length: m1.length, optimal: m1.length.between?(70, 155) },
+          page2: { text: m2, length: m2.length, optimal: m2.length.between?(70, 155) }
+        }
+      }
+    end
+
+    def compare_headings
+      h1_1 = @data1.dig(:headings, :h1) || []
+      h1_2 = @data2.dig(:headings, :h1) || []
+      h2_1 = @data1.dig(:headings, :h2) || []
+      h2_2 = @data2.dig(:headings, :h2) || []
+
+      {
+        h1_count: { page1: h1_1.length, page2: h1_2.length },
+        h1_text: { page1: h1_1.first, page2: h1_2.first },
+        h2_count: { page1: h2_1.length, page2: h2_2.length }
+      }
+    end
+
+    def compare_images
+      img1 = @data1[:images] || {}
+      img2 = @data2[:images] || {}
+
+      {
+        total_images: { page1: img1[:total] || 0, page2: img2[:total] || 0 },
+        missing_alt: { page1: img1[:missing_alt] || 0, page2: img2[:missing_alt] || 0 }
+      }
+    end
+
+    def compare_links
+      l1 = @data1[:links] || {}
+      l2 = @data2[:links] || {}
+
+      {
+        internal: { page1: l1[:internal_count] || 0, page2: l2[:internal_count] || 0 },
+        external: { page1: l1[:external_count] || 0, page2: l2[:external_count] || 0 }
+      }
+    end
+
+    def compare_perf
+      {
+        response_time_ms: { page1: @data1[:response_time_ms], page2: @data2[:response_time_ms] }
+      }
+    end
+
+    def compare_schema
+      s1 = @data1.dig(:structured_data, :schemas) || []
+      s2 = @data2.dig(:structured_data, :schemas) || []
+
+      types1 = s1.map { |s| s['@type'] }.compact
+      types2 = s2.map { |s| s['@type'] }.compact
+
+      {
+        schema_count: { page1: s1.length, page2: s2.length },
+        schema_types: { page1: types1, page2: types2 }
+      }
+    end
+  end
+end
+# --- End page_comparator.rb ---
+
+# --- Begin content_gap.rb ---
+module GSC
+  class ContentGap
+    STOP_WORDS = Set.new(%w[
+      a about above after again against all am an and any are aren't as at be because been before being below
+      between both but by can't cannot could couldn't did didn't do does doesn't doing don't down during each
+      few for from further had hadn't has hasn't have haven't having he he'd he'll he's her here here's hers
+      herself him himself his how how's i i'd i'll i'm i've if in into is isn't it it's its itself let's me
+      more most mustn't my myself no nor not of off on once only or other ought our ours ourselves out over own
+      same shan't she she'd she'll she's should shouldn't so some such than that that's the their theirs them
+      themselves then there there's these they they'd they'll they're they've this those through to too under until
+      up very was wasn't we we'd we'll we're we've were weren't what what's when when's where where's which while
+      who who's whom why why's with won't would wouldn't you you'd you'll you're you've your yours yourself yourselves
+    ])
+
+    attr_reader :url1, :url2
+
+    def initialize(url1, url2)
+      @url1 = url1
+      @url2 = url2
+    end
+
+    def analyze
+      pa1 = GSC::PageAnalyzer.new(@url1)
+      pa2 = GSC::PageAnalyzer.new(@url2)
+
+      data1 = pa1.fetch_and_analyze
+      data2 = pa2.fetch_and_analyze
+
+      text1 = extract_clean_text(pa1.html || '')
+      text2 = extract_clean_text(pa2.html || '')
+
+      tokens1 = tokenize(text1)
+      tokens2 = tokenize(text2)
+
+      unigrams1 = ngrams(tokens1, 1)
+      unigrams2 = ngrams(tokens2, 1)
+
+      bigrams1 = ngrams(tokens1, 2)
+      bigrams2 = ngrams(tokens2, 2)
+
+      trigrams1 = ngrams(tokens1, 3)
+      trigrams2 = ngrams(tokens2, 3)
+
+      # Competitor terms that occur at least 2 times, but occur 0 times in page1
+      missing_unigrams = term_gap(unigrams1, unigrams2, min_count: 2)
+      missing_bigrams  = term_gap(bigrams1, bigrams2, min_count: 2)
+      missing_trigrams = term_gap(trigrams1, trigrams2, min_count: 2)
+
+      # Heading gaps (H2/H3 in page2 that have no match in page1)
+      h1 = (data1.dig(:headings, :h2) || []) + (data1.dig(:headings, :h3) || [])
+      h2 = (data2.dig(:headings, :h2) || []) + (data2.dig(:headings, :h3) || [])
+
+      missing_headings = h2.reject do |heading|
+        h1.any? { |my_h| my_h.downcase.include?(heading.downcase[0..15]) }
+      end
+
+      {
+        page1: { url: @url1, word_count: tokens1.length },
+        page2: { url: @url2, word_count: tokens2.length },
+        missing_unigrams: missing_unigrams.first(15),
+        missing_bigrams: missing_bigrams.first(15),
+        missing_trigrams: missing_trigrams.first(10),
+        missing_headings: missing_headings.first(10)
+      }
+    end
+
+    private
+
+    def extract_clean_text(html)
+      text = html.dup
+      text.gsub!(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/i, ' ')
+      text.gsub!(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/i, ' ')
+      text.gsub!(/<nav\b[^<]*(?:(?!<\/nav>)<[^<]*)*<\/nav>/i, ' ')
+      text.gsub!(/<footer\b[^<]*(?:(?!<\/footer>)<[^<]*)*<\/footer>/i, ' ')
+      text.gsub!(/<[^>]+>/, ' ')
+      text.gsub!(/&[a-z]+;/i, ' ')
+      text.gsub!(/\s+/, ' ')
+      text.strip
+    end
+
+    def tokenize(text)
+      text.downcase.scan(/[a-z0-9]+/).reject { |w| w.length < 3 || STOP_WORDS.include?(w) }
+    end
+
+    def ngrams(tokens, n)
+      counts = Hash.new(0)
+      return counts if tokens.length < n
+
+      (0..(tokens.length - n)).each do |i|
+        gram = tokens[i, n].join(' ')
+        counts[gram] += 1
+      end
+      counts
+    end
+
+    def term_gap(counts1, counts2, min_count: 2)
+      gap = []
+      counts2.each do |term, count2|
+        count1 = counts1[term] || 0
+        if count2 >= min_count && count1 == 0
+          gap << { term: term, competitor_count: count2, your_count: count1 }
+        end
+      end
+      gap.sort_by { |item| -item[:competitor_count] }
+    end
+  end
+end
+# --- End content_gap.rb ---
+
+# --- Begin internal_links.rb ---
+module GSC
+  class InternalLinks
+    attr_reader :base_url, :pages, :graph, :orphans, :depths
+
+    def initialize(base_url, limit: 50)
+      @base_url = base_url.to_s.strip
+      @base_url = "https://#{@base_url}" unless @base_url =~ %r{^https?://}
+      @base_uri = URI.parse(@base_url)
+      @limit = limit
+      @graph = Hash.new { |h, k| h[k] = Set.new } # target_url => Set of source_urls
+      @out_links = Hash.new { |h, k| h[k] = Set.new } # source_url => Set of target_urls
+      @all_discovered = Set.new
+    end
+
+    def audit(sitemap_urls = nil)
+      urls_to_crawl = if sitemap_urls && !sitemap_urls.empty?
+                        sitemap_urls.first(@limit)
+                      else
+                        discover_urls
+                      end
+
+      urls_to_crawl.each do |url|
+        @all_discovered << normalize_url(url)
+      end
+
+      # Crawl each URL and extract internal links
+      urls_to_crawl.each do |url|
+        pa = GSC::PageAnalyzer.new(url)
+        pa.load_content! rescue next
+        dom = pa.analyze_dom rescue next
+
+        norm_source = normalize_url(url)
+        links = dom.dig(:links, :all) || []
+
+        links.each do |link_obj|
+          href = link_obj[:href]
+          target_url = resolve_internal_url(href)
+          next unless target_url
+
+          norm_target = normalize_url(target_url)
+          next if norm_target == norm_source
+
+          @graph[norm_target] << norm_source
+          @out_links[norm_source] << norm_target
+        end
+      end
+
+      # Calculate Orphans (pages in sitemap/discovered with 0 incoming internal links)
+      orphans = []
+      weak_pages = [] # only 1 internal link
+
+      @all_discovered.each do |url|
+        in_degree = @graph[url].size
+        if in_degree == 0 && url != normalize_url(@base_url)
+          orphans << url
+        elsif in_degree == 1
+          weak_pages << { url: url, source: @graph[url].first }
+        end
+      end
+
+      # Calculate click depths via BFS from root
+      depths = calculate_depths(normalize_url(@base_url))
+
+      {
+        base_url: @base_url,
+        total_pages: @all_discovered.size,
+        orphans: orphans,
+        weak_pages: weak_pages,
+        top_linked: top_linked_pages(10),
+        depths: depths
+      }
+    end
+
+    private
+
+    def discover_urls
+      loader = GSC::SitemapLoader.new(@base_url)
+      urls = loader.load
+      urls.empty? ? [@base_url] : urls.first(@limit)
+    rescue StandardError
+      [@base_url]
+    end
+
+    def resolve_internal_url(href)
+      return nil if href.nil? || href.strip.empty?
+      return nil if href =~ /^(mailto|tel|javascript|#):/i
+
+      uri = URI.join(@base_url, href) rescue nil
+      return nil unless uri && uri.scheme =~ /^https?$/i
+      return nil unless uri.host.downcase == @base_uri.host.downcase
+
+      uri.fragment = nil
+      uri.to_s
+    end
+
+    def normalize_url(url)
+      u = url.to_s.strip.sub(%r{/$}, '')
+      u
+    end
+
+    def calculate_depths(root_url)
+      depths = { root_url => 0 }
+      queue = [root_url]
+
+      until queue.empty?
+        curr = queue.shift
+        curr_depth = depths[curr]
+
+        (@out_links[curr] || []).each do |neighbor|
+          next if depths.key?(neighbor)
+
+          depths[neighbor] = curr_depth + 1
+          queue << neighbor
+        end
+      end
+
+      depths
+    end
+
+    def top_linked_pages(limit)
+      @graph.map do |url, sources|
+        { url: url, incoming_count: sources.size }
+      end.sort_by { |item| -item[:incoming_count] }.first(limit)
+    end
+  end
+end
+# --- End internal_links.rb ---
+
+# --- Begin schema_validator.rb ---
+module GSC
+  class SchemaValidator
+    attr_reader :url, :schemas, :validation_results
+
+    def initialize(url)
+      @url = url.to_s.strip
+    end
+
+    def audit
+      pa = GSC::PageAnalyzer.new(@url)
+      data = pa.fetch_and_analyze
+      @schemas = data.dig(:structured_data, :schemas) || []
+
+      results = []
+      @schemas.each_with_index do |schema, idx|
+        results << validate_single_schema(schema, idx)
+      end
+
+      {
+        url: @url,
+        total_schemas: @schemas.length,
+        schemas: results
+      }
+    end
+
+    def validate_single_schema(schema, idx)
+      type = schema['@type'] || 'Unknown'
+      errors = []
+      warnings = []
+
+      case type
+      when 'SoftwareApplication', 'WebApplication'
+        errors << 'Missing "name"' unless schema['name']
+        warnings << 'Missing "operatingSystem"' unless schema['operatingSystem']
+        warnings << 'Missing "applicationCategory"' unless schema['applicationCategory']
+        warnings << 'Missing "offers"' unless schema['offers']
+        warnings << 'Missing "aggregateRating"' unless schema['aggregateRating']
+
+      when 'FAQPage'
+        main_entity = schema['mainEntity']
+        if !main_entity || !main_entity.is_a?(Array) || main_entity.empty?
+          errors << 'FAQPage must contain a non-empty "mainEntity" array'
+        else
+          main_entity.each_with_index do |q, q_idx|
+            errors << "Question ##{q_idx + 1} missing name" unless q['name']
+            errors << "Question ##{q_idx + 1} missing acceptedAnswer" unless q['acceptedAnswer']
+          end
+        end
+
+      when 'Product'
+        errors << 'Missing "name"' unless schema['name']
+        warnings << 'Missing "image"' unless schema['image']
+        warnings << 'Missing "offers"' unless schema['offers']
+
+      when 'Article', 'BlogPosting'
+        errors << 'Missing "headline"' unless schema['headline']
+        errors << 'Missing "author"' unless schema['author']
+        warnings << 'Missing "datePublished"' unless schema['datePublished']
+        warnings << 'Missing "image"' unless schema['image']
+
+      when 'Organization', 'LocalBusiness'
+        errors << 'Missing "name"' unless schema['name']
+        errors << 'Missing "url"' unless schema['url']
+        warnings << 'Missing "logo"' unless schema['logo']
+      end
+
+      {
+        index: idx,
+        type: type,
+        valid: errors.empty?,
+        errors: errors,
+        warnings: warnings,
+        raw: schema
+      }
+    end
+
+    def self.generate_template(type, params = {})
+      case type.to_s.downcase
+      when 'faq'
+        {
+          '@context' => 'https://schema.org',
+          '@type' => 'FAQPage',
+          'mainEntity' => [
+            {
+              '@type' => 'Question',
+              'name' => params[:question] || 'What is PackingLog?',
+              'acceptedAnswer' => {
+                '@type' => 'Answer',
+                'text' => params[:answer] || 'PackingLog is a free moving box and inventory management system.'
+              }
+            }
+          ]
+        }
+      when 'software', 'app'
+        {
+          '@context' => 'https://schema.org',
+          '@type' => 'SoftwareApplication',
+          'name' => params[:name] || 'PackingLog',
+          'applicationCategory' => params[:category] || 'UtilitiesApplication',
+          'operatingSystem' => 'Web, iOS, Android',
+          'offers' => {
+            '@type' => 'Offer',
+            'price' => '0',
+            'priceCurrency' => 'USD'
+          }
+        }
+      else
+        {
+          '@context' => 'https://schema.org',
+          '@type' => 'Organization',
+          'name' => params[:name] || 'PackingLog',
+          'url' => params[:url] || 'https://packinglog.com'
+        }
+      end
+    end
+  end
+end
+# --- End schema_validator.rb ---
+
+# --- Begin llms_generator.rb ---
+module GSC
+  class LlmsGenerator
+    attr_reader :base_url, :pages
+
+    def initialize(base_url)
+      @base_url = base_url.to_s.strip
+      @base_url = "https://#{@base_url}" unless @base_url =~ %r{^https?://}
+    end
+
+    def generate_llms_txt(title: nil, summary: nil)
+      loader = GSC::SitemapLoader.new(@base_url)
+      urls = loader.load rescue [@base_url]
+      urls = [@base_url] if urls.empty?
+
+      site_title = title || URI.parse(@base_url).host.sub(/^www\./, '').capitalize
+      site_summary = summary || "Official documentation and product guides for #{site_title}."
+
+      out = []
+      out << "# #{site_title}"
+      out << ""
+      out << "> #{site_summary}"
+      out << ""
+      out << "## Core Documentation"
+      out << ""
+
+      # Sample first 15 key URLs and fetch metadata
+      urls.first(15).each do |url|
+        pa = GSC::PageAnalyzer.new(url)
+        pa.load_content! rescue next
+        dom = pa.analyze_dom rescue next
+
+        page_title = dom.dig(:title, :text) || url
+        page_desc = dom.dig(:meta_description, :text) || "Documentation page."
+
+        out << "- [#{page_title}](#{url}): #{page_desc}"
+      end
+
+      out << ""
+      out << "## Optional"
+      out << ""
+      out << "- [Full Documentation](#{@base_url}/llms-full.txt): Complete consolidated knowledge base for LLM context ingestion."
+      out << ""
+
+      out.join("\n")
+    end
+
+    def audit_ai_readability(url)
+      pa = GSC::PageAnalyzer.new(url)
+      data = pa.fetch_and_analyze
+
+      # Check criteria:
+      # 1. Clear H1 presence
+      # 2. Table presence (LLMs love tables)
+      # 3. Schema presence (structured data)
+      # 4. Definition / Bullet presence
+      html = pa.html || ''
+      has_tables = html.include?('<table')
+      has_lists = html.include?('<ul') || html.include?('<ol')
+      schemas = data.dig(:structured_data, :schemas) || []
+      h1_count = (data.dig(:headings, :h1) || []).length
+
+      score = 100
+      issues = []
+
+      if h1_count != 1
+        score -= 20
+        issues << "H1 count is #{h1_count} (Must be exactly 1 for clean LLM hierarchy)"
+      end
+
+      unless has_tables
+        score -= 15
+        issues << "No <table> found (tables increase LLM citation and fact extraction by 3x)"
+      end
+
+      unless has_lists
+        score -= 15
+        issues << "No bullet lists (<ul> or <ol>) found for quick entity consumption"
+      end
+
+      if schemas.empty?
+        score -= 20
+        issues << "No JSON-LD schemas detected (structured data accelerates AI knowledge graph inclusion)"
+      end
+
+      {
+        url: url,
+        ai_readability_score: [score, 0].max,
+        grade: score >= 80 ? 'A (Excellent)' : (score >= 60 ? 'B (Acceptable)' : 'C (Needs Work)'),
+        issues: issues,
+        features: {
+          has_tables: has_tables,
+          has_lists: has_lists,
+          schemas_found: schemas.length,
+          h1_count: h1_count
+        }
+      }
+    end
+  end
+end
+# --- End llms_generator.rb ---
+
+# --- Begin serp_preview.rb ---
+module GSC
+  class SerpPreview
+    attr_reader :url, :data
+
+    def initialize(url)
+      @url = url.to_s.strip
+    end
+
+    def generate
+      pa = GSC::PageAnalyzer.new(@url)
+      @data = pa.fetch_and_analyze
+
+      title = @data.dig(:title, :text) || 'Untitled Page'
+      desc = @data.dig(:meta_description, :text) || 'No meta description found.'
+      canonical = @data.dig(:canonical, :url) || @url
+
+      # SERP pixel calculation approximation:
+      # ~10px per character average for Arial 18px title
+      title_chars = title.length
+      is_truncated = title_chars > 60
+
+      desktop_title = is_truncated ? "#{title[0..56]}..." : title
+      desktop_snippet = desc.length > 155 ? "#{desc[0..152]}..." : desc
+
+      og = @data[:open_graph] || {}
+      twitter = @data[:twitter_card] || {}
+
+      {
+        url: @url,
+        canonical: canonical,
+        title: title,
+        meta_description: desc,
+        truncation_risk: is_truncated,
+        desktop_serp: {
+          title: desktop_title,
+          snippet: desktop_snippet,
+          breadcrumb: format_breadcrumb(canonical)
+        },
+        social: {
+          og_title: og['og:title'] || title,
+          og_description: og['og:description'] || desc,
+          og_image: og['og:image'],
+          twitter_card: twitter['twitter:card'] || 'summary_large_image'
+        }
+      }
+    end
+
+    private
+
+    def format_breadcrumb(url_str)
+      uri = URI.parse(url_str) rescue nil
+      return url_str unless uri && uri.host
+
+      domain = uri.host.sub(/^www\./, '')
+      parts = uri.path.split('/').reject(&:empty?)
+      if parts.empty?
+        "https://#{domain}"
+      else
+        "https://#{domain} > #{parts.join(' > ')}"
+      end
+    end
+  end
+end
+# --- End serp_preview.rb ---
+
+# --- Begin network_tracer.rb ---
+module GSC
+  class NetworkTracer
+    attr_reader :start_url, :max_hops
+
+    def initialize(start_url, max_hops: 10)
+      @start_url = start_url.to_s.strip
+      @start_url = "http://#{@start_url}" unless @start_url =~ %r{^https?://}
+      @max_hops = max_hops
+    end
+
+    def trace
+      current_url = @start_url
+      hops = []
+      visited = Set.new
+
+      @max_hops.times do |hop_idx|
+        break if visited.include?(current_url)
+        visited << current_url
+
+        uri = URI.parse(current_url) rescue nil
+        break unless uri && uri.host
+
+        start_t = Time.now
+        res = nil
+
+        begin
+          Net::HTTP.start(uri.hostname, uri.port, use_ssl: (uri.scheme == 'https'), open_timeout: 5, read_timeout: 10) do |http|
+            req = Net::HTTP::Get.new(uri.request_uri)
+            req['User-Agent'] = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) gsc-cli/2.1'
+            res = http.request(req)
+          end
+        rescue StandardError => e
+          hops << {
+            hop: hop_idx + 1,
+            url: current_url,
+            error: e.message
+          }
+          break
+        end
+
+        duration_ms = ((Time.now - start_t) * 1000).round(1)
+        status_code = res.code.to_i
+        location = res['location']
+
+        hop_info = {
+          hop: hop_idx + 1,
+          url: current_url,
+          status_code: status_code,
+          duration_ms: duration_ms,
+          x_robots_tag: res['x-robots-tag'],
+          canonical_header: res['link'] =~ /rel="canonical"/i ? res['link'] : nil,
+          hsts: res['strict-transport-security'],
+          content_type: res['content-type'],
+          server: res['server']
+        }
+
+        hops << hop_info
+
+        if [301, 302, 303, 307, 308].include?(status_code) && location
+          current_url = URI.join(current_url, location).to_s
+        else
+          break
+        end
+      end
+
+      total_time = hops.sum { |h| h[:duration_ms] || 0 }.round(1)
+      final_hop = hops.last || {}
+      is_redirect_chain = hops.length > 2
+
+      {
+        start_url: @start_url,
+        final_url: final_hop[:url],
+        total_hops: hops.length,
+        total_duration_ms: total_time,
+        is_redirect_chain: is_redirect_chain,
+        hops: hops
+      }
+    end
+  end
+end
+# --- End network_tracer.rb ---
+
+# --- Begin robots_checker.rb ---
+module GSC
+  class RobotsChecker
+    attr_reader :base_url, :robots_content
+
+    def initialize(target_url)
+      @target_url = target_url.to_s.strip
+      @target_url = "https://#{@target_url}" unless @target_url =~ %r{^https?://}
+      @uri = URI.parse(@target_url)
+      @robots_url = "#{@uri.scheme}://#{@uri.host}:#{@uri.port}/robots.txt"
+    end
+
+    def fetch_robots_txt
+      res = Net::HTTP.get_response(URI.parse(@robots_url))
+      return '' unless res.code == '200'
+
+      res.body.force_encoding('UTF-8')
+    rescue StandardError
+      ''
+    end
+
+    def check(path_to_test = nil, user_agent = 'googlebot')
+      @robots_content ||= fetch_robots_txt
+      path = path_to_test || @uri.path
+      path = '/' if path.empty?
+
+      ua = user_agent.to_s.downcase
+      rules = parse_rules(ua)
+
+      allowed = true
+      matched_rule = nil
+
+      rules.each do |rule|
+        pattern = rule[:path]
+        regex = Regexp.new('^' + Regexp.escape(pattern).gsub('\*', '.*'))
+        if path =~ regex
+          allowed = (rule[:type] == :allow)
+          matched_rule = rule
+        end
+      end
+
+      {
+        robots_url: @robots_url,
+        user_agent: user_agent,
+        tested_path: path,
+        allowed: allowed,
+        matched_rule: matched_rule,
+        has_robots_txt: !@robots_content.empty?
+      }
+    end
+
+    private
+
+    def parse_rules(target_ua)
+      rules = []
+      current_ua = nil
+      applies = false
+
+      @robots_content.each_line do |line|
+        line = line.strip.sub(/#.*$/, '')
+        next if line.empty?
+
+        if line =~ /^User-agent:\s*(.+)$/i
+          current_ua = $1.strip.downcase
+          applies = (current_ua == '*' || current_ua == target_ua)
+        elsif applies && line =~ /^Disallow:\s*(.*)$/i
+          val = $1.strip
+          rules << { type: :disallow, path: val } unless val.empty?
+        elsif applies && line =~ /^Allow:\s*(.*)$/i
+          val = $1.strip
+          rules << { type: :allow, path: val } unless val.empty?
+        end
+      end
+
+      rules
+    end
+  end
+end
+# --- End robots_checker.rb ---
+
+# --- Begin backlinks_manager.rb ---
+module GSC
+  class BacklinksManager
+    attr_reader :domain, :storage_file
+
+    def initialize(domain)
+      @domain = clean_domain(domain)
+      @domain_dir = File.join(Dir.home, '.config', 'gsc', 'domains', @domain)
+      FileUtils.mkdir_p(@domain_dir)
+      @storage_file = File.join(@domain_dir, 'backlinks.json')
+    end
+
+    def load_data
+      return { 'sources' => [], 'targets' => [], 'updated_at' => nil } unless File.exist?(@storage_file)
+
+      JSON.parse(File.read(@storage_file, encoding: 'UTF-8'))
+    rescue StandardError
+      { 'sources' => [], 'targets' => [], 'updated_at' => nil }
+    end
+
+    def save_data(data)
+      data['updated_at'] = Time.now.utc.iso8601
+      File.write(@storage_file, JSON.pretty_generate(data))
+    end
+
+    def import_csv(content)
+      data = load_data
+      lines = content.to_s.strip.lines
+
+      return { error: 'Empty content' } if lines.empty?
+
+      # Detect header
+      header = lines.first.downcase
+      if header.include?('top linking sites') || header.include?('root domain')
+        # Sources CSV
+        sources = []
+        CSV.parse(content, headers: true, skip_blanks: true) do |row|
+          domain_name = row['Top linking sites'] || row['Site'] || row[0]
+          links_count = (row['Target pages'] || row['Links'] || row[1] || '1').to_s.gsub(',', '').to_i
+          sources << { 'domain' => domain_name.to_s.strip, 'links_count' => links_count } if domain_name
+        end
+        data['sources'] = sources
+      else
+        # Target pages CSV
+        targets = []
+        CSV.parse(content, headers: true, skip_blanks: true) do |row|
+          target_url = row['Target page'] || row['Page'] || row[0]
+          incoming = (row['Incoming links'] || row['Links'] || row[1] || '1').to_s.gsub(',', '').to_i
+          targets << { 'target_url' => target_url.to_s.strip, 'incoming_count' => incoming } if target_url
+        end
+        data['targets'] = targets
+      end
+
+      save_data(data)
+      {
+        status: 'success',
+        sources_count: data['sources'].length,
+        targets_count: data['targets'].length,
+        updated_at: data['updated_at']
+      }
+    rescue StandardError => e
+      { error: "Failed to parse CSV: #{e.message}" }
+    end
+
+    def summary(target_page: nil)
+      data = load_data
+      sources = data['sources'] || []
+      targets = data['targets'] || []
+
+      filtered_targets = target_page ? targets.select { |t| t['target_url'].include?(target_page) } : targets
+
+      {
+        domain: @domain,
+        total_referring_domains: sources.length,
+        total_external_links: sources.sum { |s| s['links_count'] || 0 },
+        top_referring_domains: sources.sort_by { |s| -(s['links_count'] || 0) }.first(15),
+        top_target_pages: filtered_targets.sort_by { |t| -(t['incoming_count'] || 0) }.first(15),
+        updated_at: data['updated_at']
+      }
+    end
+
+    private
+
+    def clean_domain(input)
+      d = input.to_s.strip.downcase
+      d = d.sub(%r{^https?://}, '').sub(%r{/.*$}, '').sub(/^www\./, '')
+      d
+    end
+  end
+end
+# --- End backlinks_manager.rb ---
+
+# --- Begin cli_advanced.rb ---
+module GSC
+  class CLI
+    # 1. Google Suggest
+    def self.handle_suggest_command(target, options)
+      query = target.to_s.strip
+      if query.empty?
+        puts Color.c("❌ Error: Query required. Example: gsc suggest \"moving boxes\"", Color::RED)
+        return
+      end
+
+      alphabet = options[:alphabet] || false
+      suggest = GSC::GoogleSuggest.new(query, options)
+      results = suggest.fetch(alphabet: alphabet, questions: false)
+
+      if options[:json]
+        puts JSON.pretty_generate(results)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "💡 #{Color::BOLD}GOOGLE SEARCH SUGGESTIONS:#{Color::RESET} #{Color.c(query, Color::CYAN)}"
+      puts "─" * 70
+
+      if alphabet
+        results.each do |key, list|
+          next if list.empty?
+          prefix = (key == 'root') ? "Root" : "+ #{key.upcase}"
+          puts "\n#{Color.c(prefix, Color::BOLD, Color::YELLOW)}:"
+          list.each do |item|
+            puts "   • #{item[:term]}"
+          end
+        end
+      else
+        if results.empty?
+          puts "   (No search suggestions returned)"
+        else
+          results.each_with_index do |item, idx|
+            puts "   #{Color.c((idx + 1).to_s.rjust(2), Color::DIM)}. #{Color.c(item[:term], Color::BOLD)}"
+          end
+        end
+      end
+      puts ""
+    end
+
+    # 2. Questions / PAA
+    def self.handle_questions_command(target, options)
+      query = target.to_s.strip
+      if query.empty?
+        puts Color.c("❌ Error: Query required. Example: gsc questions \"packing dishes\"", Color::RED)
+        return
+      end
+
+      suggest = GSC::GoogleSuggest.new(query, options)
+      results = suggest.fetch(questions: true)
+
+      if options[:json]
+        puts JSON.pretty_generate(results)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "❓ #{Color::BOLD}SEARCH INTENT QUESTIONS & FAQs:#{Color::RESET} #{Color.c(query, Color::CYAN)}"
+      puts "─" * 70
+
+      total_found = 0
+      results.each do |prefix, list|
+        next if list.empty?
+        puts "\n#{Color.c(prefix.upcase, Color::BOLD, Color::CYAN)}:"
+        list.each do |item|
+          total_found += 1
+          puts "   • #{item[:term]}"
+        end
+      end
+
+      if total_found.zero?
+        puts "   (No question suggestions found for \"#{query}\")"
+      end
+      puts ""
+    end
+
+    # 3. OpenPageRank Domain Authority
+    def self.handle_authority_command(target, extra, options)
+      domains = [target, extra].flatten.compact.reject { |d| d.to_s.strip.empty? }
+      domains << Config.default_domain if domains.empty?
+      domains = domains.compact
+
+      if domains.empty?
+        puts Color.c("❌ Error: Domain required. Example: gsc authority packinglog.com", Color::RED)
+        return
+      end
+
+      opr = GSC::OpenPageRank.new
+      unless opr.configured?
+        puts Color.c("⚠️ OpenPageRank API key not configured.", Color::YELLOW, Color::BOLD)
+        puts "   Get a 100% free key (300,000 free queries/month) at: #{Color.c('https://openpagerank.com', Color::CYAN)}"
+        puts "   Then run: #{Color.c('gsc config set opr_api_key <YOUR_KEY>', Color::GREEN)}"
+        puts "   Or pass:  #{Color.c('OPENPAGERANK_API_KEY=<KEY> gsc authority ...', Color::DIM)}"
+        return
+      end
+
+      data = opr.check_domains(domains)
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "🌐 #{Color::BOLD}OPEN PAGERANK & DOMAIN AUTHORITY (Common Crawl Graph):#{Color::RESET}"
+      puts "─" * 75
+
+      if data[:status] == 'error'
+        puts Color.c("❌ Error: #{data[:message]}", Color::RED)
+        return
+      end
+
+      puts "#{'DOMAIN'.ljust(35)} #{'PAGERANK'.ljust(12)} #{'GLOBAL RANK'.ljust(18)} #{'STATUS'}"
+      puts "─" * 75
+
+      (data[:records] || []).each do |rec|
+        d_name = rec[:domain].to_s.ljust(35)
+        pr = sprintf("%.2f / 10", rec[:page_rank_decimal]).ljust(12)
+        gr = rec[:rank] ? "##{rec[:rank].to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse}".ljust(18) : "N/A".ljust(18)
+        st = (rec[:status_code] == 200) ? Color.c("200 OK", Color::GREEN) : Color.c(rec[:status_code].to_s, Color::YELLOW)
+
+        puts "#{Color.c(d_name, Color::BOLD)} #{Color.c(pr, Color::CYAN)} #{Color.c(gr, Color::YELLOW)} #{st}"
+      end
+      puts ""
+    end
+
+    # 4. PageSpeed Core Web Vitals
+    def self.handle_speed_command(target, options)
+      url = target || "https://#{Config.default_domain || 'example.com'}"
+      url = "https://#{url}" unless url =~ %r{^https?://}
+      strategy = options[:strategy] || 'mobile'
+
+      puts BANNER unless options[:json] || options[:in_dashboard]
+      puts "⚡ Measuring Core Web Vitals via Google PageSpeed Insights (#{strategy.upcase}):" unless options[:json]
+      puts "   #{Color.c(url, Color::CYAN)}\n" unless options[:json]
+
+      ps = GSC::PageSpeed.new(url, strategy: strategy)
+      data = ps.run
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      if data[:error]
+        puts Color.c("❌ PageSpeed API Error: #{data[:message]}", Color::RED)
+        return
+      end
+
+      perf_score = data[:performance_score]
+      score_color = perf_score >= 90 ? Color::GREEN : (perf_score >= 50 ? Color::YELLOW : Color::RED)
+
+      puts "╔══════════════════════════════════════════════════════════════╗"
+      puts "║ Lighthouse Performance Score: #{Color.c(perf_score.to_s.rjust(3) + ' / 100', score_color, Color::BOLD)}                ║"
+      puts "║ Lighthouse SEO Score        : #{Color.c(data[:seo_score].to_s.rjust(3) + ' / 100', Color::GREEN, Color::BOLD)}                ║"
+      puts "╚══════════════════════════════════════════════════════════════╝"
+
+      m = data[:metrics] || {}
+      puts "\n#{Color::BOLD}📊 CORE WEB VITALS (Lab Metrics):#{Color::RESET}"
+      puts "   • LCP (Largest Contentful Paint) : #{Color.c(m[:lcp] || 'N/A', Color::BOLD)}"
+      puts "   • FCP (First Contentful Paint)   : #{Color.c(m[:fcp] || 'N/A', Color::BOLD)}"
+      puts "   • CLS (Cumulative Layout Shift)  : #{Color.c(m[:cls] || 'N/A', Color::BOLD)}"
+      puts "   • TBT (Total Blocking Time)      : #{Color.c(m[:tbt] || 'N/A', Color::BOLD)}"
+      puts "   • Speed Index                    : #{Color.c(m[:speed_index] || 'N/A', Color::BOLD)}"
+
+      opps = data[:opportunities] || []
+      unless opps.empty?
+        puts "\n#{Color::BOLD}💡 TOP SPEED OPPORTUNITIES:#{Color::RESET}"
+        opps.each do |opp|
+          puts "   • #{opp[:title]}: #{Color.c(opp[:display] || "#{opp[:savings_ms]}ms savings", Color::YELLOW)}"
+        end
+      end
+      puts ""
+    end
+
+    # 5. Page Comparison
+    def self.handle_compare_command(target, extra, options)
+      url1 = target
+      url2 = extra
+
+      if url1.nil? || url2.nil?
+        puts Color.c("❌ Error: Two URLs required. Example: gsc compare https://site.com/p1 https://competitor.com/p2", Color::RED)
+        return
+      end
+
+      comp = GSC::PageComparator.new(url1, url2)
+      data = comp.compare
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "🥊 #{Color::BOLD}HEAD-TO-HEAD SEO ON-PAGE COMPARISON:#{Color::RESET}"
+      puts "   Page 1 (Target):     #{Color.c(url1, Color::CYAN)}"
+      puts "   Page 2 (Competitor): #{Color.c(url2, Color::YELLOW)}"
+      puts "─" * 80
+
+      c = data[:comparison] || {}
+
+      # Meta Titles
+      t1 = c.dig(:meta, :title, :page1) || {}
+      t2 = c.dig(:meta, :title, :page2) || {}
+      puts "\n#{Color::BOLD}📑 TITLE TAG:#{Color::RESET}"
+      puts "   P1: #{t1[:text]} (#{t1[:length]} chars) [#{t1[:optimal] ? Color.c('Optimal', Color::GREEN) : Color.c('Review', Color::YELLOW)}]"
+      puts "   P2: #{t2[:text]} (#{t2[:length]} chars) [#{t2[:optimal] ? Color.c('Optimal', Color::GREEN) : Color.c('Review', Color::YELLOW)}]"
+
+      # Headings
+      h = c[:headings] || {}
+      puts "\n#{Color::BOLD}🏷️ HEADINGS H1 / H2:#{Color::RESET}"
+      puts "   P1: #{h.dig(:h1_count, :page1)} H1s | #{h.dig(:h2_count, :page1)} H2s"
+      puts "   P2: #{h.dig(:h1_count, :page2)} H1s | #{h.dig(:h2_count, :page2)} H2s"
+
+      # Images
+      img = c[:images] || {}
+      puts "\n#{Color::BOLD}🖼️ IMAGES & ACCESSIBILITY:#{Color::RESET}"
+      puts "   P1: #{img.dig(:total_images, :page1)} images (#{img.dig(:missing_alt, :page1)} missing alt)"
+      puts "   P2: #{img.dig(:total_images, :page2)} images (#{img.dig(:missing_alt, :page2)} missing alt)"
+
+      # Links
+      l = c[:links] || {}
+      puts "\n#{Color::BOLD}🔗 LINK COUNTS:#{Color::RESET}"
+      puts "   P1: #{l.dig(:internal, :page1)} internal | #{l.dig(:external, :page1)} external"
+      puts "   P2: #{l.dig(:internal, :page2)} internal | #{l.dig(:external, :page2)} external"
+
+      # Schema
+      s = c[:structured_data] || {}
+      puts "\n#{Color::BOLD}📦 STRUCTURED DATA (JSON-LD):#{Color::RESET}"
+      puts "   P1: #{s.dig(:schema_count, :page1)} schemas #{(s.dig(:schema_types, :page1) || []).inspect}"
+      puts "   P2: #{s.dig(:schema_count, :page2)} schemas #{(s.dig(:schema_types, :page2) || []).inspect}"
+
+      # Speed
+      p_time = c[:performance] || {}
+      puts "\n#{Color::BOLD}⚡ RESPONSE TIME:#{Color::RESET}"
+      puts "   P1: #{p_time.dig(:response_time_ms, :page1)}ms | P2: #{p_time.dig(:response_time_ms, :page2)}ms"
+      puts ""
+    end
+
+    # 6. Content Gap
+    def self.handle_content_gap_command(target, extra, options)
+      url1 = target
+      url2 = extra
+
+      if url1.nil? || url2.nil?
+        puts Color.c("❌ Error: Two URLs required. Example: gsc content-gap https://mysite.com https://competitor.com", Color::RED)
+        return
+      end
+
+      gap = GSC::ContentGap.new(url1, url2)
+      data = gap.analyze
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "🔍 #{Color::BOLD}CONTENT & TOPICAL KEYWORD GAP (SurferSEO Style):#{Color::RESET}"
+      puts "   My URL:         #{Color.c(url1, Color::CYAN)} (#{data[:page1][:word_count]} words)"
+      puts "   Competitor URL: #{Color.c(url2, Color::YELLOW)} (#{data[:page2][:word_count]} words)"
+      puts "─" * 80
+
+      puts "\n#{Color::BOLD}🎯 HIGH-FREQUENCY PHRASES IN COMPETITOR MISSING IN YOUR CONTENT:#{Color::RESET}"
+      unigrams = data[:missing_unigrams] || []
+      bigrams  = data[:missing_bigrams] || []
+
+      if unigrams.empty? && bigrams.empty?
+        puts "   (No major content gap detected! Your page covers competitor terminology well.)"
+      else
+        puts "\n   #{Color.c('Top Missing 2-Word Keyphrases:', Color::BOLD, Color::YELLOW)}"
+        bigrams.first(8).each do |b|
+          puts "   • \"#{Color.c(b[:term], Color::BOLD)}\" (Competitor uses #{b[:competitor_count]}x, You: #{b[:your_count]}x)"
+        end
+
+        puts "\n   #{Color.c('Top Missing Keywords:', Color::BOLD, Color::CYAN)}"
+        unigrams.first(8).each do |u|
+          puts "   • \"#{Color.c(u[:term], Color::BOLD)}\" (Competitor uses #{u[:competitor_count]}x, You: #{u[:your_count]}x)"
+        end
+      end
+
+      headings = data[:missing_headings] || []
+      unless headings.empty?
+        puts "\n#{Color::BOLD}📑 COMPETITOR HEADINGS / TOPICS YOU OMITTED:#{Color::RESET}"
+        headings.each do |h|
+          puts "   • #{h}"
+        end
+      end
+      puts ""
+    end
+
+    # 7. Internal Links Audit
+    def self.handle_internal_links_command(target, options)
+      base_url = target || "https://#{Config.default_domain || 'example.com'}"
+      il = GSC::InternalLinks.new(base_url, limit: options[:limit] || 50)
+
+      puts BANNER unless options[:json] || options[:in_dashboard]
+      puts "🕸️ Auditing Internal Links & Orphan Pages for: #{Color.c(base_url, Color::CYAN)}...\n" unless options[:json]
+
+      data = il.audit
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      puts "─" * 80
+      puts "Pages Discovered: #{Color.c(data[:total_pages].to_s, Color::BOLD)}"
+      puts "Orphan Pages:     #{Color.c(data[:orphans].length.to_s, data[:orphans].empty? ? Color::GREEN : Color::RED, Color::BOLD)}"
+      puts "Weakly Linked:    #{Color.c(data[:weak_pages].length.to_s, Color::YELLOW, Color::BOLD)} (Only 1 incoming internal link)"
+      puts "─" * 80
+
+      orphans = data[:orphans] || []
+      unless orphans.empty?
+        puts "\n#{Color::BOLD}🚨 ORPHAN PAGES (0 incoming internal links - Crawl Dead Ends):#{Color::RESET}"
+        orphans.each do |orp|
+          puts "   • #{Color.c(orp, Color::RED)}"
         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=\"...\"` |"
+      puts "\n#{Color::BOLD}🔝 MOST LINKED INTERNAL PAGES:#{Color::RESET}"
+      (data[:top_linked] || []).each do |top|
+        puts "   • #{top[:url]} (#{Color.c(top[:incoming_count].to_s, Color::CYAN)} incoming links)"
+      end
+      puts ""
+    end
+
+    # 8. Schema Validator & Generator
+    def self.handle_schema_command(target, extra, options)
+      if target == 'generate' || target == 'gen'
+        schema_type = extra || 'faq'
+        tpl = GSC::SchemaValidator.generate_template(schema_type)
+        if options[:json]
+          puts JSON.pretty_generate(tpl)
+        else
+          puts Color.c("📋 Generated JSON-LD Schema (#{schema_type}):", Color::GREEN, Color::BOLD)
+          puts "<script type=\"application/ld+json\">"
+          puts JSON.pretty_generate(tpl)
+          puts "</script>"
         end
+        return
       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!**"
+      url = target || "https://#{Config.default_domain || 'example.com'}"
+      sv = GSC::SchemaValidator.new(url)
+      data = sv.audit
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "📦 #{Color::BOLD}STRUCTURED DATA & RICH SNIPPET VALIDATION:#{Color::RESET} #{Color.c(url, Color::CYAN)}"
+      puts "─" * 75
+
+      schemas = data[:schemas] || []
+      if schemas.empty?
+        puts "   (No JSON-LD structured data schemas found on this page)"
+        puts "   Tip: Run `gsc schema generate faq` to create valid JSON-LD schema."
       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 |"
+        schemas.each do |sc|
+          valid_badge = sc[:valid] ? Color.c("VALID", Color::GREEN, Color::BOLD) : Color.c("INVALID", Color::RED, Color::BOLD)
+          puts "\nSchema ##{sc[:index] + 1}: #{Color.c(sc[:type], Color::BOLD)} [#{valid_badge}]"
+          (sc[:errors] || []).each { |e| puts "   ❌ Error: #{Color.c(e, Color::RED)}" }
+          (sc[:warnings] || []).each { |w| puts "   ⚠️ Warning: #{Color.c(w, Color::YELLOW)}" }
         end
       end
-      md << ""
-      md << "---"
-      md << ""
+      puts ""
+    end
 
-      # 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!**"
+    # 9. LLMS.txt & AI Search
+    def self.handle_llms_command(target, extra, options)
+      base_url = target || "https://#{Config.default_domain || 'example.com'}"
+      llms = GSC::LlmsGenerator.new(base_url)
+
+      if extra == 'audit' || options[:audit]
+        data = llms.audit_ai_readability(base_url)
+        if options[:json]
+          puts JSON.pretty_generate(data)
+        else
+          puts BANNER unless options[:in_dashboard]
+          puts "🤖 #{Color::BOLD}AI SEARCH ENGINE / LLM READABILITY AUDIT:#{Color::RESET} #{Color.c(base_url, Color::CYAN)}"
+          puts "─" * 70
+          puts "AI Citation Readiness Score: #{Color.c(data[:ai_readability_score].to_s + '/100', Color::GREEN, Color::BOLD)} [Grade: #{data[:grade]}]"
+          puts "\nFeatures Detected:"
+          puts "   • Single H1 Heading : #{data.dig(:features, :h1_count) == 1 ? '✅ Yes' : '❌ No'}"
+          puts "   • Tables for Data   : #{data.dig(:features, :has_tables) ? '✅ Yes' : '❌ No'}"
+          puts "   • Bullet Lists      : #{data.dig(:features, :has_lists) ? '✅ Yes' : '❌ No'}"
+          puts "   • Structured Data   : #{data.dig(:features, :schemas_found)} schemas"
+          unless data[:issues].empty?
+            puts "\nOptimizations for Perplexity & ChatGPT:"
+            data[:issues].each { |iss| puts "   • #{Color.c(iss, Color::YELLOW)}" }
+          end
+          puts ""
+        end
       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]} |"
+        content = llms.generate_llms_txt
+        if options[:save]
+          File.write("llms.txt", content)
+          puts Color.c("✅ Successfully wrote llms.txt to current directory!", Color::GREEN)
+        else
+          puts content
         end
       end
-      md << ""
-      md << "---"
-      md << ""
+    end
 
-      # 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)*"
+    # 10. SERP & Social Preview
+    def self.handle_preview_command(target, options)
+      url = target || "https://#{Config.default_domain || 'example.com'}"
+      sp = GSC::SerpPreview.new(url)
+      data = sp.generate
 
-      File.write(filepath, md.join("\n"), encoding: 'UTF-8')
-      filepath
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "🖥️ #{Color::BOLD}GOOGLE SERP PREVIEW (Desktop Viewport):#{Color::RESET}"
+      puts "┌─────────────────────────────────────────────────────────────┐"
+      puts "│ #{Color.c(data.dig(:desktop_serp, :breadcrumb), Color::DIM)}│"
+      puts "│ #{Color.c(data.dig(:desktop_serp, :title).ljust(59), Color::BLUE, Color::BOLD)}│"
+      puts "│ #{Color.c(data.dig(:desktop_serp, :snippet)[0..58].ljust(59), Color::DIM)}│"
+      puts "└─────────────────────────────────────────────────────────────┘"
+      if data[:truncation_risk]
+        puts Color.c("⚠️ Warning: Title exceeds 60 characters and may truncate with '...' on Google SERPs.", Color::YELLOW)
+      else
+        puts Color.c("✅ Title length is optimal (< 60 chars / ~580px).", Color::GREEN)
+      end
+
+      puts "\n📱 #{Color::BOLD}OPEN GRAPH / SOCIAL CARD PREVIEW:#{Color::RESET}"
+      soc = data[:social] || {}
+      puts "   • Title       : #{soc[:og_title]}"
+      puts "   • Description : #{soc[:og_description]}"
+      puts "   • Card Image  : #{soc[:og_image] || '(No og:image specified)'}"
+      puts ""
     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
+    # 11. Network & Redirect Tracer
+    def self.handle_trace_command(target, options)
+      url = target || Config.default_domain || 'example.com'
+      nt = GSC::NetworkTracer.new(url)
+      data = nt.trace
 
-      {
-        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
-      }
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "🛤️ #{Color::BOLD}REDIRECT CHAIN & HTTP HEADER TRACE:#{Color::RESET} #{Color.c(url, Color::CYAN)}"
+      puts "─" * 75
+      puts "Total Hops: #{data[:total_hops]} | Duration: #{data[:total_duration_ms]}ms"
+
+      (data[:hops] || []).each do |hop|
+        status_c = (hop[:status_code] == 200) ? Color::GREEN : Color::YELLOW
+        puts "\nHop ##{hop[:hop]}: #{Color.c(hop[:status_code].to_s, status_c, Color::BOLD)} (#{hop[:duration_ms]}ms)"
+        puts "   URL:    #{hop[:url]}"
+        puts "   X-Robots-Tag: #{Color.c(hop[:x_robots_tag], Color::RED)}" if hop[:x_robots_tag]
+        puts "   Canonical:    #{hop[:canonical_header]}" if hop[:canonical_header]
+        puts "   HSTS:         #{hop[:hsts] ? 'Enabled' : 'Disabled'}"
+      end
+      puts ""
     end
 
-    private
+    # 12. Robots.txt Checker
+    def self.handle_robots_command(target, extra, options)
+      url = target || "https://#{Config.default_domain || 'example.com'}"
+      path = extra || '/'
+      bot = options[:bot] || 'googlebot'
 
-    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
+      rc = GSC::RobotsChecker.new(url)
+      data = rc.check(path, bot)
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
       end
-    rescue StandardError
-      [target.start_with?('http') ? target : "https://#{target}"]
+
+      puts BANNER unless options[:in_dashboard]
+      puts "🤖 #{Color::BOLD}ROBOTS.TXT CRAWLER SIMULATOR:#{Color::RESET}"
+      puts "   Robots URL : #{data[:robots_url]}"
+      puts "   User Agent : #{Color.c(bot, Color::CYAN)}"
+      puts "   Test Path  : #{Color.c(path, Color::BOLD)}"
+      puts "─" * 70
+
+      status_badge = data[:allowed] ? Color.c("✅ ALLOWED", Color::GREEN, Color::BOLD) : Color.c("❌ BLOCKED (DISALLOW)", Color::RED, Color::BOLD)
+      puts "Crawl Verdict : #{status_badge}"
+      if data[:matched_rule]
+        puts "Matched Rule  : #{data[:matched_rule][:type].to_s.upcase}: #{data[:matched_rule][:path]}"
+      end
+      puts ""
     end
 
-    def categorize_page_issues(data)
-      page_url = data[:url]
+    # 13. Backlinks & GSC Links Ingestion
+    def self.handle_backlinks_command(target, extra, options)
+      domain = target || Config.default_domain || 'example.com'
+      bm = GSC::BacklinksManager.new(domain)
 
-      # 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
+      if target == 'import' || extra == 'import'
+        source = (target == 'import') ? extra : target
+        content = if source == 'clip' || source == 'clipboard'
+                    `pbpaste 2>/dev/null`
+                  elsif source && File.exist?(source)
+                    File.read(source)
+                  else
+                    nil
+                  end
+
+        if content.nil? || content.strip.empty?
+          puts Color.c("❌ Error: No content provided. Usage: gsc backlinks import [file.csv|clip]", Color::RED)
+          return
         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]
-          }
+        res = bm.import_csv(content)
+        if options[:json]
+          puts JSON.pretty_generate(res)
+        else
+          puts Color.c("✅ Successfully imported GSC backlink export!", Color::GREEN, Color::BOLD)
+          puts "   Referring Domains : #{res[:sources_count]}"
+          puts "   Target Pages      : #{res[:targets_count]}"
         end
+        return
       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
+      data = bm.summary
 
-      # 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) || ''
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
 
-      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
+      puts BANNER unless options[:in_dashboard]
+      puts "🔗 #{Color::BOLD}GSC BACKLINK & REFERRING DOMAIN INTELLIGENCE:#{Color::RESET} #{Color.c(domain, Color::CYAN)}"
+      puts "─" * 75
+      puts "Total Referring Domains : #{Color.c(data[:total_referring_domains].to_s, Color::BOLD)}"
+      puts "Total External Links    : #{Color.c(data[:total_external_links].to_s, Color::BOLD)}"
+      puts "Last Updated            : #{data[:updated_at] || 'Never (Run `gsc backlinks import` to ingest GSC export)'}"
+      puts "─" * 75
 
-      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(', ')
-        }
+      sources = data[:top_referring_domains] || []
+      unless sources.empty?
+        puts "\n#{Color::BOLD}🌐 TOP REFERRING SITES:#{Color::RESET}"
+        sources.each do |s|
+          puts "   • #{s['domain'].to_s.ljust(45)} #{Color.c(s['links_count'].to_s.rjust(6) + ' links', Color::CYAN)}"
+        end
       end
 
-      # Canonical
-      if data.dig(:canonical, :url) && !data.dig(:canonical, :self_referencing)
-        @canonical_issues << {
-          page_url: page_url,
-          canonical_url: data[:canonical][:url]
-        }
+      targets = data[:top_target_pages] || []
+      unless targets.empty?
+        puts "\n#{Color::BOLD}🎯 TOP LINKED LANDING PAGES:#{Color::RESET}"
+        targets.each do |t|
+          puts "   • #{t['target_url'].to_s.ljust(45)} #{Color.c(t['incoming_count'].to_s.rjust(6) + ' links', Color::GREEN)}"
+        end
       end
+      puts ""
     end
   end
 end
+# --- End cli_advanced.rb ---
 
-# --- command_registry.rb ---
+# --- Begin command_registry.rb ---
 module GSC
   module CommandRegistry
 COMMAND_REGISTRY = [
@@ -2681,8 +4416,9 @@ COMMAND_REGISTRY = [
   COMMAND_REGISTRY = CommandRegistry::COMMAND_REGISTRY
   SKILL_MD_CONTENT = CommandRegistry::SKILL_MD_CONTENT
 end
+# --- End command_registry.rb ---
 
-# --- cli.rb ---
+# --- Begin cli.rb ---
 module GSC
   # CLI Command Runner
   class CLI
@@ -2844,6 +4580,22 @@ opts.on('--save', 'Save keyword research snapshot to ~/.config/gsc/domains/<doma
   options[:save] = true
 end
 
+opts.on('--alphabet', 'Run alphabet soup harvest (a-z) for search suggestions') do
+  options[:alphabet] = true
+end
+
+opts.on('--numbers', 'Include numbers (0-9) in alphabet soup search suggestions') do
+  options[:numbers] = true
+end
+
+opts.on('--strategy STRAT', 'PageSpeed device strategy: mobile or desktop (default: mobile)') do |s|
+  options[:strategy] = s
+end
+
+opts.on('--bot NAME', 'User agent bot name for robots.txt testing (default: googlebot)') do |b|
+  options[:bot] = b
+end
+
 
 opts.on('--delay MS', Integer, 'Delay between sequential requests in ms (default: 120)') do |delay|
   options[:delay] = delay
@@ -2913,6 +4665,72 @@ opts.on('--dry-run', 'Simulate API calls without mutating data') do
         exit 0 unless options[:in_dashboard]
         return
 
+when 'suggest', 'autocomplete', 'sug'
+  handle_suggest_command(target, options)
+  exit 0 unless options[:in_dashboard]
+  return if options[:in_dashboard]
+
+when 'questions', 'paa', 'faqs'
+  handle_questions_command(target, options)
+  exit 0 unless options[:in_dashboard]
+  return if options[:in_dashboard]
+
+when 'authority', 'opr', 'da', 'domain-authority'
+  handle_authority_command(target, extra, options)
+  exit 0 unless options[:in_dashboard]
+  return if options[:in_dashboard]
+
+when 'speed', 'vitals', 'pagespeed', 'psi'
+  handle_speed_command(target, options)
+  exit 0 unless options[:in_dashboard]
+  return if options[:in_dashboard]
+
+when 'compare', 'diff-seo', 'vs'
+  handle_compare_command(target, extra, options)
+  exit 0 unless options[:in_dashboard]
+  return if options[:in_dashboard]
+
+when 'content-gap', 'gap'
+  handle_content_gap_command(target, extra, options)
+  exit 0 unless options[:in_dashboard]
+  return if options[:in_dashboard]
+
+when 'internal-links', 'orphans', 'links-audit'
+  handle_internal_links_command(target, options)
+  exit 0 unless options[:in_dashboard]
+  return if options[:in_dashboard]
+
+when 'schema', 'rich-snippets', 'ld-json'
+  handle_schema_command(target, extra, options)
+  exit 0 unless options[:in_dashboard]
+  return if options[:in_dashboard]
+
+when 'llms', 'ai-ready'
+  handle_llms_command(target, extra, options)
+  exit 0 unless options[:in_dashboard]
+  return if options[:in_dashboard]
+
+when 'preview', 'serp-preview', 'social-preview'
+  handle_preview_command(target, options)
+  exit 0 unless options[:in_dashboard]
+  return if options[:in_dashboard]
+
+when 'trace', 'redirects', 'hops'
+  handle_trace_command(target, options)
+  exit 0 unless options[:in_dashboard]
+  return if options[:in_dashboard]
+
+when 'robots', 'robots-txt'
+  handle_robots_command(target, extra, options)
+  exit 0 unless options[:in_dashboard]
+  return if options[:in_dashboard]
+
+when 'backlinks', 'links'
+  handle_backlinks_command(target, extra, options)
+  exit 0 unless options[:in_dashboard]
+  return if options[:in_dashboard]
+
+
       when 'trends', 'tr', 'google-trends', 'gtrends', 't'
   if target.nil? || target.strip.empty?
     # No target query given: pass through to GSC period decay/trends below
@@ -6055,7 +7873,6 @@ end
         end
 
         # Validate syntax of downloaded script
-        require 'tempfile'
         temp = Tempfile.new(['gsc-update', '.rb'])
         temp.write(remote_script)
         temp.close
@@ -7916,7 +9733,6 @@ def self.handle_interactive_shell(options = {})
     end
 
     # Shellwords parse
-    require 'shellwords'
     cmd_args = Shellwords.split(input) rescue input.split
     first = cmd_args[0].downcase
 
@@ -8116,6 +9932,7 @@ def self.print_commands_help
     end
   end
 end
+# --- End cli.rb ---
 
 # Top-level aliases for backwards compatibility
 GoogleTrends       = GSC::GoogleTrends unless defined?(GoogleTrends)
@@ -8124,5 +9941,19 @@ KeywordsEverywhere = GSC::KeywordsEverywhere unless defined?(KeywordsEverywhere)
 Prompts            = GSC::Prompts unless defined?(Prompts)
 PageAnalyzer       = GSC::PageAnalyzer unless defined?(PageAnalyzer)
 SiteCrawler        = GSC::SiteCrawler unless defined?(SiteCrawler)
-
-GSC::CLI.start(ARGV)
+GoogleSuggest      = GSC::GoogleSuggest unless defined?(GoogleSuggest)
+OpenPageRank       = GSC::OpenPageRank unless defined?(OpenPageRank)
+PageSpeed          = GSC::PageSpeed unless defined?(PageSpeed)
+PageComparator     = GSC::PageComparator unless defined?(PageComparator)
+ContentGap         = GSC::ContentGap unless defined?(ContentGap)
+InternalLinks      = GSC::InternalLinks unless defined?(InternalLinks)
+SchemaValidator    = GSC::SchemaValidator unless defined?(SchemaValidator)
+LlmsGenerator      = GSC::LlmsGenerator unless defined?(LlmsGenerator)
+SerpPreview        = GSC::SerpPreview unless defined?(SerpPreview)
+NetworkTracer      = GSC::NetworkTracer unless defined?(NetworkTracer)
+RobotsChecker      = GSC::RobotsChecker unless defined?(RobotsChecker)
+BacklinksManager   = GSC::BacklinksManager unless defined?(BacklinksManager)
+
+if __FILE__ == $PROGRAM_NAME
+  GSC::CLI.start(ARGV)
+end