gsc-cli 2.1.0 → 2.2.0

data/lib/gsc/cli_advanced.rb

@@ -10,7 +10,7 @@ module GSC
     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)
+        puts Color.c("❌ Error: Query required. Example: gsc suggest \"seo audit\"", Color::RED)
         return
       end
 
@@ -52,7 +52,7 @@ module GSC
     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)
+        puts Color.c("❌ Error: Query required. Example: gsc questions \"seo audit\"", Color::RED)
         return
       end
 
@@ -91,7 +91,7 @@ module GSC
       domains = domains.compact
 
       if domains.empty?
-        puts Color.c("❌ Error: Domain required. Example: gsc authority packinglog.com", Color::RED)
+        puts Color.c("❌ Error: Domain required. Example: gsc authority example.com", Color::RED)
         return
       end
 
@@ -136,8 +136,12 @@ module GSC
 
     # 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?://}
+      raw = target || (Config.default_domain ? "https://#{Config.default_domain}" : nil)
+      if raw.nil? || raw.empty?
+        puts Color.c("❌ Error: Target URL or domain required. Example: gsc speed https://mybrand.com", Color::RED)
+        return
+      end
+      url = raw.to_s.start_with?('http') ? raw : "https://#{raw}"
       strategy = options[:strategy] || 'mobile'
 
       puts BANNER unless options[:json] || options[:in_dashboard]
@@ -183,6 +187,90 @@ module GSC
       puts ""
     end
 
+    # 4b. Core Web Vitals & GSC Performance Correlator
+    def self.handle_speed_correlate_command(target, options)
+      domain = options[:domain] || Config.default_domain
+      if (domain.nil? || domain.empty?) && (target.nil? || target.empty?)
+        puts Color.c("❌ Error: Target URL or domain required. Example: gsc speed-correlate https://mybrand.com", Color::RED)
+        return
+      end
+      url = target || "https://#{domain}/"
+      url = "https://#{url}" unless url =~ %r{^https?://}
+      strategy = options[:strategy] || 'mobile'
+      days = (options[:days] || 28).to_i
+
+      # Attempt to get GSC API client if authenticated
+      api = nil
+      sa = GSC::Auth.find_service_account(options[:key], domain)
+      if sa && sa[:data]
+        token = GSC::Auth.fetch_access_token(sa[:data])
+        client = GSC::Client.new(token: token)
+        api = GSC::API.new(client)
+      end
+
+      correlator = GSC::SpeedCorrelator.new(url, api: api, domain: domain, days: days, strategy: strategy, options: options)
+      data = correlator.correlate
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "⚡ #{Color::BOLD}CORE WEB VITALS & SEARCH CONSOLE PERFORMANCE CORRELATOR:#{Color::RESET}"
+      puts "   Target URL: #{Color.c(url, Color::CYAN, Color::BOLD)} [Strategy: #{strategy.upcase}]"
+      puts "─" * 80
+
+      cwv = data[:core_web_vitals] || {}
+      gsc = data[:gsc_performance] || {}
+      diag = data[:correlation_diagnosis] || {}
+      proj = data[:projections] || {}
+
+      perf_score = cwv[:performance_score] || 0
+      score_color = perf_score >= 90 ? Color::GREEN : (perf_score >= 50 ? Color::YELLOW : Color::RED)
+
+      puts "📱 #{Color::BOLD}LIGHTHOUSE PERFORMANCE:#{Color::RESET} #{Color.c("#{perf_score}/100", score_color, Color::BOLD)} [Source: #{cwv[:source]}]"
+      puts "   • LCP (Largest Contentful Paint) : #{Color.c(cwv[:lcp_display].to_s, Color::BOLD)} [Status: #{diag[:lcp_status]}]"
+      puts "   • CLS (Cumulative Layout Shift)  : #{Color.c(cwv[:cls_display].to_s, Color::BOLD)} [Status: #{diag[:cls_status]}]"
+      puts "   • FCP (First Contentful Paint)   : #{Color.c(cwv[:fcp_display].to_s, Color::BOLD)}"
+      puts "   • TBT (Total Blocking Time)      : #{Color.c(cwv[:tbt_display].to_s, Color::BOLD)}"
+
+      puts "\n📈 #{Color::BOLD}SEARCH CONSOLE TRACTION (Past #{days} Days):#{Color::RESET}"
+      puts "   • Impressions : #{Color.c(gsc[:impressions].to_s, Color::CYAN, Color::BOLD)}"
+      puts "   • Clicks      : #{Color.c(gsc[:clicks].to_s, Color::GREEN, Color::BOLD)}"
+      puts "   • CTR         : #{Color.c("#{gsc[:ctr]}%", Color::BOLD)}"
+      puts "   • Avg Position: #{Color.c(gsc[:position].to_s, Color::BOLD)}"
+
+      puts "\n🧠 #{Color::BOLD}ALGORITHMIC CWV IMPACT DIAGNOSIS:#{Color::RESET}"
+      diag_color = diag[:overall_cwv_pass] ? Color::GREEN : Color::YELLOW
+      puts "   • CWV Overall Verdict : [#{Color.c(diag[:overall_cwv_pass] ? 'PASSED' : 'NEEDS OPTIMIZATION', diag_color, Color::BOLD)}]"
+      puts "   • Algorithmic Drag    : #{Color.c(diag[:algorithmic_status], Color::BOLD)}"
+
+      puts "\n🚀 #{Color::BOLD}PROJECTED SEARCH IMPRESSION & TRAFFIC SURGE (Upon Reaching 'Good' CWV):#{Color::RESET}"
+      puts "   • Potential Impression Lift   : #{Color.c("+#{proj[:potential_lift_percentage]}%", Color::GREEN, Color::BOLD)} (+#{proj[:incremental_impressions_gain]} impressions)"
+      puts "   • Projected Impressions Target: #{Color.c(proj[:projected_impressions].to_s, Color::CYAN, Color::BOLD)}"
+      puts "   • Projected Rank Lift         : #{Color.c(proj[:estimated_position_improvement].to_s, Color::GREEN, Color::BOLD)} (Pos #{proj[:current_position]} -> Pos #{proj[:projected_position]})"
+      puts "   • Projected Monthly Click Gain: #{Color.c("+#{proj[:projected_incremental_monthly_clicks]} clicks/mo", Color::GREEN, Color::BOLD)}"
+
+      action_plan = data[:action_plan] || []
+      if action_plan.any?
+        puts "\n🛠️  #{Color::BOLD}PRIORITIZED ENGINEERING FIXES FOR SPEED & RANKINGS:#{Color::RESET}"
+        action_plan.each_with_index do |act, idx|
+          puts "   #{idx + 1}. [#{Color.c(act[:priority], Color::BOLD)}] [#{act[:metric]}]: #{act[:recommendation]}"
+        end
+      end
+
+      opps = cwv[:opportunities] || []
+      if opps.any?
+        puts "\n💡 #{Color::BOLD}IDENTIFIED BOTTLENECK OPPORTUNITIES:#{Color::RESET}"
+        opps.each do |o|
+          puts "   • #{o[:title]} (#{Color.c(o[:display] || "#{o[:savings_ms]}ms savings", Color::YELLOW)})"
+        end
+      end
+
+      puts "\n" + ("─" * 80) + "\n"
+    end
+
     # 5. Page Comparison
     def self.handle_compare_command(target, extra, options)
       url1 = target
@@ -299,13 +387,19 @@ module GSC
       puts ""
     end
 
-    # 7. Internal Links Audit
+    # 7. Internal Links Audit & Orphan Page Rescue Engine
     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)
