antigravity-seo-kit 2.0.0

package/.agent/skills/seo/references/schema-types.md

@@ -0,0 +1,118 @@
+<!-- Updated: 2026-02-07 -->
+# Schema.org Types: Status & Recommendations (February 2026)
+
+**Schema.org Version:** 29.4 (December 8, 2025)
+
+## Format Preference
+Always use **JSON-LD** (`<script type="application/ld+json">`).
+Google's documentation explicitly recommends JSON-LD over Microdata and RDFa.
+
+**AI Search Note:** Content with proper schema has ~2.5× higher chance of appearing in AI-generated answers (confirmed by Google and Microsoft, March 2025).
+
+---
+
+## Active: Recommend freely
+
+| Type | Use Case | Key Properties |
+|------|----------|----------------|
+| Organization | Company info | name, url, logo, contactPoint, sameAs |
+| LocalBusiness | Physical businesses | name, address, telephone, openingHours, geo, priceRange |
+| SoftwareApplication | Desktop/mobile apps | name, operatingSystem, applicationCategory, offers, aggregateRating |
+| WebApplication | Browser-based SaaS | name, applicationCategory, offers, browserRequirements, featureList |
+| Product | Physical/digital products | name, image, description, sku, brand, offers, review |
+| Offer | Pricing | price, priceCurrency, availability, url, validFrom |
+| Service | Service businesses | name, provider, areaServed, description, offers |
+| Article | Blog posts, news | headline, author, datePublished, dateModified, image, publisher |
+| BlogPosting | Blog content | Same as Article + blog-specific context |
+| NewsArticle | News content | Same as Article + news-specific context |
+| Review | Individual reviews | reviewRating, author, itemReviewed, reviewBody |
+| AggregateRating | Rating summaries | ratingValue, reviewCount, bestRating, worstRating |
+| BreadcrumbList | Navigation | itemListElement with position, name, item |
+| WebSite | Site-level | name, url, potentialAction (SearchAction for sitelinks search) |
+| WebPage | Page-level | name, description, datePublished, dateModified |
+| Person | Author/team | name, jobTitle, url, sameAs, image, worksFor |
+| ContactPage | Contact pages | name, url |
+| VideoObject | Video content | name, description, thumbnailUrl, uploadDate, duration, contentUrl |
+| ImageObject | Image content | contentUrl, caption, creator, copyrightHolder |
+| Event | Events | name, startDate, endDate, location, organizer, offers |
+| JobPosting | Job listings | title, description, datePosted, hiringOrganization, jobLocation |
+| Course | Educational content | name, description, provider, hasCourseInstance |
+| DiscussionForumPosting | Forum threads | headline, author, datePublished, text, url |
+| ProductGroup | Variant products | name, productGroupID, variesBy, hasVariant |
+| ProfilePage | Author/creator profiles | mainEntity (Person), name, url, description, sameAs |
+
+---
+
+## Restricted: Only for specific site types
+
+| Type | Restriction | Since |
+|------|------------|-------|
+| FAQPage | Government and healthcare authority sites ONLY | August 2023 |
+
+> Google severely limited FAQ rich results in August 2023. Only authoritative sources (government, health organizations) receive FAQ rich results.
+>
+> **GEO nuance**: FAQPage schema still benefits AI/LLM citation visibility (ChatGPT, Perplexity, Google AI Overviews), even without Google rich results.
+> - **Existing FAQPage on commercial site**: Flag at Info priority, not Critical. Removal removes GEO citation upside.
+> - **Adding new FAQPage**: Not recommended for Google benefit; acceptable if AI search visibility is a priority.
+
+---
+
+## Deprecated: Never recommend
+
+| Type | Status | Since | Notes |
+|------|--------|-------|-------|
+| HowTo | Rich results fully removed | September 2023 | Google stopped showing how-to rich results |
+| SpecialAnnouncement | Deprecated | July 31, 2025 | COVID-era schema, no longer processed |
+| CourseInfo | Retired from rich results | June 2025 | Merged into Course |
+| EstimatedSalary | Retired from rich results | June 2025 | No longer displayed |
+| LearningVideo | Retired from rich results | June 2025 | Use VideoObject instead |
+| ClaimReview | Retired from rich results | June 2025 | Fact-check markup no longer generates rich results |
+| VehicleListing | Retired from rich results | June 2025 | Vehicle listing structured data discontinued |
+| Book Actions | Deprecated then REVERSED | June 2025 | **Still functional as of Feb 2026**: historical note only |
+| Practice Problem | Retired from rich results | Late 2025 | Educational practice problems no longer displayed |
+| Dataset | Retired from rich results | Late 2025 | Dataset Search feature discontinued |
+
+---
+
+## Recent Additions (2024-2026)
+
+| Type/Feature | Added | Notes |
+|-------------|-------|-------|
+| Product Certification markup | April 2025 | Energy ratings, safety certifications. Replaced EnergyConsumptionDetails. |
+| ProductGroup | 2025 | E-commerce product variants with variesBy, hasVariant properties |
+| ProfilePage | 2025 | Author/creator profile pages with mainEntity Person for E-E-A-T |
+| DiscussionForumPosting | 2024 | For forum/community content |
+| Speakable | Updated 2024 | For voice search optimization |
+| LoyaltyProgram | June 2025 | Member pricing, loyalty card structured data |
+| Organization-level shipping/return policies | November 2025 | Configure via Search Console without Merchant Center |
+| ConferenceEvent | December 2025 | Schema.org v29.4 addition |
+| PerformingArtsEvent | December 2025 | Schema.org v29.4 addition |
+
+## E-commerce Requirements (Updated)
+
+| Requirement | Status | Since |
+|-------------|--------|-------|
+| `returnPolicyCountry` in MerchantReturnPolicy | **Required** | March 2025 |
+| Product variant structured data | Expanded | 2025, includes apparel, cosmetics, electronics |
+
+> **Note:** Content API for Shopping sunsets August 18, 2026. Migrate to Merchant API.
+
+---
+
+## Validation Checklist
+
+For any schema block, verify:
+
+1. ✅ `@context` is `"https://schema.org"` (not http)
+2. ✅ `@type` is a valid, non-deprecated type
+3. ✅ All required properties are present
+4. ✅ Property values match expected data types
+5. ✅ No placeholder text (e.g., "[Business Name]")
+6. ✅ URLs are absolute, not relative
+7. ✅ Dates are in ISO 8601 format
+8. ✅ Images have valid URLs
+
+## Testing Tools
+
+- [Google Rich Results Test](https://search.google.com/test/rich-results)
+- [Schema.org Validator](https://validator.schema.org/)

package/.agent/skills/seo/schema/templates.json

@@ -0,0 +1,213 @@
+{
+  "templates": [
+    {
+      "type": "VideoObject",
+      "description": "Video content pages with thumbnails, duration, and playback URLs. Enables video rich results in Google Search.",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "VideoObject",
+        "name": "[Video Title]",
+        "description": "[Video Description]",
+        "thumbnailUrl": "[Thumbnail Image URL]",
+        "uploadDate": "[YYYY-MM-DD]",
+        "duration": "[ISO 8601 Duration, e.g. PT1H30M]",
+        "contentUrl": "[Direct Video File URL]",
+        "embedUrl": "[Embed Player URL]",
+        "publisher": {
+          "@type": "Organization",
+          "name": "[Publisher Name]",
+          "logo": {
+            "@type": "ImageObject",
+            "url": "[Logo URL]"
+          }
+        }
+      }
+    },
+    {
+      "type": "BroadcastEvent",
+      "description": "Live streaming content for LIVE badge in Google Search results. Requires VideoObject and isLiveBroadcast flag.",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "VideoObject",
+        "name": "[Live Stream Title]",
+        "description": "[Live Stream Description]",
+        "thumbnailUrl": "[Thumbnail Image URL]",
+        "uploadDate": "[YYYY-MM-DD]",
+        "contentUrl": "[Stream URL]",
+        "embedUrl": "[Embed Player URL]",
+        "publication": {
+          "@type": "BroadcastEvent",
+          "isLiveBroadcast": true,
+          "startDate": "[YYYY-MM-DDTHH:MM:SSZ]",
+          "endDate": "[YYYY-MM-DDTHH:MM:SSZ]"
+        }
+      }
+    },
+    {
+      "type": "Clip",
+      "description": "Key moments or chapters within a video. Enables key moments rich results with timestamp links.",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "VideoObject",
+        "name": "[Video Title]",
+        "description": "[Video Description]",
+        "thumbnailUrl": "[Thumbnail Image URL]",
+        "uploadDate": "[YYYY-MM-DD]",
+        "contentUrl": "[Direct Video File URL]",
+        "hasPart": [
+          {
+            "@type": "Clip",
+            "name": "[Clip Title]",
+            "startOffset": 0,
+            "endOffset": 120,
+            "url": "[Video URL with timestamp, e.g. ?t=0]"
+          },
+          {
+            "@type": "Clip",
+            "name": "[Next Clip Title]",
+            "startOffset": 120,
+            "endOffset": 300,
+            "url": "[Video URL with timestamp, e.g. ?t=120]"
+          }
+        ]
+      }
+    },
+    {
+      "type": "SeekToAction",
+      "description": "Enable seek functionality in video rich results. Allows users to jump to specific timestamps from search.",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "VideoObject",
+        "name": "[Video Title]",
+        "description": "[Video Description]",
+        "thumbnailUrl": "[Thumbnail Image URL]",
+        "uploadDate": "[YYYY-MM-DD]",
+        "contentUrl": "[Direct Video File URL]",
+        "potentialAction": {
+          "@type": "SeekToAction",
+          "target": "[Video URL]?t={seek_to_second_number}",
+          "startOffset-input": "required name=seek_to_second_number"
+        }
+      }
+    },
+    {
+      "type": "SoftwareSourceCode",
+      "description": "Open source and code repository pages. Describes programming language, platform, and repository location.",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "SoftwareSourceCode",
+        "name": "[Repository Name]",
+        "description": "[Repository Description]",
+        "codeRepository": "[Repository URL, e.g. https://github.com/org/repo]",
+        "programmingLanguage": "[Language, e.g. Python]",
+        "runtimePlatform": "[Platform, e.g. Node.js]",
+        "author": {
+          "@type": "Person",
+          "name": "[Author Name]"
+        },
+        "license": "[License URL, e.g. https://opensource.org/licenses/MIT]",
+        "dateCreated": "[YYYY-MM-DD]",
+        "dateModified": "[YYYY-MM-DD]"
+      }
+    },
+    {
+      "type": "ProductGroup",
+      "description": "E-commerce product variants grouped by attributes like size, color. Enables variant-aware rich results with variesBy and hasVariant properties.",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "ProductGroup",
+        "name": "[Product Name]",
+        "description": "[Product group description]",
+        "productGroupID": "[product-group-id]",
+        "variesBy": ["https://schema.org/size", "https://schema.org/color"],
+        "hasVariant": [
+          {
+            "@type": "Product",
+            "name": "[Variant - Red, Large]",
+            "sku": "[SKU-001]",
+            "color": "[Red]",
+            "size": "[Large]",
+            "offers": {
+              "@type": "Offer",
+              "price": "[29.99]",
+              "priceCurrency": "USD",
+              "availability": "https://schema.org/InStock"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "type": "ProfilePage",
+      "description": "Author, creator, or team member profile pages. Enhances E-E-A-T signals with mainEntity Person markup and sameAs links.",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "ProfilePage",
+        "mainEntity": {
+          "@type": "Person",
+          "name": "[Author Name]",
+          "url": "[Profile URL]",
+          "description": "[Author bio and expertise summary]",
+          "sameAs": [
+            "[Twitter URL]",
+            "[LinkedIn URL]"
+          ]
+        }
+      }
+    },
+    {
+      "type": "Certification",
+      "description": "Product certifications (Energy Star, safety, organic, etc.). Replaced EnergyConsumptionDetails in April 2025.",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "Product",
+        "name": "[Product Name]",
+        "hasCertification": {
+          "@type": "Certification",
+          "certificationIdentification": "[Certification Name, e.g. Energy Star]",
+          "issuedBy": {
+            "@type": "Organization",
+            "name": "[Issuing Organization, e.g. EPA]"
+          }
+        }
+      }
+    },
+    {
+      "type": "OfferShippingDetails",
+      "description": "Shipping and delivery information for e-commerce products. Includes shipping rate, handling time, and transit time.",
+      "template": {
+        "@context": "https://schema.org",
+        "@type": "Product",
+        "name": "[Product Name]",
+        "offers": {
+          "@type": "Offer",
+          "price": "[Price]",
+          "priceCurrency": "USD",
+          "shippingDetails": {
+            "@type": "OfferShippingDetails",
+            "shippingRate": {
+              "@type": "MonetaryAmount",
+              "value": "[0]",
+              "currency": "USD"
+            },
+            "deliveryTime": {
+              "@type": "ShippingDeliveryTime",
+              "handlingTime": {
+                "@type": "QuantitativeValue",
+                "minValue": 0,
+                "maxValue": 1,
+                "unitCode": "DAY"
+              },
+              "transitTime": {
+                "@type": "QuantitativeValue",
+                "minValue": 1,
+                "maxValue": 5,
+                "unitCode": "DAY"
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/.agent/skills/seo/scripts/analyze_visual.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""
+Analyze visual aspects of a web page using Playwright.
+
+Usage:
+    python analyze_visual.py https://example.com
+"""
+
+import argparse
+import ipaddress
+import json
+import socket
+import sys
+from urllib.parse import ParseResult, urlparse
+
+try:
+    from playwright.sync_api import sync_playwright, TimeoutError as PlaywrightTimeout
+except ImportError:
+    print("Error: playwright required. Install with: pip install playwright && playwright install chromium")
+    sys.exit(1)
+
+
+def normalize_url(url: str) -> tuple[str, ParseResult]:
+    """Normalize URL and return (url, parsed_url)."""
+    parsed = urlparse(url)
+    if not parsed.scheme:
+        url = f"https://{url}"
+        parsed = urlparse(url)
+
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(f"Invalid URL scheme: {parsed.scheme}")
+    if not parsed.hostname:
+        raise ValueError("Invalid URL: missing hostname")
+
+    return url, parsed
+
+
+def analyze_visual(url: str, timeout: int = 30000) -> dict:
+    """
+    Analyze visual aspects of a web page.
+
+    Args:
+        url: URL to analyze
+        timeout: Page load timeout in milliseconds
+
+    Returns:
+        Dictionary with visual analysis results
+    """
+    result = {
+        "url": url,
+        "above_fold": {
+            "h1_visible": False,
+            "cta_visible": False,
+            "hero_image": None,
+        },
+        "mobile": {
+            "viewport_meta": False,
+            "horizontal_scroll": False,
+            "touch_targets_ok": True,
+        },
+        "layout": {
+            "overlapping_elements": [],
+            "text_overflow": [],
+        },
+        "fonts": {
+            "base_size": None,
+            "readable": True,
+        },
+        "error": None,
+    }
+
+    try:
+        url, parsed = normalize_url(url)
+        result["url"] = url
+    except ValueError as e:
+        result["error"] = str(e)
+        return result
+
+    # SSRF prevention: block private/internal IPs
+    try:
+        resolved_ip = socket.gethostbyname(parsed.hostname)
+        ip = ipaddress.ip_address(resolved_ip)
+        if ip.is_private or ip.is_loopback or ip.is_reserved:
+            result["error"] = f"Blocked: URL resolves to private/internal IP ({resolved_ip})"
+            return result
+    except socket.gaierror:
+        pass
+
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+
+            # Desktop analysis
+            desktop = browser.new_context(viewport={"width": 1920, "height": 1080})
+            page = desktop.new_page()
+            page.goto(url, wait_until="networkidle", timeout=timeout)
+
+            # Check H1 visibility above fold
+            h1 = page.query_selector("h1")
+            if h1:
+                box = h1.bounding_box()
+                if box and box["y"] < 1080:
+                    result["above_fold"]["h1_visible"] = True
+
+            # Check for CTA buttons above fold
+            cta_selectors = [
+                "a[href*='signup']",
+                "a[href*='contact']",
+                "a[href*='demo']",
+                "button:has-text('Get Started')",
+                "button:has-text('Sign Up')",
+                "button:has-text('Contact')",
+                ".cta",
+                "[class*='cta']",
+            ]
+            for selector in cta_selectors:
+                try:
+                    cta = page.query_selector(selector)
+                    if cta:
+                        box = cta.bounding_box()
+                        if box and box["y"] < 1080:
+                            result["above_fold"]["cta_visible"] = True
+                            break
+                except Exception:
+                    pass
+
+            # Check hero image
+            hero_selectors = [
+                ".hero img",
+                "[class*='hero'] img",
+                "header img",
+                "main img:first-of-type",
+            ]
+            for selector in hero_selectors:
+                try:
+                    hero = page.query_selector(selector)
+                    if hero:
+                        src = hero.get_attribute("src")
+                        if src:
+                            result["above_fold"]["hero_image"] = src
+                            break
+                except Exception:
+                    pass
+
+            desktop.close()
+
+            # Mobile analysis
+            mobile = browser.new_context(viewport={"width": 375, "height": 812})
+            page = mobile.new_page()
+            page.goto(url, wait_until="networkidle", timeout=timeout)
+
+            # Check viewport meta
+            viewport_meta = page.query_selector('meta[name="viewport"]')
+            result["mobile"]["viewport_meta"] = viewport_meta is not None
+
+            # Check for horizontal scroll
+            scroll_width = page.evaluate("document.documentElement.scrollWidth")
+            viewport_width = page.evaluate("window.innerWidth")
+            result["mobile"]["horizontal_scroll"] = scroll_width > viewport_width
+
+            # Check font size
+            base_font_size = page.evaluate("""
+                () => {
+                    const body = document.body;
+                    const style = window.getComputedStyle(body);
+                    return parseFloat(style.fontSize);
+                }
+            """)
+            result["fonts"]["base_size"] = base_font_size
+            result["fonts"]["readable"] = base_font_size >= 16
+
+            mobile.close()
+            browser.close()
+
+    except PlaywrightTimeout:
+        result["error"] = f"Page load timed out after {timeout}ms"
+    except Exception as e:
+        result["error"] = str(e)
+
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Analyze visual aspects of a web page")
+    parser.add_argument("url", help="URL to analyze")
+    parser.add_argument("--timeout", "-t", type=int, default=30000, help="Timeout in ms")
+    parser.add_argument("--json", "-j", action="store_true", help="Output as JSON")
+
+    args = parser.parse_args()
+
+    result = analyze_visual(args.url, timeout=args.timeout)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print("Visual Analysis Results")
+        print("=" * 40)
+
+        print("\nAbove the Fold:")
+        print(f"  H1 Visible: {'✓' if result['above_fold']['h1_visible'] else '✗'}")
+        print(f"  CTA Visible: {'✓' if result['above_fold']['cta_visible'] else '✗'}")
+        print(f"  Hero Image: {result['above_fold']['hero_image'] or 'None found'}")
+
+        print("\nMobile Responsiveness:")
+        print(f"  Viewport Meta: {'✓' if result['mobile']['viewport_meta'] else '✗'}")
+        print(f"  Horizontal Scroll: {'✗ (problem)' if result['mobile']['horizontal_scroll'] else '✓'}")
+
+        print("\nTypography:")
+        print(f"  Base Font Size: {result['fonts']['base_size']}px")
+        print(f"  Readable (≥16px): {'✓' if result['fonts']['readable'] else '✗'}")
+
+        if result["error"]:
+            print(f"\nError: {result['error']}")
+
+
+if __name__ == "__main__":
+    main()