+      raw = target || (Config.default_domain ? "https://#{Config.default_domain}" : nil)
+      if raw.nil? || raw.empty?
+        puts Color.c("❌ Error: Target URL or domain required. Example: gsc internal-links https://mybrand.com", Color::RED)
+        return
+      end
+      base_url = raw.to_s.start_with?('http') ? raw : "https://#{raw}"
+      conc = options[:concurrency] || 5
+      il = GSC::InternalLinks.new(base_url, limit: options[:limit] || 50, concurrency: conc)
 
       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]
+      puts "🕸️ Auditing Internal Links & Orphan Pages for: #{Color.c(base_url, Color::CYAN)} (#{conc} worker threads)...\n" unless options[:json]
 
       data = il.audit
 
@@ -314,25 +408,66 @@ module GSC
         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)"
+      score_color = case data[:health_score]
+                    when 85..100 then Color::GREEN
+                    when 70..84  then Color::YELLOW
+                    else              Color::RED
+                    end
+
+      puts "📍 Domain:            #{Color.c(data[:base_url], Color::CYAN, Color::BOLD)}"
+      puts "⚡ Crawl Performance: #{data[:total_pages]} pages mapped in #{data[:crawl_duration_s]}s"
+      puts "🏆 Link Equity Score: #{Color.c("#{data[:health_score]}/100 (Grade #{data[:health_grade]})", score_color, Color::BOLD)}"
+      puts "🚨 True Orphans:      #{Color.c(data[:orphans].length.to_s, data[:orphans].empty? ? Color::GREEN : Color::RED, Color::BOLD)} (0 incoming internal links)"
+      puts "⚠️  Weakly Linked:     #{Color.c(data[:weak_pages].length.to_s, Color::YELLOW, Color::BOLD)} (Only 1 incoming internal link)"
+      puts "🧗 Buried Pages:      #{Color.c(data[:deep_pages].length.to_s, data[:deep_pages].empty? ? Color::GREEN : Color::YELLOW, Color::BOLD)} (Click depth >= 4)"
       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)}"
+      orphan_details = data[:orphan_details] || []
+      unless orphan_details.empty?
+        puts "\n#{Color::BOLD}🚨 ORPHAN PAGE RESCUE PLAYBOOK (#{orphan_details.size} crawl dead-ends):#{Color::RESET}"
+        orphan_details.each_with_index do |orp, idx|
+          puts "\n   #{Color::BOLD}#{idx + 1}. #{Color.c(orp[:url], Color::RED, Color::BOLD)}#{Color::RESET} [Depth: #{orp[:depth]}]"
+          puts "      #{Color::BOLD}Rescue Prescriptions:#{Color::RESET}"
+          orp[:suggested_rescues].each do |rec|
+            puts "      • #{Color.c(rec[:action], Color::CYAN)}"
+          end
         end
+      else
+        puts "\n#{Color.c('✅ EXCELLENT! No orphan pages detected on site.', Color::GREEN, Color::BOLD)}"
       end
 
-      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)"
+      weak = data[:weak_pages] || []
+      unless weak.empty?
+        puts "\n#{Color::BOLD}⚠️  WEAKLY LINKED PAGES (Vulnerable to De-indexation):#{Color::RESET}"
+        weak.first(5).each do |w|
+          puts "   • #{w[:url]} (Linked only from: #{Color.c(w[:source].to_s, Color::GRAY)})"
+        end
+        puts "   ... and #{weak.size - 5} more weak pages" if weak.size > 5
       end
-      puts ""
+
+      deep = data[:deep_pages] || []
+      unless deep.empty?
+        puts "\n#{Color::BOLD}🧗 BURIED PAGES (Crawl Depth >= 4 clicks):#{Color::RESET}"
+        deep.first(5).each do |dp|
+          puts "   • #{dp[:url]} (#{Color.c("#{dp[:depth]} clicks deep", Color::YELLOW)})"
+        end
+      end
+
+      puts "\n#{Color::BOLD}🔝 TOP LINK EQUITY HUBS (High-Authority Internal Sources):#{Color::RESET}"
+      (data[:top_linked] || []).first(6).each do |top|
+        title_str = top[:title].to_s.empty? ? '' : " — \"#{top[:title][0..35]}...\""
+        puts "   • #{Color.c(top[:url], Color::BOLD)}#{title_str} (#{Color.c(top[:incoming_count].to_s, Color::CYAN)} in / #{top[:outgoing_count]} out)"
+      end
+
+      if options[:csv]
+        csv_data = orphan_details.map do |o|
+          [o[:url], o[:depth], o[:suggested_rescues].map { |r| r[:source_url] }.join('; ')]
+        end
+        write_csv(options[:csv], %w[OrphanURL Depth RecommendedRescueSources], csv_data)
+        puts Color.c("\n📁 Exported orphan rescue playbook to #{options[:csv]}", Color::CYAN)
+      end
+
+      puts "\n" + ("─" * 80) + "\n"
     end
 
     # 8. Schema Validator & Generator
@@ -351,7 +486,12 @@ module GSC
         return
       end
 
-      url = target || "https://#{Config.default_domain || 'example.com'}"
+      raw = target || (Config.default_domain ? "https://#{Config.default_domain}" : nil)
+      if raw.nil? || raw.empty?
+        puts Color.c("❌ Error: Target URL or domain required. Example: gsc schema https://mybrand.com", Color::RED)
+        return
+      end
+      url = raw.to_s.start_with?('http') ? raw : "https://#{raw}"
       sv = GSC::SchemaValidator.new(url)
       data = sv.audit
 
@@ -381,7 +521,12 @@ module GSC
 
     # 9. LLMS.txt & AI Search
     def self.handle_llms_command(target, extra, options)
-      base_url = target || "https://#{Config.default_domain || 'example.com'}"
+      raw = target || (Config.default_domain ? "https://#{Config.default_domain}" : nil)
+      if raw.nil? || raw.empty?
+        puts Color.c("❌ Error: Target URL or domain required. Example: gsc llms https://mybrand.com", Color::RED)
+        return
+      end
+      base_url = raw.to_s.start_with?('http') ? raw : "https://#{raw}"
       llms = GSC::LlmsGenerator.new(base_url)
 
       if extra == 'audit' || options[:audit]
@@ -415,10 +560,27 @@ module GSC
       end
     end
 
-    # 10. SERP & Social Preview
+    # 10. SERP & Social Preview / Live SERP Feature Detector
     def self.handle_preview_command(target, options)
-      url = target || "https://#{Config.default_domain || 'example.com'}"
-      sp = GSC::SerpPreview.new(url)
+      is_url = target.to_s.start_with?('http://', 'https://')
+      has_title_or_url = is_url || options[:url] || options[:title] || options[:desc] || options[:description] || options[:preview] || (target.to_s =~ /[:|—]/)
+
+      if options[:live] || options[:features] || (!has_title_or_url && !target.to_s.empty?)
+        return handle_serp_features_command(target, options)
+      end
+
+      url = options[:url] || (target if is_url)
+      url ||= (Config.default_domain ? "https://#{Config.default_domain}" : nil)
+      title = options[:title] || (!is_url && !target.to_s.empty? ? target.to_s : nil)
+      desc = options[:desc] || options[:description]
+
+      if url.nil? && (title.nil? || title.empty?)
+        puts Color.c("❌ Error: Target URL or title required for SERP preview. Example: gsc preview https://mybrand.com/page", Color::RED)
+        return
+      end
+      url ||= "https://#{title.to_s.downcase.gsub(/[^a-z0-9]+/, '-')}.local"
+
+      sp = GSC::SerpPreview.new(url, title: title, desc: desc)
       data = sp.generate
 
       if options[:json]
@@ -427,29 +589,241 @@ module GSC
       end
 
       puts BANNER unless options[:in_dashboard]
+      m = data[:metrics] || {}
+
       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 "┌─────────────────────────────────────────────────────────────────────────┐"
+      puts "│ #{Color.c(data.dig(:desktop_serp, :breadcrumb).to_s.ljust(71), Color::DIM)}│"
+      puts "│ #{Color.c(data.dig(:desktop_serp, :title).to_s.ljust(71), Color::BLUE, Color::BOLD)}│"
+      puts "│ #{Color.c(data.dig(:desktop_serp, :snippet).to_s[0..70].ljust(71), Color::DIM)}│"
+      puts "└─────────────────────────────────────────────────────────────────────────┘"
+
+      t_status = if m[:title_truncated]
+                   Color.c("⚠️ TRUNCATED (+#{(m[:title_pixel_est] - m[:title_desktop_limit]).round(1)}px over 580px limit)", Color::YELLOW, Color::BOLD)
+                 else
+                   Color.c('✅ OPTIMAL (< 580px desktop limit)', Color::GREEN, Color::BOLD)
+                 end
+
+      d_status = if m[:desc_truncated]
+                   Color.c("⚠️ TRUNCATED (+#{(m[:desc_pixel_est] - m[:desc_desktop_limit]).round(1)}px over 960px limit)", Color::YELLOW, Color::BOLD)
+                 else
+                   Color.c('✅ OPTIMAL (< 960px desktop limit)', Color::GREEN, Color::BOLD)
+                 end
+
+      puts "   • Title Width:       #{m[:title_chars]} chars / ~#{m[:title_pixel_est]}px  [#{t_status}]"
+      puts "   • Description Width: #{m[:desc_chars]} chars / ~#{m[:desc_pixel_est]}px  [#{d_status}]"
+
+      puts "\n📱 #{Color::BOLD}GOOGLE SERP PREVIEW (Mobile Viewport):#{Color::RESET}"
+      puts "┌─────────────────────────────────────────────────────────────────────────┐"
+      puts "│ #{Color.c(data.dig(:mobile_serp, :breadcrumb).to_s.ljust(71), Color::DIM)}│"
+      puts "│ #{Color.c(data.dig(:mobile_serp, :title).to_s.ljust(71), Color::BLUE, Color::BOLD)}│"
+      puts "│ #{Color.c(data.dig(:mobile_serp, :snippet).to_s[0..70].ljust(71), Color::DIM)}│"
+      puts "└─────────────────────────────────────────────────────────────────────────┘"
 
-      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)'}"
+      if soc[:og_title] || soc[:og_image]
+        puts "\n🌐 #{Color::BOLD}OPEN GRAPH / SOCIAL CARD PREVIEW:#{Color::RESET}"
+        puts "   • Title       : #{soc[:og_title]}"
+        puts "   • Description : #{soc[:og_description]}"
+        puts "   • Card Image  : #{soc[:og_image] || '(No og:image specified)'}"
+      end
+      puts ""
+    end
+
+    # 10a. Live SERP Feature Detector & Zero-Click Threat Analysis
+    def self.handle_serp_features_command(query, options)
+      query_str = query.to_s.sub(/^(query|live):/, '').strip
+      query_str = "what is #{Config.default_domain || 'technical seo'}" if query_str.empty?
+
+      detector = GSC::SerpFeatureDetector.new(query_str, options)
+      data = detector.detect
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "🔍 #{Color::BOLD}LIVE SERP FEATURE & ZERO-CLICK THREAT DETECTOR:#{Color::RESET} #{Color.c(query_str, Color::CYAN, Color::BOLD)}"
+      puts "─" * 80
+
+      zt = data[:zero_click_threat] || {}
+      threat_color = case zt[:level]
+                     when 'LOW'      then Color::GREEN
+                     when 'MODERATE' then Color::YELLOW
+                     else                 Color::RED
+                     end
+
+      puts "🎯 Search Intent:     #{Color.c(data.dig(:intent, :primary).to_s, Color::BOLD)} (#{data.dig(:intent, :description)})"
+      puts "🚨 Zero-Click Threat: #{Color.c("#{zt[:level]} (#{zt[:score]}/100)", threat_color, Color::BOLD)} [Organic CTR Impact: #{zt[:estimated_organic_ctr_suppression]}]"
+      puts "─" * 80
+
+      f = data[:features] || {}
+      puts "\n#{Color::BOLD}📊 DETECTED SERP REAL ESTATE FEATURES:#{Color::RESET}"
+
+      # AI Overview
+      aio = f[:ai_overview] || {}
+      aio_badge = aio[:detected] ? Color.c("ACTIVE (#{aio[:probability_pct]}% prob)", Color::RED, Color::BOLD) : Color.c("Unlikely (#{aio[:probability_pct]}%)", Color::GRAY)
+      puts "   • Google AI Overview (Gemini) : [#{aio_badge}]"
+      puts "     └─ #{Color.c(aio[:impact], Color::DIM)}" if aio[:detected]
+
+      # Featured Snippet
+      fs = f[:featured_snippet] || {}
+      fs_badge = fs[:detected] ? Color.c("OPPORTUNITY (#{fs[:target_format].capitalize} - #{fs[:probability_pct]}%)", Color::GREEN, Color::BOLD) : Color.c("None", Color::GRAY)
+      puts "   • Featured Snippet Box        : [#{fs_badge}]"
+      puts "     └─ Target Recipe: #{Color.c(fs[:capture_prescription], Color::CYAN)}" if fs[:detected]
+
+      # People Also Ask
+      paa = f[:people_also_ask] || {}
+      paa_badge = paa[:detected] ? Color.c("#{paa[:count]} Live Questions Extracted", Color::CYAN, Color::BOLD) : Color.c("None", Color::GRAY)
+      puts "   • People Also Ask (PAA)       : [#{paa_badge}]"
+      if paa[:detected] && (paa[:questions] || []).any?
+        paa[:questions].first(5).each do |q_text|
+          puts "     ❓ \"#{Color.c(q_text, Color::YELLOW)}\""
+        end
+      end
+
+      # Local Pack
+      lp = f[:local_3_pack] || {}
+      lp_badge = lp[:detected] ? Color.c("DETECTED (Google Maps 3-Pack)", Color::YELLOW, Color::BOLD) : Color.c("None", Color::GRAY)
+      puts "   • Local Maps 3-Pack           : [#{lp_badge}]"
+
+      # Video Carousel
+      vc = f[:video_carousel] || {}
+      vc_badge = vc[:detected] ? Color.c("DETECTED (Video Carousel)", Color::YELLOW, Color::BOLD) : Color.c("None", Color::GRAY)
+      puts "   • Video Carousel / YouTube    : [#{vc_badge}]"
+
+      # Discussions & Forums
+      df = f[:discussions_and_forums] || {}
+      df_badge = df[:detected] ? Color.c("DETECTED (Reddit/Quora Modules)", Color::CYAN, Color::BOLD) : Color.c("None", Color::GRAY)
+      puts "   • Discussions & Forums        : [#{df_badge}]"
+
+      # Shopping Pack
+      sp = f[:shopping_pack] || {}
+      sp_badge = sp[:detected] ? Color.c("DETECTED (Shopping Product Grid)", Color::YELLOW, Color::BOLD) : Color.c("None", Color::GRAY)
+      puts "   • Google Shopping Grid        : [#{sp_badge}]"
+
+      # Playbook
+      playbook = data[:playbook] || []
+      if playbook.any?
+        puts "\n#{Color::BOLD}🏆 RICH SNIPPET & CITATION CAPTURE PLAYBOOK:#{Color::RESET}"
+        playbook.each_with_index do |p, idx|
+          puts "   #{idx + 1}. [#{Color.c(p[:priority], Color::BOLD)}] #{Color.c(p[:target], Color::CYAN)}:"
+          puts "      👉 #{p[:action]}"
+        end
+      end
+
+      # Live SERP Sampling
+      serp = data[:serp_sampling] || []
+      if serp.any?
+        puts "\n#{Color::BOLD}🌐 LIVE SERP SAMPLING (Top Competitor Results):#{Color::RESET}"
+        serp.each do |r|
+          puts "   #{r[:position]}. #{Color.c(r[:title], Color::BOLD)} [#{Color.c(r[:domain], Color::GRAY)}]"
+          puts "      └─ #{Color.c(r[:url], Color::BLUE)}"
+        end
+      end
+
+      puts "\n" + ("─" * 80) + "\n"
+    end
+
+    # 10b. IndexNow Multi-Engine Instant Indexing (Bing, Yandex, Seznam, Naver)
+    def self.handle_indexnow_command(target, extra, options)
+      if target == 'key' || target == 'connect'
+        if extra && !extra.strip.empty?
+          key = IndexNow.set_key(extra)
+          puts Color.c("✅ Successfully set IndexNow API key to: #{key}", Color::GREEN, Color::BOLD)
+        else
+          key = IndexNow.get_or_create_key
+          host = Config.default_domain || 'yourdomain.com'
+          puts "🔑 #{Color::BOLD}INDEXNOW API KEY & HOST SETUP:#{Color::RESET}"
+          puts "   • Active Key:          #{Color.c(key, Color::CYAN, Color::BOLD)}"
+          puts "   • Host Verification:   #{Color.c("https://#{host}/#{key}.txt", Color::BLUE)}"
+          puts "   • Required Content:    #{Color.c(key, Color::BOLD)}"
+          puts "\n💡 #{Color.c('Verification Tip:', Color::YELLOW)} Create a plain text file at the root of your web server named '#{key}.txt' with '#{key}' as the content."
+        end
+        return
+      end
+
+      if target == 'sitemap' || target.to_s.end_with?('.xml')
+        sitemap_target = (target == 'sitemap') ? extra : target
+        handle_indexnow_sitemap_command(sitemap_target, options)
+        return
+      end
+
+      target_url = target || options[:url]
+      unless target_url
+        if Config.default_domain
+          target_url = "https://#{Config.default_domain}"
+        else
+          raise 'Please provide a URL to index (e.g. gsc indexnow https://example.com/new-page) or connect a default domain.'
+        end
+      end
+
+      urls = [target_url]
+      urls << extra if extra && extra.start_with?('http')
+
+      key = options[:key] || IndexNow.get_or_create_key
+      res = IndexNow.submit(urls, key: key)
+
+      if options[:json]
+        puts JSON.pretty_generate(res)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "⚡ #{Color::BOLD}INDEXNOW MULTI-SEARCH ENGINE SUBMISSION:#{Color::RESET}"
+      puts "─" * 75
+      status_color = res[:success] ? Color::GREEN : Color::RED
+      puts "Status          : #{Color.c(res[:message], status_color, Color::BOLD)}"
+      puts "Submitted URLs  : #{Color.c(res[:submitted_urls].to_s, Color::CYAN, Color::BOLD)}"
+      puts "Host            : #{res[:host]}"
+      puts "Key Location    : #{res[:key_location]}"
+      puts "Engines Notified: #{Color.c('Microsoft Bing, Yandex, Seznam, Naver', Color::BOLD)}"
+      puts "─" * 75
+
+      urls.each_with_index do |u, idx|
+        puts "   #{idx + 1}. #{Color.c(u, Color::CYAN)}"
+      end
+
+      unless res[:success]
+        puts "\n#{Color.c('⚠️ Note:', Color::YELLOW)} Ensure you have created #{res[:key_location]} with content: #{res[:key]}"
+      end
+      puts ""
+    end
+
+    def self.handle_indexnow_sitemap_command(target, options)
+      sitemap = target || options[:sitemap] || 'sitemap.xml'
+      key = options[:key] || IndexNow.get_or_create_key
+      limit = options[:limit] ? options[:limit].to_i : nil
+
+      puts BANNER unless options[:in_dashboard]
+      puts "📄 #{Color::BOLD}BATCH INDEXNOW SITEMAP SUBMISSION:#{Color::RESET} #{Color.c(sitemap, Color::CYAN)}"
+      puts "─" * 75
+
+      res = IndexNow.submit_sitemap(sitemap, key: key, limit: limit)
+
+      if options[:json]
+        puts JSON.pretty_generate(res)
+        return
+      end
+
+      status_color = res[:success] ? Color::GREEN : Color::RED
+      puts "Status          : #{Color.c(res[:message], status_color, Color::BOLD)}"
+      puts "URLs Submitted  : #{Color.c(res[:submitted_urls].to_s, Color::GREEN, Color::BOLD)}"
+      puts "Host            : #{res[:host]}"
+      puts "Engines Notified: #{Color.c('Microsoft Bing, Yandex, Seznam, Naver', Color::BOLD)}"
+      puts "─" * 75
+      puts "✨ All URLs pushed to IndexNow instant crawl queue."
       puts ""
     end
 
     # 11. Network & Redirect Tracer
     def self.handle_trace_command(target, options)
-      url = target || Config.default_domain || 'example.com'
+      url = target || (Config.default_domain ? "https://#{Config.default_domain}" : nil)
+      if url.nil? || url.empty?
+        puts Color.c("❌ Error: Target URL or domain required. Example: gsc trace https://mybrand.com", Color::RED)
+        return
+      end
       nt = GSC::NetworkTracer.new(url)
       data = nt.trace
 
@@ -476,7 +850,12 @@ module GSC
 
     # 12. Robots.txt Checker
     def self.handle_robots_command(target, extra, options)
-      url = target || "https://#{Config.default_domain || 'example.com'}"
+      raw = target || (Config.default_domain ? "https://#{Config.default_domain}" : nil)
+      if raw.nil? || raw.empty?
+        puts Color.c("❌ Error: Target URL or domain required. Example: gsc robots https://mybrand.com", Color::RED)
+        return
+      end
+      url = raw.to_s.start_with?('http') ? raw : "https://#{raw}"
       path = extra || '/'
       bot = options[:bot] || 'googlebot'
 
@@ -505,7 +884,11 @@ module GSC
 
     # 13. Backlinks & GSC Links Ingestion
     def self.handle_backlinks_command(target, extra, options)
-      domain = target || Config.default_domain || 'example.com'
+      domain = (target unless target == 'import') || Config.default_domain
+      if domain.nil? || domain.empty?
+        puts Color.c("❌ Error: Target domain required. Example: gsc backlinks mybrand.com", Color::RED)
+        return
+      end
       bm = GSC::BacklinksManager.new(domain)
 
       if target == 'import' || extra == 'import'
@@ -566,5 +949,565 @@ module GSC
       end
       puts ""
     end
+
+    # 14. Generative Engine Optimization (GEO / AEO) Citability Auditor
+    def self.handle_geo_command(target, options)
+      raw = target || (Config.default_domain ? "https://#{Config.default_domain}" : nil)
+      if raw.nil? || raw.empty?
+        puts Color.c("❌ Error: Target URL or domain required. Example: gsc geo https://mybrand.com", Color::RED)
+        return
+      end
+      url = raw.to_s.start_with?('http') ? raw : "https://#{raw}"
+      auditor = GSC::GeoAuditor.new(url)
+
+      puts "🤖 Analyzing Generative Engine Optimization (GEO) & Citability for #{Color.c(url, Color::CYAN)}...\n" unless options[:json]
+
+      data = auditor.audit
+      if data[:error]
+        if options[:json]
+          puts JSON.pretty_generate(data)
+        else
+          puts Color.c("❌ Error: #{data[:message]}", Color::RED, Color::BOLD)
+        end
+        return
+      end
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "🤖 #{Color::BOLD}GENERATIVE ENGINE OPTIMIZATION (GEO / AEO) AUDIT#{Color::RESET}"
+      puts "🎯 Target URL : #{Color.c(data[:url], Color::CYAN)}"
+      puts "─" * 75
+
+      score_color = case data[:score]
+                    when 85..100 then Color::GREEN
+                    when 70..84  then Color::CYAN
+                    when 50..69  then Color::YELLOW
+                    else              Color::RED
+                    end
+
+      puts "🏆 #{Color::BOLD}AI CITABILITY SCORE:#{Color::RESET} #{Color.c("#{data[:score]}/100", score_color, Color::BOLD)} — #{data[:grade]}"
+      puts "   • AI Bot Access (Robots.txt)   : #{data[:category_scores][:ai_bot_access][:score]}/25"
+      puts "   • Direct Question Answers      : #{data[:category_scores][:direct_answers][:score]}/25"
+      puts "   • Factual & Data Citability    : #{data[:category_scores][:facts_and_data][:score]}/25"
+      puts "   • Entity Schema & Authority    : #{data[:category_scores][:entity_schema][:score]}/25"
+      puts "─" * 75
+
+      puts "\n🤖 #{Color::BOLD}AI SEARCH CRAWLER ACCESS (Robots.txt):#{Color::RESET}"
+      data[:ai_crawlers][:bots].each do |bot, info|
+        badge = info[:allowed] ? Color.c("✅ ALLOWED", Color::GREEN) : Color.c("❌ BLOCKED", Color::RED, Color::BOLD)
+        puts "   • #{bot.ljust(20)} [#{info[:provider]}]: #{badge} (#{info[:rule]})"
+      end
+
+      puts "\n📝 #{Color::BOLD}DIRECT ANSWER & CITABILITY DENSITY:#{Color::RESET}"
+      puts "   • Question Headings Detected   : #{data[:direct_answers][:total_question_headings]}"
+      puts "   • Direct Answer Paragraphs     : #{data[:direct_answers][:direct_answer_blocks_found]}"
+      puts "   • Optimal Length Answers (30-80w): #{data[:direct_answers][:optimal_answers_count]}"
+
+      samples = data[:direct_answers][:samples] || []
+      if samples.any?
+        puts "   #{Color::BOLD}Sample Answer Pairs:#{Color::RESET}"
+        samples.each do |s|
+          puts "     Q: #{Color.c(s[:question], Color::CYAN)}"
+          puts "     A: #{s[:answer_preview]} (#{s[:word_count]} words)"
+        end
+      end
+
+      puts "\n📊 #{Color::BOLD}FACTUAL & INFORMATION GAIN SIGNALS:#{Color::RESET}"
+      puts "   • Statistics & Percentages     : #{data[:facts_and_citability][:percentage_mentions]}"
+      puts "   • Currency / Pricing Signals   : #{data[:facts_and_citability][:currency_mentions]}"
+      puts "   • Structured Bullet Items (<li>): #{data[:facts_and_citability][:bullet_list_items]}"
+      puts "   • Comparison Table Rows (<tr>) : #{data[:facts_and_citability][:comparison_table_rows]}"
+      puts "   • Recent Year Signals (2024-26): #{data[:facts_and_citability][:recent_year_mentions]}"
+
+      puts "\n🏛️ #{Color::BOLD}ENTITY KNOWLEDGE GRAPH & SCHEMA:#{Color::RESET}"
+      puts "   • Schemas Found                : #{data[:entity_knowledge_graph][:schema_count]} (#{data[:entity_knowledge_graph][:schema_types].join(', ')})"
+      puts "   • Organization / Brand Schema  : #{data[:entity_knowledge_graph][:has_organization_or_brand] ? Color.c("Yes", Color::GREEN) : Color.c("Missing", Color::YELLOW)}"
+      puts "   • FAQ / HowTo Rich Schema      : #{data[:entity_knowledge_graph][:has_faq_or_howto] ? Color.c("Yes", Color::GREEN) : Color.c("None", Color::YELLOW)}"
+      puts "   • Wikidata / Wikipedia Linked  : #{data[:entity_knowledge_graph][:wikidata_or_wikipedia_linked] ? Color.c("Yes", Color::GREEN) : Color.c("No", Color::YELLOW)}"
+      if data[:entity_knowledge_graph][:same_as_domains].any?
+        puts "   • Social Authority Entity Links: #{data[:entity_knowledge_graph][:same_as_domains].join(', ')}"
+      end
+
+      recs = data[:recommendations] || []
+      if recs.any?
+        puts "\n💡 #{Color::BOLD}AI CITABILITY OPTIMIZATION RECOMMENDATIONS:#{Color::RESET}"
+        recs.each_with_index do |r, i|
+          puts "   #{i + 1}. #{Color.c(r, Color::YELLOW)}"
+        end
+      end
+      puts ""
+    end
+
+    # 15. Knowledge Graph Entity & sameAs Disambiguation Auditor
+    def self.handle_entity_command(target, options)
+      raw = target || (Config.default_domain ? "https://#{Config.default_domain}" : nil)
+      if raw.nil? || raw.empty?
+        puts Color.c("❌ Error: Target URL or domain required. Example: gsc entity https://mybrand.com", Color::RED)
+        return
+      end
+      url = raw.to_s.start_with?('http') ? raw : "https://#{raw}"
+
+      puts "🏛️  Auditing Knowledge Graph Entity & sameAs Identity for #{Color.c(url, Color::CYAN)}...\n" unless options[:json]
+
+      data = GSC::EntityAuditor.audit(url)
+      if data[:error]
+        if options[:json]
+          puts JSON.pretty_generate(data)
+        else
+          puts Color.c("❌ Error: #{data[:error]}", Color::RED, Color::BOLD)
+        end
+        return
+      end
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "🏛️  #{Color::BOLD}KNOWLEDGE GRAPH ENTITY & sameAs DISAMBIGUATION AUDIT#{Color::RESET}"
+      puts "🎯 Target URL : #{Color.c(data[:url], Color::CYAN)}"
+      puts "─" * 75
+
+      score_color = case data[:score]
+                    when 85..100 then Color::GREEN
+                    when 70..84  then Color::CYAN
+                    when 50..69  then Color::YELLOW
+                    else              Color::RED
+                    end
+
+      puts "🏆 #{Color::BOLD}ENTITY AUTHORITY SCORE:#{Color::RESET} #{Color.c("#{data[:score]}/100", score_color, Color::BOLD)} — Grade #{data[:grade]}"
+      puts "📦 Detected Entities : #{data[:entities_found]}"
+      puts "─" * 75
+
+      if data[:findings].any?
+        puts "\n🔎 #{Color::BOLD}ENTITY SIGNALS DETECTED:#{Color::RESET}"
+        data[:findings].each do |f|
+          puts "   • #{Color.c(f, Color::GREEN)}"
+        end
+      end
+
+      if data[:authoritative_links].any?
+        puts "\n🌐 #{Color::BOLD}HIGH-AUTHORITY SAMEAS IDENTITY LINKS:#{Color::RESET}"
+        data[:authoritative_links].each do |source, link|
+          puts "   • #{source.to_s.capitalize.ljust(15)}: #{Color.c(link, Color::CYAN)}"
+        end
+      end
+
+      if data[:recommendations].any?
+        puts "\n💡 #{Color::BOLD}OPTIMIZATION DIRECTIVES:#{Color::RESET}"
+        data[:recommendations].each_with_index do |r, i|
+          puts "   #{i + 1}. #{Color.c(r, Color::YELLOW)}"
+        end
+      end
+
+      if options[:generate] || data[:score] < 70
+        puts "\n📋 #{Color::BOLD}RECOMMENDED ENHANCED JSON-LD SCHEMA SNIPPET:#{Color::RESET}"
+        puts "<!-- Paste inside <head> on your homepage/about page -->"
+        puts "<script type=\"application/ld+json\">"
+        puts JSON.pretty_generate(data[:recommended_json_ld])
+        puts "</script>"
+      end
+      puts ""
+    end
+
+    # 16. Multi-Domain Agency Vault & Key Manager
+    def self.handle_vault_command(subcmd, target, extra, options)
+      action = subcmd.to_s.downcase
+      action = 'list' if action.empty? || action == 'vault'
+
+      case action
+      when 'status'
+        stat = GSC::Vault.status
+        if options[:json]
+          puts JSON.pretty_generate(stat)
+        else
+          puts BANNER unless options[:in_dashboard]
+          puts "🔐 #{Color::BOLD}AGENCY CREDENTIAL VAULT SECURITY STATUS#{Color::RESET}"
+          puts "─" * 70
+          puts "  • Vault Directory:       #{stat[:vault_dir]}"
+          puts "  • Encryption Algorithm:  #{Color.c(stat[:encryption_algorithm], Color::GREEN, Color::BOLD)}"
+          puts "  • Master Key Present:    #{stat[:master_key_present] ? Color.c('Yes (Stored locally)', Color::GREEN) : Color.c('Generated on demand', Color::YELLOW)}"
+          puts "  • Stored Client Keys:    #{Color.c(stat[:keys_stored].to_s, Color::CYAN, Color::BOLD)}"
+          puts "  • Domains Mapped:        #{Color.c(stat[:domains_mapped].to_s, Color::CYAN)}"
+          puts "  • POSIX 0700 Security:   #{stat[:permissions_secure] ? Color.c('ENFORCED', Color::GREEN) : Color.c('PERMISSIVE', Color::YELLOW)}"
+          puts "  • Active Target Domain:  #{Color.c(stat[:active_domain] || 'None', Color::GREEN, Color::BOLD)}"
+          puts "─" * 70
+          puts "💡 Switch active client anytime: #{Color.c('gsc switch <domain|alias|#>', Color::CYAN)}"
+          puts ""
+        end
+
+      when 'add', 'import'
+        key_path = target
+        unless key_path && File.file?(File.expand_path(key_path))
+          puts Color.c("❌ Error: Valid service account JSON path required. Example: gsc vault add ./client-key.json --domain client.com", Color::RED)
+          return
+        end
+
+        domain = options[:domain] || extra
+        alias_name = options[:alias]
+        ga4_id = options[:property]
+
+        begin
+          entry = GSC::Vault.add_key(key_path, domain: domain, alias_name: alias_name, ga4_id: ga4_id)
+          if options[:json]
+            puts JSON.pretty_generate({ status: 'ok', entry: entry })
+          else
+            puts Color.c("✅ Successfully encrypted and added key to Agency Vault!", Color::GREEN, Color::BOLD)
+            puts "   • Client Email: #{Color.c(entry['client_email'], Color::CYAN)}"
+            puts "   • Domain:       #{Color.c(entry['domain'] || 'Not set', Color::GREEN)}"
+            puts "   • Alias:        #{Color.c(entry['alias'] || 'Not set', Color::YELLOW)}"
+            puts "   • Key Vault:    #{entry['key_file']} (AES-256-GCM Encrypted)"
+          end
+        rescue StandardError => e
+          puts Color.c("❌ Vault Error: #{e.message}", Color::RED)
+        end
+
+      when 'remove', 'rm', 'delete'
+        target_query = target
+        unless target_query
+          puts Color.c("❌ Error: Specify domain or alias to remove. Example: gsc vault remove client.com", Color::RED)
+          return
+        end
+
+        ok = GSC::Vault.remove_entry(target_query)
+        if ok
+          puts Color.c("✅ Removed #{target_query} from Agency Vault.", Color::GREEN)
+        else
+          puts Color.c("⚠️ Entry not found in Agency Vault: #{target_query}", Color::YELLOW)
+        end
+
+      when 'list', 'ls'
+        entries = GSC::Vault.list_entries
+        if options[:json]
+          puts JSON.pretty_generate({ vault: GSC::Vault.status, entries: entries })
+          return
+        end
+
+        puts BANNER unless options[:in_dashboard]
+        puts "🔐 #{Color::BOLD}AGENCY CREDENTIAL VAULT (AES-256-GCM Secure Store)#{Color::RESET}"
+        puts "─" * 75
+
+        if entries.empty?
+          puts Color.c("No client keys registered in Agency Vault yet.", Color::YELLOW)
+          puts "To add a key: #{Color.c('gsc vault add /path/to/key.json --domain client.com --alias client', Color::CYAN)}"
+          puts "─" * 75
+          return
+        end
+
+        puts "#{Color::BOLD} #  | Domain                       | Alias      | Client Account / Email#{Color::RESET}"
+        puts "─" * 75
+        entries.each_with_index do |e, i|
+          num_str = "[#{i + 1}]".ljust(4)
+          dom_str = (e['domain'] || 'unassigned').ljust(28)
+          alias_str = (e['alias'] || '-').ljust(10)
+          email_str = e['client_email'].to_s
+          marker = e['active'] ? " #{Color.c('👈 [ACTIVE]', Color::GREEN, Color::BOLD)}" : ""
+
+          puts "#{Color.c(num_str, Color::CYAN)}| #{dom_str} | #{Color.c(alias_str, Color::YELLOW)} | #{email_str}#{marker}"
+        end
+        puts "─" * 75
+        puts "💡 Switch active client anytime: #{Color.c('gsc switch <domain|alias|#>', Color::CYAN)}"
+        puts ""
+      else
+        puts Color.c("Unknown vault action: #{action}. Valid actions: list, add, remove, status", Color::YELLOW)
+      end
+    end
+
+    # 18. Direct Answer & Information Gain Snippet Synthesizer
+    def self.handle_answer_command(query, options = {})
+      if query.nil? || query.to_s.strip.empty?
+        puts Color.c("❌ Error: Query required. Usage: gsc answer <query> [--brand <name>] [--type <definition|steps|comparison|faq>] [--generate] [--json]", Color::RED, Color::BOLD)
+        return
+      end
+
+      data = GSC::AnswerSynthesizer.synthesize(query, options)
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "🗣️  #{Color::BOLD}DIRECT ANSWER & INFORMATION GAIN SNIPPET (GEO / AEO)#{Color::RESET}"
+      puts "🎯 Target Query  : #{Color.c("\"#{data[:query]}\"", Color::YELLOW, Color::BOLD)}"
+      puts "🏷️  Intent Type   : [#{Color.c(data[:intent_type].upcase, Color::MAGENTA, Color::BOLD)}]"
+      puts "📊 Word Count    : #{data[:word_count]} words (#{Color.c("Optimal: #{data[:target_optimal_range]}", Color::GREEN)})"
+      puts "🏆 Citability    : #{Color.c("#{data[:citability_score]}/100", Color::GREEN, Color::BOLD)} (Optimized for Featured Snippets, ChatGPT & Perplexity)"
+      puts "─" * 75
+
+      puts "\n#{Color::BOLD}💬 OPTIMIZED DIRECT ANSWER PARAGRAPH:#{Color::RESET}"
+      puts "   #{Color.c(data[:direct_answer], Color::BOLD)}"
+
+      puts "\n#{Color::BOLD}📌 STRUCTURED ATTRIBUTES & KEY POINTS:#{Color::RESET}"
+      data[:key_points].each do |kp|
+        clean_kp = kp.gsub(/\*\*(.*?)\*\*/, "#{Color::BOLD}\\1#{Color::RESET}")
+        puts "   • #{clean_kp}"
+      end
+
+      puts "\n#{Color::BOLD}📈 INFORMATION GAIN FACTOID:#{Color::RESET}"
+      puts "   💡 #{Color.c(data[:information_gain_stat], Color::CYAN)}"
+
+      if options[:generate]
+        puts "\n#{Color::BOLD}💻 READY-TO-PASTE HTML SNIPPET:#{Color::RESET}"
+        puts Color.c(data[:html_markup], Color::DIM)
+
+        puts "\n#{Color::BOLD}💎 SCHEMA.ORG JSON-LD SCRIPT BLOCK:#{Color::RESET}"
+        puts Color.c("<script type=\"application/ld+json\">\n#{JSON.pretty_generate(data[:schema_jsonld])}\n</script>", Color::CYAN)
+      else
+        puts "\n💡 #{Color.c('Tip: Pass --generate to print copy-paste HTML and Schema.org JSON-LD blocks.', Color::GRAY)}"
+      end
+      puts "─" * 75 + "\n"
+    end
+
+    # 19. AI Bot Robots.txt & Cloudflare Firewall Scanner
+    def self.handle_firewall_command(target, options = {})
+      scanner = GSC::FirewallScanner.new(target, options)
+      data = scanner.scan
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      puts BANNER unless options[:in_dashboard]
+      puts "🛡️  #{Color::BOLD}AI BOT ACCESSIBILITY & CLOUDFLARE/WAF FIREWALL AUDITOR#{Color::RESET}"
+      puts "🎯 Target URL    : #{Color.c(data[:url], Color::YELLOW, Color::BOLD)}"
+      puts "🌐 Hostname      : #{data[:host]}"
+
+      # Edge Infrastructure
+      edge_names = data[:edge_infrastructure].map { |i| "#{i[:name]} (#{i[:role]})" }.join(' | ')
+      puts "☁️  Edge CDN/WAF  : #{Color.c(edge_names, Color::CYAN)}"
+
+      # Score & Grade
+      grade_color = case data[:grade]
+                    when 'A' then Color::GREEN
+                    when 'B' then Color::CYAN
+                    when 'C' then Color::YELLOW
+                    when 'D' then Color::RED
+                    else Color::RED
+                    end
+
+      score_str = "#{data[:score]}/100 [Grade #{data[:grade]}]"
+      puts "🏆 AI Access     : #{Color.c(score_str, Color::BOLD, grade_color)} - #{data[:verdict]}"
+      puts "─" * 80
+
+      # Section 1: Live HTTP Probes
+      puts "\n#{Color::BOLD}📡 LIVE EDGE WAF MULTI-USER-AGENT PROBES (LIVE PASS-THROUGH):#{Color::RESET}"
+      puts "#{Color::BOLD}%-18s %-24s %-12s %-10s %-14s %s#{Color::RESET}" % ['Persona', 'Client Name', 'HTTP Status', 'Latency', 'WAF Verdict', 'Challenge / Block']
+      puts "─" * 80
+
+      data[:live_probes].each do |probe|
+        status_col = case probe[:status]
+                     when 200..299 then Color.c("#{probe[:status]} OK", Color::GREEN)
+                     when 300..399 then Color.c("#{probe[:status]} REDIR", Color::YELLOW)
+                     when 403 then Color.c("403 FORBID", Color::RED, Color::BOLD)
+                     when 503 then Color.c("503 UNAVAIL", Color::RED, Color::BOLD)
+                     else Color.c(probe[:status].to_s, Color::RED)
+                     end
+
+        verdict_col = case probe[:verdict]
+                      when :pass then Color.c("PASS", Color::GREEN)
+                      when :redirect then Color.c("REDIRECT", Color::YELLOW)
+                      when :challenge then Color.c("CHALLENGE", Color::RED, Color::BOLD)
+                      when :blocked then Color.c("BLOCKED", Color::RED, Color::BOLD)
+                      else Color.c("ERROR", Color::RED)
+                      end
+
+        challenges_str = probe[:challenges].empty? ? '-' : probe[:challenges].join(', ')
+        challenges_col = probe[:challenges].empty? ? Color.c(challenges_str, Color::GRAY) : Color.c(challenges_str, Color::RED, Color::BOLD)
+
+        puts "%-18s %-24s %-21s %-10s %-23s %s" % [
+          probe[:persona],
+          probe[:name],
+          status_col,
+          "#{probe[:duration_ms]}ms",
+          verdict_col,
+          challenges_col
+        ]
+      end
+
+      # Section 2: Robots.txt Crawler Governance
+      puts "\n#{Color::BOLD}🤖 ROBOTS.TXT AI SEARCH & TRAINING CRAWLER DIRECTIVES:#{Color::RESET}"
+      puts "#{Color::BOLD}%-20s %-15s %-12s %-12s %s#{Color::RESET}" % ['Bot User-Agent', 'Provider', 'Role', 'Status', 'Matched Rule / Reason']
+      puts "─" * 80
+
+      data[:robots_txt][:bots].each do |bot_name, bot_info|
+        status_col = case bot_info[:status]
+                     when :allowed then Color.c("ALLOWED", Color::GREEN, Color::BOLD)
+                     when :restricted then Color.c("RESTRICTED", Color::YELLOW)
+                     when :blocked then Color.c("BLOCKED", Color::RED, Color::BOLD)
+                     else Color.c("UNKNOWN", Color::GRAY)
+                     end
+
+        category_label = bot_info[:category].to_s.sub('_', ' ').capitalize
+
+        puts "%-20s %-15s %-12s %-21s %s" % [
+          bot_name,
+          bot_info[:provider],
+          category_label,
+          status_col,
+          Color.c(bot_info[:reason].to_s, Color::GRAY)
+        ]
+      end
+
+      # Section 3: Blockade Diagnosis
+      puts "\n#{Color::BOLD}🔍 SILENT BOT BLOCKADE DIAGNOSIS:#{Color::RESET}"
+      diag = data[:blockade_diagnosis]
+      if diag[:silent_blockade_detected]
+        puts Color.c("   🚨 #{diag[:summary]}", Color::RED, Color::BOLD)
+        puts "   ⚠️ Browser pass: #{diag[:browser_accessible]} | Googlebot pass: #{diag[:googlebot_accessible]}"
+        puts "   ❌ Blocked AI crawlers: #{diag[:blocked_probes].map { |p| "#{p[:name]} (#{p[:status]})" }.join(', ')}"
+      else
+        puts Color.c("   #{diag[:summary]}", Color::GREEN)
+      end
+
+      # Section 4: Prescriptive WAF & Robots.txt Remediation Recipes
+      recipes = data[:remediation_recipes]
+      if recipes[:cloudflare_waf_rule]
+        puts "\n#{Color::BOLD}🛠️  RECOMMENDED CLOUDFLARE CUSTOM WAF BYPASS RULE:#{Color::RESET}"
+        puts "   Rule Name: #{Color.c(recipes[:cloudflare_waf_rule][:name], Color::CYAN, Color::BOLD)}"
+        puts "   Expression:\n   #{Color.c(recipes[:cloudflare_waf_rule][:filter_expression], Color::YELLOW)}"
+        puts "   Action: #{Color.c('Skip', Color::GREEN, Color::BOLD)} (Skip WAF Managed Rules, Super Bot Fight Mode, Rate Limiting)"
+        puts "\n   #{Color::BOLD}Dashboard Deployment Steps:#{Color::RESET}"
+        recipes[:cloudflare_waf_rule][:dashboard_instructions].each do |step|
+          puts "   #{Color.c(step, Color::GRAY)}"
+        end
+      end
+
+      if options[:generate] || diag[:silent_blockade_detected] || diag[:robots_critical_blocked].any?
+        puts "\n#{Color::BOLD}📄 RECOMMENDED ROBOTS.TXT CONFIGURATION FOR AI SEARCH:#{Color::RESET}"
+        puts Color.c(recipes[:recommended_robots_txt], Color::DIM)
+      else
+        puts "\n💡 #{Color.c('Tip: Pass --generate to display copy-paste robots.txt configuration.', Color::GRAY)}"
+      end
+
+      puts "─" * 80 + "\n"
+    end
+
+    # 20. Title Tag Length & Pixel Width Batch Optimizer
+    def self.handle_titles_command(target, options = {})
+      target_site = target.to_s.strip
+      target_site = Config.default_domain || '' if target_site.empty?
+      if target_site.empty?
+        puts Color.c("❌ Error: Target domain or sitemap required. Example: gsc titles mybrand.com", Color::RED)
+        return
+      end
+
+      optimizer = GSC::TitleOptimizer.new(target_site, options)
+
+      unless options[:json] || options[:csv]
+        puts BANNER unless options[:in_dashboard]
+        puts "📏 #{Color::BOLD}GOOGLE SERP TITLE LENGTH & PIXEL OVERFLOW AUDITOR#{Color::RESET}"
+        puts "🎯 Target: #{Color.c(target_site, Color::YELLOW, Color::BOLD)}"
+        print "🔄 Crawling and calculating pixel metrics across pages... "
+        $stdout.flush
+      end
+
+      data = optimizer.audit do |_url, current, total|
+        unless options[:json] || options[:csv]
+          print "\r🔄 Crawling and calculating pixel metrics across pages... [#{current}/#{total}]"
+          $stdout.flush
+        end
+      end
+
+      unless options[:json] || options[:csv]
+        puts " Done!\n"
+      end
+
+      if options[:json]
+        puts JSON.pretty_generate(data)
+        return
+      end
+
+      if options[:csv]
+        require 'csv'
+        puts "URL,Characters,Pixel_Width,Status,Current_Title,Desktop_Preview,Suggested_Rewrite_1,Suggested_Rewrite_2"
+        data[:pages].each do |p|
+          r1 = p[:suggested_rewrites][0] ? p[:suggested_rewrites][0][:title].gsub('"', '""') : ''
+          r2 = p[:suggested_rewrites][1] ? p[:suggested_rewrites][1][:title].gsub('"', '""') : ''
+          title_clean = p[:title].to_s.gsub('"', '""')
+          prev_clean = p[:desktop_preview].to_s.gsub('"', '""')
+          puts "\"#{p[:url]}\",#{p[:char_count]},#{p[:pixel_width]},#{p[:status]},\"#{title_clean}\",\"#{prev_clean}\",\"#{r1}\",\"#{r2}\""
+        end
+        return
+      end
+
+      # Health Grade & Color
+      grade_color = case data[:grade]
+                    when 'A' then Color::GREEN
+                    when 'B' then Color::CYAN
+                    when 'C' then Color::YELLOW
+                    when 'D' then Color::RED
+                    else Color::RED
+                    end
+
+      puts "🏆 Title Health  : #{Color.c("#{data[:health_score]}/100 [Grade #{data[:grade]}]", Color::BOLD, grade_color)} - #{data[:verdict]}"
+      puts "📊 Overview      : #{data[:total_pages]} Pages Audited | #{Color.c("#{data[:percentages][:optimal_pct]}% Optimal", Color::GREEN)} | #{Color.c("#{data[:percentages][:overflow_pct]}% Overflowing", Color::YELLOW)}"
+      puts "📈 Breakdown     : ✅ #{data[:counts][:optimal]} Optimal | ⚠️ #{data[:counts][:desktop_overflow]} Desktop Overflow | 🚨 #{data[:counts][:critical_overflow]} Critical Overflow | ℹ️ #{data[:counts][:too_short]} Too Short | ❌ #{data[:counts][:missing]} Missing"
+      puts "─" * 80
+
+      pages_to_display = options[:overflow_only] ? data[:pages].select { |p| [:desktop_overflow, :critical_overflow].include?(p[:status]) } : data[:pages]
+
+      if pages_to_display.empty?
+        puts "\n🎉 #{Color.c('All audited pages have optimal title tags with zero pixel overflow!', Color::GREEN, Color::BOLD)}"
+      else
+        puts "\n#{Color::BOLD}%-16s %-7s %-10s %s#{Color::RESET}" % ['Status', 'Chars', 'Width', 'URL & Title Tag']
+        puts "─" * 80
+
+        pages_to_display.each do |page|
+          status_col = case page[:status]
+                       when :optimal then Color.c("OPTIMAL", Color::GREEN)
+                       when :desktop_overflow then Color.c("DESK OVERFLOW", Color::YELLOW, Color::BOLD)
+                       when :critical_overflow then Color.c("CRIT OVERFLOW", Color::RED, Color::BOLD)
+                       when :too_short then Color.c("TOO SHORT", Color::CYAN)
+                       when :missing then Color.c("MISSING", Color::RED, Color::BOLD)
+                       end
+
+          px_str = "#{page[:pixel_width]}px"
+          px_col = page[:pixel_width] > 580.0 ? Color.c(px_str, Color::RED, Color::BOLD) : Color.c(px_str, Color::GREEN)
+
+          puts "%-23s %-7s %-18s %s" % [
+            status_col,
+            "#{page[:char_count]}c",
+            px_col,
+            Color.c(page[:url], Color::BOLD)
+          ]
+          puts "   ↳ #{Color.c(page[:title].empty? ? '(No Title Tag)' : page[:title], Color::DIM)}"
+        end
+      end
+
+      # Section: Title Rewrite Optimization Playbook
+      overflowing_pages = data[:pages].reject { |p| p[:suggested_rewrites].empty? }
+
+      if overflowing_pages.any?
+        puts "\n\n#{Color::BOLD}📝 TITLE REWRITE & CTR OPTIMIZATION PLAYBOOK (#{overflowing_pages.size} Pages Flagged):#{Color::RESET}"
+        puts "─" * 80
+
+        overflowing_pages.first(8).each_with_index do |p, idx|
+          puts "\n#{Color.c("[#{idx + 1}]", Color::CYAN, Color::BOLD)} #{Color.c(p[:url], Color::BOLD)}"
+          puts "   ❌ Current Title  : #{Color.c("\"#{p[:title]}\"", Color::RED)} (#{p[:pixel_width]}px, #{p[:char_count]} chars)"
+          puts "   👀 Desktop SERP   : #{Color.c(p[:desktop_preview], Color::GRAY)}"
+
+          puts "   💡 #{Color::BOLD}Synthesized Non-Truncating Title Rewrites (<560px):#{Color::RESET}"
+          p[:suggested_rewrites].each do |rewrite|
+            puts "      • [#{Color.c(rewrite[:type], Color::YELLOW)}] #{Color.c(rewrite[:title], Color::GREEN, Color::BOLD)}"
+            puts "        ↳ #{rewrite[:pixel_width]}px | #{rewrite[:char_count]} chars | Desktop SERP: #{Color.c('FITS CLEANLY', Color::GREEN)}"
+          end
+        end
+
+        if overflowing_pages.size > 8
+          puts "\n... and #{overflowing_pages.size - 8} more pages flagged. Run with #{Color.c('--csv', Color::CYAN)} or #{Color.c('--json', Color::CYAN)} to export all rewrites."
+        end
+      end
+
+      puts "\n" + ("─" * 80) + "\n"
+    end
   end
 end
+
+